]>
Commit | Line | Data |
---|---|---|
e1e5ecb2 | 1 | @c Copyright (C) 1988-2023 Free Software Foundation, Inc. |
d77de738 ML |
2 | |
3 | @c This is part of the GCC manual. | |
4 | @c For copying conditions, see the file gcc.texi. | |
5 | ||
6 | @node C Extensions | |
7 | @chapter Extensions to the C Language Family | |
8 | @cindex extensions, C language | |
9 | @cindex C language extensions | |
10 | ||
11 | @opindex pedantic | |
12 | GNU C provides several language features not found in ISO standard C@. | |
13 | (The @option{-pedantic} option directs GCC to print a warning message if | |
14 | any of these features is used.) To test for the availability of these | |
15 | features in conditional compilation, check for a predefined macro | |
16 | @code{__GNUC__}, which is always defined under GCC@. | |
17 | ||
18 | These extensions are available in C and Objective-C@. Most of them are | |
19 | also available in C++. @xref{C++ Extensions,,Extensions to the | |
20 | C++ Language}, for extensions that apply @emph{only} to C++. | |
21 | ||
22 | Some features that are in ISO C99 but not C90 or C++ are also, as | |
23 | extensions, accepted by GCC in C90 mode and in C++. | |
24 | ||
25 | @menu | |
26 | * Statement Exprs:: Putting statements and declarations inside expressions. | |
27 | * Local Labels:: Labels local to a block. | |
28 | * Labels as Values:: Getting pointers to labels, and computed gotos. | |
29 | * Nested Functions:: Nested function in GNU C. | |
30 | * Nonlocal Gotos:: Nonlocal gotos. | |
31 | * Constructing Calls:: Dispatching a call to another function. | |
32 | * Typeof:: @code{typeof}: referring to the type of an expression. | |
33 | * Conditionals:: Omitting the middle operand of a @samp{?:} expression. | |
34 | * __int128:: 128-bit integers---@code{__int128}. | |
35 | * Long Long:: Double-word integers---@code{long long int}. | |
36 | * Complex:: Data types for complex numbers. | |
37 | * Floating Types:: Additional Floating Types. | |
38 | * Half-Precision:: Half-Precision Floating Point. | |
39 | * Decimal Float:: Decimal Floating Types. | |
40 | * Hex Floats:: Hexadecimal floating-point constants. | |
41 | * Fixed-Point:: Fixed-Point Types. | |
42 | * Named Address Spaces::Named address spaces. | |
43 | * Zero Length:: Zero-length arrays. | |
44 | * Empty Structures:: Structures with no members. | |
45 | * Variable Length:: Arrays whose length is computed at run time. | |
46 | * Variadic Macros:: Macros with a variable number of arguments. | |
47 | * Escaped Newlines:: Slightly looser rules for escaped newlines. | |
48 | * Subscripting:: Any array can be subscripted, even if not an lvalue. | |
49 | * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. | |
50 | * Variadic Pointer Args:: Pointer arguments to variadic functions. | |
51 | * Pointers to Arrays:: Pointers to arrays with qualifiers work as expected. | |
52 | * Initializers:: Non-constant initializers. | |
53 | * Compound Literals:: Compound literals give structures, unions | |
54 | or arrays as values. | |
55 | * Designated Inits:: Labeling elements of initializers. | |
56 | * Case Ranges:: `case 1 ... 9' and such. | |
57 | * Cast to Union:: Casting to union type from any member of the union. | |
58 | * Mixed Labels and Declarations:: Mixing declarations, labels and code. | |
59 | * Function Attributes:: Declaring that functions have no side effects, | |
60 | or that they can never return. | |
61 | * Variable Attributes:: Specifying attributes of variables. | |
62 | * Type Attributes:: Specifying attributes of types. | |
63 | * Label Attributes:: Specifying attributes on labels. | |
64 | * Enumerator Attributes:: Specifying attributes on enumerators. | |
65 | * Statement Attributes:: Specifying attributes on statements. | |
66 | * Attribute Syntax:: Formal syntax for attributes. | |
67 | * Function Prototypes:: Prototype declarations and old-style definitions. | |
68 | * C++ Comments:: C++ comments are recognized. | |
69 | * Dollar Signs:: Dollar sign is allowed in identifiers. | |
70 | * Character Escapes:: @samp{\e} stands for the character @key{ESC}. | |
71 | * Alignment:: Determining the alignment of a function, type or variable. | |
72 | * Inline:: Defining inline functions (as fast as macros). | |
73 | * Volatiles:: What constitutes an access to a volatile object. | |
74 | * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. | |
75 | * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. | |
76 | * Incomplete Enums:: @code{enum foo;}, with details to follow. | |
77 | * Function Names:: Printable strings which are the name of the current | |
78 | function. | |
79 | * Return Address:: Getting the return or frame address of a function. | |
80 | * Vector Extensions:: Using vector instructions through built-in functions. | |
81 | * Offsetof:: Special syntax for implementing @code{offsetof}. | |
82 | * __sync Builtins:: Legacy built-in functions for atomic memory access. | |
83 | * __atomic Builtins:: Atomic built-in functions with memory model. | |
84 | * Integer Overflow Builtins:: Built-in functions to perform arithmetics and | |
85 | arithmetic overflow checking. | |
86 | * x86 specific memory model extensions for transactional memory:: x86 memory models. | |
87 | * Object Size Checking:: Built-in functions for limited buffer overflow | |
88 | checking. | |
89 | * Other Builtins:: Other built-in functions. | |
90 | * Target Builtins:: Built-in functions specific to particular targets. | |
91 | * Target Format Checks:: Format checks specific to particular targets. | |
92 | * Pragmas:: Pragmas accepted by GCC. | |
93 | * Unnamed Fields:: Unnamed struct/union fields within structs/unions. | |
94 | * Thread-Local:: Per-thread variables. | |
95 | * Binary constants:: Binary constants using the @samp{0b} prefix. | |
96 | @end menu | |
97 | ||
98 | @node Statement Exprs | |
99 | @section Statements and Declarations in Expressions | |
100 | @cindex statements inside expressions | |
101 | @cindex declarations inside expressions | |
102 | @cindex expressions containing statements | |
103 | @cindex macros, statements in expressions | |
104 | ||
105 | @c the above section title wrapped and causes an underfull hbox.. i | |
106 | @c changed it from "within" to "in". --mew 4feb93 | |
107 | A compound statement enclosed in parentheses may appear as an expression | |
108 | in GNU C@. This allows you to use loops, switches, and local variables | |
109 | within an expression. | |
110 | ||
111 | Recall that a compound statement is a sequence of statements surrounded | |
112 | by braces; in this construct, parentheses go around the braces. For | |
113 | example: | |
114 | ||
115 | @smallexample | |
116 | (@{ int y = foo (); int z; | |
117 | if (y > 0) z = y; | |
118 | else z = - y; | |
119 | z; @}) | |
120 | @end smallexample | |
121 | ||
122 | @noindent | |
123 | is a valid (though slightly more complex than necessary) expression | |
124 | for the absolute value of @code{foo ()}. | |
125 | ||
126 | The last thing in the compound statement should be an expression | |
127 | followed by a semicolon; the value of this subexpression serves as the | |
128 | value of the entire construct. (If you use some other kind of statement | |
129 | last within the braces, the construct has type @code{void}, and thus | |
130 | effectively no value.) | |
131 | ||
132 | This feature is especially useful in making macro definitions ``safe'' (so | |
133 | that they evaluate each operand exactly once). For example, the | |
134 | ``maximum'' function is commonly defined as a macro in standard C as | |
135 | follows: | |
136 | ||
137 | @smallexample | |
138 | #define max(a,b) ((a) > (b) ? (a) : (b)) | |
139 | @end smallexample | |
140 | ||
141 | @noindent | |
142 | @cindex side effects, macro argument | |
143 | But this definition computes either @var{a} or @var{b} twice, with bad | |
144 | results if the operand has side effects. In GNU C, if you know the | |
145 | type of the operands (here taken as @code{int}), you can avoid this | |
146 | problem by defining the macro as follows: | |
147 | ||
148 | @smallexample | |
149 | #define maxint(a,b) \ | |
150 | (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) | |
151 | @end smallexample | |
152 | ||
153 | Note that introducing variable declarations (as we do in @code{maxint}) can | |
154 | cause variable shadowing, so while this example using the @code{max} macro | |
155 | produces correct results: | |
156 | @smallexample | |
157 | int _a = 1, _b = 2, c; | |
158 | c = max (_a, _b); | |
159 | @end smallexample | |
160 | @noindent | |
161 | this example using maxint will not: | |
162 | @smallexample | |
163 | int _a = 1, _b = 2, c; | |
164 | c = maxint (_a, _b); | |
165 | @end smallexample | |
166 | ||
167 | This problem may for instance occur when we use this pattern recursively, like | |
168 | so: | |
169 | ||
170 | @smallexample | |
171 | #define maxint3(a, b, c) \ | |
172 | (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @}) | |
173 | @end smallexample | |
174 | ||
175 | Embedded statements are not allowed in constant expressions, such as | |
176 | the value of an enumeration constant, the width of a bit-field, or | |
177 | the initial value of a static variable. | |
178 | ||
179 | If you don't know the type of the operand, you can still do this, but you | |
180 | must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}). | |
181 | ||
182 | In G++, the result value of a statement expression undergoes array and | |
183 | function pointer decay, and is returned by value to the enclosing | |
184 | expression. For instance, if @code{A} is a class, then | |
185 | ||
186 | @smallexample | |
187 | A a; | |
188 | ||
189 | (@{a;@}).Foo () | |
190 | @end smallexample | |
191 | ||
192 | @noindent | |
193 | constructs a temporary @code{A} object to hold the result of the | |
194 | statement expression, and that is used to invoke @code{Foo}. | |
195 | Therefore the @code{this} pointer observed by @code{Foo} is not the | |
196 | address of @code{a}. | |
197 | ||
198 | In a statement expression, any temporaries created within a statement | |
199 | are destroyed at that statement's end. This makes statement | |
200 | expressions inside macros slightly different from function calls. In | |
201 | the latter case temporaries introduced during argument evaluation are | |
202 | destroyed at the end of the statement that includes the function | |
203 | call. In the statement expression case they are destroyed during | |
204 | the statement expression. For instance, | |
205 | ||
206 | @smallexample | |
207 | #define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) | |
208 | template<typename T> T function(T a) @{ T b = a; return b + 3; @} | |
209 | ||
210 | void foo () | |
211 | @{ | |
212 | macro (X ()); | |
213 | function (X ()); | |
214 | @} | |
215 | @end smallexample | |
216 | ||
217 | @noindent | |
218 | has different places where temporaries are destroyed. For the | |
219 | @code{macro} case, the temporary @code{X} is destroyed just after | |
220 | the initialization of @code{b}. In the @code{function} case that | |
221 | temporary is destroyed when the function returns. | |
222 | ||
223 | These considerations mean that it is probably a bad idea to use | |
224 | statement expressions of this form in header files that are designed to | |
225 | work with C++. (Note that some versions of the GNU C Library contained | |
226 | header files using statement expressions that lead to precisely this | |
227 | bug.) | |
228 | ||
229 | Jumping into a statement expression with @code{goto} or using a | |
230 | @code{switch} statement outside the statement expression with a | |
231 | @code{case} or @code{default} label inside the statement expression is | |
232 | not permitted. Jumping into a statement expression with a computed | |
233 | @code{goto} (@pxref{Labels as Values}) has undefined behavior. | |
234 | Jumping out of a statement expression is permitted, but if the | |
235 | statement expression is part of a larger expression then it is | |
236 | unspecified which other subexpressions of that expression have been | |
237 | evaluated except where the language definition requires certain | |
238 | subexpressions to be evaluated before or after the statement | |
239 | expression. A @code{break} or @code{continue} statement inside of | |
240 | a statement expression used in @code{while}, @code{do} or @code{for} | |
241 | loop or @code{switch} statement condition | |
242 | or @code{for} statement init or increment expressions jumps to an | |
243 | outer loop or @code{switch} statement if any (otherwise it is an error), | |
244 | rather than to the loop or @code{switch} statement in whose condition | |
245 | or init or increment expression it appears. | |
246 | In any case, as with a function call, the evaluation of a | |
247 | statement expression is not interleaved with the evaluation of other | |
248 | parts of the containing expression. For example, | |
249 | ||
250 | @smallexample | |
251 | foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); | |
252 | @end smallexample | |
253 | ||
254 | @noindent | |
255 | calls @code{foo} and @code{bar1} and does not call @code{baz} but | |
256 | may or may not call @code{bar2}. If @code{bar2} is called, it is | |
257 | called after @code{foo} and before @code{bar1}. | |
258 | ||
259 | @node Local Labels | |
260 | @section Locally Declared Labels | |
261 | @cindex local labels | |
262 | @cindex macros, local labels | |
263 | ||
264 | GCC allows you to declare @dfn{local labels} in any nested block | |
265 | scope. A local label is just like an ordinary label, but you can | |
266 | only reference it (with a @code{goto} statement, or by taking its | |
267 | address) within the block in which it is declared. | |
268 | ||
269 | A local label declaration looks like this: | |
270 | ||
271 | @smallexample | |
272 | __label__ @var{label}; | |
273 | @end smallexample | |
274 | ||
275 | @noindent | |
276 | or | |
277 | ||
278 | @smallexample | |
279 | __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; | |
280 | @end smallexample | |
281 | ||
282 | Local label declarations must come at the beginning of the block, | |
283 | before any ordinary declarations or statements. | |
284 | ||
285 | The label declaration defines the label @emph{name}, but does not define | |
286 | the label itself. You must do this in the usual way, with | |
287 | @code{@var{label}:}, within the statements of the statement expression. | |
288 | ||
289 | The local label feature is useful for complex macros. If a macro | |
290 | contains nested loops, a @code{goto} can be useful for breaking out of | |
291 | them. However, an ordinary label whose scope is the whole function | |
292 | cannot be used: if the macro can be expanded several times in one | |
293 | function, the label is multiply defined in that function. A | |
294 | local label avoids this problem. For example: | |
295 | ||
296 | @smallexample | |
297 | #define SEARCH(value, array, target) \ | |
298 | do @{ \ | |
299 | __label__ found; \ | |
300 | typeof (target) _SEARCH_target = (target); \ | |
301 | typeof (*(array)) *_SEARCH_array = (array); \ | |
302 | int i, j; \ | |
303 | int value; \ | |
304 | for (i = 0; i < max; i++) \ | |
305 | for (j = 0; j < max; j++) \ | |
306 | if (_SEARCH_array[i][j] == _SEARCH_target) \ | |
307 | @{ (value) = i; goto found; @} \ | |
308 | (value) = -1; \ | |
309 | found:; \ | |
310 | @} while (0) | |
311 | @end smallexample | |
312 | ||
313 | This could also be written using a statement expression: | |
314 | ||
315 | @smallexample | |
316 | #define SEARCH(array, target) \ | |
317 | (@{ \ | |
318 | __label__ found; \ | |
319 | typeof (target) _SEARCH_target = (target); \ | |
320 | typeof (*(array)) *_SEARCH_array = (array); \ | |
321 | int i, j; \ | |
322 | int value; \ | |
323 | for (i = 0; i < max; i++) \ | |
324 | for (j = 0; j < max; j++) \ | |
325 | if (_SEARCH_array[i][j] == _SEARCH_target) \ | |
326 | @{ value = i; goto found; @} \ | |
327 | value = -1; \ | |
328 | found: \ | |
329 | value; \ | |
330 | @}) | |
331 | @end smallexample | |
332 | ||
333 | Local label declarations also make the labels they declare visible to | |
334 | nested functions, if there are any. @xref{Nested Functions}, for details. | |
335 | ||
336 | @node Labels as Values | |
337 | @section Labels as Values | |
338 | @cindex labels as values | |
339 | @cindex computed gotos | |
340 | @cindex goto with computed label | |
341 | @cindex address of a label | |
342 | ||
343 | You can get the address of a label defined in the current function | |
344 | (or a containing function) with the unary operator @samp{&&}. The | |
345 | value has type @code{void *}. This value is a constant and can be used | |
346 | wherever a constant of that type is valid. For example: | |
347 | ||
348 | @smallexample | |
349 | void *ptr; | |
350 | /* @r{@dots{}} */ | |
351 | ptr = &&foo; | |
352 | @end smallexample | |
353 | ||
354 | To use these values, you need to be able to jump to one. This is done | |
355 | with the computed goto statement@footnote{The analogous feature in | |
356 | Fortran is called an assigned goto, but that name seems inappropriate in | |
357 | C, where one can do more than simply store label addresses in label | |
358 | variables.}, @code{goto *@var{exp};}. For example, | |
359 | ||
360 | @smallexample | |
361 | goto *ptr; | |
362 | @end smallexample | |
363 | ||
364 | @noindent | |
365 | Any expression of type @code{void *} is allowed. | |
366 | ||
367 | One way of using these constants is in initializing a static array that | |
368 | serves as a jump table: | |
369 | ||
370 | @smallexample | |
371 | static void *array[] = @{ &&foo, &&bar, &&hack @}; | |
372 | @end smallexample | |
373 | ||
374 | @noindent | |
375 | Then you can select a label with indexing, like this: | |
376 | ||
377 | @smallexample | |
378 | goto *array[i]; | |
379 | @end smallexample | |
380 | ||
381 | @noindent | |
382 | Note that this does not check whether the subscript is in bounds---array | |
383 | indexing in C never does that. | |
384 | ||
385 | Such an array of label values serves a purpose much like that of the | |
386 | @code{switch} statement. The @code{switch} statement is cleaner, so | |
387 | use that rather than an array unless the problem does not fit a | |
388 | @code{switch} statement very well. | |
389 | ||
390 | Another use of label values is in an interpreter for threaded code. | |
391 | The labels within the interpreter function can be stored in the | |
392 | threaded code for super-fast dispatching. | |
393 | ||
394 | You may not use this mechanism to jump to code in a different function. | |
395 | If you do that, totally unpredictable things happen. The best way to | |
396 | avoid this is to store the label address only in automatic variables and | |
397 | never pass it as an argument. | |
398 | ||
399 | An alternate way to write the above example is | |
400 | ||
401 | @smallexample | |
402 | static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, | |
403 | &&hack - &&foo @}; | |
404 | goto *(&&foo + array[i]); | |
405 | @end smallexample | |
406 | ||
407 | @noindent | |
408 | This is more friendly to code living in shared libraries, as it reduces | |
409 | the number of dynamic relocations that are needed, and by consequence, | |
410 | allows the data to be read-only. | |
411 | This alternative with label differences is not supported for the AVR target, | |
412 | please use the first approach for AVR programs. | |
413 | ||
414 | The @code{&&foo} expressions for the same label might have different | |
415 | values if the containing function is inlined or cloned. If a program | |
416 | relies on them being always the same, | |
417 | @code{__attribute__((__noinline__,__noclone__))} should be used to | |
418 | prevent inlining and cloning. If @code{&&foo} is used in a static | |
419 | variable initializer, inlining and cloning is forbidden. | |
420 | ||
421 | @node Nested Functions | |
422 | @section Nested Functions | |
423 | @cindex nested functions | |
424 | @cindex downward funargs | |
425 | @cindex thunks | |
426 | ||
427 | A @dfn{nested function} is a function defined inside another function. | |
428 | Nested functions are supported as an extension in GNU C, but are not | |
429 | supported by GNU C++. | |
430 | ||
431 | The nested function's name is local to the block where it is defined. | |
432 | For example, here we define a nested function named @code{square}, and | |
433 | call it twice: | |
434 | ||
435 | @smallexample | |
436 | @group | |
437 | foo (double a, double b) | |
438 | @{ | |
439 | double square (double z) @{ return z * z; @} | |
440 | ||
441 | return square (a) + square (b); | |
442 | @} | |
443 | @end group | |
444 | @end smallexample | |
445 | ||
446 | The nested function can access all the variables of the containing | |
447 | function that are visible at the point of its definition. This is | |
448 | called @dfn{lexical scoping}. For example, here we show a nested | |
449 | function which uses an inherited variable named @code{offset}: | |
450 | ||
451 | @smallexample | |
452 | @group | |
453 | bar (int *array, int offset, int size) | |
454 | @{ | |
455 | int access (int *array, int index) | |
456 | @{ return array[index + offset]; @} | |
457 | int i; | |
458 | /* @r{@dots{}} */ | |
459 | for (i = 0; i < size; i++) | |
460 | /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ | |
461 | @} | |
462 | @end group | |
463 | @end smallexample | |
464 | ||
465 | Nested function definitions are permitted within functions in the places | |
466 | where variable definitions are allowed; that is, in any block, mixed | |
467 | with the other declarations and statements in the block. | |
468 | ||
469 | It is possible to call the nested function from outside the scope of its | |
470 | name by storing its address or passing the address to another function: | |
471 | ||
472 | @smallexample | |
473 | hack (int *array, int size) | |
474 | @{ | |
475 | void store (int index, int value) | |
476 | @{ array[index] = value; @} | |
477 | ||
478 | intermediate (store, size); | |
479 | @} | |
480 | @end smallexample | |
481 | ||
482 | Here, the function @code{intermediate} receives the address of | |
483 | @code{store} as an argument. If @code{intermediate} calls @code{store}, | |
484 | the arguments given to @code{store} are used to store into @code{array}. | |
485 | But this technique works only so long as the containing function | |
486 | (@code{hack}, in this example) does not exit. | |
487 | ||
488 | If you try to call the nested function through its address after the | |
489 | containing function exits, all hell breaks loose. If you try | |
490 | to call it after a containing scope level exits, and if it refers | |
491 | to some of the variables that are no longer in scope, you may be lucky, | |
492 | but it's not wise to take the risk. If, however, the nested function | |
493 | does not refer to anything that has gone out of scope, you should be | |
494 | safe. | |
495 | ||
496 | GCC implements taking the address of a nested function using a technique | |
497 | called @dfn{trampolines}. This technique was described in | |
498 | @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX | |
499 | C++ Conference Proceedings, October 17-21, 1988). | |
500 | ||
501 | A nested function can jump to a label inherited from a containing | |
502 | function, provided the label is explicitly declared in the containing | |
503 | function (@pxref{Local Labels}). Such a jump returns instantly to the | |
504 | containing function, exiting the nested function that did the | |
505 | @code{goto} and any intermediate functions as well. Here is an example: | |
506 | ||
507 | @smallexample | |
508 | @group | |
509 | bar (int *array, int offset, int size) | |
510 | @{ | |
511 | __label__ failure; | |
512 | int access (int *array, int index) | |
513 | @{ | |
514 | if (index > size) | |
515 | goto failure; | |
516 | return array[index + offset]; | |
517 | @} | |
518 | int i; | |
519 | /* @r{@dots{}} */ | |
520 | for (i = 0; i < size; i++) | |
521 | /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ | |
522 | /* @r{@dots{}} */ | |
523 | return 0; | |
524 | ||
525 | /* @r{Control comes here from @code{access} | |
526 | if it detects an error.} */ | |
527 | failure: | |
528 | return -1; | |
529 | @} | |
530 | @end group | |
531 | @end smallexample | |
532 | ||
533 | A nested function always has no linkage. Declaring one with | |
534 | @code{extern} or @code{static} is erroneous. If you need to declare the nested function | |
535 | before its definition, use @code{auto} (which is otherwise meaningless | |
536 | for function declarations). | |
537 | ||
538 | @smallexample | |
539 | bar (int *array, int offset, int size) | |
540 | @{ | |
541 | __label__ failure; | |
542 | auto int access (int *, int); | |
543 | /* @r{@dots{}} */ | |
544 | int access (int *array, int index) | |
545 | @{ | |
546 | if (index > size) | |
547 | goto failure; | |
548 | return array[index + offset]; | |
549 | @} | |
550 | /* @r{@dots{}} */ | |
551 | @} | |
552 | @end smallexample | |
553 | ||
554 | @node Nonlocal Gotos | |
555 | @section Nonlocal Gotos | |
556 | @cindex nonlocal gotos | |
557 | ||
558 | GCC provides the built-in functions @code{__builtin_setjmp} and | |
559 | @code{__builtin_longjmp} which are similar to, but not interchangeable | |
560 | with, the C library functions @code{setjmp} and @code{longjmp}. | |
561 | The built-in versions are used internally by GCC's libraries | |
562 | to implement exception handling on some targets. You should use the | |
563 | standard C library functions declared in @code{<setjmp.h>} in user code | |
564 | instead of the builtins. | |
565 | ||
566 | The built-in versions of these functions use GCC's normal | |
567 | mechanisms to save and restore registers using the stack on function | |
568 | entry and exit. The jump buffer argument @var{buf} holds only the | |
569 | information needed to restore the stack frame, rather than the entire | |
570 | set of saved register values. | |
571 | ||
572 | An important caveat is that GCC arranges to save and restore only | |
573 | those registers known to the specific architecture variant being | |
574 | compiled for. This can make @code{__builtin_setjmp} and | |
575 | @code{__builtin_longjmp} more efficient than their library | |
576 | counterparts in some cases, but it can also cause incorrect and | |
577 | mysterious behavior when mixing with code that uses the full register | |
578 | set. | |
579 | ||
580 | You should declare the jump buffer argument @var{buf} to the | |
581 | built-in functions as: | |
582 | ||
583 | @smallexample | |
584 | #include <stdint.h> | |
585 | intptr_t @var{buf}[5]; | |
586 | @end smallexample | |
587 | ||
f25efe50 | 588 | @defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})} |
d77de738 ML |
589 | This function saves the current stack context in @var{buf}. |
590 | @code{__builtin_setjmp} returns 0 when returning directly, | |
591 | and 1 when returning from @code{__builtin_longjmp} using the same | |
592 | @var{buf}. | |
f25efe50 | 593 | @enddefbuiltin |
d77de738 | 594 | |
f25efe50 | 595 | @defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})} |
d77de738 ML |
596 | This function restores the stack context in @var{buf}, |
597 | saved by a previous call to @code{__builtin_setjmp}. After | |
598 | @code{__builtin_longjmp} is finished, the program resumes execution as | |
599 | if the matching @code{__builtin_setjmp} returns the value @var{val}, | |
600 | which must be 1. | |
601 | ||
602 | Because @code{__builtin_longjmp} depends on the function return | |
603 | mechanism to restore the stack context, it cannot be called | |
604 | from the same function calling @code{__builtin_setjmp} to | |
605 | initialize @var{buf}. It can only be called from a function called | |
606 | (directly or indirectly) from the function calling @code{__builtin_setjmp}. | |
f25efe50 | 607 | @enddefbuiltin |
d77de738 ML |
608 | |
609 | @node Constructing Calls | |
610 | @section Constructing Function Calls | |
611 | @cindex constructing calls | |
612 | @cindex forwarding calls | |
613 | ||
614 | Using the built-in functions described below, you can record | |
615 | the arguments a function received, and call another function | |
616 | with the same arguments, without knowing the number or types | |
617 | of the arguments. | |
618 | ||
619 | You can also record the return value of that function call, | |
620 | and later return that value, without knowing what data type | |
621 | the function tried to return (as long as your caller expects | |
622 | that data type). | |
623 | ||
624 | However, these built-in functions may interact badly with some | |
625 | sophisticated features or other extensions of the language. It | |
626 | is, therefore, not recommended to use them outside very simple | |
627 | functions acting as mere forwarders for their arguments. | |
628 | ||
f25efe50 | 629 | @defbuiltin{{void *} __builtin_apply_args ()} |
d77de738 ML |
630 | This built-in function returns a pointer to data |
631 | describing how to perform a call with the same arguments as are passed | |
632 | to the current function. | |
633 | ||
634 | The function saves the arg pointer register, structure value address, | |
635 | and all registers that might be used to pass arguments to a function | |
636 | into a block of memory allocated on the stack. Then it returns the | |
637 | address of that block. | |
f25efe50 | 638 | @enddefbuiltin |
d77de738 | 639 | |
f25efe50 | 640 | @defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})} |
d77de738 ML |
641 | This built-in function invokes @var{function} |
642 | with a copy of the parameters described by @var{arguments} | |
643 | and @var{size}. | |
644 | ||
645 | The value of @var{arguments} should be the value returned by | |
646 | @code{__builtin_apply_args}. The argument @var{size} specifies the size | |
647 | of the stack argument data, in bytes. | |
648 | ||
649 | This function returns a pointer to data describing | |
650 | how to return whatever value is returned by @var{function}. The data | |
651 | is saved in a block of memory allocated on the stack. | |
652 | ||
653 | It is not always simple to compute the proper value for @var{size}. The | |
654 | value is used by @code{__builtin_apply} to compute the amount of data | |
655 | that should be pushed on the stack and copied from the incoming argument | |
656 | area. | |
f25efe50 | 657 | @enddefbuiltin |
d77de738 | 658 | |
f25efe50 | 659 | @defbuiltin{{void} __builtin_return (void *@var{result})} |
d77de738 ML |
660 | This built-in function returns the value described by @var{result} from |
661 | the containing function. You should specify, for @var{result}, a value | |
662 | returned by @code{__builtin_apply}. | |
f25efe50 | 663 | @enddefbuiltin |
d77de738 | 664 | |
f25efe50 | 665 | @defbuiltin{{} __builtin_va_arg_pack ()} |
d77de738 ML |
666 | This built-in function represents all anonymous arguments of an inline |
667 | function. It can be used only in inline functions that are always | |
668 | inlined, never compiled as a separate function, such as those using | |
669 | @code{__attribute__ ((__always_inline__))} or | |
670 | @code{__attribute__ ((__gnu_inline__))} extern inline functions. | |
671 | It must be only passed as last argument to some other function | |
672 | with variable arguments. This is useful for writing small wrapper | |
673 | inlines for variable argument functions, when using preprocessor | |
674 | macros is undesirable. For example: | |
675 | @smallexample | |
676 | extern int myprintf (FILE *f, const char *format, ...); | |
677 | extern inline __attribute__ ((__gnu_inline__)) int | |
678 | myprintf (FILE *f, const char *format, ...) | |
679 | @{ | |
680 | int r = fprintf (f, "myprintf: "); | |
681 | if (r < 0) | |
682 | return r; | |
683 | int s = fprintf (f, format, __builtin_va_arg_pack ()); | |
684 | if (s < 0) | |
685 | return s; | |
686 | return r + s; | |
687 | @} | |
688 | @end smallexample | |
f25efe50 | 689 | @enddefbuiltin |
d77de738 | 690 | |
f25efe50 | 691 | @defbuiltin{int __builtin_va_arg_pack_len ()} |
d77de738 ML |
692 | This built-in function returns the number of anonymous arguments of |
693 | an inline function. It can be used only in inline functions that | |
694 | are always inlined, never compiled as a separate function, such | |
695 | as those using @code{__attribute__ ((__always_inline__))} or | |
696 | @code{__attribute__ ((__gnu_inline__))} extern inline functions. | |
697 | For example following does link- or run-time checking of open | |
698 | arguments for optimized code: | |
699 | @smallexample | |
700 | #ifdef __OPTIMIZE__ | |
701 | extern inline __attribute__((__gnu_inline__)) int | |
702 | myopen (const char *path, int oflag, ...) | |
703 | @{ | |
704 | if (__builtin_va_arg_pack_len () > 1) | |
705 | warn_open_too_many_arguments (); | |
706 | ||
707 | if (__builtin_constant_p (oflag)) | |
708 | @{ | |
709 | if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) | |
710 | @{ | |
711 | warn_open_missing_mode (); | |
712 | return __open_2 (path, oflag); | |
713 | @} | |
714 | return open (path, oflag, __builtin_va_arg_pack ()); | |
715 | @} | |
716 | ||
717 | if (__builtin_va_arg_pack_len () < 1) | |
718 | return __open_2 (path, oflag); | |
719 | ||
720 | return open (path, oflag, __builtin_va_arg_pack ()); | |
721 | @} | |
722 | #endif | |
723 | @end smallexample | |
f25efe50 | 724 | @enddefbuiltin |
d77de738 ML |
725 | |
726 | @node Typeof | |
727 | @section Referring to a Type with @code{typeof} | |
728 | @findex typeof | |
729 | @findex sizeof | |
730 | @cindex macros, types of arguments | |
731 | ||
732 | Another way to refer to the type of an expression is with @code{typeof}. | |
733 | The syntax of using of this keyword looks like @code{sizeof}, but the | |
734 | construct acts semantically like a type name defined with @code{typedef}. | |
735 | ||
736 | There are two ways of writing the argument to @code{typeof}: with an | |
737 | expression or with a type. Here is an example with an expression: | |
738 | ||
739 | @smallexample | |
740 | typeof (x[0](1)) | |
741 | @end smallexample | |
742 | ||
743 | @noindent | |
744 | This assumes that @code{x} is an array of pointers to functions; | |
745 | the type described is that of the values of the functions. | |
746 | ||
747 | Here is an example with a typename as the argument: | |
748 | ||
749 | @smallexample | |
750 | typeof (int *) | |
751 | @end smallexample | |
752 | ||
753 | @noindent | |
754 | Here the type described is that of pointers to @code{int}. | |
755 | ||
756 | If you are writing a header file that must work when included in ISO C | |
757 | programs, write @code{__typeof__} instead of @code{typeof}. | |
758 | @xref{Alternate Keywords}. | |
759 | ||
760 | A @code{typeof} construct can be used anywhere a typedef name can be | |
761 | used. For example, you can use it in a declaration, in a cast, or inside | |
762 | of @code{sizeof} or @code{typeof}. | |
763 | ||
764 | The operand of @code{typeof} is evaluated for its side effects if and | |
765 | only if it is an expression of variably modified type or the name of | |
766 | such a type. | |
767 | ||
768 | @code{typeof} is often useful in conjunction with | |
769 | statement expressions (@pxref{Statement Exprs}). | |
770 | Here is how the two together can | |
771 | be used to define a safe ``maximum'' macro which operates on any | |
772 | arithmetic type and evaluates each of its arguments exactly once: | |
773 | ||
774 | @smallexample | |
775 | #define max(a,b) \ | |
776 | (@{ typeof (a) _a = (a); \ | |
777 | typeof (b) _b = (b); \ | |
778 | _a > _b ? _a : _b; @}) | |
779 | @end smallexample | |
780 | ||
781 | @cindex underscores in variables in macros | |
782 | @cindex @samp{_} in variables in macros | |
783 | @cindex local variables in macros | |
784 | @cindex variables, local, in macros | |
785 | @cindex macros, local variables in | |
786 | ||
787 | The reason for using names that start with underscores for the local | |
788 | variables is to avoid conflicts with variable names that occur within the | |
789 | expressions that are substituted for @code{a} and @code{b}. Eventually we | |
790 | hope to design a new form of declaration syntax that allows you to declare | |
791 | variables whose scopes start only after their initializers; this will be a | |
792 | more reliable way to prevent such conflicts. | |
793 | ||
794 | @noindent | |
795 | Some more examples of the use of @code{typeof}: | |
796 | ||
797 | @itemize @bullet | |
798 | @item | |
799 | This declares @code{y} with the type of what @code{x} points to. | |
800 | ||
801 | @smallexample | |
802 | typeof (*x) y; | |
803 | @end smallexample | |
804 | ||
805 | @item | |
806 | This declares @code{y} as an array of such values. | |
807 | ||
808 | @smallexample | |
809 | typeof (*x) y[4]; | |
810 | @end smallexample | |
811 | ||
812 | @item | |
813 | This declares @code{y} as an array of pointers to characters: | |
814 | ||
815 | @smallexample | |
816 | typeof (typeof (char *)[4]) y; | |
817 | @end smallexample | |
818 | ||
819 | @noindent | |
820 | It is equivalent to the following traditional C declaration: | |
821 | ||
822 | @smallexample | |
823 | char *y[4]; | |
824 | @end smallexample | |
825 | ||
826 | To see the meaning of the declaration using @code{typeof}, and why it | |
827 | might be a useful way to write, rewrite it with these macros: | |
828 | ||
829 | @smallexample | |
830 | #define pointer(T) typeof(T *) | |
831 | #define array(T, N) typeof(T [N]) | |
832 | @end smallexample | |
833 | ||
834 | @noindent | |
835 | Now the declaration can be rewritten this way: | |
836 | ||
837 | @smallexample | |
838 | array (pointer (char), 4) y; | |
839 | @end smallexample | |
840 | ||
841 | @noindent | |
842 | Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 | |
843 | pointers to @code{char}. | |
844 | @end itemize | |
845 | ||
846 | In GNU C, but not GNU C++, you may also declare the type of a variable | |
847 | as @code{__auto_type}. In that case, the declaration must declare | |
848 | only one variable, whose declarator must just be an identifier, the | |
849 | declaration must be initialized, and the type of the variable is | |
850 | determined by the initializer; the name of the variable is not in | |
851 | scope until after the initializer. (In C++, you should use C++11 | |
852 | @code{auto} for this purpose.) Using @code{__auto_type}, the | |
853 | ``maximum'' macro above could be written as: | |
854 | ||
855 | @smallexample | |
856 | #define max(a,b) \ | |
857 | (@{ __auto_type _a = (a); \ | |
858 | __auto_type _b = (b); \ | |
859 | _a > _b ? _a : _b; @}) | |
860 | @end smallexample | |
861 | ||
862 | Using @code{__auto_type} instead of @code{typeof} has two advantages: | |
863 | ||
864 | @itemize @bullet | |
865 | @item Each argument to the macro appears only once in the expansion of | |
866 | the macro. This prevents the size of the macro expansion growing | |
867 | exponentially when calls to such macros are nested inside arguments of | |
868 | such macros. | |
869 | ||
870 | @item If the argument to the macro has variably modified type, it is | |
871 | evaluated only once when using @code{__auto_type}, but twice if | |
872 | @code{typeof} is used. | |
873 | @end itemize | |
874 | ||
875 | @node Conditionals | |
876 | @section Conditionals with Omitted Operands | |
877 | @cindex conditional expressions, extensions | |
878 | @cindex omitted middle-operands | |
879 | @cindex middle-operands, omitted | |
880 | @cindex extensions, @code{?:} | |
881 | @cindex @code{?:} extensions | |
882 | ||
883 | The middle operand in a conditional expression may be omitted. Then | |
884 | if the first operand is nonzero, its value is the value of the conditional | |
885 | expression. | |
886 | ||
887 | Therefore, the expression | |
888 | ||
889 | @smallexample | |
890 | x ? : y | |
891 | @end smallexample | |
892 | ||
893 | @noindent | |
894 | has the value of @code{x} if that is nonzero; otherwise, the value of | |
895 | @code{y}. | |
896 | ||
897 | This example is perfectly equivalent to | |
898 | ||
899 | @smallexample | |
900 | x ? x : y | |
901 | @end smallexample | |
902 | ||
903 | @cindex side effect in @code{?:} | |
904 | @cindex @code{?:} side effect | |
905 | @noindent | |
906 | In this simple case, the ability to omit the middle operand is not | |
907 | especially useful. When it becomes useful is when the first operand does, | |
908 | or may (if it is a macro argument), contain a side effect. Then repeating | |
909 | the operand in the middle would perform the side effect twice. Omitting | |
910 | the middle operand uses the value already computed without the undesirable | |
911 | effects of recomputing it. | |
912 | ||
913 | @node __int128 | |
914 | @section 128-bit Integers | |
915 | @cindex @code{__int128} data types | |
916 | ||
917 | As an extension the integer scalar type @code{__int128} is supported for | |
918 | targets which have an integer mode wide enough to hold 128 bits. | |
919 | Simply write @code{__int128} for a signed 128-bit integer, or | |
920 | @code{unsigned __int128} for an unsigned 128-bit integer. There is no | |
921 | support in GCC for expressing an integer constant of type @code{__int128} | |
922 | for targets with @code{long long} integer less than 128 bits wide. | |
923 | ||
924 | @node Long Long | |
925 | @section Double-Word Integers | |
926 | @cindex @code{long long} data types | |
927 | @cindex double-word arithmetic | |
928 | @cindex multiprecision arithmetic | |
929 | @cindex @code{LL} integer suffix | |
930 | @cindex @code{ULL} integer suffix | |
931 | ||
932 | ISO C99 and ISO C++11 support data types for integers that are at least | |
933 | 64 bits wide, and as an extension GCC supports them in C90 and C++98 modes. | |
934 | Simply write @code{long long int} for a signed integer, or | |
935 | @code{unsigned long long int} for an unsigned integer. To make an | |
936 | integer constant of type @code{long long int}, add the suffix @samp{LL} | |
937 | to the integer. To make an integer constant of type @code{unsigned long | |
938 | long int}, add the suffix @samp{ULL} to the integer. | |
939 | ||
940 | You can use these types in arithmetic like any other integer types. | |
941 | Addition, subtraction, and bitwise boolean operations on these types | |
942 | are open-coded on all types of machines. Multiplication is open-coded | |
943 | if the machine supports a fullword-to-doubleword widening multiply | |
944 | instruction. Division and shifts are open-coded only on machines that | |
945 | provide special support. The operations that are not open-coded use | |
946 | special library routines that come with GCC@. | |
947 | ||
948 | There may be pitfalls when you use @code{long long} types for function | |
949 | arguments without function prototypes. If a function | |
950 | expects type @code{int} for its argument, and you pass a value of type | |
951 | @code{long long int}, confusion results because the caller and the | |
952 | subroutine disagree about the number of bytes for the argument. | |
953 | Likewise, if the function expects @code{long long int} and you pass | |
954 | @code{int}. The best way to avoid such problems is to use prototypes. | |
955 | ||
956 | @node Complex | |
957 | @section Complex Numbers | |
958 | @cindex complex numbers | |
959 | @cindex @code{_Complex} keyword | |
960 | @cindex @code{__complex__} keyword | |
961 | ||
962 | ISO C99 supports complex floating data types, and as an extension GCC | |
963 | supports them in C90 mode and in C++. GCC also supports complex integer data | |
964 | types which are not part of ISO C99. You can declare complex types | |
965 | using the keyword @code{_Complex}. As an extension, the older GNU | |
966 | keyword @code{__complex__} is also supported. | |
967 | ||
968 | For example, @samp{_Complex double x;} declares @code{x} as a | |
969 | variable whose real part and imaginary part are both of type | |
970 | @code{double}. @samp{_Complex short int y;} declares @code{y} to | |
971 | have real and imaginary parts of type @code{short int}; this is not | |
972 | likely to be useful, but it shows that the set of complex types is | |
973 | complete. | |
974 | ||
975 | To write a constant with a complex data type, use the suffix @samp{i} or | |
976 | @samp{j} (either one; they are equivalent). For example, @code{2.5fi} | |
977 | has type @code{_Complex float} and @code{3i} has type | |
978 | @code{_Complex int}. Such a constant always has a pure imaginary | |
979 | value, but you can form any complex value you like by adding one to a | |
980 | real constant. This is a GNU extension; if you have an ISO C99 | |
981 | conforming C library (such as the GNU C Library), and want to construct complex | |
982 | constants of floating type, you should include @code{<complex.h>} and | |
983 | use the macros @code{I} or @code{_Complex_I} instead. | |
984 | ||
985 | The ISO C++14 library also defines the @samp{i} suffix, so C++14 code | |
986 | that includes the @samp{<complex>} header cannot use @samp{i} for the | |
987 | GNU extension. The @samp{j} suffix still has the GNU meaning. | |
988 | ||
989 | GCC can handle both implicit and explicit casts between the @code{_Complex} | |
990 | types and other @code{_Complex} types as casting both the real and imaginary | |
991 | parts to the scalar type. | |
992 | GCC can handle implicit and explicit casts from a scalar type to a @code{_Complex} | |
993 | type and where the imaginary part will be considered zero. | |
994 | The C front-end can handle implicit and explicit casts from a @code{_Complex} type | |
995 | to a scalar type where the imaginary part will be ignored. In C++ code, this cast | |
996 | is considered illformed and G++ will error out. | |
997 | ||
998 | GCC provides a built-in function @code{__builtin_complex} will can be used to | |
999 | construct a complex value. | |
1000 | ||
1001 | @cindex @code{__real__} keyword | |
1002 | @cindex @code{__imag__} keyword | |
1003 | ||
1004 | GCC has a few extensions which can be used to extract the real | |
1005 | and the imaginary part of the complex-valued expression. Note | |
1006 | these expressions are lvalues if the @var{exp} is an lvalue. | |
1007 | These expressions operands have the type of a complex type | |
1008 | which might get prompoted to a complex type from a scalar type. | |
1009 | E.g. @code{__real__ (int)@var{x}} is the same as casting to | |
1010 | @code{_Complex int} before @code{__real__} is done. | |
1011 | ||
1012 | @multitable @columnfractions .4 .6 | |
1013 | @headitem Expression @tab Description | |
1014 | @item @code{__real__ @var{exp}} | |
1015 | @tab Extract the real part of @var{exp}. | |
1016 | @item @code{__imag__ @var{exp}} | |
1017 | @tab Extract the imaginary part of @var{exp}. | |
1018 | @end multitable | |
1019 | ||
1020 | For values of floating point, you should use the ISO C99 | |
1021 | functions, declared in @code{<complex.h>} and also provided as | |
1022 | built-in functions by GCC@. | |
1023 | ||
1024 | @multitable @columnfractions .4 .2 .2 .2 | |
1025 | @headitem Expression @tab float @tab double @tab long double | |
1026 | @item @code{__real__ @var{exp}} | |
1027 | @tab @code{crealf} @tab @code{creal} @tab @code{creall} | |
1028 | @item @code{__imag__ @var{exp}} | |
1029 | @tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl} | |
1030 | @end multitable | |
1031 | ||
1032 | @cindex complex conjugation | |
1033 | The operator @samp{~} performs complex conjugation when used on a value | |
1034 | with a complex type. This is a GNU extension; for values of | |
1035 | floating type, you should use the ISO C99 functions @code{conjf}, | |
1036 | @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also | |
1037 | provided as built-in functions by GCC@. Note unlike the @code{__real__} | |
1038 | and @code{__imag__} operators, this operator will not do an implicit cast | |
1039 | to the complex type because the @samp{~} is already a normal operator. | |
1040 | ||
1041 | GCC can allocate complex automatic variables in a noncontiguous | |
1042 | fashion; it's even possible for the real part to be in a register while | |
1043 | the imaginary part is on the stack (or vice versa). Only the DWARF | |
1044 | debug info format can represent this, so use of DWARF is recommended. | |
1045 | If you are using the stabs debug info format, GCC describes a noncontiguous | |
1046 | complex variable as if it were two separate variables of noncomplex type. | |
1047 | If the variable's actual name is @code{foo}, the two fictitious | |
1048 | variables are named @code{foo$real} and @code{foo$imag}. You can | |
1049 | examine and set these two fictitious variables with your debugger. | |
1050 | ||
f25efe50 | 1051 | @defbuiltin{@var{type} __builtin_complex (@var{real}, @var{imag})} |
d77de738 ML |
1052 | |
1053 | The built-in function @code{__builtin_complex} is provided for use in | |
1054 | implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and | |
1055 | @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a | |
1056 | real binary floating-point type, and the result has the corresponding | |
1057 | complex type with real and imaginary parts @var{real} and @var{imag}. | |
1058 | Unlike @samp{@var{real} + I * @var{imag}}, this works even when | |
1059 | infinities, NaNs and negative zeros are involved. | |
1060 | ||
f25efe50 | 1061 | @enddefbuiltin |
d77de738 ML |
1062 | |
1063 | @node Floating Types | |
1064 | @section Additional Floating Types | |
1065 | @cindex additional floating types | |
1066 | @cindex @code{_Float@var{n}} data types | |
1067 | @cindex @code{_Float@var{n}x} data types | |
1068 | @cindex @code{__float80} data type | |
1069 | @cindex @code{__float128} data type | |
1070 | @cindex @code{__ibm128} data type | |
1071 | @cindex @code{w} floating point suffix | |
1072 | @cindex @code{q} floating point suffix | |
1073 | @cindex @code{W} floating point suffix | |
1074 | @cindex @code{Q} floating point suffix | |
1075 | ||
1076 | ISO/IEC TS 18661-3:2015 defines C support for additional floating | |
1077 | types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports | |
1078 | these type names; the set of types supported depends on the target | |
1079 | architecture. These types are not supported when compiling C++. | |
1080 | Constants with these types use suffixes @code{f@var{n}} or | |
1081 | @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type | |
1082 | names can be used together with @code{_Complex} to declare complex | |
1083 | types. | |
1084 | ||
1085 | As an extension, GNU C and GNU C++ support additional floating | |
1086 | types, which are not supported by all targets. | |
1087 | @itemize @bullet | |
1088 | @item @code{__float128} is available on i386, x86_64, IA-64, and | |
1089 | hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable | |
1090 | the vector scalar (VSX) instruction set. @code{__float128} supports | |
1091 | the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64 | |
1092 | other than HP-UX, @code{__float128} is an alias for @code{_Float128}. | |
1093 | On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long | |
1094 | double}. | |
1095 | ||
1096 | @item @code{__float80} is available on the i386, x86_64, and IA-64 | |
1097 | targets, and supports the 80-bit (@code{XFmode}) floating type. It is | |
1098 | an alias for the type name @code{_Float64x} on these targets. | |
1099 | ||
1100 | @item @code{__ibm128} is available on PowerPC targets, and provides | |
1101 | access to the IBM extended double format which is the current format | |
1102 | used for @code{long double}. When @code{long double} transitions to | |
1103 | @code{__float128} on PowerPC in the future, @code{__ibm128} will remain | |
1104 | for use in conversions between the two types. | |
1105 | @end itemize | |
1106 | ||
1107 | Support for these additional types includes the arithmetic operators: | |
1108 | add, subtract, multiply, divide; unary arithmetic operators; | |
1109 | relational operators; equality operators; and conversions to and from | |
1110 | integer and other floating types. Use a suffix @samp{w} or @samp{W} | |
1111 | in a literal constant of type @code{__float80} or type | |
1112 | @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{__float128}. | |
1113 | ||
1114 | In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128} | |
1115 | on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is | |
1116 | expected in future versions of GCC that @code{_Float128} and @code{__float128} | |
1117 | will be enabled automatically. | |
1118 | ||
1119 | The @code{_Float128} type is supported on all systems where | |
1120 | @code{__float128} is supported or where @code{long double} has the | |
1121 | IEEE binary128 format. The @code{_Float64x} type is supported on all | |
1122 | systems where @code{__float128} is supported. The @code{_Float32} | |
1123 | type is supported on all systems supporting IEEE binary32; the | |
1124 | @code{_Float64} and @code{_Float32x} types are supported on all systems | |
1125 | supporting IEEE binary64. The @code{_Float16} type is supported on AArch64 | |
1126 | systems by default, on ARM systems when the IEEE format for 16-bit | |
1127 | floating-point types is selected with @option{-mfp16-format=ieee} and, | |
1128 | for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently | |
1129 | support @code{_Float128x} on any systems. | |
1130 | ||
1131 | On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex | |
1132 | types using the corresponding internal complex type, @code{XCmode} for | |
1133 | @code{__float80} type and @code{TCmode} for @code{__float128} type: | |
1134 | ||
1135 | @smallexample | |
1136 | typedef _Complex float __attribute__((mode(TC))) _Complex128; | |
1137 | typedef _Complex float __attribute__((mode(XC))) _Complex80; | |
1138 | @end smallexample | |
1139 | ||
1140 | On the PowerPC Linux VSX targets, you can declare complex types using | |
1141 | the corresponding internal complex type, @code{KCmode} for | |
1142 | @code{__float128} type and @code{ICmode} for @code{__ibm128} type: | |
1143 | ||
1144 | @smallexample | |
1145 | typedef _Complex float __attribute__((mode(KC))) _Complex_float128; | |
1146 | typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128; | |
1147 | @end smallexample | |
1148 | ||
1149 | @node Half-Precision | |
1150 | @section Half-Precision Floating Point | |
1151 | @cindex half-precision floating point | |
1152 | @cindex @code{__fp16} data type | |
1153 | @cindex @code{__Float16} data type | |
1154 | ||
1155 | On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating | |
1156 | point via the @code{__fp16} type defined in the ARM C Language Extensions. | |
1157 | On ARM systems, you must enable this type explicitly with the | |
1158 | @option{-mfp16-format} command-line option in order to use it. | |
1159 | On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit) | |
1160 | floating point via the @code{_Float16} type. For C++, x86 provides a builtin | |
1161 | type named @code{_Float16} which contains same data format as C. | |
1162 | ||
1163 | ARM targets support two incompatible representations for half-precision | |
1164 | floating-point values. You must choose one of the representations and | |
1165 | use it consistently in your program. | |
1166 | ||
1167 | Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. | |
1168 | This format can represent normalized values in the range of @math{2^{-14}} to 65504. | |
1169 | There are 11 bits of significand precision, approximately 3 | |
1170 | decimal digits. | |
1171 | ||
1172 | Specifying @option{-mfp16-format=alternative} selects the ARM | |
1173 | alternative format. This representation is similar to the IEEE | |
1174 | format, but does not support infinities or NaNs. Instead, the range | |
1175 | of exponents is extended, so that this format can represent normalized | |
1176 | values in the range of @math{2^{-14}} to 131008. | |
1177 | ||
1178 | The GCC port for AArch64 only supports the IEEE 754-2008 format, and does | |
1179 | not require use of the @option{-mfp16-format} command-line option. | |
1180 | ||
1181 | The @code{__fp16} type may only be used as an argument to intrinsics defined | |
1182 | in @code{<arm_fp16.h>}, or as a storage format. For purposes of | |
1183 | arithmetic and other operations, @code{__fp16} values in C or C++ | |
1184 | expressions are automatically promoted to @code{float}. | |
1185 | ||
1186 | The ARM target provides hardware support for conversions between | |
1187 | @code{__fp16} and @code{float} values | |
1188 | as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides | |
1189 | hardware support for conversions between @code{__fp16} and @code{double} | |
1190 | values. GCC generates code using these hardware instructions if you | |
1191 | compile with options to select an FPU that provides them; | |
1192 | for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, | |
1193 | in addition to the @option{-mfp16-format} option to select | |
1194 | a half-precision format. | |
1195 | ||
1196 | Language-level support for the @code{__fp16} data type is | |
1197 | independent of whether GCC generates code using hardware floating-point | |
1198 | instructions. In cases where hardware support is not specified, GCC | |
1199 | implements conversions between @code{__fp16} and other types as library | |
1200 | calls. | |
1201 | ||
1202 | It is recommended that portable code use the @code{_Float16} type defined | |
1203 | by ISO/IEC TS 18661-3:2015. @xref{Floating Types}. | |
1204 | ||
1205 | On x86 targets with SSE2 enabled, without @option{-mavx512fp16}, | |
1206 | all operations will be emulated by software emulation and the @code{float} | |
1207 | instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the | |
1208 | intermediate result of the operation as 32-bit precision. This may lead to | |
1209 | inconsistent behavior between software emulation and AVX512-FP16 instructions. | |
1210 | Using @option{-fexcess-precision=16} will force round back after each operation. | |
1211 | ||
1212 | Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of | |
1213 | software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round | |
1214 | after each operation. The same is true with @option{-fexcess-precision=standard} | |
1215 | and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse}, | |
1216 | @option{-fexcess-precision=standard} alone does the same thing as before, | |
1217 | It is useful for code that does not have @code{_Float16} and runs on the x87 | |
1218 | FPU. | |
1219 | ||
1220 | @node Decimal Float | |
1221 | @section Decimal Floating Types | |
1222 | @cindex decimal floating types | |
1223 | @cindex @code{_Decimal32} data type | |
1224 | @cindex @code{_Decimal64} data type | |
1225 | @cindex @code{_Decimal128} data type | |
1226 | @cindex @code{df} integer suffix | |
1227 | @cindex @code{dd} integer suffix | |
1228 | @cindex @code{dl} integer suffix | |
1229 | @cindex @code{DF} integer suffix | |
1230 | @cindex @code{DD} integer suffix | |
1231 | @cindex @code{DL} integer suffix | |
1232 | ||
1233 | As an extension, GNU C supports decimal floating types as | |
1234 | defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal | |
1235 | floating types in GCC will evolve as the draft technical report changes. | |
1236 | Calling conventions for any target might also change. Not all targets | |
1237 | support decimal floating types. | |
1238 | ||
1239 | The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and | |
1240 | @code{_Decimal128}. They use a radix of ten, unlike the floating types | |
1241 | @code{float}, @code{double}, and @code{long double} whose radix is not | |
1242 | specified by the C standard but is usually two. | |
1243 | ||
1244 | Support for decimal floating types includes the arithmetic operators | |
1245 | add, subtract, multiply, divide; unary arithmetic operators; | |
1246 | relational operators; equality operators; and conversions to and from | |
1247 | integer and other floating types. Use a suffix @samp{df} or | |
1248 | @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} | |
1249 | or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for | |
1250 | @code{_Decimal128}. | |
1251 | ||
1252 | GCC support of decimal float as specified by the draft technical report | |
1253 | is incomplete: | |
1254 | ||
1255 | @itemize @bullet | |
1256 | @item | |
1257 | When the value of a decimal floating type cannot be represented in the | |
1258 | integer type to which it is being converted, the result is undefined | |
1259 | rather than the result value specified by the draft technical report. | |
1260 | ||
1261 | @item | |
1262 | GCC does not provide the C library functionality associated with | |
1263 | @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and | |
1264 | @file{wchar.h}, which must come from a separate C library implementation. | |
1265 | Because of this the GNU C compiler does not define macro | |
1266 | @code{__STDC_DEC_FP__} to indicate that the implementation conforms to | |
1267 | the technical report. | |
1268 | @end itemize | |
1269 | ||
1270 | Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} | |
1271 | are supported by the DWARF debug information format. | |
1272 | ||
1273 | @node Hex Floats | |
1274 | @section Hex Floats | |
1275 | @cindex hex floats | |
1276 | ||
1277 | ISO C99 and ISO C++17 support floating-point numbers written not only in | |
1278 | the usual decimal notation, such as @code{1.55e1}, but also numbers such as | |
1279 | @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC | |
1280 | supports this in C90 mode (except in some cases when strictly | |
1281 | conforming) and in C++98, C++11 and C++14 modes. In that format the | |
1282 | @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are | |
1283 | mandatory. The exponent is a decimal number that indicates the power of | |
1284 | 2 by which the significant part is multiplied. Thus @samp{0x1.f} is | |
1285 | @tex | |
1286 | $1 {15\over16}$, | |
1287 | @end tex | |
1288 | @ifnottex | |
1289 | 1 15/16, | |
1290 | @end ifnottex | |
1291 | @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} | |
1292 | is the same as @code{1.55e1}. | |
1293 | ||
1294 | Unlike for floating-point numbers in the decimal notation the exponent | |
1295 | is always required in the hexadecimal notation. Otherwise the compiler | |
1296 | would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This | |
1297 | could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the | |
1298 | extension for floating-point constants of type @code{float}. | |
1299 | ||
1300 | @node Fixed-Point | |
1301 | @section Fixed-Point Types | |
1302 | @cindex fixed-point types | |
1303 | @cindex @code{_Fract} data type | |
1304 | @cindex @code{_Accum} data type | |
1305 | @cindex @code{_Sat} data type | |
1306 | @cindex @code{hr} fixed-suffix | |
1307 | @cindex @code{r} fixed-suffix | |
1308 | @cindex @code{lr} fixed-suffix | |
1309 | @cindex @code{llr} fixed-suffix | |
1310 | @cindex @code{uhr} fixed-suffix | |
1311 | @cindex @code{ur} fixed-suffix | |
1312 | @cindex @code{ulr} fixed-suffix | |
1313 | @cindex @code{ullr} fixed-suffix | |
1314 | @cindex @code{hk} fixed-suffix | |
1315 | @cindex @code{k} fixed-suffix | |
1316 | @cindex @code{lk} fixed-suffix | |
1317 | @cindex @code{llk} fixed-suffix | |
1318 | @cindex @code{uhk} fixed-suffix | |
1319 | @cindex @code{uk} fixed-suffix | |
1320 | @cindex @code{ulk} fixed-suffix | |
1321 | @cindex @code{ullk} fixed-suffix | |
1322 | @cindex @code{HR} fixed-suffix | |
1323 | @cindex @code{R} fixed-suffix | |
1324 | @cindex @code{LR} fixed-suffix | |
1325 | @cindex @code{LLR} fixed-suffix | |
1326 | @cindex @code{UHR} fixed-suffix | |
1327 | @cindex @code{UR} fixed-suffix | |
1328 | @cindex @code{ULR} fixed-suffix | |
1329 | @cindex @code{ULLR} fixed-suffix | |
1330 | @cindex @code{HK} fixed-suffix | |
1331 | @cindex @code{K} fixed-suffix | |
1332 | @cindex @code{LK} fixed-suffix | |
1333 | @cindex @code{LLK} fixed-suffix | |
1334 | @cindex @code{UHK} fixed-suffix | |
1335 | @cindex @code{UK} fixed-suffix | |
1336 | @cindex @code{ULK} fixed-suffix | |
1337 | @cindex @code{ULLK} fixed-suffix | |
1338 | ||
1339 | As an extension, GNU C supports fixed-point types as | |
1340 | defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point | |
1341 | types in GCC will evolve as the draft technical report changes. | |
1342 | Calling conventions for any target might also change. Not all targets | |
1343 | support fixed-point types. | |
1344 | ||
1345 | The fixed-point types are | |
1346 | @code{short _Fract}, | |
1347 | @code{_Fract}, | |
1348 | @code{long _Fract}, | |
1349 | @code{long long _Fract}, | |
1350 | @code{unsigned short _Fract}, | |
1351 | @code{unsigned _Fract}, | |
1352 | @code{unsigned long _Fract}, | |
1353 | @code{unsigned long long _Fract}, | |
1354 | @code{_Sat short _Fract}, | |
1355 | @code{_Sat _Fract}, | |
1356 | @code{_Sat long _Fract}, | |
1357 | @code{_Sat long long _Fract}, | |
1358 | @code{_Sat unsigned short _Fract}, | |
1359 | @code{_Sat unsigned _Fract}, | |
1360 | @code{_Sat unsigned long _Fract}, | |
1361 | @code{_Sat unsigned long long _Fract}, | |
1362 | @code{short _Accum}, | |
1363 | @code{_Accum}, | |
1364 | @code{long _Accum}, | |
1365 | @code{long long _Accum}, | |
1366 | @code{unsigned short _Accum}, | |
1367 | @code{unsigned _Accum}, | |
1368 | @code{unsigned long _Accum}, | |
1369 | @code{unsigned long long _Accum}, | |
1370 | @code{_Sat short _Accum}, | |
1371 | @code{_Sat _Accum}, | |
1372 | @code{_Sat long _Accum}, | |
1373 | @code{_Sat long long _Accum}, | |
1374 | @code{_Sat unsigned short _Accum}, | |
1375 | @code{_Sat unsigned _Accum}, | |
1376 | @code{_Sat unsigned long _Accum}, | |
1377 | @code{_Sat unsigned long long _Accum}. | |
1378 | ||
1379 | Fixed-point data values contain fractional and optional integral parts. | |
1380 | The format of fixed-point data varies and depends on the target machine. | |
1381 | ||
1382 | Support for fixed-point types includes: | |
1383 | @itemize @bullet | |
1384 | @item | |
1385 | prefix and postfix increment and decrement operators (@code{++}, @code{--}) | |
1386 | @item | |
1387 | unary arithmetic operators (@code{+}, @code{-}, @code{!}) | |
1388 | @item | |
1389 | binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) | |
1390 | @item | |
1391 | binary shift operators (@code{<<}, @code{>>}) | |
1392 | @item | |
1393 | relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) | |
1394 | @item | |
1395 | equality operators (@code{==}, @code{!=}) | |
1396 | @item | |
1397 | assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, | |
1398 | @code{<<=}, @code{>>=}) | |
1399 | @item | |
1400 | conversions to and from integer, floating-point, or fixed-point types | |
1401 | @end itemize | |
1402 | ||
1403 | Use a suffix in a fixed-point literal constant: | |
1404 | @itemize | |
1405 | @item @samp{hr} or @samp{HR} for @code{short _Fract} and | |
1406 | @code{_Sat short _Fract} | |
1407 | @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} | |
1408 | @item @samp{lr} or @samp{LR} for @code{long _Fract} and | |
1409 | @code{_Sat long _Fract} | |
1410 | @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and | |
1411 | @code{_Sat long long _Fract} | |
1412 | @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and | |
1413 | @code{_Sat unsigned short _Fract} | |
1414 | @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and | |
1415 | @code{_Sat unsigned _Fract} | |
1416 | @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and | |
1417 | @code{_Sat unsigned long _Fract} | |
1418 | @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} | |
1419 | and @code{_Sat unsigned long long _Fract} | |
1420 | @item @samp{hk} or @samp{HK} for @code{short _Accum} and | |
1421 | @code{_Sat short _Accum} | |
1422 | @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} | |
1423 | @item @samp{lk} or @samp{LK} for @code{long _Accum} and | |
1424 | @code{_Sat long _Accum} | |
1425 | @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and | |
1426 | @code{_Sat long long _Accum} | |
1427 | @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and | |
1428 | @code{_Sat unsigned short _Accum} | |
1429 | @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and | |
1430 | @code{_Sat unsigned _Accum} | |
1431 | @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and | |
1432 | @code{_Sat unsigned long _Accum} | |
1433 | @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} | |
1434 | and @code{_Sat unsigned long long _Accum} | |
1435 | @end itemize | |
1436 | ||
1437 | GCC support of fixed-point types as specified by the draft technical report | |
1438 | is incomplete: | |
1439 | ||
1440 | @itemize @bullet | |
1441 | @item | |
1442 | Pragmas to control overflow and rounding behaviors are not implemented. | |
1443 | @end itemize | |
1444 | ||
1445 | Fixed-point types are supported by the DWARF debug information format. | |
1446 | ||
1447 | @node Named Address Spaces | |
1448 | @section Named Address Spaces | |
1449 | @cindex Named Address Spaces | |
1450 | ||
1451 | As an extension, GNU C supports named address spaces as | |
1452 | defined in the N1275 draft of ISO/IEC DTR 18037. Support for named | |
1453 | address spaces in GCC will evolve as the draft technical report | |
1454 | changes. Calling conventions for any target might also change. At | |
1455 | present, only the AVR, M32C, PRU, RL78, and x86 targets support | |
1456 | address spaces other than the generic address space. | |
1457 | ||
1458 | Address space identifiers may be used exactly like any other C type | |
1459 | qualifier (e.g., @code{const} or @code{volatile}). See the N1275 | |
1460 | document for more details. | |
1461 | ||
1462 | @anchor{AVR Named Address Spaces} | |
1463 | @subsection AVR Named Address Spaces | |
1464 | ||
1465 | On the AVR target, there are several address spaces that can be used | |
1466 | in order to put read-only data into the flash memory and access that | |
1467 | data by means of the special instructions @code{LPM} or @code{ELPM} | |
1468 | needed to read from flash. | |
1469 | ||
1470 | Devices belonging to @code{avrtiny} and @code{avrxmega3} can access | |
1471 | flash memory by means of @code{LD*} instructions because the flash | |
1472 | memory is mapped into the RAM address space. There is @emph{no need} | |
1473 | for language extensions like @code{__flash} or attribute | |
1474 | @ref{AVR Variable Attributes,,@code{progmem}}. | |
1475 | The default linker description files for these devices cater for that | |
1476 | feature and @code{.rodata} stays in flash: The compiler just generates | |
1477 | @code{LD*} instructions, and the linker script adds core specific | |
1478 | offsets to all @code{.rodata} symbols: @code{0x4000} in the case of | |
1479 | @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}. | |
1480 | See @ref{AVR Options} for a list of respective devices. | |
1481 | ||
1482 | For devices not in @code{avrtiny} or @code{avrxmega3}, | |
1483 | any data including read-only data is located in RAM (the generic | |
1484 | address space) because flash memory is not visible in the RAM address | |
1485 | space. In order to locate read-only data in flash memory @emph{and} | |
1486 | to generate the right instructions to access this data without | |
1487 | using (inline) assembler code, special address spaces are needed. | |
1488 | ||
1489 | @table @code | |
d77de738 | 1490 | @cindex @code{__flash} AVR Named Address Spaces |
f33d7a88 | 1491 | @item __flash |
d77de738 ML |
1492 | The @code{__flash} qualifier locates data in the |
1493 | @code{.progmem.data} section. Data is read using the @code{LPM} | |
1494 | instruction. Pointers to this address space are 16 bits wide. | |
1495 | ||
d77de738 ML |
1496 | @cindex @code{__flash1} AVR Named Address Spaces |
1497 | @cindex @code{__flash2} AVR Named Address Spaces | |
1498 | @cindex @code{__flash3} AVR Named Address Spaces | |
1499 | @cindex @code{__flash4} AVR Named Address Spaces | |
1500 | @cindex @code{__flash5} AVR Named Address Spaces | |
f33d7a88 AA |
1501 | @item __flash1 |
1502 | @itemx __flash2 | |
1503 | @itemx __flash3 | |
1504 | @itemx __flash4 | |
1505 | @itemx __flash5 | |
d77de738 ML |
1506 | These are 16-bit address spaces locating data in section |
1507 | @code{.progmem@var{N}.data} where @var{N} refers to | |
1508 | address space @code{__flash@var{N}}. | |
1509 | The compiler sets the @code{RAMPZ} segment register appropriately | |
1510 | before reading data by means of the @code{ELPM} instruction. | |
1511 | ||
d77de738 | 1512 | @cindex @code{__memx} AVR Named Address Spaces |
f33d7a88 | 1513 | @item __memx |
d77de738 ML |
1514 | This is a 24-bit address space that linearizes flash and RAM: |
1515 | If the high bit of the address is set, data is read from | |
1516 | RAM using the lower two bytes as RAM address. | |
1517 | If the high bit of the address is clear, data is read from flash | |
1518 | with @code{RAMPZ} set according to the high byte of the address. | |
1519 | @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. | |
1520 | ||
1521 | Objects in this address space are located in @code{.progmemx.data}. | |
1522 | @end table | |
1523 | ||
1524 | @b{Example} | |
1525 | ||
1526 | @smallexample | |
1527 | char my_read (const __flash char ** p) | |
1528 | @{ | |
1529 | /* p is a pointer to RAM that points to a pointer to flash. | |
1530 | The first indirection of p reads that flash pointer | |
1531 | from RAM and the second indirection reads a char from this | |
1532 | flash address. */ | |
1533 | ||
1534 | return **p; | |
1535 | @} | |
1536 | ||
1537 | /* Locate array[] in flash memory */ | |
1538 | const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; | |
1539 | ||
1540 | int i = 1; | |
1541 | ||
1542 | int main (void) | |
1543 | @{ | |
1544 | /* Return 17 by reading from flash memory */ | |
1545 | return array[array[i]]; | |
1546 | @} | |
1547 | @end smallexample | |
1548 | ||
1549 | @noindent | |
1550 | For each named address space supported by avr-gcc there is an equally | |
1551 | named but uppercase built-in macro defined. | |
1552 | The purpose is to facilitate testing if respective address space | |
1553 | support is available or not: | |
1554 | ||
1555 | @smallexample | |
1556 | #ifdef __FLASH | |
1557 | const __flash int var = 1; | |
1558 | ||
1559 | int read_var (void) | |
1560 | @{ | |
1561 | return var; | |
1562 | @} | |
1563 | #else | |
1564 | #include <avr/pgmspace.h> /* From AVR-LibC */ | |
1565 | ||
1566 | const int var PROGMEM = 1; | |
1567 | ||
1568 | int read_var (void) | |
1569 | @{ | |
1570 | return (int) pgm_read_word (&var); | |
1571 | @} | |
1572 | #endif /* __FLASH */ | |
1573 | @end smallexample | |
1574 | ||
1575 | @noindent | |
1576 | Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} | |
1577 | locates data in flash but | |
1578 | accesses to these data read from generic address space, i.e.@: | |
1579 | from RAM, | |
1580 | so that you need special accessors like @code{pgm_read_byte} | |
38bce6ff | 1581 | from @w{@uref{https://www.nongnu.org/avr-libc/user-manual/,AVR-LibC}} |
d77de738 ML |
1582 | together with attribute @code{progmem}. |
1583 | ||
1584 | @noindent | |
1585 | @b{Limitations and caveats} | |
1586 | ||
1587 | @itemize | |
1588 | @item | |
1589 | Reading across the 64@tie{}KiB section boundary of | |
1590 | the @code{__flash} or @code{__flash@var{N}} address spaces | |
1591 | shows undefined behavior. The only address space that | |
1592 | supports reading across the 64@tie{}KiB flash segment boundaries is | |
1593 | @code{__memx}. | |
1594 | ||
1595 | @item | |
1596 | If you use one of the @code{__flash@var{N}} address spaces | |
1597 | you must arrange your linker script to locate the | |
1598 | @code{.progmem@var{N}.data} sections according to your needs. | |
1599 | ||
1600 | @item | |
1601 | Any data or pointers to the non-generic address spaces must | |
1602 | be qualified as @code{const}, i.e.@: as read-only data. | |
1603 | This still applies if the data in one of these address | |
1604 | spaces like software version number or calibration lookup table are intended to | |
1605 | be changed after load time by, say, a boot loader. In this case | |
1606 | the right qualification is @code{const} @code{volatile} so that the compiler | |
1607 | must not optimize away known values or insert them | |
1608 | as immediates into operands of instructions. | |
1609 | ||
1610 | @item | |
1611 | The following code initializes a variable @code{pfoo} | |
1612 | located in static storage with a 24-bit address: | |
1613 | @smallexample | |
1614 | extern const __memx char foo; | |
1615 | const __memx void *pfoo = &foo; | |
1616 | @end smallexample | |
1617 | ||
1618 | @item | |
1619 | On the reduced Tiny devices like ATtiny40, no address spaces are supported. | |
1620 | Just use vanilla C / C++ code without overhead as outlined above. | |
1621 | Attribute @code{progmem} is supported but works differently, | |
1622 | see @ref{AVR Variable Attributes}. | |
1623 | ||
1624 | @end itemize | |
1625 | ||
1626 | @subsection M32C Named Address Spaces | |
1627 | @cindex @code{__far} M32C Named Address Spaces | |
1628 | ||
1629 | On the M32C target, with the R8C and M16C CPU variants, variables | |
1630 | qualified with @code{__far} are accessed using 32-bit addresses in | |
1631 | order to access memory beyond the first 64@tie{}Ki bytes. If | |
1632 | @code{__far} is used with the M32CM or M32C CPU variants, it has no | |
1633 | effect. | |
1634 | ||
1635 | @subsection PRU Named Address Spaces | |
1636 | @cindex @code{__regio_symbol} PRU Named Address Spaces | |
1637 | ||
1638 | On the PRU target, variables qualified with @code{__regio_symbol} are | |
1639 | aliases used to access the special I/O CPU registers. They must be | |
1640 | declared as @code{extern} because such variables will not be allocated in | |
1641 | any data memory. They must also be marked as @code{volatile}, and can | |
1642 | only be 32-bit integer types. The only names those variables can have | |
1643 | are @code{__R30} and @code{__R31}, representing respectively the | |
1644 | @code{R30} and @code{R31} special I/O CPU registers. Hence the following | |
1645 | example is the only valid usage of @code{__regio_symbol}: | |
1646 | ||
1647 | @smallexample | |
1648 | extern volatile __regio_symbol uint32_t __R30; | |
1649 | extern volatile __regio_symbol uint32_t __R31; | |
1650 | @end smallexample | |
1651 | ||
1652 | @subsection RL78 Named Address Spaces | |
1653 | @cindex @code{__far} RL78 Named Address Spaces | |
1654 | ||
1655 | On the RL78 target, variables qualified with @code{__far} are accessed | |
1656 | with 32-bit pointers (20-bit addresses) rather than the default 16-bit | |
1657 | addresses. Non-far variables are assumed to appear in the topmost | |
1658 | 64@tie{}KiB of the address space. | |
1659 | ||
1660 | @subsection x86 Named Address Spaces | |
1661 | @cindex x86 named address spaces | |
1662 | ||
1663 | On the x86 target, variables may be declared as being relative | |
1664 | to the @code{%fs} or @code{%gs} segments. | |
1665 | ||
1666 | @table @code | |
d77de738 ML |
1667 | @cindex @code{__seg_fs} x86 named address space |
1668 | @cindex @code{__seg_gs} x86 named address space | |
f33d7a88 AA |
1669 | @item __seg_fs |
1670 | @itemx __seg_gs | |
d77de738 ML |
1671 | The object is accessed with the respective segment override prefix. |
1672 | ||
1673 | The respective segment base must be set via some method specific to | |
1674 | the operating system. Rather than require an expensive system call | |
1675 | to retrieve the segment base, these address spaces are not considered | |
1676 | to be subspaces of the generic (flat) address space. This means that | |
1677 | explicit casts are required to convert pointers between these address | |
1678 | spaces and the generic address space. In practice the application | |
1679 | should cast to @code{uintptr_t} and apply the segment base offset | |
1680 | that it installed previously. | |
1681 | ||
1682 | The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are | |
1683 | defined when these address spaces are supported. | |
1684 | @end table | |
1685 | ||
1686 | @node Zero Length | |
1687 | @section Arrays of Length Zero | |
1688 | @cindex arrays of length zero | |
1689 | @cindex zero-length arrays | |
1690 | @cindex length-zero arrays | |
1691 | @cindex flexible array members | |
1692 | ||
1693 | Declaring zero-length arrays is allowed in GNU C as an extension. | |
1694 | A zero-length array can be useful as the last element of a structure | |
1695 | that is really a header for a variable-length object: | |
1696 | ||
1697 | @smallexample | |
1698 | struct line @{ | |
1699 | int length; | |
1700 | char contents[0]; | |
1701 | @}; | |
1702 | ||
1703 | struct line *thisline = (struct line *) | |
1704 | malloc (sizeof (struct line) + this_length); | |
1705 | thisline->length = this_length; | |
1706 | @end smallexample | |
1707 | ||
1708 | Although the size of a zero-length array is zero, an array member of | |
1709 | this kind may increase the size of the enclosing type as a result of tail | |
1710 | padding. The offset of a zero-length array member from the beginning | |
1711 | of the enclosing structure is the same as the offset of an array with | |
1712 | one or more elements of the same type. The alignment of a zero-length | |
1713 | array is the same as the alignment of its elements. | |
1714 | ||
1715 | Declaring zero-length arrays in other contexts, including as interior | |
1716 | members of structure objects or as non-member objects, is discouraged. | |
1717 | Accessing elements of zero-length arrays declared in such contexts is | |
1718 | undefined and may be diagnosed. | |
1719 | ||
1720 | In the absence of the zero-length array extension, in ISO C90 | |
1721 | the @code{contents} array in the example above would typically be declared | |
1722 | to have a single element. Unlike a zero-length array which only contributes | |
1723 | to the size of the enclosing structure for the purposes of alignment, | |
1724 | a one-element array always occupies at least as much space as a single | |
1725 | object of the type. Although using one-element arrays this way is | |
1726 | discouraged, GCC handles accesses to trailing one-element array members | |
1727 | analogously to zero-length arrays. | |
1728 | ||
1729 | The preferred mechanism to declare variable-length types like | |
1730 | @code{struct line} above is the ISO C99 @dfn{flexible array member}, | |
1731 | with slightly different syntax and semantics: | |
1732 | ||
1733 | @itemize @bullet | |
1734 | @item | |
1735 | Flexible array members are written as @code{contents[]} without | |
1736 | the @code{0}. | |
1737 | ||
1738 | @item | |
1739 | Flexible array members have incomplete type, and so the @code{sizeof} | |
1740 | operator may not be applied. As a quirk of the original implementation | |
1741 | of zero-length arrays, @code{sizeof} evaluates to zero. | |
1742 | ||
1743 | @item | |
1744 | Flexible array members may only appear as the last member of a | |
1745 | @code{struct} that is otherwise non-empty. | |
1746 | ||
1747 | @item | |
1748 | A structure containing a flexible array member, or a union containing | |
1749 | such a structure (possibly recursively), may not be a member of a | |
1750 | structure or an element of an array. (However, these uses are | |
1751 | permitted by GCC as extensions.) | |
1752 | @end itemize | |
1753 | ||
1754 | Non-empty initialization of zero-length | |
1755 | arrays is treated like any case where there are more initializer | |
1756 | elements than the array holds, in that a suitable warning about ``excess | |
1757 | elements in array'' is given, and the excess elements (all of them, in | |
1758 | this case) are ignored. | |
1759 | ||
1760 | GCC allows static initialization of flexible array members. | |
1761 | This is equivalent to defining a new structure containing the original | |
1762 | structure followed by an array of sufficient size to contain the data. | |
1763 | E.g.@: in the following, @code{f1} is constructed as if it were declared | |
1764 | like @code{f2}. | |
1765 | ||
1766 | @smallexample | |
1767 | struct f1 @{ | |
1768 | int x; int y[]; | |
1769 | @} f1 = @{ 1, @{ 2, 3, 4 @} @}; | |
1770 | ||
1771 | struct f2 @{ | |
1772 | struct f1 f1; int data[3]; | |
1773 | @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; | |
1774 | @end smallexample | |
1775 | ||
1776 | @noindent | |
1777 | The convenience of this extension is that @code{f1} has the desired | |
1778 | type, eliminating the need to consistently refer to @code{f2.f1}. | |
1779 | ||
1780 | This has symmetry with normal static arrays, in that an array of | |
1781 | unknown size is also written with @code{[]}. | |
1782 | ||
1783 | Of course, this extension only makes sense if the extra data comes at | |
1784 | the end of a top-level object, as otherwise we would be overwriting | |
1785 | data at subsequent offsets. To avoid undue complication and confusion | |
1786 | with initialization of deeply nested arrays, we simply disallow any | |
1787 | non-empty initialization except when the structure is the top-level | |
1788 | object. For example: | |
1789 | ||
1790 | @smallexample | |
1791 | struct foo @{ int x; int y[]; @}; | |
1792 | struct bar @{ struct foo z; @}; | |
1793 | ||
1794 | struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} | |
1795 | struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} | |
1796 | struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} | |
1797 | struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} | |
1798 | @end smallexample | |
1799 | ||
1800 | @node Empty Structures | |
1801 | @section Structures with No Members | |
1802 | @cindex empty structures | |
1803 | @cindex zero-size structures | |
1804 | ||
1805 | GCC permits a C structure to have no members: | |
1806 | ||
1807 | @smallexample | |
1808 | struct empty @{ | |
1809 | @}; | |
1810 | @end smallexample | |
1811 | ||
1812 | The structure has size zero. In C++, empty structures are part | |
1813 | of the language. G++ treats empty structures as if they had a single | |
1814 | member of type @code{char}. | |
1815 | ||
1816 | @node Variable Length | |
1817 | @section Arrays of Variable Length | |
1818 | @cindex variable-length arrays | |
1819 | @cindex arrays of variable length | |
1820 | @cindex VLAs | |
1821 | ||
1822 | Variable-length automatic arrays are allowed in ISO C99, and as an | |
1823 | extension GCC accepts them in C90 mode and in C++. These arrays are | |
1824 | declared like any other automatic arrays, but with a length that is not | |
1825 | a constant expression. The storage is allocated at the point of | |
1826 | declaration and deallocated when the block scope containing the declaration | |
1827 | exits. For | |
1828 | example: | |
1829 | ||
1830 | @smallexample | |
1831 | FILE * | |
1832 | concat_fopen (char *s1, char *s2, char *mode) | |
1833 | @{ | |
1834 | char str[strlen (s1) + strlen (s2) + 1]; | |
1835 | strcpy (str, s1); | |
1836 | strcat (str, s2); | |
1837 | return fopen (str, mode); | |
1838 | @} | |
1839 | @end smallexample | |
1840 | ||
1841 | @cindex scope of a variable length array | |
1842 | @cindex variable-length array scope | |
1843 | @cindex deallocating variable length arrays | |
1844 | Jumping or breaking out of the scope of the array name deallocates the | |
1845 | storage. Jumping into the scope is not allowed; you get an error | |
1846 | message for it. | |
1847 | ||
1848 | @cindex variable-length array in a structure | |
1849 | As an extension, GCC accepts variable-length arrays as a member of | |
1850 | a structure or a union. For example: | |
1851 | ||
1852 | @smallexample | |
1853 | void | |
1854 | foo (int n) | |
1855 | @{ | |
1856 | struct S @{ int x[n]; @}; | |
1857 | @} | |
1858 | @end smallexample | |
1859 | ||
1860 | @cindex @code{alloca} vs variable-length arrays | |
1861 | You can use the function @code{alloca} to get an effect much like | |
1862 | variable-length arrays. The function @code{alloca} is available in | |
1863 | many other C implementations (but not in all). On the other hand, | |
1864 | variable-length arrays are more elegant. | |
1865 | ||
1866 | There are other differences between these two methods. Space allocated | |
1867 | with @code{alloca} exists until the containing @emph{function} returns. | |
1868 | The space for a variable-length array is deallocated as soon as the array | |
1869 | name's scope ends, unless you also use @code{alloca} in this scope. | |
1870 | ||
1871 | You can also use variable-length arrays as arguments to functions: | |
1872 | ||
1873 | @smallexample | |
1874 | struct entry | |
1875 | tester (int len, char data[len][len]) | |
1876 | @{ | |
1877 | /* @r{@dots{}} */ | |
1878 | @} | |
1879 | @end smallexample | |
1880 | ||
1881 | The length of an array is computed once when the storage is allocated | |
1882 | and is remembered for the scope of the array in case you access it with | |
1883 | @code{sizeof}. | |
1884 | ||
1885 | If you want to pass the array first and the length afterward, you can | |
1886 | use a forward declaration in the parameter list---another GNU extension. | |
1887 | ||
1888 | @smallexample | |
1889 | struct entry | |
1890 | tester (int len; char data[len][len], int len) | |
1891 | @{ | |
1892 | /* @r{@dots{}} */ | |
1893 | @} | |
1894 | @end smallexample | |
1895 | ||
1896 | @cindex parameter forward declaration | |
1897 | The @samp{int len} before the semicolon is a @dfn{parameter forward | |
1898 | declaration}, and it serves the purpose of making the name @code{len} | |
1899 | known when the declaration of @code{data} is parsed. | |
1900 | ||
1901 | You can write any number of such parameter forward declarations in the | |
1902 | parameter list. They can be separated by commas or semicolons, but the | |
1903 | last one must end with a semicolon, which is followed by the ``real'' | |
1904 | parameter declarations. Each forward declaration must match a ``real'' | |
1905 | declaration in parameter name and data type. ISO C99 does not support | |
1906 | parameter forward declarations. | |
1907 | ||
1908 | @node Variadic Macros | |
1909 | @section Macros with a Variable Number of Arguments. | |
1910 | @cindex variable number of arguments | |
1911 | @cindex macro with variable arguments | |
1912 | @cindex rest argument (in macro) | |
1913 | @cindex variadic macros | |
1914 | ||
1915 | In the ISO C standard of 1999, a macro can be declared to accept a | |
1916 | variable number of arguments much as a function can. The syntax for | |
1917 | defining the macro is similar to that of a function. Here is an | |
1918 | example: | |
1919 | ||
1920 | @smallexample | |
1921 | #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) | |
1922 | @end smallexample | |
1923 | ||
1924 | @noindent | |
1925 | Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of | |
1926 | such a macro, it represents the zero or more tokens until the closing | |
1927 | parenthesis that ends the invocation, including any commas. This set of | |
1928 | tokens replaces the identifier @code{__VA_ARGS__} in the macro body | |
1929 | wherever it appears. See the CPP manual for more information. | |
1930 | ||
1931 | GCC has long supported variadic macros, and used a different syntax that | |
1932 | allowed you to give a name to the variable arguments just like any other | |
1933 | argument. Here is an example: | |
1934 | ||
1935 | @smallexample | |
1936 | #define debug(format, args...) fprintf (stderr, format, args) | |
1937 | @end smallexample | |
1938 | ||
1939 | @noindent | |
1940 | This is in all ways equivalent to the ISO C example above, but arguably | |
1941 | more readable and descriptive. | |
1942 | ||
1943 | GNU CPP has two further variadic macro extensions, and permits them to | |
1944 | be used with either of the above forms of macro definition. | |
1945 | ||
1946 | In standard C, you are not allowed to leave the variable argument out | |
1947 | entirely; but you are allowed to pass an empty argument. For example, | |
1948 | this invocation is invalid in ISO C, because there is no comma after | |
1949 | the string: | |
1950 | ||
1951 | @smallexample | |
1952 | debug ("A message") | |
1953 | @end smallexample | |
1954 | ||
1955 | GNU CPP permits you to completely omit the variable arguments in this | |
1956 | way. In the above examples, the compiler would complain, though since | |
1957 | the expansion of the macro still has the extra comma after the format | |
1958 | string. | |
1959 | ||
1960 | To help solve this problem, CPP behaves specially for variable arguments | |
1961 | used with the token paste operator, @samp{##}. If instead you write | |
1962 | ||
1963 | @smallexample | |
1964 | #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) | |
1965 | @end smallexample | |
1966 | ||
1967 | @noindent | |
1968 | and if the variable arguments are omitted or empty, the @samp{##} | |
1969 | operator causes the preprocessor to remove the comma before it. If you | |
1970 | do provide some variable arguments in your macro invocation, GNU CPP | |
1971 | does not complain about the paste operation and instead places the | |
1972 | variable arguments after the comma. Just like any other pasted macro | |
1973 | argument, these arguments are not macro expanded. | |
1974 | ||
1975 | @node Escaped Newlines | |
1976 | @section Slightly Looser Rules for Escaped Newlines | |
1977 | @cindex escaped newlines | |
1978 | @cindex newlines (escaped) | |
1979 | ||
1980 | The preprocessor treatment of escaped newlines is more relaxed | |
1981 | than that specified by the C90 standard, which requires the newline | |
1982 | to immediately follow a backslash. | |
1983 | GCC's implementation allows whitespace in the form | |
1984 | of spaces, horizontal and vertical tabs, and form feeds between the | |
1985 | backslash and the subsequent newline. The preprocessor issues a | |
1986 | warning, but treats it as a valid escaped newline and combines the two | |
1987 | lines to form a single logical line. This works within comments and | |
1988 | tokens, as well as between tokens. Comments are @emph{not} treated as | |
1989 | whitespace for the purposes of this relaxation, since they have not | |
1990 | yet been replaced with spaces. | |
1991 | ||
1992 | @node Subscripting | |
1993 | @section Non-Lvalue Arrays May Have Subscripts | |
1994 | @cindex subscripting | |
1995 | @cindex arrays, non-lvalue | |
1996 | ||
1997 | @cindex subscripting and function values | |
1998 | In ISO C99, arrays that are not lvalues still decay to pointers, and | |
1999 | may be subscripted, although they may not be modified or used after | |
2000 | the next sequence point and the unary @samp{&} operator may not be | |
2001 | applied to them. As an extension, GNU C allows such arrays to be | |
2002 | subscripted in C90 mode, though otherwise they do not decay to | |
2003 | pointers outside C99 mode. For example, | |
2004 | this is valid in GNU C though not valid in C90: | |
2005 | ||
2006 | @smallexample | |
2007 | @group | |
2008 | struct foo @{int a[4];@}; | |
2009 | ||
2010 | struct foo f(); | |
2011 | ||
2012 | bar (int index) | |
2013 | @{ | |
2014 | return f().a[index]; | |
2015 | @} | |
2016 | @end group | |
2017 | @end smallexample | |
2018 | ||
2019 | @node Pointer Arith | |
2020 | @section Arithmetic on @code{void}- and Function-Pointers | |
2021 | @cindex void pointers, arithmetic | |
2022 | @cindex void, size of pointer to | |
2023 | @cindex function pointers, arithmetic | |
2024 | @cindex function, size of pointer to | |
2025 | ||
2026 | In GNU C, addition and subtraction operations are supported on pointers to | |
2027 | @code{void} and on pointers to functions. This is done by treating the | |
2028 | size of a @code{void} or of a function as 1. | |
2029 | ||
2030 | A consequence of this is that @code{sizeof} is also allowed on @code{void} | |
2031 | and on function types, and returns 1. | |
2032 | ||
2033 | @opindex Wpointer-arith | |
2034 | The option @option{-Wpointer-arith} requests a warning if these extensions | |
2035 | are used. | |
2036 | ||
2037 | @node Variadic Pointer Args | |
2038 | @section Pointer Arguments in Variadic Functions | |
2039 | @cindex pointer arguments in variadic functions | |
2040 | @cindex variadic functions, pointer arguments | |
2041 | ||
2042 | Standard C requires that pointer types used with @code{va_arg} in | |
2043 | functions with variable argument lists either must be compatible with | |
2044 | that of the actual argument, or that one type must be a pointer to | |
2045 | @code{void} and the other a pointer to a character type. GNU C | |
2046 | implements the POSIX XSI extension that additionally permits the use | |
2047 | of @code{va_arg} with a pointer type to receive arguments of any other | |
2048 | pointer type. | |
2049 | ||
2050 | In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used | |
2051 | to consume an argument of any pointer type. | |
2052 | ||
2053 | @node Pointers to Arrays | |
2054 | @section Pointers to Arrays with Qualifiers Work as Expected | |
2055 | @cindex pointers to arrays | |
2056 | @cindex const qualifier | |
2057 | ||
2058 | In GNU C, pointers to arrays with qualifiers work similar to pointers | |
2059 | to other qualified types. For example, a value of type @code{int (*)[5]} | |
2060 | can be used to initialize a variable of type @code{const int (*)[5]}. | |
2061 | These types are incompatible in ISO C because the @code{const} qualifier | |
2062 | is formally attached to the element type of the array and not the | |
2063 | array itself. | |
2064 | ||
2065 | @smallexample | |
2066 | extern void | |
2067 | transpose (int N, int M, double out[M][N], const double in[N][M]); | |
2068 | double x[3][2]; | |
2069 | double y[2][3]; | |
2070 | @r{@dots{}} | |
2071 | transpose(3, 2, y, x); | |
2072 | @end smallexample | |
2073 | ||
2074 | @node Initializers | |
2075 | @section Non-Constant Initializers | |
2076 | @cindex initializers, non-constant | |
2077 | @cindex non-constant initializers | |
2078 | ||
2079 | As in standard C++ and ISO C99, the elements of an aggregate initializer for an | |
2080 | automatic variable are not required to be constant expressions in GNU C@. | |
2081 | Here is an example of an initializer with run-time varying elements: | |
2082 | ||
2083 | @smallexample | |
2084 | foo (float f, float g) | |
2085 | @{ | |
2086 | float beat_freqs[2] = @{ f-g, f+g @}; | |
2087 | /* @r{@dots{}} */ | |
2088 | @} | |
2089 | @end smallexample | |
2090 | ||
2091 | @node Compound Literals | |
2092 | @section Compound Literals | |
2093 | @cindex constructor expressions | |
2094 | @cindex initializations in expressions | |
2095 | @cindex structures, constructor expression | |
2096 | @cindex expressions, constructor | |
2097 | @cindex compound literals | |
2098 | @c The GNU C name for what C99 calls compound literals was "constructor expressions". | |
2099 | ||
2100 | A compound literal looks like a cast of a brace-enclosed aggregate | |
2101 | initializer list. Its value is an object of the type specified in | |
2102 | the cast, containing the elements specified in the initializer. | |
2103 | Unlike the result of a cast, a compound literal is an lvalue. ISO | |
2104 | C99 and later support compound literals. As an extension, GCC | |
2105 | supports compound literals also in C90 mode and in C++, although | |
2106 | as explained below, the C++ semantics are somewhat different. | |
2107 | ||
2108 | Usually, the specified type of a compound literal is a structure. Assume | |
2109 | that @code{struct foo} and @code{structure} are declared as shown: | |
2110 | ||
2111 | @smallexample | |
2112 | struct foo @{int a; char b[2];@} structure; | |
2113 | @end smallexample | |
2114 | ||
2115 | @noindent | |
2116 | Here is an example of constructing a @code{struct foo} with a compound literal: | |
2117 | ||
2118 | @smallexample | |
2119 | structure = ((struct foo) @{x + y, 'a', 0@}); | |
2120 | @end smallexample | |
2121 | ||
2122 | @noindent | |
2123 | This is equivalent to writing the following: | |
2124 | ||
2125 | @smallexample | |
2126 | @{ | |
2127 | struct foo temp = @{x + y, 'a', 0@}; | |
2128 | structure = temp; | |
2129 | @} | |
2130 | @end smallexample | |
2131 | ||
2132 | You can also construct an array, though this is dangerous in C++, as | |
2133 | explained below. If all the elements of the compound literal are | |
2134 | (made up of) simple constant expressions suitable for use in | |
2135 | initializers of objects of static storage duration, then the compound | |
2136 | literal can be coerced to a pointer to its first element and used in | |
2137 | such an initializer, as shown here: | |
2138 | ||
2139 | @smallexample | |
2140 | char **foo = (char *[]) @{ "x", "y", "z" @}; | |
2141 | @end smallexample | |
2142 | ||
2143 | Compound literals for scalar types and union types are also allowed. In | |
2144 | the following example the variable @code{i} is initialized to the value | |
2145 | @code{2}, the result of incrementing the unnamed object created by | |
2146 | the compound literal. | |
2147 | ||
2148 | @smallexample | |
2149 | int i = ++(int) @{ 1 @}; | |
2150 | @end smallexample | |
2151 | ||
2152 | As a GNU extension, GCC allows initialization of objects with static storage | |
2153 | duration by compound literals (which is not possible in ISO C99 because | |
2154 | the initializer is not a constant). | |
2155 | It is handled as if the object were initialized only with the brace-enclosed | |
2156 | list if the types of the compound literal and the object match. | |
2157 | The elements of the compound literal must be constant. | |
2158 | If the object being initialized has array type of unknown size, the size is | |
2159 | determined by the size of the compound literal. | |
2160 | ||
2161 | @smallexample | |
2162 | static struct foo x = (struct foo) @{1, 'a', 'b'@}; | |
2163 | static int y[] = (int []) @{1, 2, 3@}; | |
2164 | static int z[] = (int [3]) @{1@}; | |
2165 | @end smallexample | |
2166 | ||
2167 | @noindent | |
2168 | The above lines are equivalent to the following: | |
2169 | @smallexample | |
2170 | static struct foo x = @{1, 'a', 'b'@}; | |
2171 | static int y[] = @{1, 2, 3@}; | |
2172 | static int z[] = @{1, 0, 0@}; | |
2173 | @end smallexample | |
2174 | ||
2175 | In C, a compound literal designates an unnamed object with static or | |
2176 | automatic storage duration. In C++, a compound literal designates a | |
2177 | temporary object that only lives until the end of its full-expression. | |
2178 | As a result, well-defined C code that takes the address of a subobject | |
2179 | of a compound literal can be undefined in C++, so G++ rejects | |
2180 | the conversion of a temporary array to a pointer. For instance, if | |
2181 | the array compound literal example above appeared inside a function, | |
2182 | any subsequent use of @code{foo} in C++ would have undefined behavior | |
2183 | because the lifetime of the array ends after the declaration of @code{foo}. | |
2184 | ||
2185 | As an optimization, G++ sometimes gives array compound literals longer | |
2186 | lifetimes: when the array either appears outside a function or has | |
2187 | a @code{const}-qualified type. If @code{foo} and its initializer had | |
2188 | elements of type @code{char *const} rather than @code{char *}, or if | |
2189 | @code{foo} were a global variable, the array would have static storage | |
2190 | duration. But it is probably safest just to avoid the use of array | |
2191 | compound literals in C++ code. | |
2192 | ||
2193 | @node Designated Inits | |
2194 | @section Designated Initializers | |
2195 | @cindex initializers with labeled elements | |
2196 | @cindex labeled elements in initializers | |
2197 | @cindex case labels in initializers | |
2198 | @cindex designated initializers | |
2199 | ||
2200 | Standard C90 requires the elements of an initializer to appear in a fixed | |
2201 | order, the same as the order of the elements in the array or structure | |
2202 | being initialized. | |
2203 | ||
2204 | In ISO C99 you can give the elements in any order, specifying the array | |
2205 | indices or structure field names they apply to, and GNU C allows this as | |
2206 | an extension in C90 mode as well. This extension is not | |
2207 | implemented in GNU C++. | |
2208 | ||
2209 | To specify an array index, write | |
2210 | @samp{[@var{index}] =} before the element value. For example, | |
2211 | ||
2212 | @smallexample | |
2213 | int a[6] = @{ [4] = 29, [2] = 15 @}; | |
2214 | @end smallexample | |
2215 | ||
2216 | @noindent | |
2217 | is equivalent to | |
2218 | ||
2219 | @smallexample | |
2220 | int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; | |
2221 | @end smallexample | |
2222 | ||
2223 | @noindent | |
2224 | The index values must be constant expressions, even if the array being | |
2225 | initialized is automatic. | |
2226 | ||
2227 | An alternative syntax for this that has been obsolete since GCC 2.5 but | |
2228 | GCC still accepts is to write @samp{[@var{index}]} before the element | |
2229 | value, with no @samp{=}. | |
2230 | ||
2231 | To initialize a range of elements to the same value, write | |
2232 | @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU | |
2233 | extension. For example, | |
2234 | ||
2235 | @smallexample | |
2236 | int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; | |
2237 | @end smallexample | |
2238 | ||
2239 | @noindent | |
2240 | If the value in it has side effects, the side effects happen only once, | |
2241 | not for each initialized field by the range initializer. | |
2242 | ||
2243 | @noindent | |
2244 | Note that the length of the array is the highest value specified | |
2245 | plus one. | |
2246 | ||
2247 | In a structure initializer, specify the name of a field to initialize | |
2248 | with @samp{.@var{fieldname} =} before the element value. For example, | |
2249 | given the following structure, | |
2250 | ||
2251 | @smallexample | |
2252 | struct point @{ int x, y; @}; | |
2253 | @end smallexample | |
2254 | ||
2255 | @noindent | |
2256 | the following initialization | |
2257 | ||
2258 | @smallexample | |
2259 | struct point p = @{ .y = yvalue, .x = xvalue @}; | |
2260 | @end smallexample | |
2261 | ||
2262 | @noindent | |
2263 | is equivalent to | |
2264 | ||
2265 | @smallexample | |
2266 | struct point p = @{ xvalue, yvalue @}; | |
2267 | @end smallexample | |
2268 | ||
2269 | Another syntax that has the same meaning, obsolete since GCC 2.5, is | |
2270 | @samp{@var{fieldname}:}, as shown here: | |
2271 | ||
2272 | @smallexample | |
2273 | struct point p = @{ y: yvalue, x: xvalue @}; | |
2274 | @end smallexample | |
2275 | ||
2276 | Omitted fields are implicitly initialized the same as for objects | |
2277 | that have static storage duration. | |
2278 | ||
2279 | @cindex designators | |
2280 | The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a | |
2281 | @dfn{designator}. You can also use a designator (or the obsolete colon | |
2282 | syntax) when initializing a union, to specify which element of the union | |
2283 | should be used. For example, | |
2284 | ||
2285 | @smallexample | |
2286 | union foo @{ int i; double d; @}; | |
2287 | ||
2288 | union foo f = @{ .d = 4 @}; | |
2289 | @end smallexample | |
2290 | ||
2291 | @noindent | |
2292 | converts 4 to a @code{double} to store it in the union using | |
2293 | the second element. By contrast, casting 4 to type @code{union foo} | |
2294 | stores it into the union as the integer @code{i}, since it is | |
2295 | an integer. @xref{Cast to Union}. | |
2296 | ||
2297 | You can combine this technique of naming elements with ordinary C | |
2298 | initialization of successive elements. Each initializer element that | |
2299 | does not have a designator applies to the next consecutive element of the | |
2300 | array or structure. For example, | |
2301 | ||
2302 | @smallexample | |
2303 | int a[6] = @{ [1] = v1, v2, [4] = v4 @}; | |
2304 | @end smallexample | |
2305 | ||
2306 | @noindent | |
2307 | is equivalent to | |
2308 | ||
2309 | @smallexample | |
2310 | int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; | |
2311 | @end smallexample | |
2312 | ||
2313 | Labeling the elements of an array initializer is especially useful | |
2314 | when the indices are characters or belong to an @code{enum} type. | |
2315 | For example: | |
2316 | ||
2317 | @smallexample | |
2318 | int whitespace[256] | |
2319 | = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, | |
2320 | ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; | |
2321 | @end smallexample | |
2322 | ||
2323 | @cindex designator lists | |
2324 | You can also write a series of @samp{.@var{fieldname}} and | |
2325 | @samp{[@var{index}]} designators before an @samp{=} to specify a | |
2326 | nested subobject to initialize; the list is taken relative to the | |
2327 | subobject corresponding to the closest surrounding brace pair. For | |
2328 | example, with the @samp{struct point} declaration above: | |
2329 | ||
2330 | @smallexample | |
2331 | struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; | |
2332 | @end smallexample | |
2333 | ||
2334 | If the same field is initialized multiple times, or overlapping | |
2335 | fields of a union are initialized, the value from the last | |
2336 | initialization is used. When a field of a union is itself a structure, | |
2337 | the entire structure from the last field initialized is used. If any previous | |
2338 | initializer has side effect, it is unspecified whether the side effect | |
2339 | happens or not. Currently, GCC discards the side-effecting | |
2340 | initializer expressions and issues a warning. | |
2341 | ||
2342 | @node Case Ranges | |
2343 | @section Case Ranges | |
2344 | @cindex case ranges | |
2345 | @cindex ranges in case statements | |
2346 | ||
2347 | You can specify a range of consecutive values in a single @code{case} label, | |
2348 | like this: | |
2349 | ||
2350 | @smallexample | |
2351 | case @var{low} ... @var{high}: | |
2352 | @end smallexample | |
2353 | ||
2354 | @noindent | |
2355 | This has the same effect as the proper number of individual @code{case} | |
2356 | labels, one for each integer value from @var{low} to @var{high}, inclusive. | |
2357 | ||
2358 | This feature is especially useful for ranges of ASCII character codes: | |
2359 | ||
2360 | @smallexample | |
2361 | case 'A' ... 'Z': | |
2362 | @end smallexample | |
2363 | ||
2364 | @strong{Be careful:} Write spaces around the @code{...}, for otherwise | |
2365 | it may be parsed wrong when you use it with integer values. For example, | |
2366 | write this: | |
2367 | ||
2368 | @smallexample | |
2369 | case 1 ... 5: | |
2370 | @end smallexample | |
2371 | ||
2372 | @noindent | |
2373 | rather than this: | |
2374 | ||
2375 | @smallexample | |
2376 | case 1...5: | |
2377 | @end smallexample | |
2378 | ||
2379 | @node Cast to Union | |
2380 | @section Cast to a Union Type | |
2381 | @cindex cast to a union | |
2382 | @cindex union, casting to a | |
2383 | ||
2384 | A cast to a union type is a C extension not available in C++. It looks | |
2385 | just like ordinary casts with the constraint that the type specified is | |
2386 | a union type. You can specify the type either with the @code{union} | |
2387 | keyword or with a @code{typedef} name that refers to a union. The result | |
2388 | of a cast to a union is a temporary rvalue of the union type with a member | |
2389 | whose type matches that of the operand initialized to the value of | |
2390 | the operand. The effect of a cast to a union is similar to a compound | |
2391 | literal except that it yields an rvalue like standard casts do. | |
2392 | @xref{Compound Literals}. | |
2393 | ||
2394 | Expressions that may be cast to the union type are those whose type matches | |
2395 | at least one of the members of the union. Thus, given the following union | |
2396 | and variables: | |
2397 | ||
2398 | @smallexample | |
2399 | union foo @{ int i; double d; @}; | |
2400 | int x; | |
2401 | double y; | |
2402 | union foo z; | |
2403 | @end smallexample | |
2404 | ||
2405 | @noindent | |
2406 | both @code{x} and @code{y} can be cast to type @code{union foo} and | |
2407 | the following assignments | |
2408 | @smallexample | |
2409 | z = (union foo) x; | |
2410 | z = (union foo) y; | |
2411 | @end smallexample | |
2412 | are shorthand equivalents of these | |
2413 | @smallexample | |
2414 | z = (union foo) @{ .i = x @}; | |
2415 | z = (union foo) @{ .d = y @}; | |
2416 | @end smallexample | |
2417 | ||
2418 | However, @code{(union foo) FLT_MAX;} is not a valid cast because the union | |
2419 | has no member of type @code{float}. | |
2420 | ||
2421 | Using the cast as the right-hand side of an assignment to a variable of | |
2422 | union type is equivalent to storing in a member of the union with | |
2423 | the same type | |
2424 | ||
2425 | @smallexample | |
2426 | union foo u; | |
2427 | /* @r{@dots{}} */ | |
2428 | u = (union foo) x @equiv{} u.i = x | |
2429 | u = (union foo) y @equiv{} u.d = y | |
2430 | @end smallexample | |
2431 | ||
2432 | You can also use the union cast as a function argument: | |
2433 | ||
2434 | @smallexample | |
2435 | void hack (union foo); | |
2436 | /* @r{@dots{}} */ | |
2437 | hack ((union foo) x); | |
2438 | @end smallexample | |
2439 | ||
2440 | @node Mixed Labels and Declarations | |
2441 | @section Mixed Declarations, Labels and Code | |
2442 | @cindex mixed declarations and code | |
2443 | @cindex declarations, mixed with code | |
2444 | @cindex code, mixed with declarations | |
2445 | ||
2446 | ISO C99 and ISO C++ allow declarations and code to be freely mixed | |
2447 | within compound statements. ISO C2X allows labels to be | |
2448 | placed before declarations and at the end of a compound statement. | |
2449 | As an extension, GNU C also allows all this in C90 mode. For example, | |
2450 | you could do: | |
2451 | ||
2452 | @smallexample | |
2453 | int i; | |
2454 | /* @r{@dots{}} */ | |
2455 | i++; | |
2456 | int j = i + 2; | |
2457 | @end smallexample | |
2458 | ||
2459 | Each identifier is visible from where it is declared until the end of | |
2460 | the enclosing block. | |
2461 | ||
2462 | @node Function Attributes | |
2463 | @section Declaring Attributes of Functions | |
2464 | @cindex function attributes | |
2465 | @cindex declaring attributes of functions | |
2466 | @cindex @code{volatile} applied to function | |
2467 | @cindex @code{const} applied to function | |
2468 | ||
2469 | In GNU C and C++, you can use function attributes to specify certain | |
2470 | function properties that may help the compiler optimize calls or | |
2471 | check code more carefully for correctness. For example, you | |
2472 | can use attributes to specify that a function never returns | |
2473 | (@code{noreturn}), returns a value depending only on the values of | |
2474 | its arguments (@code{const}), or has @code{printf}-style arguments | |
2475 | (@code{format}). | |
2476 | ||
2477 | You can also use attributes to control memory placement, code | |
2478 | generation options or call/return conventions within the function | |
2479 | being annotated. Many of these attributes are target-specific. For | |
2480 | example, many targets support attributes for defining interrupt | |
2481 | handler functions, which typically must follow special register usage | |
2482 | and return conventions. Such attributes are described in the subsection | |
2483 | for each target. However, a considerable number of attributes are | |
2484 | supported by most, if not all targets. Those are described in | |
2485 | the @ref{Common Function Attributes} section. | |
2486 | ||
2487 | Function attributes are introduced by the @code{__attribute__} keyword | |
2488 | in the declaration of a function, followed by an attribute specification | |
2489 | enclosed in double parentheses. You can specify multiple attributes in | |
2490 | a declaration by separating them by commas within the double parentheses | |
2491 | or by immediately following one attribute specification with another. | |
2492 | @xref{Attribute Syntax}, for the exact rules on attribute syntax and | |
2493 | placement. Compatible attribute specifications on distinct declarations | |
2494 | of the same function are merged. An attribute specification that is not | |
2495 | compatible with attributes already applied to a declaration of the same | |
2496 | function is ignored with a warning. | |
2497 | ||
2498 | Some function attributes take one or more arguments that refer to | |
2499 | the function's parameters by their positions within the function parameter | |
2500 | list. Such attribute arguments are referred to as @dfn{positional arguments}. | |
2501 | Unless specified otherwise, positional arguments that specify properties | |
2502 | of parameters with pointer types can also specify the same properties of | |
2503 | the implicit C++ @code{this} argument in non-static member functions, and | |
2504 | of parameters of reference to a pointer type. For ordinary functions, | |
2505 | position one refers to the first parameter on the list. In C++ non-static | |
2506 | member functions, position one refers to the implicit @code{this} pointer. | |
2507 | The same restrictions and effects apply to function attributes used with | |
2508 | ordinary functions or C++ member functions. | |
2509 | ||
2510 | GCC also supports attributes on | |
2511 | variable declarations (@pxref{Variable Attributes}), | |
2512 | labels (@pxref{Label Attributes}), | |
2513 | enumerators (@pxref{Enumerator Attributes}), | |
2514 | statements (@pxref{Statement Attributes}), | |
2515 | types (@pxref{Type Attributes}), | |
2516 | and on field declarations (for @code{tainted_args}). | |
2517 | ||
2518 | There is some overlap between the purposes of attributes and pragmas | |
2519 | (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been | |
2520 | found convenient to use @code{__attribute__} to achieve a natural | |
2521 | attachment of attributes to their corresponding declarations, whereas | |
2522 | @code{#pragma} is of use for compatibility with other compilers | |
2523 | or constructs that do not naturally form part of the grammar. | |
2524 | ||
2525 | In addition to the attributes documented here, | |
2526 | GCC plugins may provide their own attributes. | |
2527 | ||
2528 | @menu | |
2529 | * Common Function Attributes:: | |
2530 | * AArch64 Function Attributes:: | |
2531 | * AMD GCN Function Attributes:: | |
2532 | * ARC Function Attributes:: | |
2533 | * ARM Function Attributes:: | |
2534 | * AVR Function Attributes:: | |
2535 | * Blackfin Function Attributes:: | |
2536 | * BPF Function Attributes:: | |
2537 | * C-SKY Function Attributes:: | |
2538 | * Epiphany Function Attributes:: | |
2539 | * H8/300 Function Attributes:: | |
2540 | * IA-64 Function Attributes:: | |
2541 | * M32C Function Attributes:: | |
2542 | * M32R/D Function Attributes:: | |
2543 | * m68k Function Attributes:: | |
2544 | * MCORE Function Attributes:: | |
d77de738 ML |
2545 | * MicroBlaze Function Attributes:: |
2546 | * Microsoft Windows Function Attributes:: | |
2547 | * MIPS Function Attributes:: | |
2548 | * MSP430 Function Attributes:: | |
2549 | * NDS32 Function Attributes:: | |
2550 | * Nios II Function Attributes:: | |
2551 | * Nvidia PTX Function Attributes:: | |
2552 | * PowerPC Function Attributes:: | |
2553 | * RISC-V Function Attributes:: | |
2554 | * RL78 Function Attributes:: | |
2555 | * RX Function Attributes:: | |
2556 | * S/390 Function Attributes:: | |
2557 | * SH Function Attributes:: | |
2558 | * Symbian OS Function Attributes:: | |
2559 | * V850 Function Attributes:: | |
2560 | * Visium Function Attributes:: | |
2561 | * x86 Function Attributes:: | |
2562 | * Xstormy16 Function Attributes:: | |
2563 | @end menu | |
2564 | ||
2565 | @node Common Function Attributes | |
2566 | @subsection Common Function Attributes | |
2567 | ||
2568 | The following attributes are supported on most targets. | |
2569 | ||
2570 | @table @code | |
2571 | @c Keep this table alphabetized by attribute name. Treat _ as space. | |
2572 | ||
2573 | @item access (@var{access-mode}, @var{ref-index}) | |
2574 | @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index}) | |
2575 | ||
2576 | The @code{access} attribute enables the detection of invalid or unsafe | |
2577 | accesses by functions to which they apply or their callers, as well as | |
2578 | write-only accesses to objects that are never read from. Such accesses | |
2579 | may be diagnosed by warnings such as @option{-Wstringop-overflow}, | |
2580 | @option{-Wuninitialized}, @option{-Wunused}, and others. | |
2581 | ||
2582 | The @code{access} attribute specifies that a function to whose by-reference | |
2583 | arguments the attribute applies accesses the referenced object according to | |
2584 | @var{access-mode}. The @var{access-mode} argument is required and must be | |
2585 | one of four names: @code{read_only}, @code{read_write}, @code{write_only}, | |
2586 | or @code{none}. The remaining two are positional arguments. | |
2587 | ||
2588 | The required @var{ref-index} positional argument denotes a function | |
2589 | argument of pointer (or in C++, reference) type that is subject to | |
2590 | the access. The same pointer argument can be referenced by at most one | |
2591 | distinct @code{access} attribute. | |
2592 | ||
2593 | The optional @var{size-index} positional argument denotes a function | |
2594 | argument of integer type that specifies the maximum size of the access. | |
2595 | The size is the number of elements of the type referenced by @var{ref-index}, | |
2596 | or the number of bytes when the pointer type is @code{void*}. When no | |
2597 | @var{size-index} argument is specified, the pointer argument must be either | |
2598 | null or point to a space that is suitably aligned and large for at least one | |
2599 | object of the referenced type (this implies that a past-the-end pointer is | |
2600 | not a valid argument). The actual size of the access may be less but it | |
2601 | must not be more. | |
2602 | ||
2603 | The @code{read_only} access mode specifies that the pointer to which it | |
2604 | applies is used to read the referenced object but not write to it. Unless | |
2605 | the argument specifying the size of the access denoted by @var{size-index} | |
2606 | is zero, the referenced object must be initialized. The mode implies | |
2607 | a stronger guarantee than the @code{const} qualifier which, when cast away | |
2608 | from a pointer, does not prevent the pointed-to object from being modified. | |
2609 | Examples of the use of the @code{read_only} access mode is the argument to | |
2610 | the @code{puts} function, or the second and third arguments to | |
2611 | the @code{memcpy} function. | |
2612 | ||
2613 | @smallexample | |
4ace81b6 SL |
2614 | __attribute__ ((access (read_only, 1))) |
2615 | int puts (const char*); | |
2616 | ||
2617 | __attribute__ ((access (read_only, 2, 3))) | |
2618 | void* memcpy (void*, const void*, size_t); | |
d77de738 ML |
2619 | @end smallexample |
2620 | ||
2621 | The @code{read_write} access mode applies to arguments of pointer types | |
2622 | without the @code{const} qualifier. It specifies that the pointer to which | |
2623 | it applies is used to both read and write the referenced object. Unless | |
2624 | the argument specifying the size of the access denoted by @var{size-index} | |
2625 | is zero, the object referenced by the pointer must be initialized. An example | |
2626 | of the use of the @code{read_write} access mode is the first argument to | |
2627 | the @code{strcat} function. | |
2628 | ||
2629 | @smallexample | |
4ace81b6 SL |
2630 | __attribute__ ((access (read_write, 1), access (read_only, 2))) |
2631 | char* strcat (char*, const char*); | |
d77de738 ML |
2632 | @end smallexample |
2633 | ||
2634 | The @code{write_only} access mode applies to arguments of pointer types | |
2635 | without the @code{const} qualifier. It specifies that the pointer to which | |
2636 | it applies is used to write to the referenced object but not read from it. | |
2637 | The object referenced by the pointer need not be initialized. An example | |
2638 | of the use of the @code{write_only} access mode is the first argument to | |
2639 | the @code{strcpy} function, or the first two arguments to the @code{fgets} | |
2640 | function. | |
2641 | ||
2642 | @smallexample | |
4ace81b6 SL |
2643 | __attribute__ ((access (write_only, 1), access (read_only, 2))) |
2644 | char* strcpy (char*, const char*); | |
2645 | ||
2646 | __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) | |
2647 | int fgets (char*, int, FILE*); | |
d77de738 ML |
2648 | @end smallexample |
2649 | ||
2650 | The access mode @code{none} specifies that the pointer to which it applies | |
2651 | is not used to access the referenced object at all. Unless the pointer is | |
2652 | null the pointed-to object must exist and have at least the size as denoted | |
2653 | by the @var{size-index} argument. When the optional @var{size-index} | |
2654 | argument is omitted for an argument of @code{void*} type the actual pointer | |
2655 | agument is ignored. The referenced object need not be initialized. | |
2656 | The mode is intended to be used as a means to help validate the expected | |
2657 | object size, for example in functions that call @code{__builtin_object_size}. | |
2658 | @xref{Object Size Checking}. | |
2659 | ||
2660 | Note that the @code{access} attribute merely specifies how an object | |
2661 | referenced by the pointer argument can be accessed; it does not imply that | |
2662 | an access @strong{will} happen. Also, the @code{access} attribute does not | |
2663 | imply the attribute @code{nonnull}; it may be appropriate to add both attributes | |
2664 | at the declaration of a function that unconditionally manipulates a buffer via | |
2665 | a pointer argument. See the @code{nonnull} attribute for more information and | |
2666 | caveats. | |
2667 | ||
d77de738 | 2668 | @cindex @code{alias} function attribute |
f33d7a88 | 2669 | @item alias ("@var{target}") |
d77de738 ML |
2670 | The @code{alias} attribute causes the declaration to be emitted as an alias |
2671 | for another symbol, which must have been previously declared with the same | |
2672 | type, and for variables, also the same size and alignment. Declaring an alias | |
2673 | with a different type than the target is undefined and may be diagnosed. As | |
2674 | an example, the following declarations: | |
2675 | ||
2676 | @smallexample | |
2677 | void __f () @{ /* @r{Do something.} */; @} | |
2678 | void f () __attribute__ ((weak, alias ("__f"))); | |
2679 | @end smallexample | |
2680 | ||
2681 | @noindent | |
2682 | define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name | |
2683 | for the target must be used. It is an error if @samp{__f} is not defined in | |
2684 | the same translation unit. | |
2685 | ||
2686 | This attribute requires assembler and object file support, | |
2687 | and may not be available on all targets. | |
2688 | ||
f33d7a88 | 2689 | @cindex @code{aligned} function attribute |
d77de738 ML |
2690 | @item aligned |
2691 | @itemx aligned (@var{alignment}) | |
d77de738 ML |
2692 | The @code{aligned} attribute specifies a minimum alignment for |
2693 | the first instruction of the function, measured in bytes. When specified, | |
2694 | @var{alignment} must be an integer constant power of 2. Specifying no | |
2695 | @var{alignment} argument implies the ideal alignment for the target. | |
2696 | The @code{__alignof__} operator can be used to determine what that is | |
2697 | (@pxref{Alignment}). The attribute has no effect when a definition for | |
2698 | the function is not provided in the same translation unit. | |
2699 | ||
2700 | The attribute cannot be used to decrease the alignment of a function | |
2701 | previously declared with a more restrictive alignment; only to increase | |
2702 | it. Attempts to do otherwise are diagnosed. Some targets specify | |
2703 | a minimum default alignment for functions that is greater than 1. On | |
2704 | such targets, specifying a less restrictive alignment is silently ignored. | |
2705 | Using the attribute overrides the effect of the @option{-falign-functions} | |
2706 | (@pxref{Optimize Options}) option for this function. | |
2707 | ||
2708 | Note that the effectiveness of @code{aligned} attributes may be | |
2709 | limited by inherent limitations in the system linker | |
2710 | and/or object file format. On some systems, the | |
2711 | linker is only able to arrange for functions to be aligned up to a | |
2712 | certain maximum alignment. (For some linkers, the maximum supported | |
2713 | alignment may be very very small.) See your linker documentation for | |
2714 | further information. | |
2715 | ||
2716 | The @code{aligned} attribute can also be used for variables and fields | |
2717 | (@pxref{Variable Attributes}.) | |
2718 | ||
d77de738 | 2719 | @cindex @code{alloc_align} function attribute |
f33d7a88 | 2720 | @item alloc_align (@var{position}) |
d77de738 ML |
2721 | The @code{alloc_align} attribute may be applied to a function that |
2722 | returns a pointer and takes at least one argument of an integer or | |
2723 | enumerated type. | |
2724 | It indicates that the returned pointer is aligned on a boundary given | |
2725 | by the function argument at @var{position}. Meaningful alignments are | |
2726 | powers of 2 greater than one. GCC uses this information to improve | |
2727 | pointer alignment analysis. | |
2728 | ||
2729 | The function parameter denoting the allocated alignment is specified by | |
2730 | one constant integer argument whose number is the argument of the attribute. | |
2731 | Argument numbering starts at one. | |
2732 | ||
2733 | For instance, | |
2734 | ||
2735 | @smallexample | |
2736 | void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1))); | |
2737 | @end smallexample | |
2738 | ||
2739 | @noindent | |
2740 | declares that @code{my_memalign} returns memory with minimum alignment | |
2741 | given by parameter 1. | |
2742 | ||
f33d7a88 | 2743 | @cindex @code{alloc_size} function attribute |
d77de738 ML |
2744 | @item alloc_size (@var{position}) |
2745 | @itemx alloc_size (@var{position-1}, @var{position-2}) | |
d77de738 ML |
2746 | The @code{alloc_size} attribute may be applied to a function that |
2747 | returns a pointer and takes at least one argument of an integer or | |
2748 | enumerated type. | |
2749 | It indicates that the returned pointer points to memory whose size is | |
2750 | given by the function argument at @var{position-1}, or by the product | |
2751 | of the arguments at @var{position-1} and @var{position-2}. Meaningful | |
2752 | sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this | |
2753 | information to improve the results of @code{__builtin_object_size}. | |
2754 | ||
2755 | The function parameter(s) denoting the allocated size are specified by | |
2756 | one or two integer arguments supplied to the attribute. The allocated size | |
2757 | is either the value of the single function argument specified or the product | |
2758 | of the two function arguments specified. Argument numbering starts at | |
2759 | one for ordinary functions, and at two for C++ non-static member functions. | |
2760 | ||
2761 | For instance, | |
2762 | ||
2763 | @smallexample | |
2764 | void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2))); | |
2765 | void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2))); | |
2766 | @end smallexample | |
2767 | ||
2768 | @noindent | |
2769 | declares that @code{my_calloc} returns memory of the size given by | |
2770 | the product of parameter 1 and 2 and that @code{my_realloc} returns memory | |
2771 | of the size given by parameter 2. | |
2772 | ||
d77de738 | 2773 | @cindex @code{always_inline} function attribute |
f33d7a88 | 2774 | @item always_inline |
d77de738 ML |
2775 | Generally, functions are not inlined unless optimization is specified. |
2776 | For functions declared inline, this attribute inlines the function | |
2777 | independent of any restrictions that otherwise apply to inlining. | |
2778 | Failure to inline such a function is diagnosed as an error. | |
2779 | Note that if such a function is called indirectly the compiler may | |
2780 | or may not inline it depending on optimization level and a failure | |
2781 | to inline an indirect call may or may not be diagnosed. | |
2782 | ||
d77de738 | 2783 | @cindex @code{artificial} function attribute |
f33d7a88 | 2784 | @item artificial |
d77de738 ML |
2785 | This attribute is useful for small inline wrappers that if possible |
2786 | should appear during debugging as a unit. Depending on the debug | |
2787 | info format it either means marking the function as artificial | |
2788 | or using the caller location for all instructions within the inlined | |
2789 | body. | |
2790 | ||
f33d7a88 | 2791 | @cindex @code{assume_aligned} function attribute |
d77de738 ML |
2792 | @item assume_aligned (@var{alignment}) |
2793 | @itemx assume_aligned (@var{alignment}, @var{offset}) | |
d77de738 ML |
2794 | The @code{assume_aligned} attribute may be applied to a function that |
2795 | returns a pointer. It indicates that the returned pointer is aligned | |
2796 | on a boundary given by @var{alignment}. If the attribute has two | |
2797 | arguments, the second argument is misalignment @var{offset}. Meaningful | |
2798 | values of @var{alignment} are powers of 2 greater than one. Meaningful | |
2799 | values of @var{offset} are greater than zero and less than @var{alignment}. | |
2800 | ||
2801 | For instance | |
2802 | ||
2803 | @smallexample | |
2804 | void* my_alloc1 (size_t) __attribute__((assume_aligned (16))); | |
2805 | void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8))); | |
2806 | @end smallexample | |
2807 | ||
2808 | @noindent | |
2809 | declares that @code{my_alloc1} returns 16-byte aligned pointers and | |
2810 | that @code{my_alloc2} returns a pointer whose value modulo 32 is equal | |
2811 | to 8. | |
2812 | ||
d77de738 | 2813 | @cindex @code{cold} function attribute |
f33d7a88 | 2814 | @item cold |
d77de738 ML |
2815 | The @code{cold} attribute on functions is used to inform the compiler that |
2816 | the function is unlikely to be executed. The function is optimized for | |
2817 | size rather than speed and on many targets it is placed into a special | |
2818 | subsection of the text section so all cold functions appear close together, | |
2819 | improving code locality of non-cold parts of program. The paths leading | |
2820 | to calls of cold functions within code are marked as unlikely by the branch | |
2821 | prediction mechanism. It is thus useful to mark functions used to handle | |
2822 | unlikely conditions, such as @code{perror}, as cold to improve optimization | |
2823 | of hot functions that do call marked functions in rare occasions. | |
2824 | ||
2825 | When profile feedback is available, via @option{-fprofile-use}, cold functions | |
2826 | are automatically detected and this attribute is ignored. | |
2827 | ||
d77de738 ML |
2828 | @cindex @code{const} function attribute |
2829 | @cindex functions that have no side effects | |
f33d7a88 | 2830 | @item const |
d77de738 ML |
2831 | Calls to functions whose return value is not affected by changes to |
2832 | the observable state of the program and that have no observable effects | |
2833 | on such state other than to return a value may lend themselves to | |
2834 | optimizations such as common subexpression elimination. Declaring such | |
2835 | functions with the @code{const} attribute allows GCC to avoid emitting | |
2836 | some calls in repeated invocations of the function with the same argument | |
2837 | values. | |
2838 | ||
2839 | For example, | |
2840 | ||
2841 | @smallexample | |
2842 | int square (int) __attribute__ ((const)); | |
2843 | @end smallexample | |
2844 | ||
2845 | @noindent | |
2846 | tells GCC that subsequent calls to function @code{square} with the same | |
2847 | argument value can be replaced by the result of the first call regardless | |
2848 | of the statements in between. | |
2849 | ||
2850 | The @code{const} attribute prohibits a function from reading objects | |
2851 | that affect its return value between successive invocations. However, | |
2852 | functions declared with the attribute can safely read objects that do | |
2853 | not change their return value, such as non-volatile constants. | |
2854 | ||
2855 | The @code{const} attribute imposes greater restrictions on a function's | |
2856 | definition than the similar @code{pure} attribute. Declaring the same | |
2857 | function with both the @code{const} and the @code{pure} attribute is | |
2858 | diagnosed. Because a const function cannot have any observable side | |
2859 | effects it does not make sense for it to return @code{void}. Declaring | |
2860 | such a function is diagnosed. | |
2861 | ||
2862 | @cindex pointer arguments | |
2863 | Note that a function that has pointer arguments and examines the data | |
2864 | pointed to must @emph{not} be declared @code{const} if the pointed-to | |
2865 | data might change between successive invocations of the function. In | |
2866 | general, since a function cannot distinguish data that might change | |
2867 | from data that cannot, const functions should never take pointer or, | |
2868 | in C++, reference arguments. Likewise, a function that calls a non-const | |
2869 | function usually must not be const itself. | |
2870 | ||
f33d7a88 AA |
2871 | @cindex @code{constructor} function attribute |
2872 | @cindex @code{destructor} function attribute | |
d77de738 ML |
2873 | @item constructor |
2874 | @itemx destructor | |
2875 | @itemx constructor (@var{priority}) | |
2876 | @itemx destructor (@var{priority}) | |
d77de738 ML |
2877 | The @code{constructor} attribute causes the function to be called |
2878 | automatically before execution enters @code{main ()}. Similarly, the | |
2879 | @code{destructor} attribute causes the function to be called | |
2880 | automatically after @code{main ()} completes or @code{exit ()} is | |
2881 | called. Functions with these attributes are useful for | |
2882 | initializing data that is used implicitly during the execution of | |
2883 | the program. | |
2884 | ||
2885 | On some targets the attributes also accept an integer argument to | |
2886 | specify a priority to control the order in which constructor and | |
2887 | destructor functions are run. A constructor | |
2888 | with a smaller priority number runs before a constructor with a larger | |
2889 | priority number; the opposite relationship holds for destructors. Note | |
2890 | that priorities 0-100 are reserved. So, if you have a constructor that | |
2891 | allocates a resource and a destructor that deallocates the same | |
2892 | resource, both functions typically have the same priority. The | |
2893 | priorities for constructor and destructor functions are the same as | |
2894 | those specified for namespace-scope C++ objects (@pxref{C++ Attributes}). | |
2895 | However, at present, the order in which constructors for C++ objects | |
2896 | with static storage duration and functions decorated with attribute | |
2897 | @code{constructor} are invoked is unspecified. In mixed declarations, | |
2898 | attribute @code{init_priority} can be used to impose a specific ordering. | |
2899 | ||
2900 | Using the argument forms of the @code{constructor} and @code{destructor} | |
2901 | attributes on targets where the feature is not supported is rejected with | |
2902 | an error. | |
2903 | ||
f33d7a88 | 2904 | @cindex @code{copy} function attribute |
d77de738 ML |
2905 | @item copy |
2906 | @itemx copy (@var{function}) | |
d77de738 ML |
2907 | The @code{copy} attribute applies the set of attributes with which |
2908 | @var{function} has been declared to the declaration of the function | |
2909 | to which the attribute is applied. The attribute is designed for | |
2910 | libraries that define aliases or function resolvers that are expected | |
2911 | to specify the same set of attributes as their targets. The @code{copy} | |
2912 | attribute can be used with functions, variables, or types. However, | |
2913 | the kind of symbol to which the attribute is applied (either function | |
2914 | or variable) must match the kind of symbol to which the argument refers. | |
2915 | The @code{copy} attribute copies only syntactic and semantic attributes | |
2916 | but not attributes that affect a symbol's linkage or visibility such as | |
2917 | @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} | |
2918 | and @code{target_clones} attribute are also not copied. | |
2919 | @xref{Common Type Attributes}. | |
2920 | @xref{Common Variable Attributes}. | |
2921 | ||
2922 | For example, the @var{StrongAlias} macro below makes use of the @code{alias} | |
2923 | and @code{copy} attributes to define an alias named @var{alloc} for function | |
2924 | @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and | |
2925 | @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has | |
2926 | the same type as the target function. As a result of the @code{copy} | |
2927 | attribute the alias also shares the same attributes as the target. | |
2928 | ||
2929 | @smallexample | |
2930 | #define StrongAlias(TargetFunc, AliasDecl) \ | |
2931 | extern __typeof__ (TargetFunc) AliasDecl \ | |
2932 | __attribute__ ((alias (#TargetFunc), copy (TargetFunc))); | |
2933 | ||
2934 | extern __attribute__ ((alloc_size (1), malloc, nothrow)) | |
2935 | void* allocate (size_t); | |
2936 | StrongAlias (allocate, alloc); | |
2937 | @end smallexample | |
2938 | ||
f33d7a88 | 2939 | @cindex @code{deprecated} function attribute |
d77de738 ML |
2940 | @item deprecated |
2941 | @itemx deprecated (@var{msg}) | |
d77de738 ML |
2942 | The @code{deprecated} attribute results in a warning if the function |
2943 | is used anywhere in the source file. This is useful when identifying | |
2944 | functions that are expected to be removed in a future version of a | |
2945 | program. The warning also includes the location of the declaration | |
2946 | of the deprecated function, to enable users to easily find further | |
2947 | information about why the function is deprecated, or what they should | |
2948 | do instead. Note that the warnings only occurs for uses: | |
2949 | ||
2950 | @smallexample | |
2951 | int old_fn () __attribute__ ((deprecated)); | |
2952 | int old_fn (); | |
2953 | int (*fn_ptr)() = old_fn; | |
2954 | @end smallexample | |
2955 | ||
2956 | @noindent | |
2957 | results in a warning on line 3 but not line 2. The optional @var{msg} | |
2958 | argument, which must be a string, is printed in the warning if | |
2959 | present. | |
2960 | ||
2961 | The @code{deprecated} attribute can also be used for variables and | |
2962 | types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) | |
2963 | ||
2964 | The message attached to the attribute is affected by the setting of | |
2965 | the @option{-fmessage-length} option. | |
2966 | ||
f33d7a88 | 2967 | @cindex @code{unavailable} function attribute |
d77de738 ML |
2968 | @item unavailable |
2969 | @itemx unavailable (@var{msg}) | |
d77de738 ML |
2970 | The @code{unavailable} attribute results in an error if the function |
2971 | is used anywhere in the source file. This is useful when identifying | |
2972 | functions that have been removed from a particular variation of an | |
2973 | interface. Other than emitting an error rather than a warning, the | |
2974 | @code{unavailable} attribute behaves in the same manner as | |
2975 | @code{deprecated}. | |
2976 | ||
2977 | The @code{unavailable} attribute can also be used for variables and | |
2978 | types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) | |
2979 | ||
d77de738 ML |
2980 | @cindex @code{error} function attribute |
2981 | @cindex @code{warning} function attribute | |
f33d7a88 AA |
2982 | @item error ("@var{message}") |
2983 | @itemx warning ("@var{message}") | |
d77de738 ML |
2984 | If the @code{error} or @code{warning} attribute |
2985 | is used on a function declaration and a call to such a function | |
2986 | is not eliminated through dead code elimination or other optimizations, | |
2987 | an error or warning (respectively) that includes @var{message} is diagnosed. | |
2988 | This is useful | |
2989 | for compile-time checking, especially together with @code{__builtin_constant_p} | |
2990 | and inline functions where checking the inline function arguments is not | |
2991 | possible through @code{extern char [(condition) ? 1 : -1];} tricks. | |
2992 | ||
2993 | While it is possible to leave the function undefined and thus invoke | |
2994 | a link failure (to define the function with | |
2995 | a message in @code{.gnu.warning*} section), | |
2996 | when using these attributes the problem is diagnosed | |
2997 | earlier and with exact location of the call even in presence of inline | |
2998 | functions or when not emitting debugging information. | |
2999 | ||
d77de738 | 3000 | @cindex @code{externally_visible} function attribute |
f33d7a88 | 3001 | @item externally_visible |
d77de738 ML |
3002 | This attribute, attached to a global variable or function, nullifies |
3003 | the effect of the @option{-fwhole-program} command-line option, so the | |
3004 | object remains visible outside the current compilation unit. | |
3005 | ||
3006 | If @option{-fwhole-program} is used together with @option{-flto} and | |
3007 | @command{gold} is used as the linker plugin, | |
3008 | @code{externally_visible} attributes are automatically added to functions | |
3009 | (not variable yet due to a current @command{gold} issue) | |
3010 | that are accessed outside of LTO objects according to resolution file | |
3011 | produced by @command{gold}. | |
3012 | For other linkers that cannot generate resolution file, | |
3013 | explicit @code{externally_visible} attributes are still necessary. | |
3014 | ||
f33d7a88 | 3015 | @cindex @code{fd_arg} function attribute |
d77de738 ML |
3016 | @item fd_arg |
3017 | @itemx fd_arg (@var{N}) | |
d77de738 ML |
3018 | The @code{fd_arg} attribute may be applied to a function that takes an open |
3019 | file descriptor at referenced argument @var{N}. | |
3020 | ||
3021 | It indicates that the passed filedescriptor must not have been closed. | |
3022 | Therefore, when the analyzer is enabled with @option{-fanalyzer}, the | |
3023 | analyzer may emit a @option{-Wanalyzer-fd-use-after-close} diagnostic | |
3024 | if it detects a code path in which a function with this attribute is | |
3025 | called with a closed file descriptor. | |
3026 | ||
3027 | The attribute also indicates that the file descriptor must have been checked for | |
3028 | validity before usage. Therefore, analyzer may emit | |
3029 | @option{-Wanalyzer-fd-use-without-check} diagnostic if it detects a code path in | |
3030 | which a function with this attribute is called with a file descriptor that has | |
3031 | not been checked for validity. | |
3032 | ||
f33d7a88 | 3033 | @cindex @code{fd_arg_read} function attribute |
d77de738 ML |
3034 | @item fd_arg_read |
3035 | @itemx fd_arg_read (@var{N}) | |
d77de738 ML |
3036 | The @code{fd_arg_read} is identical to @code{fd_arg}, but with the additional |
3037 | requirement that it might read from the file descriptor, and thus, the file | |
3038 | descriptor must not have been opened as write-only. | |
3039 | ||
3040 | The analyzer may emit a @option{-Wanalyzer-access-mode-mismatch} | |
3041 | diagnostic if it detects a code path in which a function with this | |
3042 | attribute is called on a file descriptor opened with @code{O_WRONLY}. | |
3043 | ||
f33d7a88 | 3044 | @cindex @code{fd_arg_write} function attribute |
d77de738 ML |
3045 | @item fd_arg_write |
3046 | @itemx fd_arg_write (@var{N}) | |
d77de738 ML |
3047 | The @code{fd_arg_write} is identical to @code{fd_arg_read} except that the |
3048 | analyzer may emit a @option{-Wanalyzer-access-mode-mismatch} diagnostic if | |
3049 | it detects a code path in which a function with this attribute is called on a | |
3050 | file descriptor opened with @code{O_RDONLY}. | |
3051 | ||
d77de738 | 3052 | @cindex @code{flatten} function attribute |
f33d7a88 | 3053 | @item flatten |
d77de738 ML |
3054 | Generally, inlining into a function is limited. For a function marked with |
3055 | this attribute, every call inside this function is inlined, if possible. | |
3056 | Functions declared with attribute @code{noinline} and similar are not | |
3057 | inlined. Whether the function itself is considered for inlining depends | |
3058 | on its size and the current inlining parameters. | |
3059 | ||
d77de738 ML |
3060 | @cindex @code{format} function attribute |
3061 | @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments | |
3062 | @opindex Wformat | |
f33d7a88 | 3063 | @item format (@var{archetype}, @var{string-index}, @var{first-to-check}) |
d77de738 ML |
3064 | The @code{format} attribute specifies that a function takes @code{printf}, |
3065 | @code{scanf}, @code{strftime} or @code{strfmon} style arguments that | |
3066 | should be type-checked against a format string. For example, the | |
3067 | declaration: | |
3068 | ||
3069 | @smallexample | |
3070 | extern int | |
3071 | my_printf (void *my_object, const char *my_format, ...) | |
3072 | __attribute__ ((format (printf, 2, 3))); | |
3073 | @end smallexample | |
3074 | ||
3075 | @noindent | |
3076 | causes the compiler to check the arguments in calls to @code{my_printf} | |
3077 | for consistency with the @code{printf} style format string argument | |
3078 | @code{my_format}. | |
3079 | ||
3080 | The parameter @var{archetype} determines how the format string is | |
3081 | interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, | |
3082 | @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or | |
3083 | @code{strfmon}. (You can also use @code{__printf__}, | |
3084 | @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On | |
3085 | MinGW targets, @code{ms_printf}, @code{ms_scanf}, and | |
3086 | @code{ms_strftime} are also present. | |
3087 | @var{archetype} values such as @code{printf} refer to the formats accepted | |
3088 | by the system's C runtime library, | |
3089 | while values prefixed with @samp{gnu_} always refer | |
3090 | to the formats accepted by the GNU C Library. On Microsoft Windows | |
3091 | targets, values prefixed with @samp{ms_} refer to the formats accepted by the | |
3092 | @file{msvcrt.dll} library. | |
3093 | The parameter @var{string-index} | |
3094 | specifies which argument is the format string argument (starting | |
3095 | from 1), while @var{first-to-check} is the number of the first | |
3096 | argument to check against the format string. For functions | |
3097 | where the arguments are not available to be checked (such as | |
3098 | @code{vprintf}), specify the third parameter as zero. In this case the | |
3099 | compiler only checks the format string for consistency. For | |
3100 | @code{strftime} formats, the third parameter is required to be zero. | |
3101 | Since non-static C++ methods have an implicit @code{this} argument, the | |
3102 | arguments of such methods should be counted from two, not one, when | |
3103 | giving values for @var{string-index} and @var{first-to-check}. | |
3104 | ||
3105 | In the example above, the format string (@code{my_format}) is the second | |
3106 | argument of the function @code{my_print}, and the arguments to check | |
3107 | start with the third argument, so the correct parameters for the format | |
3108 | attribute are 2 and 3. | |
3109 | ||
3110 | @opindex ffreestanding | |
3111 | @opindex fno-builtin | |
3112 | The @code{format} attribute allows you to identify your own functions | |
3113 | that take format strings as arguments, so that GCC can check the | |
3114 | calls to these functions for errors. The compiler always (unless | |
3115 | @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats | |
3116 | for the standard library functions @code{printf}, @code{fprintf}, | |
3117 | @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, | |
3118 | @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such | |
3119 | warnings are requested (using @option{-Wformat}), so there is no need to | |
3120 | modify the header file @file{stdio.h}. In C99 mode, the functions | |
3121 | @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and | |
3122 | @code{vsscanf} are also checked. Except in strictly conforming C | |
3123 | standard modes, the X/Open function @code{strfmon} is also checked as | |
3124 | are @code{printf_unlocked} and @code{fprintf_unlocked}. | |
3125 | @xref{C Dialect Options,,Options Controlling C Dialect}. | |
3126 | ||
3127 | For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is | |
3128 | recognized in the same context. Declarations including these format attributes | |
3129 | are parsed for correct syntax, however the result of checking of such format | |
3130 | strings is not yet defined, and is not carried out by this version of the | |
3131 | compiler. | |
3132 | ||
3133 | The target may also provide additional types of format checks. | |
3134 | @xref{Target Format Checks,,Format Checks Specific to Particular | |
3135 | Target Machines}. | |
3136 | ||
d77de738 ML |
3137 | @cindex @code{format_arg} function attribute |
3138 | @opindex Wformat-nonliteral | |
f33d7a88 | 3139 | @item format_arg (@var{string-index}) |
d77de738 ML |
3140 | The @code{format_arg} attribute specifies that a function takes one or |
3141 | more format strings for a @code{printf}, @code{scanf}, @code{strftime} or | |
3142 | @code{strfmon} style function and modifies it (for example, to translate | |
3143 | it into another language), so the result can be passed to a | |
3144 | @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style | |
3145 | function (with the remaining arguments to the format function the same | |
3146 | as they would have been for the unmodified string). Multiple | |
3147 | @code{format_arg} attributes may be applied to the same function, each | |
3148 | designating a distinct parameter as a format string. For example, the | |
3149 | declaration: | |
3150 | ||
3151 | @smallexample | |
3152 | extern char * | |
3153 | my_dgettext (char *my_domain, const char *my_format) | |
3154 | __attribute__ ((format_arg (2))); | |
3155 | @end smallexample | |
3156 | ||
3157 | @noindent | |
3158 | causes the compiler to check the arguments in calls to a @code{printf}, | |
3159 | @code{scanf}, @code{strftime} or @code{strfmon} type function, whose | |
3160 | format string argument is a call to the @code{my_dgettext} function, for | |
3161 | consistency with the format string argument @code{my_format}. If the | |
3162 | @code{format_arg} attribute had not been specified, all the compiler | |
3163 | could tell in such calls to format functions would be that the format | |
3164 | string argument is not constant; this would generate a warning when | |
3165 | @option{-Wformat-nonliteral} is used, but the calls could not be checked | |
3166 | without the attribute. | |
3167 | ||
3168 | In calls to a function declared with more than one @code{format_arg} | |
3169 | attribute, each with a distinct argument value, the corresponding | |
3170 | actual function arguments are checked against all format strings | |
3171 | designated by the attributes. This capability is designed to support | |
3172 | the GNU @code{ngettext} family of functions. | |
3173 | ||
3174 | The parameter @var{string-index} specifies which argument is the format | |
3175 | string argument (starting from one). Since non-static C++ methods have | |
3176 | an implicit @code{this} argument, the arguments of such methods should | |
3177 | be counted from two. | |
3178 | ||
3179 | The @code{format_arg} attribute allows you to identify your own | |
3180 | functions that modify format strings, so that GCC can check the | |
3181 | calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} | |
3182 | type function whose operands are a call to one of your own function. | |
3183 | The compiler always treats @code{gettext}, @code{dgettext}, and | |
3184 | @code{dcgettext} in this manner except when strict ISO C support is | |
3185 | requested by @option{-ansi} or an appropriate @option{-std} option, or | |
3186 | @option{-ffreestanding} or @option{-fno-builtin} | |
3187 | is used. @xref{C Dialect Options,,Options | |
3188 | Controlling C Dialect}. | |
3189 | ||
3190 | For Objective-C dialects, the @code{format-arg} attribute may refer to an | |
3191 | @code{NSString} reference for compatibility with the @code{format} attribute | |
3192 | above. | |
3193 | ||
3194 | The target may also allow additional types in @code{format-arg} attributes. | |
3195 | @xref{Target Format Checks,,Format Checks Specific to Particular | |
3196 | Target Machines}. | |
3197 | ||
d77de738 | 3198 | @cindex @code{gnu_inline} function attribute |
f33d7a88 | 3199 | @item gnu_inline |
d77de738 ML |
3200 | This attribute should be used with a function that is also declared |
3201 | with the @code{inline} keyword. It directs GCC to treat the function | |
3202 | as if it were defined in gnu90 mode even when compiling in C99 or | |
3203 | gnu99 mode. | |
3204 | ||
3205 | If the function is declared @code{extern}, then this definition of the | |
3206 | function is used only for inlining. In no case is the function | |
3207 | compiled as a standalone function, not even if you take its address | |
3208 | explicitly. Such an address becomes an external reference, as if you | |
3209 | had only declared the function, and had not defined it. This has | |
3210 | almost the effect of a macro. The way to use this is to put a | |
3211 | function definition in a header file with this attribute, and put | |
3212 | another copy of the function, without @code{extern}, in a library | |
3213 | file. The definition in the header file causes most calls to the | |
3214 | function to be inlined. If any uses of the function remain, they | |
3215 | refer to the single copy in the library. Note that the two | |
3216 | definitions of the functions need not be precisely the same, although | |
3217 | if they do not have the same effect your program may behave oddly. | |
3218 | ||
3219 | In C, if the function is neither @code{extern} nor @code{static}, then | |
3220 | the function is compiled as a standalone function, as well as being | |
3221 | inlined where possible. | |
3222 | ||
3223 | This is how GCC traditionally handled functions declared | |
3224 | @code{inline}. Since ISO C99 specifies a different semantics for | |
3225 | @code{inline}, this function attribute is provided as a transition | |
3226 | measure and as a useful feature in its own right. This attribute is | |
3227 | available in GCC 4.1.3 and later. It is available if either of the | |
3228 | preprocessor macros @code{__GNUC_GNU_INLINE__} or | |
3229 | @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline | |
3230 | Function is As Fast As a Macro}. | |
3231 | ||
3232 | In C++, this attribute does not depend on @code{extern} in any way, | |
3233 | but it still requires the @code{inline} keyword to enable its special | |
3234 | behavior. | |
3235 | ||
d77de738 | 3236 | @cindex @code{hot} function attribute |
f33d7a88 | 3237 | @item hot |
d77de738 ML |
3238 | The @code{hot} attribute on a function is used to inform the compiler that |
3239 | the function is a hot spot of the compiled program. The function is | |
3240 | optimized more aggressively and on many targets it is placed into a special | |
3241 | subsection of the text section so all hot functions appear close together, | |
3242 | improving locality. | |
3243 | ||
3244 | When profile feedback is available, via @option{-fprofile-use}, hot functions | |
3245 | are automatically detected and this attribute is ignored. | |
3246 | ||
d77de738 ML |
3247 | @cindex @code{ifunc} function attribute |
3248 | @cindex indirect functions | |
3249 | @cindex functions that are dynamically resolved | |
f33d7a88 | 3250 | @item ifunc ("@var{resolver}") |
d77de738 ML |
3251 | The @code{ifunc} attribute is used to mark a function as an indirect |
3252 | function using the STT_GNU_IFUNC symbol type extension to the ELF | |
3253 | standard. This allows the resolution of the symbol value to be | |
3254 | determined dynamically at load time, and an optimized version of the | |
3255 | routine to be selected for the particular processor or other system | |
3256 | characteristics determined then. To use this attribute, first define | |
3257 | the implementation functions available, and a resolver function that | |
3258 | returns a pointer to the selected implementation function. The | |
3259 | implementation functions' declarations must match the API of the | |
3260 | function being implemented. The resolver should be declared to | |
3261 | be a function taking no arguments and returning a pointer to | |
3262 | a function of the same type as the implementation. For example: | |
3263 | ||
3264 | @smallexample | |
3265 | void *my_memcpy (void *dst, const void *src, size_t len) | |
3266 | @{ | |
3267 | @dots{} | |
3268 | return dst; | |
3269 | @} | |
3270 | ||
3271 | static void * (*resolve_memcpy (void))(void *, const void *, size_t) | |
3272 | @{ | |
3273 | return my_memcpy; // we will just always select this routine | |
3274 | @} | |
3275 | @end smallexample | |
3276 | ||
3277 | @noindent | |
3278 | The exported header file declaring the function the user calls would | |
3279 | contain: | |
3280 | ||
3281 | @smallexample | |
3282 | extern void *memcpy (void *, const void *, size_t); | |
3283 | @end smallexample | |
3284 | ||
3285 | @noindent | |
3286 | allowing the user to call @code{memcpy} as a regular function, unaware of | |
3287 | the actual implementation. Finally, the indirect function needs to be | |
3288 | defined in the same translation unit as the resolver function: | |
3289 | ||
3290 | @smallexample | |
3291 | void *memcpy (void *, const void *, size_t) | |
3292 | __attribute__ ((ifunc ("resolve_memcpy"))); | |
3293 | @end smallexample | |
3294 | ||
3295 | In C++, the @code{ifunc} attribute takes a string that is the mangled name | |
3296 | of the resolver function. A C++ resolver for a non-static member function | |
3297 | of class @code{C} should be declared to return a pointer to a non-member | |
3298 | function taking pointer to @code{C} as the first argument, followed by | |
3299 | the same arguments as of the implementation function. G++ checks | |
3300 | the signatures of the two functions and issues | |
3301 | a @option{-Wattribute-alias} warning for mismatches. To suppress a warning | |
3302 | for the necessary cast from a pointer to the implementation member function | |
3303 | to the type of the corresponding non-member function use | |
3304 | the @option{-Wno-pmf-conversions} option. For example: | |
3305 | ||
3306 | @smallexample | |
3307 | class S | |
3308 | @{ | |
3309 | private: | |
3310 | int debug_impl (int); | |
3311 | int optimized_impl (int); | |
3312 | ||
3313 | typedef int Func (S*, int); | |
3314 | ||
3315 | static Func* resolver (); | |
3316 | public: | |
3317 | ||
3318 | int interface (int); | |
3319 | @}; | |
3320 | ||
3321 | int S::debug_impl (int) @{ /* @r{@dots{}} */ @} | |
3322 | int S::optimized_impl (int) @{ /* @r{@dots{}} */ @} | |
3323 | ||
3324 | S::Func* S::resolver () | |
3325 | @{ | |
3326 | int (S::*pimpl) (int) | |
3327 | = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl; | |
3328 | ||
3329 | // Cast triggers -Wno-pmf-conversions. | |
3330 | return reinterpret_cast<Func*>(pimpl); | |
3331 | @} | |
3332 | ||
3333 | int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv"))); | |
3334 | @end smallexample | |
3335 | ||
3336 | Indirect functions cannot be weak. Binutils version 2.20.1 or higher | |
3337 | and GNU C Library version 2.11.1 are required to use this feature. | |
3338 | ||
3339 | @item interrupt | |
3340 | @itemx interrupt_handler | |
3341 | Many GCC back ends support attributes to indicate that a function is | |
3342 | an interrupt handler, which tells the compiler to generate function | |
3343 | entry and exit sequences that differ from those from regular | |
3344 | functions. The exact syntax and behavior are target-specific; | |
3345 | refer to the following subsections for details. | |
3346 | ||
d77de738 | 3347 | @cindex @code{leaf} function attribute |
f33d7a88 | 3348 | @item leaf |
d77de738 ML |
3349 | Calls to external functions with this attribute must return to the |
3350 | current compilation unit only by return or by exception handling. In | |
3351 | particular, a leaf function is not allowed to invoke callback functions | |
3352 | passed to it from the current compilation unit, directly call functions | |
3353 | exported by the unit, or @code{longjmp} into the unit. Leaf functions | |
3354 | might still call functions from other compilation units and thus they | |
3355 | are not necessarily leaf in the sense that they contain no function | |
3356 | calls at all. | |
3357 | ||
3358 | The attribute is intended for library functions to improve dataflow | |
3359 | analysis. The compiler takes the hint that any data not escaping the | |
3360 | current compilation unit cannot be used or modified by the leaf | |
3361 | function. For example, the @code{sin} function is a leaf function, but | |
3362 | @code{qsort} is not. | |
3363 | ||
3364 | Note that leaf functions might indirectly run a signal handler defined | |
3365 | in the current compilation unit that uses static variables. Similarly, | |
3366 | when lazy symbol resolution is in effect, leaf functions might invoke | |
3367 | indirect functions whose resolver function or implementation function is | |
3368 | defined in the current compilation unit and uses static variables. There | |
3369 | is no standard-compliant way to write such a signal handler, resolver | |
3370 | function, or implementation function, and the best that you can do is to | |
3371 | remove the @code{leaf} attribute or mark all such static variables | |
3372 | @code{volatile}. Lastly, for ELF-based systems that support symbol | |
3373 | interposition, care should be taken that functions defined in the | |
3374 | current compilation unit do not unexpectedly interpose other symbols | |
3375 | based on the defined standards mode and defined feature test macros; | |
3376 | otherwise an inadvertent callback would be added. | |
3377 | ||
3378 | The attribute has no effect on functions defined within the current | |
3379 | compilation unit. This is to allow easy merging of multiple compilation | |
3380 | units into one, for example, by using the link-time optimization. For | |
3381 | this reason the attribute is not allowed on types to annotate indirect | |
3382 | calls. | |
3383 | ||
f33d7a88 AA |
3384 | @cindex @code{malloc} function attribute |
3385 | @cindex functions that behave like malloc | |
d77de738 ML |
3386 | @item malloc |
3387 | @item malloc (@var{deallocator}) | |
3388 | @item malloc (@var{deallocator}, @var{ptr-index}) | |
d77de738 ML |
3389 | Attribute @code{malloc} indicates that a function is @code{malloc}-like, |
3390 | i.e., that the pointer @var{P} returned by the function cannot alias any | |
3391 | other pointer valid when the function returns, and moreover no | |
3392 | pointers to valid objects occur in any storage addressed by @var{P}. In | |
dfc5ea6b | 3393 | addition, GCC predicts that a function with the attribute returns |
d77de738 ML |
3394 | non-null in most cases. |
3395 | ||
3396 | Independently, the form of the attribute with one or two arguments | |
3397 | associates @code{deallocator} as a suitable deallocation function for | |
3398 | pointers returned from the @code{malloc}-like function. @var{ptr-index} | |
3399 | denotes the positional argument to which when the pointer is passed in | |
3400 | calls to @code{deallocator} has the effect of deallocating it. | |
3401 | ||
3402 | Using the attribute with no arguments is designed to improve optimization | |
3403 | by relying on the aliasing property it implies. Functions like @code{malloc} | |
3404 | and @code{calloc} have this property because they return a pointer to | |
3405 | uninitialized or zeroed-out, newly obtained storage. However, functions | |
3406 | like @code{realloc} do not have this property, as they may return pointers | |
3407 | to storage containing pointers to existing objects. Additionally, since | |
3408 | all such functions are assumed to return null only infrequently, callers | |
3409 | can be optimized based on that assumption. | |
3410 | ||
3411 | Associating a function with a @var{deallocator} helps detect calls to | |
3412 | mismatched allocation and deallocation functions and diagnose them under | |
3413 | the control of options such as @option{-Wmismatched-dealloc}. It also | |
3414 | makes it possible to diagnose attempts to deallocate objects that were not | |
3415 | allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate | |
3416 | that an allocation function both satisifies the nonaliasing property and | |
3417 | has a deallocator associated with it, both the plain form of the attribute | |
3418 | and the one with the @var{deallocator} argument must be used. The same | |
3419 | function can be both an allocator and a deallocator. Since inlining one | |
3420 | of the associated functions but not the other could result in apparent | |
3421 | mismatches, this form of attribute @code{malloc} is not accepted on inline | |
3422 | functions. For the same reason, using the attribute prevents both | |
3423 | the allocation and deallocation functions from being expanded inline. | |
3424 | ||
3425 | For example, besides stating that the functions return pointers that do | |
3426 | not alias any others, the following declarations make @code{fclose} | |
3427 | a suitable deallocator for pointers returned from all functions except | |
3428 | @code{popen}, and @code{pclose} as the only suitable deallocator for | |
3429 | pointers returned from @code{popen}. The deallocator functions must | |
3430 | be declared before they can be referenced in the attribute. | |
3431 | ||
3432 | @smallexample | |
3433 | int fclose (FILE*); | |
3434 | int pclose (FILE*); | |
3435 | ||
3436 | __attribute__ ((malloc, malloc (fclose, 1))) | |
3437 | FILE* fdopen (int, const char*); | |
3438 | __attribute__ ((malloc, malloc (fclose, 1))) | |
3439 | FILE* fopen (const char*, const char*); | |
3440 | __attribute__ ((malloc, malloc (fclose, 1))) | |
3441 | FILE* fmemopen(void *, size_t, const char *); | |
3442 | __attribute__ ((malloc, malloc (pclose, 1))) | |
3443 | FILE* popen (const char*, const char*); | |
3444 | __attribute__ ((malloc, malloc (fclose, 1))) | |
3445 | FILE* tmpfile (void); | |
3446 | @end smallexample | |
3447 | ||
3448 | The warnings guarded by @option{-fanalyzer} respect allocation and | |
3449 | deallocation pairs marked with the @code{malloc}. In particular: | |
3450 | ||
3451 | @itemize @bullet | |
3452 | ||
3453 | @item | |
4ace81b6 | 3454 | The analyzer emits a @option{-Wanalyzer-mismatching-deallocation} |
d77de738 ML |
3455 | diagnostic if there is an execution path in which the result of an |
3456 | allocation call is passed to a different deallocator. | |
3457 | ||
3458 | @item | |
4ace81b6 | 3459 | The analyzer emits a @option{-Wanalyzer-double-free} |
d77de738 ML |
3460 | diagnostic if there is an execution path in which a value is passed |
3461 | more than once to a deallocation call. | |
3462 | ||
3463 | @item | |
4ace81b6 SL |
3464 | The analyzer considers the possibility that an allocation function |
3465 | could fail and return null. If there are | |
d77de738 | 3466 | execution paths in which an unchecked result of an allocation call is |
4ace81b6 SL |
3467 | dereferenced or passed to a function requiring a non-null argument, |
3468 | it emits | |
3469 | @option{-Wanalyzer-possible-null-dereference} and | |
3470 | @option{-Wanalyzer-possible-null-argument} diagnostics. | |
d77de738 ML |
3471 | If the allocator always returns non-null, use |
3472 | @code{__attribute__ ((returns_nonnull))} to suppress these warnings. | |
3473 | For example: | |
3474 | @smallexample | |
3475 | char *xstrdup (const char *) | |
3476 | __attribute__((malloc (free), returns_nonnull)); | |
3477 | @end smallexample | |
3478 | ||
3479 | @item | |
4ace81b6 | 3480 | The analyzer emits a @option{-Wanalyzer-use-after-free} |
d77de738 ML |
3481 | diagnostic if there is an execution path in which the memory passed |
3482 | by pointer to a deallocation call is used after the deallocation. | |
3483 | ||
3484 | @item | |
4ace81b6 | 3485 | The analyzer emits a @option{-Wanalyzer-malloc-leak} diagnostic if |
d77de738 ML |
3486 | there is an execution path in which the result of an allocation call |
3487 | is leaked (without being passed to the deallocation function). | |
3488 | ||
3489 | @item | |
4ace81b6 | 3490 | The analyzer emits a @option{-Wanalyzer-free-of-non-heap} diagnostic |
d77de738 ML |
3491 | if a deallocation function is used on a global or on-stack variable. |
3492 | ||
3493 | @end itemize | |
3494 | ||
4ace81b6 | 3495 | The analyzer assumes that deallocators can gracefully handle the null |
d77de738 ML |
3496 | pointer. If this is not the case, the deallocator can be marked with |
3497 | @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit | |
3498 | a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths | |
4ace81b6 | 3499 | in which the deallocator is called with null. |
d77de738 | 3500 | |
d77de738 | 3501 | @cindex @code{no_icf} function attribute |
f33d7a88 | 3502 | @item no_icf |
d77de738 ML |
3503 | This function attribute prevents a functions from being merged with another |
3504 | semantically equivalent function. | |
3505 | ||
d77de738 ML |
3506 | @cindex @code{no_instrument_function} function attribute |
3507 | @opindex finstrument-functions | |
3508 | @opindex p | |
3509 | @opindex pg | |
f33d7a88 | 3510 | @item no_instrument_function |
d77de738 ML |
3511 | If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are |
3512 | given, profiling function calls are | |
3513 | generated at entry and exit of most user-compiled functions. | |
3514 | Functions with this attribute are not so instrumented. | |
3515 | ||
d77de738 | 3516 | @cindex @code{no_profile_instrument_function} function attribute |
f33d7a88 | 3517 | @item no_profile_instrument_function |
d77de738 ML |
3518 | The @code{no_profile_instrument_function} attribute on functions is used |
3519 | to inform the compiler that it should not process any profile feedback based | |
3520 | optimization code instrumentation. | |
3521 | ||
d77de738 | 3522 | @cindex @code{no_reorder} function attribute |
f33d7a88 | 3523 | @item no_reorder |
d77de738 ML |
3524 | Do not reorder functions or variables marked @code{no_reorder} |
3525 | against each other or top level assembler statements the executable. | |
3526 | The actual order in the program will depend on the linker command | |
3527 | line. Static variables marked like this are also not removed. | |
3528 | This has a similar effect | |
3529 | as the @option{-fno-toplevel-reorder} option, but only applies to the | |
3530 | marked symbols. | |
3531 | ||
d77de738 | 3532 | @cindex @code{no_sanitize} function attribute |
f33d7a88 | 3533 | @item no_sanitize ("@var{sanitize_option}") |
d77de738 ML |
3534 | The @code{no_sanitize} attribute on functions is used |
3535 | to inform the compiler that it should not do sanitization of any option | |
3536 | mentioned in @var{sanitize_option}. A list of values acceptable by | |
3537 | the @option{-fsanitize} option can be provided. | |
3538 | ||
3539 | @smallexample | |
3540 | void __attribute__ ((no_sanitize ("alignment", "object-size"))) | |
3541 | f () @{ /* @r{Do something.} */; @} | |
3542 | void __attribute__ ((no_sanitize ("alignment,object-size"))) | |
3543 | g () @{ /* @r{Do something.} */; @} | |
3544 | @end smallexample | |
3545 | ||
f33d7a88 | 3546 | @cindex @code{no_sanitize_address} function attribute |
d77de738 ML |
3547 | @item no_sanitize_address |
3548 | @itemx no_address_safety_analysis | |
d77de738 ML |
3549 | The @code{no_sanitize_address} attribute on functions is used |
3550 | to inform the compiler that it should not instrument memory accesses | |
3551 | in the function when compiling with the @option{-fsanitize=address} option. | |
3552 | The @code{no_address_safety_analysis} is a deprecated alias of the | |
3553 | @code{no_sanitize_address} attribute, new code should use | |
3554 | @code{no_sanitize_address}. | |
3555 | ||
d77de738 | 3556 | @cindex @code{no_sanitize_thread} function attribute |
f33d7a88 | 3557 | @item no_sanitize_thread |
d77de738 ML |
3558 | The @code{no_sanitize_thread} attribute on functions is used |
3559 | to inform the compiler that it should not instrument memory accesses | |
3560 | in the function when compiling with the @option{-fsanitize=thread} option. | |
3561 | ||
d77de738 | 3562 | @cindex @code{no_sanitize_undefined} function attribute |
f33d7a88 | 3563 | @item no_sanitize_undefined |
d77de738 ML |
3564 | The @code{no_sanitize_undefined} attribute on functions is used |
3565 | to inform the compiler that it should not check for undefined behavior | |
3566 | in the function when compiling with the @option{-fsanitize=undefined} option. | |
3567 | ||
d77de738 | 3568 | @cindex @code{no_sanitize_coverage} function attribute |
f33d7a88 | 3569 | @item no_sanitize_coverage |
d77de738 ML |
3570 | The @code{no_sanitize_coverage} attribute on functions is used |
3571 | to inform the compiler that it should not do coverage-guided | |
3572 | fuzzing code instrumentation (@option{-fsanitize-coverage}). | |
3573 | ||
d77de738 ML |
3574 | @cindex @code{no_split_stack} function attribute |
3575 | @opindex fsplit-stack | |
f33d7a88 | 3576 | @item no_split_stack |
d77de738 ML |
3577 | If @option{-fsplit-stack} is given, functions have a small |
3578 | prologue which decides whether to split the stack. Functions with the | |
3579 | @code{no_split_stack} attribute do not have that prologue, and thus | |
3580 | may run with only a small amount of stack space available. | |
3581 | ||
d77de738 | 3582 | @cindex @code{no_stack_limit} function attribute |
f33d7a88 | 3583 | @item no_stack_limit |
d77de738 ML |
3584 | This attribute locally overrides the @option{-fstack-limit-register} |
3585 | and @option{-fstack-limit-symbol} command-line options; it has the effect | |
3586 | of disabling stack limit checking in the function it applies to. | |
3587 | ||
d77de738 | 3588 | @cindex @code{noclone} function attribute |
f33d7a88 | 3589 | @item noclone |
d77de738 ML |
3590 | This function attribute prevents a function from being considered for |
3591 | cloning---a mechanism that produces specialized copies of functions | |
3592 | and which is (currently) performed by interprocedural constant | |
3593 | propagation. | |
3594 | ||
d77de738 | 3595 | @cindex @code{noinline} function attribute |
f33d7a88 | 3596 | @item noinline |
d77de738 ML |
3597 | This function attribute prevents a function from being considered for |
3598 | inlining. | |
3599 | @c Don't enumerate the optimizations by name here; we try to be | |
3600 | @c future-compatible with this mechanism. | |
3601 | If the function does not have side effects, there are optimizations | |
3602 | other than inlining that cause function calls to be optimized away, | |
3603 | although the function call is live. To keep such calls from being | |
3604 | optimized away, put | |
3605 | @smallexample | |
3606 | asm (""); | |
3607 | @end smallexample | |
3608 | ||
3609 | @noindent | |
3610 | (@pxref{Extended Asm}) in the called function, to serve as a special | |
3611 | side effect. | |
3612 | ||
d77de738 | 3613 | @cindex @code{noipa} function attribute |
f33d7a88 | 3614 | @item noipa |
d77de738 ML |
3615 | Disable interprocedural optimizations between the function with this |
3616 | attribute and its callers, as if the body of the function is not available | |
3617 | when optimizing callers and the callers are unavailable when optimizing | |
3618 | the body. This attribute implies @code{noinline}, @code{noclone} and | |
3619 | @code{no_icf} attributes. However, this attribute is not equivalent | |
3620 | to a combination of other attributes, because its purpose is to suppress | |
3621 | existing and future optimizations employing interprocedural analysis, | |
3622 | including those that do not have an attribute suitable for disabling | |
3623 | them individually. This attribute is supported mainly for the purpose | |
3624 | of testing the compiler. | |
3625 | ||
d77de738 ML |
3626 | @cindex @code{nonnull} function attribute |
3627 | @cindex functions with non-null pointer arguments | |
f33d7a88 AA |
3628 | @item nonnull |
3629 | @itemx nonnull (@var{arg-index}, @dots{}) | |
d77de738 ML |
3630 | The @code{nonnull} attribute may be applied to a function that takes at |
3631 | least one argument of a pointer type. It indicates that the referenced | |
3632 | arguments must be non-null pointers. For instance, the declaration: | |
3633 | ||
3634 | @smallexample | |
3635 | extern void * | |
3636 | my_memcpy (void *dest, const void *src, size_t len) | |
3637 | __attribute__((nonnull (1, 2))); | |
3638 | @end smallexample | |
3639 | ||
3640 | @noindent | |
3641 | informs the compiler that, in calls to @code{my_memcpy}, arguments | |
3642 | @var{dest} and @var{src} must be non-null. | |
3643 | ||
3644 | The attribute has an effect both on functions calls and function definitions. | |
3645 | ||
3646 | For function calls: | |
3647 | @itemize @bullet | |
3648 | @item If the compiler determines that a null pointer is | |
3649 | passed in an argument slot marked as non-null, and the | |
3650 | @option{-Wnonnull} option is enabled, a warning is issued. | |
3651 | @xref{Warning Options}. | |
3652 | @item The @option{-fisolate-erroneous-paths-attribute} option can be | |
3653 | specified to have GCC transform calls with null arguments to non-null | |
3654 | functions into traps. @xref{Optimize Options}. | |
3655 | @item The compiler may also perform optimizations based on the | |
3656 | knowledge that certain function arguments cannot be null. These | |
3657 | optimizations can be disabled by the | |
3658 | @option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}. | |
3659 | @end itemize | |
3660 | ||
3661 | For function definitions: | |
3662 | @itemize @bullet | |
3663 | @item If the compiler determines that a function parameter that is | |
3664 | marked with nonnull is compared with null, and | |
3665 | @option{-Wnonnull-compare} option is enabled, a warning is issued. | |
3666 | @xref{Warning Options}. | |
3667 | @item The compiler may also perform optimizations based on the | |
0e38aedc | 3668 | knowledge that @code{nonnull} parameters cannot be null. This can |
d77de738 ML |
3669 | currently not be disabled other than by removing the nonnull |
3670 | attribute. | |
3671 | @end itemize | |
3672 | ||
3673 | If no @var{arg-index} is given to the @code{nonnull} attribute, | |
3674 | all pointer arguments are marked as non-null. To illustrate, the | |
3675 | following declaration is equivalent to the previous example: | |
3676 | ||
3677 | @smallexample | |
3678 | extern void * | |
3679 | my_memcpy (void *dest, const void *src, size_t len) | |
3680 | __attribute__((nonnull)); | |
3681 | @end smallexample | |
3682 | ||
d77de738 | 3683 | @cindex @code{noplt} function attribute |
f33d7a88 | 3684 | @item noplt |
d77de738 ML |
3685 | The @code{noplt} attribute is the counterpart to option @option{-fno-plt}. |
3686 | Calls to functions marked with this attribute in position-independent code | |
3687 | do not use the PLT. | |
3688 | ||
3689 | @smallexample | |
3690 | @group | |
3691 | /* Externally defined function foo. */ | |
3692 | int foo () __attribute__ ((noplt)); | |
3693 | ||
3694 | int | |
3695 | main (/* @r{@dots{}} */) | |
3696 | @{ | |
3697 | /* @r{@dots{}} */ | |
3698 | foo (); | |
3699 | /* @r{@dots{}} */ | |
3700 | @} | |
3701 | @end group | |
3702 | @end smallexample | |
3703 | ||
3704 | The @code{noplt} attribute on function @code{foo} | |
3705 | tells the compiler to assume that | |
3706 | the function @code{foo} is externally defined and that the call to | |
3707 | @code{foo} must avoid the PLT | |
3708 | in position-independent code. | |
3709 | ||
3710 | In position-dependent code, a few targets also convert calls to | |
3711 | functions that are marked to not use the PLT to use the GOT instead. | |
3712 | ||
d77de738 ML |
3713 | @cindex @code{noreturn} function attribute |
3714 | @cindex functions that never return | |
f33d7a88 | 3715 | @item noreturn |
d77de738 ML |
3716 | A few standard library functions, such as @code{abort} and @code{exit}, |
3717 | cannot return. GCC knows this automatically. Some programs define | |
3718 | their own functions that never return. You can declare them | |
3719 | @code{noreturn} to tell the compiler this fact. For example, | |
3720 | ||
3721 | @smallexample | |
3722 | @group | |
3723 | void fatal () __attribute__ ((noreturn)); | |
3724 | ||
3725 | void | |
3726 | fatal (/* @r{@dots{}} */) | |
3727 | @{ | |
3728 | /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ | |
3729 | exit (1); | |
3730 | @} | |
3731 | @end group | |
3732 | @end smallexample | |
3733 | ||
3734 | The @code{noreturn} keyword tells the compiler to assume that | |
3735 | @code{fatal} cannot return. It can then optimize without regard to what | |
3736 | would happen if @code{fatal} ever did return. This makes slightly | |
3737 | better code. More importantly, it helps avoid spurious warnings of | |
3738 | uninitialized variables. | |
3739 | ||
3740 | The @code{noreturn} keyword does not affect the exceptional path when that | |
3741 | applies: a @code{noreturn}-marked function may still return to the caller | |
3742 | by throwing an exception or calling @code{longjmp}. | |
3743 | ||
3744 | In order to preserve backtraces, GCC will never turn calls to | |
3745 | @code{noreturn} functions into tail calls. | |
3746 | ||
3747 | Do not assume that registers saved by the calling function are | |
3748 | restored before calling the @code{noreturn} function. | |
3749 | ||
3750 | It does not make sense for a @code{noreturn} function to have a return | |
3751 | type other than @code{void}. | |
3752 | ||
d77de738 | 3753 | @cindex @code{nothrow} function attribute |
f33d7a88 | 3754 | @item nothrow |
d77de738 ML |
3755 | The @code{nothrow} attribute is used to inform the compiler that a |
3756 | function cannot throw an exception. For example, most functions in | |
3757 | the standard C library can be guaranteed not to throw an exception | |
3758 | with the notable exceptions of @code{qsort} and @code{bsearch} that | |
3759 | take function pointer arguments. | |
3760 | ||
f33d7a88 | 3761 | @cindex @code{optimize} function attribute |
d77de738 ML |
3762 | @item optimize (@var{level}, @dots{}) |
3763 | @item optimize (@var{string}, @dots{}) | |
d77de738 ML |
3764 | The @code{optimize} attribute is used to specify that a function is to |
3765 | be compiled with different optimization options than specified on the | |
3766 | command line. The optimize attribute arguments of a function behave | |
3767 | behave as if appended to the command-line. | |
3768 | ||
3769 | Valid arguments are constant non-negative integers and | |
3770 | strings. Each numeric argument specifies an optimization @var{level}. | |
3771 | Each @var{string} argument consists of one or more comma-separated | |
3772 | substrings. Each substring that begins with the letter @code{O} refers | |
3773 | to an optimization option such as @option{-O0} or @option{-Os}. Other | |
3774 | substrings are taken as suffixes to the @code{-f} prefix jointly | |
3775 | forming the name of an optimization option. @xref{Optimize Options}. | |
3776 | ||
3777 | @samp{#pragma GCC optimize} can be used to set optimization options | |
3778 | for more than one function. @xref{Function Specific Option Pragmas}, | |
3779 | for details about the pragma. | |
3780 | ||
3781 | Providing multiple strings as arguments separated by commas to specify | |
3782 | multiple options is equivalent to separating the option suffixes with | |
3783 | a comma (@samp{,}) within a single string. Spaces are not permitted | |
3784 | within the strings. | |
3785 | ||
3786 | Not every optimization option that starts with the @var{-f} prefix | |
3787 | specified by the attribute necessarily has an effect on the function. | |
3788 | The @code{optimize} attribute should be used for debugging purposes only. | |
3789 | It is not suitable in production code. | |
3790 | ||
d77de738 ML |
3791 | @cindex @code{patchable_function_entry} function attribute |
3792 | @cindex extra NOP instructions at the function entry point | |
f33d7a88 | 3793 | @item patchable_function_entry |
d77de738 ML |
3794 | In case the target's text segment can be made writable at run time by |
3795 | any means, padding the function entry with a number of NOPs can be | |
3796 | used to provide a universal tool for instrumentation. | |
3797 | ||
3798 | The @code{patchable_function_entry} function attribute can be used to | |
3799 | change the number of NOPs to any desired value. The two-value syntax | |
3800 | is the same as for the command-line switch | |
3801 | @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with | |
3802 | the function entry point before the @var{M}th NOP instruction. | |
3803 | @var{M} defaults to 0 if omitted e.g.@: function entry point is before | |
3804 | the first NOP. | |
3805 | ||
3806 | If patchable function entries are enabled globally using the command-line | |
3807 | option @option{-fpatchable-function-entry=N,M}, then you must disable | |
3808 | instrumentation on all functions that are part of the instrumentation | |
3809 | framework with the attribute @code{patchable_function_entry (0)} | |
3810 | to prevent recursion. | |
3811 | ||
d77de738 ML |
3812 | @cindex @code{pure} function attribute |
3813 | @cindex functions that have no side effects | |
f33d7a88 | 3814 | @item pure |
d77de738 ML |
3815 | |
3816 | Calls to functions that have no observable effects on the state of | |
3817 | the program other than to return a value may lend themselves to optimizations | |
3818 | such as common subexpression elimination. Declaring such functions with | |
3819 | the @code{pure} attribute allows GCC to avoid emitting some calls in repeated | |
3820 | invocations of the function with the same argument values. | |
3821 | ||
3822 | The @code{pure} attribute prohibits a function from modifying the state | |
3823 | of the program that is observable by means other than inspecting | |
3824 | the function's return value. However, functions declared with the @code{pure} | |
3825 | attribute can safely read any non-volatile objects, and modify the value of | |
3826 | objects in a way that does not affect their return value or the observable | |
3827 | state of the program. | |
3828 | ||
3829 | For example, | |
3830 | ||
3831 | @smallexample | |
3832 | int hash (char *) __attribute__ ((pure)); | |
3833 | @end smallexample | |
3834 | ||
3835 | @noindent | |
3836 | tells GCC that subsequent calls to the function @code{hash} with the same | |
3837 | string can be replaced by the result of the first call provided the state | |
3838 | of the program observable by @code{hash}, including the contents of the array | |
3839 | itself, does not change in between. Even though @code{hash} takes a non-const | |
3840 | pointer argument it must not modify the array it points to, or any other object | |
3841 | whose value the rest of the program may depend on. However, the caller may | |
3842 | safely change the contents of the array between successive calls to | |
3843 | the function (doing so disables the optimization). The restriction also | |
3844 | applies to member objects referenced by the @code{this} pointer in C++ | |
3845 | non-static member functions. | |
3846 | ||
3847 | Some common examples of pure functions are @code{strlen} or @code{memcmp}. | |
3848 | Interesting non-pure functions are functions with infinite loops or those | |
3849 | depending on volatile memory or other system resource, that may change between | |
3850 | consecutive calls (such as the standard C @code{feof} function in | |
3851 | a multithreading environment). | |
3852 | ||
3853 | The @code{pure} attribute imposes similar but looser restrictions on | |
3854 | a function's definition than the @code{const} attribute: @code{pure} | |
3855 | allows the function to read any non-volatile memory, even if it changes | |
3856 | in between successive invocations of the function. Declaring the same | |
3857 | function with both the @code{pure} and the @code{const} attribute is | |
3858 | diagnosed. Because a pure function cannot have any observable side | |
3859 | effects it does not make sense for such a function to return @code{void}. | |
3860 | Declaring such a function is diagnosed. | |
3861 | ||
d77de738 | 3862 | @cindex @code{returns_nonnull} function attribute |
f33d7a88 | 3863 | @item returns_nonnull |
d77de738 ML |
3864 | The @code{returns_nonnull} attribute specifies that the function |
3865 | return value should be a non-null pointer. For instance, the declaration: | |
3866 | ||
3867 | @smallexample | |
3868 | extern void * | |
3869 | mymalloc (size_t len) __attribute__((returns_nonnull)); | |
3870 | @end smallexample | |
3871 | ||
3872 | @noindent | |
3873 | lets the compiler optimize callers based on the knowledge | |
3874 | that the return value will never be null. | |
3875 | ||
d77de738 ML |
3876 | @cindex @code{returns_twice} function attribute |
3877 | @cindex functions that return more than once | |
f33d7a88 | 3878 | @item returns_twice |
d77de738 ML |
3879 | The @code{returns_twice} attribute tells the compiler that a function may |
3880 | return more than one time. The compiler ensures that all registers | |
3881 | are dead before calling such a function and emits a warning about | |
3882 | the variables that may be clobbered after the second return from the | |
3883 | function. Examples of such functions are @code{setjmp} and @code{vfork}. | |
3884 | The @code{longjmp}-like counterpart of such function, if any, might need | |
3885 | to be marked with the @code{noreturn} attribute. | |
3886 | ||
d77de738 ML |
3887 | @cindex @code{section} function attribute |
3888 | @cindex functions in arbitrary sections | |
f33d7a88 | 3889 | @item section ("@var{section-name}") |
d77de738 ML |
3890 | Normally, the compiler places the code it generates in the @code{text} section. |
3891 | Sometimes, however, you need additional sections, or you need certain | |
3892 | particular functions to appear in special sections. The @code{section} | |
3893 | attribute specifies that a function lives in a particular section. | |
3894 | For example, the declaration: | |
3895 | ||
3896 | @smallexample | |
3897 | extern void foobar (void) __attribute__ ((section ("bar"))); | |
3898 | @end smallexample | |
3899 | ||
3900 | @noindent | |
3901 | puts the function @code{foobar} in the @code{bar} section. | |
3902 | ||
3903 | Some file formats do not support arbitrary sections so the @code{section} | |
3904 | attribute is not available on all platforms. | |
3905 | If you need to map the entire contents of a module to a particular | |
3906 | section, consider using the facilities of the linker instead. | |
3907 | ||
f33d7a88 | 3908 | @cindex @code{sentinel} function attribute |
d77de738 ML |
3909 | @item sentinel |
3910 | @itemx sentinel (@var{position}) | |
d77de738 ML |
3911 | This function attribute indicates that an argument in a call to the function |
3912 | is expected to be an explicit @code{NULL}. The attribute is only valid on | |
3913 | variadic functions. By default, the sentinel is expected to be the last | |
3914 | argument of the function call. If the optional @var{position} argument | |
3915 | is specified to the attribute, the sentinel must be located at | |
3916 | @var{position} counting backwards from the end of the argument list. | |
3917 | ||
3918 | @smallexample | |
3919 | __attribute__ ((sentinel)) | |
3920 | is equivalent to | |
3921 | __attribute__ ((sentinel(0))) | |
3922 | @end smallexample | |
3923 | ||
3924 | The attribute is automatically set with a position of 0 for the built-in | |
3925 | functions @code{execl} and @code{execlp}. The built-in function | |
3926 | @code{execle} has the attribute set with a position of 1. | |
3927 | ||
3928 | A valid @code{NULL} in this context is defined as zero with any object | |
3929 | pointer type. If your system defines the @code{NULL} macro with | |
3930 | an integer type then you need to add an explicit cast. During | |
3931 | installation GCC replaces the system @code{<stddef.h>} header with | |
3932 | a copy that redefines NULL appropriately. | |
3933 | ||
3934 | The warnings for missing or incorrect sentinels are enabled with | |
3935 | @option{-Wformat}. | |
3936 | ||
f33d7a88 | 3937 | @cindex @code{simd} function attribute |
d77de738 ML |
3938 | @item simd |
3939 | @itemx simd("@var{mask}") | |
d77de738 ML |
3940 | This attribute enables creation of one or more function versions that |
3941 | can process multiple arguments using SIMD instructions from a | |
3942 | single invocation. Specifying this attribute allows compiler to | |
3943 | assume that such versions are available at link time (provided | |
3944 | in the same or another translation unit). Generated versions are | |
3945 | target-dependent and described in the corresponding Vector ABI document. For | |
3946 | x86_64 target this document can be found | |
3947 | @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}. | |
3948 | ||
3949 | The optional argument @var{mask} may have the value | |
3950 | @code{notinbranch} or @code{inbranch}, | |
3951 | and instructs the compiler to generate non-masked or masked | |
3952 | clones correspondingly. By default, all clones are generated. | |
3953 | ||
3954 | If the attribute is specified and @code{#pragma omp declare simd} is | |
3955 | present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd} | |
3956 | switch is specified, then the attribute is ignored. | |
3957 | ||
d77de738 | 3958 | @cindex @code{stack_protect} function attribute |
f33d7a88 | 3959 | @item stack_protect |
d77de738 ML |
3960 | This attribute adds stack protection code to the function if |
3961 | flags @option{-fstack-protector}, @option{-fstack-protector-strong} | |
3962 | or @option{-fstack-protector-explicit} are set. | |
3963 | ||
d77de738 | 3964 | @cindex @code{no_stack_protector} function attribute |
f33d7a88 | 3965 | @item no_stack_protector |
d77de738 ML |
3966 | This attribute prevents stack protection code for the function. |
3967 | ||
d77de738 | 3968 | @cindex @code{target} function attribute |
f33d7a88 | 3969 | @item target (@var{string}, @dots{}) |
d77de738 ML |
3970 | Multiple target back ends implement the @code{target} attribute |
3971 | to specify that a function is to | |
3972 | be compiled with different target options than specified on the | |
3973 | command line. The original target command-line options are ignored. | |
3974 | One or more strings can be provided as arguments. | |
3975 | Each string consists of one or more comma-separated suffixes to | |
3976 | the @code{-m} prefix jointly forming the name of a machine-dependent | |
3977 | option. @xref{Submodel Options,,Machine-Dependent Options}. | |
3978 | ||
3979 | The @code{target} attribute can be used for instance to have a function | |
3980 | compiled with a different ISA (instruction set architecture) than the | |
3981 | default. @samp{#pragma GCC target} can be used to specify target-specific | |
3982 | options for more than one function. @xref{Function Specific Option Pragmas}, | |
3983 | for details about the pragma. | |
3984 | ||
3985 | For instance, on an x86, you could declare one function with the | |
3986 | @code{target("sse4.1,arch=core2")} attribute and another with | |
3987 | @code{target("sse4a,arch=amdfam10")}. This is equivalent to | |
3988 | compiling the first function with @option{-msse4.1} and | |
3989 | @option{-march=core2} options, and the second function with | |
3990 | @option{-msse4a} and @option{-march=amdfam10} options. It is up to you | |
3991 | to make sure that a function is only invoked on a machine that | |
3992 | supports the particular ISA it is compiled for (for example by using | |
3993 | @code{cpuid} on x86 to determine what feature bits and architecture | |
3994 | family are used). | |
3995 | ||
3996 | @smallexample | |
3997 | int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); | |
3998 | int sse3_func (void) __attribute__ ((__target__ ("sse3"))); | |
3999 | @end smallexample | |
4000 | ||
4001 | Providing multiple strings as arguments separated by commas to specify | |
4002 | multiple options is equivalent to separating the option suffixes with | |
4003 | a comma (@samp{,}) within a single string. Spaces are not permitted | |
4004 | within the strings. | |
4005 | ||
4006 | The options supported are specific to each target; refer to @ref{x86 | |
4007 | Function Attributes}, @ref{PowerPC Function Attributes}, | |
4008 | @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes}, | |
4009 | @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes} | |
4010 | for details. | |
4011 | ||
d77de738 | 4012 | @cindex @code{symver} function attribute |
f33d7a88 | 4013 | @item symver ("@var{name2}@@@var{nodename}") |
d77de738 ML |
4014 | On ELF targets this attribute creates a symbol version. The @var{name2} part |
4015 | of the parameter is the actual name of the symbol by which it will be | |
4016 | externally referenced. The @code{nodename} portion should be the name of a | |
4017 | node specified in the version script supplied to the linker when building a | |
4018 | shared library. Versioned symbol must be defined and must be exported with | |
4019 | default visibility. | |
4020 | ||
4021 | @smallexample | |
4022 | __attribute__ ((__symver__ ("foo@@VERS_1"))) int | |
4023 | foo_v1 (void) | |
4024 | @{ | |
4025 | @} | |
4026 | @end smallexample | |
4027 | ||
4028 | Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler | |
4029 | output. | |
4030 | ||
4031 | One can also define multiple version for a given symbol | |
4032 | (starting from binutils 2.35). | |
4033 | ||
4034 | @smallexample | |
4035 | __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3"))) | |
4036 | int symver_foo_v1 (void) | |
4037 | @{ | |
4038 | @} | |
4039 | @end smallexample | |
4040 | ||
4041 | This example creates a symbol name @code{symver_foo_v1} | |
4042 | which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}. | |
4043 | ||
4044 | If you have an older release of binutils, then symbol alias needs to | |
4045 | be used: | |
4046 | ||
4047 | @smallexample | |
4048 | __attribute__ ((__symver__ ("foo@@VERS_2"))) | |
4049 | int foo_v1 (void) | |
4050 | @{ | |
4051 | return 0; | |
4052 | @} | |
4053 | ||
4054 | __attribute__ ((__symver__ ("foo@@VERS_3"))) | |
4055 | __attribute__ ((alias ("foo_v1"))) | |
4056 | int symver_foo_v1 (void); | |
4057 | @end smallexample | |
4058 | ||
4059 | Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in | |
4060 | addition to creating a symbol version (as if | |
4061 | @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used | |
4062 | to resolve @var{name2} by the linker. | |
4063 | ||
d77de738 | 4064 | @cindex @code{tainted_args} function attribute |
f33d7a88 | 4065 | @item tainted_args |
d77de738 ML |
4066 | The @code{tainted_args} attribute is used to specify that a function is called |
4067 | in a way that requires sanitization of its arguments, such as a system | |
4068 | call in an operating system kernel. Such a function can be considered part | |
4069 | of the ``attack surface'' of the program. The attribute can be used both | |
4070 | on function declarations, and on field declarations containing function | |
4071 | pointers. In the latter case, any function used as an initializer of | |
4072 | such a callback field will be treated as being called with tainted | |
4073 | arguments. | |
4074 | ||
4075 | The analyzer will pay particular attention to such functions when both | |
4076 | @option{-fanalyzer} and @option{-fanalyzer-checker=taint} are supplied, | |
4077 | potentially issuing warnings guarded by | |
4078 | @option{-Wanalyzer-tainted-allocation-size}, | |
4079 | @option{-Wanalyzer-tainted-array-index}, | |
4080 | @option{-Wanalyzer-tainted-divisor}, | |
4081 | @option{-Wanalyzer-tainted-offset}, | |
4082 | and @option{-Wanalyzer-tainted-size}. | |
4083 | ||
d77de738 | 4084 | @cindex @code{target_clones} function attribute |
f33d7a88 | 4085 | @item target_clones (@var{options}) |
d77de738 ML |
4086 | The @code{target_clones} attribute is used to specify that a function |
4087 | be cloned into multiple versions compiled with different target options | |
4088 | than specified on the command line. The supported options and restrictions | |
4089 | are the same as for @code{target} attribute. | |
4090 | ||
4091 | For instance, on an x86, you could compile a function with | |
4092 | @code{target_clones("sse4.1,avx")}. GCC creates two function clones, | |
4093 | one compiled with @option{-msse4.1} and another with @option{-mavx}. | |
4094 | ||
4095 | On a PowerPC, you can compile a function with | |
4096 | @code{target_clones("cpu=power9,default")}. GCC will create two | |
4097 | function clones, one compiled with @option{-mcpu=power9} and another | |
4098 | with the default options. GCC must be configured to use GLIBC 2.23 or | |
4099 | newer in order to use the @code{target_clones} attribute. | |
4100 | ||
4101 | It also creates a resolver function (see | |
4102 | the @code{ifunc} attribute above) that dynamically selects a clone | |
4103 | suitable for current architecture. The resolver is created only if there | |
4104 | is a usage of a function with @code{target_clones} attribute. | |
4105 | ||
4106 | Note that any subsequent call of a function without @code{target_clone} | |
4107 | from a @code{target_clone} caller will not lead to copying | |
4108 | (target clone) of the called function. | |
4109 | If you want to enforce such behaviour, | |
4110 | we recommend declaring the calling function with the @code{flatten} attribute? | |
4111 | ||
d77de738 | 4112 | @cindex @code{unused} function attribute |
f33d7a88 | 4113 | @item unused |
d77de738 ML |
4114 | This attribute, attached to a function, means that the function is meant |
4115 | to be possibly unused. GCC does not produce a warning for this | |
4116 | function. | |
4117 | ||
d77de738 | 4118 | @cindex @code{used} function attribute |
f33d7a88 | 4119 | @item used |
d77de738 ML |
4120 | This attribute, attached to a function, means that code must be emitted |
4121 | for the function even if it appears that the function is not referenced. | |
4122 | This is useful, for example, when the function is referenced only in | |
4123 | inline assembly. | |
4124 | ||
4125 | When applied to a member function of a C++ class template, the | |
4126 | attribute also means that the function is instantiated if the | |
4127 | class itself is instantiated. | |
4128 | ||
d77de738 | 4129 | @cindex @code{retain} function attribute |
f33d7a88 | 4130 | @item retain |
d77de738 ML |
4131 | For ELF targets that support the GNU or FreeBSD OSABIs, this attribute |
4132 | will save the function from linker garbage collection. To support | |
4133 | this behavior, functions that have not been placed in specific sections | |
4134 | (e.g. by the @code{section} attribute, or the @code{-ffunction-sections} | |
4135 | option), will be placed in new, unique sections. | |
4136 | ||
4137 | This additional functionality requires Binutils version 2.36 or later. | |
4138 | ||
d77de738 | 4139 | @cindex @code{visibility} function attribute |
f33d7a88 | 4140 | @item visibility ("@var{visibility_type}") |
d77de738 ML |
4141 | This attribute affects the linkage of the declaration to which it is attached. |
4142 | It can be applied to variables (@pxref{Common Variable Attributes}) and types | |
4143 | (@pxref{Common Type Attributes}) as well as functions. | |
4144 | ||
4145 | There are four supported @var{visibility_type} values: default, | |
4146 | hidden, protected or internal visibility. | |
4147 | ||
4148 | @smallexample | |
4149 | void __attribute__ ((visibility ("protected"))) | |
4150 | f () @{ /* @r{Do something.} */; @} | |
4151 | int i __attribute__ ((visibility ("hidden"))); | |
4152 | @end smallexample | |
4153 | ||
4154 | The possible values of @var{visibility_type} correspond to the | |
4155 | visibility settings in the ELF gABI. | |
4156 | ||
4157 | @table @code | |
4158 | @c keep this list of visibilities in alphabetical order. | |
4159 | ||
4160 | @item default | |
4161 | Default visibility is the normal case for the object file format. | |
4162 | This value is available for the visibility attribute to override other | |
4163 | options that may change the assumed visibility of entities. | |
4164 | ||
4165 | On ELF, default visibility means that the declaration is visible to other | |
4166 | modules and, in shared libraries, means that the declared entity may be | |
4167 | overridden. | |
4168 | ||
4169 | On Darwin, default visibility means that the declaration is visible to | |
4170 | other modules. | |
4171 | ||
4172 | Default visibility corresponds to ``external linkage'' in the language. | |
4173 | ||
4174 | @item hidden | |
4175 | Hidden visibility indicates that the entity declared has a new | |
4176 | form of linkage, which we call ``hidden linkage''. Two | |
4177 | declarations of an object with hidden linkage refer to the same object | |
4178 | if they are in the same shared object. | |
4179 | ||
4180 | @item internal | |
4181 | Internal visibility is like hidden visibility, but with additional | |
4182 | processor specific semantics. Unless otherwise specified by the | |
4183 | psABI, GCC defines internal visibility to mean that a function is | |
4184 | @emph{never} called from another module. Compare this with hidden | |
4185 | functions which, while they cannot be referenced directly by other | |
4186 | modules, can be referenced indirectly via function pointers. By | |
4187 | indicating that a function cannot be called from outside the module, | |
4188 | GCC may for instance omit the load of a PIC register since it is known | |
4189 | that the calling function loaded the correct value. | |
4190 | ||
4191 | @item protected | |
4192 | Protected visibility is like default visibility except that it | |
4193 | indicates that references within the defining module bind to the | |
4194 | definition in that module. That is, the declared entity cannot be | |
4195 | overridden by another module. | |
4196 | ||
4197 | @end table | |
4198 | ||
4199 | All visibilities are supported on many, but not all, ELF targets | |
4200 | (supported when the assembler supports the @samp{.visibility} | |
4201 | pseudo-op). Default visibility is supported everywhere. Hidden | |
4202 | visibility is supported on Darwin targets. | |
4203 | ||
4204 | The visibility attribute should be applied only to declarations that | |
4205 | would otherwise have external linkage. The attribute should be applied | |
4206 | consistently, so that the same entity should not be declared with | |
4207 | different settings of the attribute. | |
4208 | ||
4209 | In C++, the visibility attribute applies to types as well as functions | |
4210 | and objects, because in C++ types have linkage. A class must not have | |
4211 | greater visibility than its non-static data member types and bases, | |
4212 | and class members default to the visibility of their class. Also, a | |
4213 | declaration without explicit visibility is limited to the visibility | |
4214 | of its type. | |
4215 | ||
4216 | In C++, you can mark member functions and static member variables of a | |
4217 | class with the visibility attribute. This is useful if you know a | |
4218 | particular method or static member variable should only be used from | |
4219 | one shared object; then you can mark it hidden while the rest of the | |
4220 | class has default visibility. Care must be taken to avoid breaking | |
4221 | the One Definition Rule; for example, it is usually not useful to mark | |
4222 | an inline method as hidden without marking the whole class as hidden. | |
4223 | ||
4224 | A C++ namespace declaration can also have the visibility attribute. | |
4225 | ||
4226 | @smallexample | |
4227 | namespace nspace1 __attribute__ ((visibility ("protected"))) | |
4228 | @{ /* @r{Do something.} */; @} | |
4229 | @end smallexample | |
4230 | ||
4231 | This attribute applies only to the particular namespace body, not to | |
4232 | other definitions of the same namespace; it is equivalent to using | |
4233 | @samp{#pragma GCC visibility} before and after the namespace | |
4234 | definition (@pxref{Visibility Pragmas}). | |
4235 | ||
4236 | In C++, if a template argument has limited visibility, this | |
4237 | restriction is implicitly propagated to the template instantiation. | |
4238 | Otherwise, template instantiations and specializations default to the | |
4239 | visibility of their template. | |
4240 | ||
4241 | If both the template and enclosing class have explicit visibility, the | |
4242 | visibility from the template is used. | |
4243 | ||
d77de738 | 4244 | @cindex @code{warn_unused_result} function attribute |
f33d7a88 | 4245 | @item warn_unused_result |
d77de738 ML |
4246 | The @code{warn_unused_result} attribute causes a warning to be emitted |
4247 | if a caller of the function with this attribute does not use its | |
4248 | return value. This is useful for functions where not checking | |
4249 | the result is either a security problem or always a bug, such as | |
4250 | @code{realloc}. | |
4251 | ||
4252 | @smallexample | |
4253 | int fn () __attribute__ ((warn_unused_result)); | |
4254 | int foo () | |
4255 | @{ | |
4256 | if (fn () < 0) return -1; | |
4257 | fn (); | |
4258 | return 0; | |
4259 | @} | |
4260 | @end smallexample | |
4261 | ||
4262 | @noindent | |
4263 | results in warning on line 5. | |
4264 | ||
d77de738 | 4265 | @cindex @code{weak} function attribute |
f33d7a88 | 4266 | @item weak |
d77de738 ML |
4267 | The @code{weak} attribute causes a declaration of an external symbol |
4268 | to be emitted as a weak symbol rather than a global. This is primarily | |
4269 | useful in defining library functions that can be overridden in user code, | |
4270 | though it can also be used with non-function declarations. The overriding | |
4271 | symbol must have the same type as the weak symbol. In addition, if it | |
4272 | designates a variable it must also have the same size and alignment as | |
4273 | the weak symbol. Weak symbols are supported for ELF targets, and also | |
4274 | for a.out targets when using the GNU assembler and linker. | |
4275 | ||
f33d7a88 | 4276 | @cindex @code{weakref} function attribute |
d77de738 ML |
4277 | @item weakref |
4278 | @itemx weakref ("@var{target}") | |
d77de738 ML |
4279 | The @code{weakref} attribute marks a declaration as a weak reference. |
4280 | Without arguments, it should be accompanied by an @code{alias} attribute | |
4281 | naming the target symbol. Alternatively, @var{target} may be given as | |
4282 | an argument to @code{weakref} itself, naming the target definition of | |
4283 | the alias. The @var{target} must have the same type as the declaration. | |
4284 | In addition, if it designates a variable it must also have the same size | |
4285 | and alignment as the declaration. In either form of the declaration | |
4286 | @code{weakref} implicitly marks the declared symbol as @code{weak}. Without | |
4287 | a @var{target} given as an argument to @code{weakref} or to @code{alias}, | |
4288 | @code{weakref} is equivalent to @code{weak} (in that case the declaration | |
4289 | may be @code{extern}). | |
4290 | ||
4291 | @smallexample | |
4292 | /* Given the declaration: */ | |
4293 | extern int y (void); | |
4294 | ||
4295 | /* the following... */ | |
4296 | static int x (void) __attribute__ ((weakref ("y"))); | |
4297 | ||
4298 | /* is equivalent to... */ | |
4299 | static int x (void) __attribute__ ((weakref, alias ("y"))); | |
4300 | ||
4301 | /* or, alternatively, to... */ | |
4302 | static int x (void) __attribute__ ((weakref)); | |
4303 | static int x (void) __attribute__ ((alias ("y"))); | |
4304 | @end smallexample | |
4305 | ||
4306 | A weak reference is an alias that does not by itself require a | |
4307 | definition to be given for the target symbol. If the target symbol is | |
4308 | only referenced through weak references, then it becomes a @code{weak} | |
4309 | undefined symbol. If it is directly referenced, however, then such | |
4310 | strong references prevail, and a definition is required for the | |
4311 | symbol, not necessarily in the same translation unit. | |
4312 | ||
4313 | The effect is equivalent to moving all references to the alias to a | |
4314 | separate translation unit, renaming the alias to the aliased symbol, | |
4315 | declaring it as weak, compiling the two separate translation units and | |
4316 | performing a link with relocatable output (i.e.@: @code{ld -r}) on them. | |
4317 | ||
4318 | A declaration to which @code{weakref} is attached and that is associated | |
4319 | with a named @code{target} must be @code{static}. | |
4320 | ||
d77de738 | 4321 | @cindex @code{zero_call_used_regs} function attribute |
f33d7a88 | 4322 | @item zero_call_used_regs ("@var{choice}") |
d77de738 ML |
4323 | |
4324 | The @code{zero_call_used_regs} attribute causes the compiler to zero | |
4325 | a subset of all call-used registers@footnote{A ``call-used'' register | |
4326 | is a register whose contents can be changed by a function call; | |
4327 | therefore, a caller cannot assume that the register has the same contents | |
4328 | on return from the function as it had before calling the function. Such | |
4329 | registers are also called ``call-clobbered'', ``caller-saved'', or | |
4330 | ``volatile''.} at function return. | |
4331 | This is used to increase program security by either mitigating | |
4332 | Return-Oriented Programming (ROP) attacks or preventing information leakage | |
4333 | through registers. | |
4334 | ||
4335 | In order to satisfy users with different security needs and control the | |
4336 | run-time overhead at the same time, the @var{choice} parameter provides a | |
4337 | flexible way to choose the subset of the call-used registers to be zeroed. | |
4338 | The three basic values of @var{choice} are: | |
4339 | ||
4340 | @itemize @bullet | |
4341 | @item | |
4342 | @samp{skip} doesn't zero any call-used registers. | |
4343 | ||
4344 | @item | |
4345 | @samp{used} only zeros call-used registers that are used in the function. | |
4346 | A ``used'' register is one whose content has been set or referenced in | |
4347 | the function. | |
4348 | ||
4349 | @item | |
4350 | @samp{all} zeros all call-used registers. | |
4351 | @end itemize | |
4352 | ||
4353 | In addition to these three basic choices, it is possible to modify | |
4354 | @samp{used} or @samp{all} as follows: | |
4355 | ||
4356 | @itemize @bullet | |
4357 | @item | |
4358 | Adding @samp{-gpr} restricts the zeroing to general-purpose registers. | |
4359 | ||
4360 | @item | |
4361 | Adding @samp{-arg} restricts the zeroing to registers that can sometimes | |
4362 | be used to pass function arguments. This includes all argument registers | |
4363 | defined by the platform's calling conversion, regardless of whether the | |
4364 | function uses those registers for function arguments or not. | |
4365 | @end itemize | |
4366 | ||
4367 | The modifiers can be used individually or together. If they are used | |
4368 | together, they must appear in the order above. | |
4369 | ||
4370 | The full list of @var{choice}s is therefore: | |
4371 | ||
4372 | @table @code | |
4373 | @item skip | |
4374 | doesn't zero any call-used register. | |
4375 | ||
4376 | @item used | |
4377 | only zeros call-used registers that are used in the function. | |
4378 | ||
4379 | @item used-gpr | |
4380 | only zeros call-used general purpose registers that are used in the function. | |
4381 | ||
4382 | @item used-arg | |
4383 | only zeros call-used registers that are used in the function and pass arguments. | |
4384 | ||
4385 | @item used-gpr-arg | |
4386 | only zeros call-used general purpose registers that are used in the function | |
4387 | and pass arguments. | |
4388 | ||
4389 | @item all | |
4390 | zeros all call-used registers. | |
4391 | ||
4392 | @item all-gpr | |
4393 | zeros all call-used general purpose registers. | |
4394 | ||
4395 | @item all-arg | |
4396 | zeros all call-used registers that pass arguments. | |
4397 | ||
4398 | @item all-gpr-arg | |
4399 | zeros all call-used general purpose registers that pass | |
4400 | arguments. | |
4401 | @end table | |
4402 | ||
4403 | Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg}, | |
4404 | and @samp{all-gpr-arg} are mainly used for ROP mitigation. | |
4405 | ||
4406 | The default for the attribute is controlled by @option{-fzero-call-used-regs}. | |
4407 | @end table | |
4408 | ||
4409 | @c This is the end of the target-independent attribute table | |
4410 | ||
4411 | @node AArch64 Function Attributes | |
4412 | @subsection AArch64 Function Attributes | |
4413 | ||
4414 | The following target-specific function attributes are available for the | |
4415 | AArch64 target. For the most part, these options mirror the behavior of | |
4416 | similar command-line options (@pxref{AArch64 Options}), but on a | |
4417 | per-function basis. | |
4418 | ||
4419 | @table @code | |
d77de738 | 4420 | @cindex @code{general-regs-only} function attribute, AArch64 |
f33d7a88 | 4421 | @item general-regs-only |
d77de738 ML |
4422 | Indicates that no floating-point or Advanced SIMD registers should be |
4423 | used when generating code for this function. If the function explicitly | |
4424 | uses floating-point code, then the compiler gives an error. This is | |
4425 | the same behavior as that of the command-line option | |
4426 | @option{-mgeneral-regs-only}. | |
4427 | ||
d77de738 | 4428 | @cindex @code{fix-cortex-a53-835769} function attribute, AArch64 |
f33d7a88 | 4429 | @item fix-cortex-a53-835769 |
d77de738 ML |
4430 | Indicates that the workaround for the Cortex-A53 erratum 835769 should be |
4431 | applied to this function. To explicitly disable the workaround for this | |
4432 | function specify the negated form: @code{no-fix-cortex-a53-835769}. | |
4433 | This corresponds to the behavior of the command line options | |
4434 | @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}. | |
4435 | ||
d77de738 | 4436 | @cindex @code{cmodel=} function attribute, AArch64 |
f33d7a88 | 4437 | @item cmodel= |
d77de738 ML |
4438 | Indicates that code should be generated for a particular code model for |
4439 | this function. The behavior and permissible arguments are the same as | |
4440 | for the command line option @option{-mcmodel=}. | |
4441 | ||
f33d7a88 | 4442 | @cindex @code{strict-align} function attribute, AArch64 |
d77de738 ML |
4443 | @item strict-align |
4444 | @itemx no-strict-align | |
d77de738 ML |
4445 | @code{strict-align} indicates that the compiler should not assume that unaligned |
4446 | memory references are handled by the system. To allow the compiler to assume | |
4447 | that aligned memory references are handled by the system, the inverse attribute | |
4448 | @code{no-strict-align} can be specified. The behavior is same as for the | |
4449 | command-line option @option{-mstrict-align} and @option{-mno-strict-align}. | |
4450 | ||
d77de738 | 4451 | @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64 |
f33d7a88 | 4452 | @item omit-leaf-frame-pointer |
d77de738 ML |
4453 | Indicates that the frame pointer should be omitted for a leaf function call. |
4454 | To keep the frame pointer, the inverse attribute | |
4455 | @code{no-omit-leaf-frame-pointer} can be specified. These attributes have | |
4456 | the same behavior as the command-line options @option{-momit-leaf-frame-pointer} | |
4457 | and @option{-mno-omit-leaf-frame-pointer}. | |
4458 | ||
d77de738 | 4459 | @cindex @code{tls-dialect=} function attribute, AArch64 |
f33d7a88 | 4460 | @item tls-dialect= |
d77de738 ML |
4461 | Specifies the TLS dialect to use for this function. The behavior and |
4462 | permissible arguments are the same as for the command-line option | |
4463 | @option{-mtls-dialect=}. | |
4464 | ||
d77de738 | 4465 | @cindex @code{arch=} function attribute, AArch64 |
f33d7a88 | 4466 | @item arch= |
d77de738 ML |
4467 | Specifies the architecture version and architectural extensions to use |
4468 | for this function. The behavior and permissible arguments are the same as | |
4469 | for the @option{-march=} command-line option. | |
4470 | ||
d77de738 | 4471 | @cindex @code{tune=} function attribute, AArch64 |
f33d7a88 | 4472 | @item tune= |
d77de738 ML |
4473 | Specifies the core for which to tune the performance of this function. |
4474 | The behavior and permissible arguments are the same as for the @option{-mtune=} | |
4475 | command-line option. | |
4476 | ||
d77de738 | 4477 | @cindex @code{cpu=} function attribute, AArch64 |
f33d7a88 | 4478 | @item cpu= |
d77de738 ML |
4479 | Specifies the core for which to tune the performance of this function and also |
4480 | whose architectural features to use. The behavior and valid arguments are the | |
4481 | same as for the @option{-mcpu=} command-line option. | |
4482 | ||
d77de738 | 4483 | @cindex @code{sign-return-address} function attribute, AArch64 |
f33d7a88 | 4484 | @item sign-return-address |
d77de738 ML |
4485 | Select the function scope on which return address signing will be applied. The |
4486 | behavior and permissible arguments are the same as for the command-line option | |
4487 | @option{-msign-return-address=}. The default value is @code{none}. This | |
4488 | attribute is deprecated. The @code{branch-protection} attribute should | |
4489 | be used instead. | |
4490 | ||
d77de738 | 4491 | @cindex @code{branch-protection} function attribute, AArch64 |
f33d7a88 | 4492 | @item branch-protection |
d77de738 ML |
4493 | Select the function scope on which branch protection will be applied. The |
4494 | behavior and permissible arguments are the same as for the command-line option | |
4495 | @option{-mbranch-protection=}. The default value is @code{none}. | |
4496 | ||
d77de738 | 4497 | @cindex @code{outline-atomics} function attribute, AArch64 |
f33d7a88 | 4498 | @item outline-atomics |
d77de738 ML |
4499 | Enable or disable calls to out-of-line helpers to implement atomic operations. |
4500 | This corresponds to the behavior of the command line options | |
4501 | @option{-moutline-atomics} and @option{-mno-outline-atomics}. | |
4502 | ||
4503 | @end table | |
4504 | ||
4505 | The above target attributes can be specified as follows: | |
4506 | ||
4507 | @smallexample | |
4508 | __attribute__((target("@var{attr-string}"))) | |
4509 | int | |
4510 | f (int a) | |
4511 | @{ | |
4512 | return a + 5; | |
4513 | @} | |
4514 | @end smallexample | |
4515 | ||
4516 | where @code{@var{attr-string}} is one of the attribute strings specified above. | |
4517 | ||
4518 | Additionally, the architectural extension string may be specified on its | |
4519 | own. This can be used to turn on and off particular architectural extensions | |
4520 | without having to specify a particular architecture version or core. Example: | |
4521 | ||
4522 | @smallexample | |
4523 | __attribute__((target("+crc+nocrypto"))) | |
4524 | int | |
4525 | foo (int a) | |
4526 | @{ | |
4527 | return a + 5; | |
4528 | @} | |
4529 | @end smallexample | |
4530 | ||
4531 | In this example @code{target("+crc+nocrypto")} enables the @code{crc} | |
4532 | extension and disables the @code{crypto} extension for the function @code{foo} | |
4533 | without modifying an existing @option{-march=} or @option{-mcpu} option. | |
4534 | ||
4535 | Multiple target function attributes can be specified by separating them with | |
4536 | a comma. For example: | |
4537 | @smallexample | |
4538 | __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53"))) | |
4539 | int | |
4540 | foo (int a) | |
4541 | @{ | |
4542 | return a + 5; | |
4543 | @} | |
4544 | @end smallexample | |
4545 | ||
4546 | is valid and compiles function @code{foo} for ARMv8-A with @code{crc} | |
4547 | and @code{crypto} extensions and tunes it for @code{cortex-a53}. | |
4548 | ||
4549 | @subsubsection Inlining rules | |
4550 | Specifying target attributes on individual functions or performing link-time | |
4551 | optimization across translation units compiled with different target options | |
4552 | can affect function inlining rules: | |
4553 | ||
4554 | In particular, a caller function can inline a callee function only if the | |
4555 | architectural features available to the callee are a subset of the features | |
4556 | available to the caller. | |
4557 | For example: A function @code{foo} compiled with @option{-march=armv8-a+crc}, | |
4558 | or tagged with the equivalent @code{arch=armv8-a+crc} attribute, | |
4559 | can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc} | |
4560 | because the all the architectural features that function @code{bar} requires | |
4561 | are available to function @code{foo}. Conversely, function @code{bar} cannot | |
4562 | inline function @code{foo}. | |
4563 | ||
4564 | Additionally inlining a function compiled with @option{-mstrict-align} into a | |
4565 | function compiled without @code{-mstrict-align} is not allowed. | |
4566 | However, inlining a function compiled without @option{-mstrict-align} into a | |
4567 | function compiled with @option{-mstrict-align} is allowed. | |
4568 | ||
4569 | Note that CPU tuning options and attributes such as the @option{-mcpu=}, | |
4570 | @option{-mtune=} do not inhibit inlining unless the CPU specified by the | |
4571 | @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the | |
4572 | architectural feature rules specified above. | |
4573 | ||
4574 | @node AMD GCN Function Attributes | |
4575 | @subsection AMD GCN Function Attributes | |
4576 | ||
4577 | These function attributes are supported by the AMD GCN back end: | |
4578 | ||
4579 | @table @code | |
d77de738 | 4580 | @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN |
f33d7a88 | 4581 | @item amdgpu_hsa_kernel |
d77de738 ML |
4582 | This attribute indicates that the corresponding function should be compiled as |
4583 | a kernel function, that is an entry point that can be invoked from the host | |
4584 | via the HSA runtime library. By default functions are only callable only from | |
4585 | other GCN functions. | |
4586 | ||
4587 | This attribute is implicitly applied to any function named @code{main}, using | |
4588 | default parameters. | |
4589 | ||
4590 | Kernel functions may return an integer value, which will be written to a | |
4591 | conventional place within the HSA "kernargs" region. | |
4592 | ||
4593 | The attribute parameters configure what values are passed into the kernel | |
4594 | function by the GPU drivers, via the initial register state. Some values are | |
4595 | used by the compiler, and therefore forced on. Enabling other options may | |
4596 | break assumptions in the compiler and/or run-time libraries. | |
4597 | ||
4598 | @table @code | |
4599 | @item private_segment_buffer | |
4600 | Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to | |
4601 | locate the stack). | |
4602 | ||
4603 | @item dispatch_ptr | |
4604 | Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the | |
4605 | launch dimensions). | |
4606 | ||
4607 | @item queue_ptr | |
4608 | Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address | |
4609 | spaces). | |
4610 | ||
4611 | @item kernarg_segment_ptr | |
4612 | Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to | |
4613 | locate the kernel arguments, "kernargs"). | |
4614 | ||
4615 | @item dispatch_id | |
4616 | Set @code{enable_sgpr_dispatch_id} flag. | |
4617 | ||
4618 | @item flat_scratch_init | |
4619 | Set @code{enable_sgpr_flat_scratch_init} flag. | |
4620 | ||
4621 | @item private_segment_size | |
4622 | Set @code{enable_sgpr_private_segment_size} flag. | |
4623 | ||
4624 | @item grid_workgroup_count_X | |
4625 | Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to | |
4626 | use OpenACC/OpenMP). | |
4627 | ||
4628 | @item grid_workgroup_count_Y | |
4629 | Set @code{enable_sgpr_grid_workgroup_count_y} flag. | |
4630 | ||
4631 | @item grid_workgroup_count_Z | |
4632 | Set @code{enable_sgpr_grid_workgroup_count_z} flag. | |
4633 | ||
4634 | @item workgroup_id_X | |
4635 | Set @code{enable_sgpr_workgroup_id_x} flag. | |
4636 | ||
4637 | @item workgroup_id_Y | |
4638 | Set @code{enable_sgpr_workgroup_id_y} flag. | |
4639 | ||
4640 | @item workgroup_id_Z | |
4641 | Set @code{enable_sgpr_workgroup_id_z} flag. | |
4642 | ||
4643 | @item workgroup_info | |
4644 | Set @code{enable_sgpr_workgroup_info} flag. | |
4645 | ||
4646 | @item private_segment_wave_offset | |
4647 | Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on | |
4648 | (required to locate the stack). | |
4649 | ||
4650 | @item work_item_id_X | |
4651 | Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled). | |
4652 | ||
4653 | @item work_item_id_Y | |
4654 | Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable | |
4655 | vectorization.) | |
4656 | ||
4657 | @item work_item_id_Z | |
4658 | Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use | |
4659 | OpenACC/OpenMP). | |
4660 | ||
4661 | @end table | |
4662 | @end table | |
4663 | ||
4664 | @node ARC Function Attributes | |
4665 | @subsection ARC Function Attributes | |
4666 | ||
4667 | These function attributes are supported by the ARC back end: | |
4668 | ||
4669 | @table @code | |
d77de738 | 4670 | @cindex @code{interrupt} function attribute, ARC |
f33d7a88 | 4671 | @item interrupt |
d77de738 ML |
4672 | Use this attribute to indicate |
4673 | that the specified function is an interrupt handler. The compiler generates | |
4674 | function entry and exit sequences suitable for use in an interrupt handler | |
4675 | when this attribute is present. | |
4676 | ||
4677 | On the ARC, you must specify the kind of interrupt to be handled | |
4678 | in a parameter to the interrupt attribute like this: | |
4679 | ||
4680 | @smallexample | |
4681 | void f () __attribute__ ((interrupt ("ilink1"))); | |
4682 | @end smallexample | |
4683 | ||
4684 | Permissible values for this parameter are: @w{@code{ilink1}} and | |
4685 | @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and | |
4686 | @w{@code{firq}} for ARCv2 architecture. | |
4687 | ||
d77de738 ML |
4688 | @cindex @code{long_call} function attribute, ARC |
4689 | @cindex @code{medium_call} function attribute, ARC | |
4690 | @cindex @code{short_call} function attribute, ARC | |
4691 | @cindex indirect calls, ARC | |
f33d7a88 AA |
4692 | @item long_call |
4693 | @itemx medium_call | |
4694 | @itemx short_call | |
d77de738 ML |
4695 | These attributes specify how a particular function is called. |
4696 | These attributes override the | |
4697 | @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options}) | |
4698 | command-line switches and @code{#pragma long_calls} settings. | |
4699 | ||
4700 | For ARC, a function marked with the @code{long_call} attribute is | |
4701 | always called using register-indirect jump-and-link instructions, | |
4702 | thereby enabling the called function to be placed anywhere within the | |
4703 | 32-bit address space. A function marked with the @code{medium_call} | |
4704 | attribute will always be close enough to be called with an unconditional | |
4705 | branch-and-link instruction, which has a 25-bit offset from | |
4706 | the call site. A function marked with the @code{short_call} | |
4707 | attribute will always be close enough to be called with a conditional | |
4708 | branch-and-link instruction, which has a 21-bit offset from | |
4709 | the call site. | |
4710 | ||
d77de738 | 4711 | @cindex @code{jli_always} function attribute, ARC |
f33d7a88 | 4712 | @item jli_always |
d77de738 ML |
4713 | Forces a particular function to be called using @code{jli} |
4714 | instruction. The @code{jli} instruction makes use of a table stored | |
4715 | into @code{.jlitab} section, which holds the location of the functions | |
4716 | which are addressed using this instruction. | |
4717 | ||
d77de738 | 4718 | @cindex @code{jli_fixed} function attribute, ARC |
f33d7a88 | 4719 | @item jli_fixed |
d77de738 ML |
4720 | Identical like the above one, but the location of the function in the |
4721 | @code{jli} table is known and given as an attribute parameter. | |
4722 | ||
d77de738 | 4723 | @cindex @code{secure_call} function attribute, ARC |
f33d7a88 | 4724 | @item secure_call |
d77de738 ML |
4725 | This attribute allows one to mark secure-code functions that are |
4726 | callable from normal mode. The location of the secure call function | |
4727 | into the @code{sjli} table needs to be passed as argument. | |
4728 | ||
d77de738 | 4729 | @cindex @code{naked} function attribute, ARC |
f33d7a88 | 4730 | @item naked |
d77de738 ML |
4731 | This attribute allows the compiler to construct the requisite function |
4732 | declaration, while allowing the body of the function to be assembly | |
4733 | code. The specified function will not have prologue/epilogue | |
4734 | sequences generated by the compiler. Only basic @code{asm} statements | |
4735 | can safely be included in naked functions (@pxref{Basic Asm}). While | |
4736 | using extended @code{asm} or a mixture of basic @code{asm} and C code | |
4737 | may appear to work, they cannot be depended upon to work reliably and | |
4738 | are not supported. | |
4739 | ||
4740 | @end table | |
4741 | ||
4742 | @node ARM Function Attributes | |
4743 | @subsection ARM Function Attributes | |
4744 | ||
4745 | These function attributes are supported for ARM targets: | |
4746 | ||
4747 | @table @code | |
4748 | ||
d77de738 | 4749 | @cindex @code{general-regs-only} function attribute, ARM |
f33d7a88 | 4750 | @item general-regs-only |
d77de738 ML |
4751 | Indicates that no floating-point or Advanced SIMD registers should be |
4752 | used when generating code for this function. If the function explicitly | |
4753 | uses floating-point code, then the compiler gives an error. This is | |
4754 | the same behavior as that of the command-line option | |
4755 | @option{-mgeneral-regs-only}. | |
4756 | ||
d77de738 | 4757 | @cindex @code{interrupt} function attribute, ARM |
f33d7a88 | 4758 | @item interrupt |
d77de738 ML |
4759 | Use this attribute to indicate |
4760 | that the specified function is an interrupt handler. The compiler generates | |
4761 | function entry and exit sequences suitable for use in an interrupt handler | |
4762 | when this attribute is present. | |
4763 | ||
4764 | You can specify the kind of interrupt to be handled by | |
4765 | adding an optional parameter to the interrupt attribute like this: | |
4766 | ||
4767 | @smallexample | |
4768 | void f () __attribute__ ((interrupt ("IRQ"))); | |
4769 | @end smallexample | |
4770 | ||
4771 | @noindent | |
4772 | Permissible values for this parameter are: @code{IRQ}, @code{FIQ}, | |
4773 | @code{SWI}, @code{ABORT} and @code{UNDEF}. | |
4774 | ||
4775 | On ARMv7-M the interrupt type is ignored, and the attribute means the function | |
4776 | may be called with a word-aligned stack pointer. | |
4777 | ||
d77de738 | 4778 | @cindex @code{isr} function attribute, ARM |
f33d7a88 | 4779 | @item isr |
d77de738 ML |
4780 | Use this attribute on ARM to write Interrupt Service Routines. This is an |
4781 | alias to the @code{interrupt} attribute above. | |
4782 | ||
d77de738 ML |
4783 | @cindex @code{long_call} function attribute, ARM |
4784 | @cindex @code{short_call} function attribute, ARM | |
4785 | @cindex indirect calls, ARM | |
f33d7a88 AA |
4786 | @item long_call |
4787 | @itemx short_call | |
d77de738 ML |
4788 | These attributes specify how a particular function is called. |
4789 | These attributes override the | |
4790 | @option{-mlong-calls} (@pxref{ARM Options}) | |
4791 | command-line switch and @code{#pragma long_calls} settings. For ARM, the | |
4792 | @code{long_call} attribute indicates that the function might be far | |
4793 | away from the call site and require a different (more expensive) | |
4794 | calling sequence. The @code{short_call} attribute always places | |
4795 | the offset to the function from the call site into the @samp{BL} | |
4796 | instruction directly. | |
4797 | ||
d77de738 | 4798 | @cindex @code{naked} function attribute, ARM |
f33d7a88 | 4799 | @item naked |
d77de738 ML |
4800 | This attribute allows the compiler to construct the |
4801 | requisite function declaration, while allowing the body of the | |
4802 | function to be assembly code. The specified function will not have | |
4803 | prologue/epilogue sequences generated by the compiler. Only basic | |
4804 | @code{asm} statements can safely be included in naked functions | |
4805 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
4806 | basic @code{asm} and C code may appear to work, they cannot be | |
4807 | depended upon to work reliably and are not supported. | |
4808 | ||
d77de738 | 4809 | @cindex @code{pcs} function attribute, ARM |
f33d7a88 | 4810 | @item pcs |
d77de738 ML |
4811 | |
4812 | The @code{pcs} attribute can be used to control the calling convention | |
4813 | used for a function on ARM. The attribute takes an argument that specifies | |
4814 | the calling convention to use. | |
4815 | ||
4816 | When compiling using the AAPCS ABI (or a variant of it) then valid | |
4817 | values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In | |
4818 | order to use a variant other than @code{"aapcs"} then the compiler must | |
4819 | be permitted to use the appropriate co-processor registers (i.e., the | |
4820 | VFP registers must be available in order to use @code{"aapcs-vfp"}). | |
4821 | For example, | |
4822 | ||
4823 | @smallexample | |
4824 | /* Argument passed in r0, and result returned in r0+r1. */ | |
4825 | double f2d (float) __attribute__((pcs("aapcs"))); | |
4826 | @end smallexample | |
4827 | ||
4828 | Variadic functions always use the @code{"aapcs"} calling convention and | |
4829 | the compiler rejects attempts to specify an alternative. | |
4830 | ||
d77de738 | 4831 | @cindex @code{target} function attribute |
f33d7a88 | 4832 | @item target (@var{options}) |
d77de738 ML |
4833 | As discussed in @ref{Common Function Attributes}, this attribute |
4834 | allows specification of target-specific compilation options. | |
4835 | ||
4836 | On ARM, the following options are allowed: | |
4837 | ||
4838 | @table @samp | |
d77de738 | 4839 | @cindex @code{target("thumb")} function attribute, ARM |
f33d7a88 | 4840 | @item thumb |
d77de738 ML |
4841 | Force code generation in the Thumb (T16/T32) ISA, depending on the |
4842 | architecture level. | |
4843 | ||
d77de738 | 4844 | @cindex @code{target("arm")} function attribute, ARM |
f33d7a88 | 4845 | @item arm |
d77de738 ML |
4846 | Force code generation in the ARM (A32) ISA. |
4847 | ||
4848 | Functions from different modes can be inlined in the caller's mode. | |
4849 | ||
d77de738 | 4850 | @cindex @code{target("fpu=")} function attribute, ARM |
f33d7a88 | 4851 | @item fpu= |
d77de738 ML |
4852 | Specifies the fpu for which to tune the performance of this function. |
4853 | The behavior and permissible arguments are the same as for the @option{-mfpu=} | |
4854 | command-line option. | |
4855 | ||
d77de738 | 4856 | @cindex @code{arch=} function attribute, ARM |
f33d7a88 | 4857 | @item arch= |
d77de738 ML |
4858 | Specifies the architecture version and architectural extensions to use |
4859 | for this function. The behavior and permissible arguments are the same as | |
4860 | for the @option{-march=} command-line option. | |
4861 | ||
4862 | The above target attributes can be specified as follows: | |
4863 | ||
4864 | @smallexample | |
4865 | __attribute__((target("arch=armv8-a+crc"))) | |
4866 | int | |
4867 | f (int a) | |
4868 | @{ | |
4869 | return a + 5; | |
4870 | @} | |
4871 | @end smallexample | |
4872 | ||
4873 | Additionally, the architectural extension string may be specified on its | |
4874 | own. This can be used to turn on and off particular architectural extensions | |
4875 | without having to specify a particular architecture version or core. Example: | |
4876 | ||
4877 | @smallexample | |
4878 | __attribute__((target("+crc+nocrypto"))) | |
4879 | int | |
4880 | foo (int a) | |
4881 | @{ | |
4882 | return a + 5; | |
4883 | @} | |
4884 | @end smallexample | |
4885 | ||
4886 | In this example @code{target("+crc+nocrypto")} enables the @code{crc} | |
4887 | extension and disables the @code{crypto} extension for the function @code{foo} | |
4888 | without modifying an existing @option{-march=} or @option{-mcpu} option. | |
4889 | ||
4890 | @end table | |
4891 | ||
4892 | @end table | |
4893 | ||
4894 | @node AVR Function Attributes | |
4895 | @subsection AVR Function Attributes | |
4896 | ||
4897 | These function attributes are supported by the AVR back end: | |
4898 | ||
4899 | @table @code | |
d77de738 | 4900 | @cindex @code{interrupt} function attribute, AVR |
f33d7a88 | 4901 | @item interrupt |
d77de738 ML |
4902 | Use this attribute to indicate |
4903 | that the specified function is an interrupt handler. The compiler generates | |
4904 | function entry and exit sequences suitable for use in an interrupt handler | |
4905 | when this attribute is present. | |
4906 | ||
4907 | On the AVR, the hardware globally disables interrupts when an | |
4908 | interrupt is executed. The first instruction of an interrupt handler | |
4909 | declared with this attribute is a @code{SEI} instruction to | |
4910 | re-enable interrupts. See also the @code{signal} function attribute | |
4911 | that does not insert a @code{SEI} instruction. If both @code{signal} and | |
4912 | @code{interrupt} are specified for the same function, @code{signal} | |
4913 | is silently ignored. | |
4914 | ||
d77de738 | 4915 | @cindex @code{naked} function attribute, AVR |
f33d7a88 | 4916 | @item naked |
d77de738 ML |
4917 | This attribute allows the compiler to construct the |
4918 | requisite function declaration, while allowing the body of the | |
4919 | function to be assembly code. The specified function will not have | |
4920 | prologue/epilogue sequences generated by the compiler. Only basic | |
4921 | @code{asm} statements can safely be included in naked functions | |
4922 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
4923 | basic @code{asm} and C code may appear to work, they cannot be | |
4924 | depended upon to work reliably and are not supported. | |
4925 | ||
d77de738 | 4926 | @cindex @code{no_gccisr} function attribute, AVR |
f33d7a88 | 4927 | @item no_gccisr |
d77de738 ML |
4928 | Do not use @code{__gcc_isr} pseudo instructions in a function with |
4929 | the @code{interrupt} or @code{signal} attribute aka. interrupt | |
4930 | service routine (ISR). | |
4931 | Use this attribute if the preamble of the ISR prologue should always read | |
4932 | @example | |
4933 | push __zero_reg__ | |
4934 | push __tmp_reg__ | |
4935 | in __tmp_reg__, __SREG__ | |
4936 | push __tmp_reg__ | |
4937 | clr __zero_reg__ | |
4938 | @end example | |
4939 | and accordingly for the postamble of the epilogue --- no matter whether | |
4940 | the mentioned registers are actually used in the ISR or not. | |
4941 | Situations where you might want to use this attribute include: | |
4942 | @itemize @bullet | |
4943 | @item | |
4944 | Code that (effectively) clobbers bits of @code{SREG} other than the | |
4945 | @code{I}-flag by writing to the memory location of @code{SREG}. | |
4946 | @item | |
4947 | Code that uses inline assembler to jump to a different function which | |
4948 | expects (parts of) the prologue code as outlined above to be present. | |
4949 | @end itemize | |
4950 | To disable @code{__gcc_isr} generation for the whole compilation unit, | |
4951 | there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}. | |
4952 | ||
d77de738 ML |
4953 | @cindex @code{OS_main} function attribute, AVR |
4954 | @cindex @code{OS_task} function attribute, AVR | |
f33d7a88 AA |
4955 | @item OS_main |
4956 | @itemx OS_task | |
d77de738 ML |
4957 | On AVR, functions with the @code{OS_main} or @code{OS_task} attribute |
4958 | do not save/restore any call-saved register in their prologue/epilogue. | |
4959 | ||
4960 | The @code{OS_main} attribute can be used when there @emph{is | |
4961 | guarantee} that interrupts are disabled at the time when the function | |
4962 | is entered. This saves resources when the stack pointer has to be | |
4963 | changed to set up a frame for local variables. | |
4964 | ||
4965 | The @code{OS_task} attribute can be used when there is @emph{no | |
4966 | guarantee} that interrupts are disabled at that time when the function | |
4967 | is entered like for, e@.g@. task functions in a multi-threading operating | |
4968 | system. In that case, changing the stack pointer register is | |
4969 | guarded by save/clear/restore of the global interrupt enable flag. | |
4970 | ||
4971 | The differences to the @code{naked} function attribute are: | |
4972 | @itemize @bullet | |
4973 | @item @code{naked} functions do not have a return instruction whereas | |
4974 | @code{OS_main} and @code{OS_task} functions have a @code{RET} or | |
4975 | @code{RETI} return instruction. | |
4976 | @item @code{naked} functions do not set up a frame for local variables | |
4977 | or a frame pointer whereas @code{OS_main} and @code{OS_task} do this | |
4978 | as needed. | |
4979 | @end itemize | |
4980 | ||
d77de738 | 4981 | @cindex @code{signal} function attribute, AVR |
f33d7a88 | 4982 | @item signal |
d77de738 ML |
4983 | Use this attribute on the AVR to indicate that the specified |
4984 | function is an interrupt handler. The compiler generates function | |
4985 | entry and exit sequences suitable for use in an interrupt handler when this | |
4986 | attribute is present. | |
4987 | ||
4988 | See also the @code{interrupt} function attribute. | |
4989 | ||
4990 | The AVR hardware globally disables interrupts when an interrupt is executed. | |
4991 | Interrupt handler functions defined with the @code{signal} attribute | |
4992 | do not re-enable interrupts. It is save to enable interrupts in a | |
4993 | @code{signal} handler. This ``save'' only applies to the code | |
4994 | generated by the compiler and not to the IRQ layout of the | |
4995 | application which is responsibility of the application. | |
4996 | ||
4997 | If both @code{signal} and @code{interrupt} are specified for the same | |
4998 | function, @code{signal} is silently ignored. | |
4999 | @end table | |
5000 | ||
5001 | @node Blackfin Function Attributes | |
5002 | @subsection Blackfin Function Attributes | |
5003 | ||
5004 | These function attributes are supported by the Blackfin back end: | |
5005 | ||
5006 | @table @code | |
5007 | ||
d77de738 ML |
5008 | @cindex @code{exception_handler} function attribute |
5009 | @cindex exception handler functions, Blackfin | |
f33d7a88 | 5010 | @item exception_handler |
d77de738 ML |
5011 | Use this attribute on the Blackfin to indicate that the specified function |
5012 | is an exception handler. The compiler generates function entry and | |
5013 | exit sequences suitable for use in an exception handler when this | |
5014 | attribute is present. | |
5015 | ||
d77de738 | 5016 | @cindex @code{interrupt_handler} function attribute, Blackfin |
f33d7a88 | 5017 | @item interrupt_handler |
d77de738 ML |
5018 | Use this attribute to |
5019 | indicate that the specified function is an interrupt handler. The compiler | |
5020 | generates function entry and exit sequences suitable for use in an | |
5021 | interrupt handler when this attribute is present. | |
5022 | ||
d77de738 ML |
5023 | @cindex @code{kspisusp} function attribute, Blackfin |
5024 | @cindex User stack pointer in interrupts on the Blackfin | |
f33d7a88 | 5025 | @item kspisusp |
d77de738 ML |
5026 | When used together with @code{interrupt_handler}, @code{exception_handler} |
5027 | or @code{nmi_handler}, code is generated to load the stack pointer | |
5028 | from the USP register in the function prologue. | |
5029 | ||
d77de738 | 5030 | @cindex @code{l1_text} function attribute, Blackfin |
f33d7a88 | 5031 | @item l1_text |
d77de738 ML |
5032 | This attribute specifies a function to be placed into L1 Instruction |
5033 | SRAM@. The function is put into a specific section named @code{.l1.text}. | |
5034 | With @option{-mfdpic}, function calls with a such function as the callee | |
5035 | or caller uses inlined PLT. | |
5036 | ||
d77de738 | 5037 | @cindex @code{l2} function attribute, Blackfin |
f33d7a88 | 5038 | @item l2 |
d77de738 ML |
5039 | This attribute specifies a function to be placed into L2 |
5040 | SRAM. The function is put into a specific section named | |
5041 | @code{.l2.text}. With @option{-mfdpic}, callers of such functions use | |
5042 | an inlined PLT. | |
5043 | ||
d77de738 ML |
5044 | @cindex indirect calls, Blackfin |
5045 | @cindex @code{longcall} function attribute, Blackfin | |
5046 | @cindex @code{shortcall} function attribute, Blackfin | |
f33d7a88 AA |
5047 | @item longcall |
5048 | @itemx shortcall | |
d77de738 ML |
5049 | The @code{longcall} attribute |
5050 | indicates that the function might be far away from the call site and | |
5051 | require a different (more expensive) calling sequence. The | |
5052 | @code{shortcall} attribute indicates that the function is always close | |
5053 | enough for the shorter calling sequence to be used. These attributes | |
5054 | override the @option{-mlongcall} switch. | |
5055 | ||
d77de738 ML |
5056 | @cindex @code{nesting} function attribute, Blackfin |
5057 | @cindex Allow nesting in an interrupt handler on the Blackfin processor | |
f33d7a88 | 5058 | @item nesting |
d77de738 ML |
5059 | Use this attribute together with @code{interrupt_handler}, |
5060 | @code{exception_handler} or @code{nmi_handler} to indicate that the function | |
5061 | entry code should enable nested interrupts or exceptions. | |
5062 | ||
d77de738 ML |
5063 | @cindex @code{nmi_handler} function attribute, Blackfin |
5064 | @cindex NMI handler functions on the Blackfin processor | |
f33d7a88 | 5065 | @item nmi_handler |
d77de738 ML |
5066 | Use this attribute on the Blackfin to indicate that the specified function |
5067 | is an NMI handler. The compiler generates function entry and | |
5068 | exit sequences suitable for use in an NMI handler when this | |
5069 | attribute is present. | |
5070 | ||
d77de738 ML |
5071 | @cindex @code{saveall} function attribute, Blackfin |
5072 | @cindex save all registers on the Blackfin | |
f33d7a88 | 5073 | @item saveall |
d77de738 ML |
5074 | Use this attribute to indicate that |
5075 | all registers except the stack pointer should be saved in the prologue | |
5076 | regardless of whether they are used or not. | |
5077 | @end table | |
5078 | ||
5079 | @node BPF Function Attributes | |
5080 | @subsection BPF Function Attributes | |
5081 | ||
5082 | These function attributes are supported by the BPF back end: | |
5083 | ||
5084 | @table @code | |
d77de738 | 5085 | @cindex @code{kernel helper}, function attribute, BPF |
f33d7a88 | 5086 | @item kernel_helper |
d77de738 ML |
5087 | use this attribute to indicate the specified function declaration is a |
5088 | kernel helper. The helper function is passed as an argument to the | |
5089 | attribute. Example: | |
5090 | ||
5091 | @smallexample | |
5092 | int bpf_probe_read (void *dst, int size, const void *unsafe_ptr) | |
5093 | __attribute__ ((kernel_helper (4))); | |
5094 | @end smallexample | |
5095 | @end table | |
5096 | ||
5097 | @node C-SKY Function Attributes | |
5098 | @subsection C-SKY Function Attributes | |
5099 | ||
5100 | These function attributes are supported by the C-SKY back end: | |
5101 | ||
5102 | @table @code | |
d77de738 ML |
5103 | @cindex @code{interrupt} function attribute, C-SKY |
5104 | @cindex @code{isr} function attribute, C-SKY | |
f33d7a88 AA |
5105 | @item interrupt |
5106 | @itemx isr | |
d77de738 ML |
5107 | Use these attributes to indicate that the specified function |
5108 | is an interrupt handler. | |
5109 | The compiler generates function entry and exit sequences suitable for | |
5110 | use in an interrupt handler when either of these attributes are present. | |
5111 | ||
5112 | Use of these options requires the @option{-mistack} command-line option | |
5113 | to enable support for the necessary interrupt stack instructions. They | |
5114 | are ignored with a warning otherwise. @xref{C-SKY Options}. | |
5115 | ||
d77de738 | 5116 | @cindex @code{naked} function attribute, C-SKY |
f33d7a88 | 5117 | @item naked |
d77de738 ML |
5118 | This attribute allows the compiler to construct the |
5119 | requisite function declaration, while allowing the body of the | |
5120 | function to be assembly code. The specified function will not have | |
5121 | prologue/epilogue sequences generated by the compiler. Only basic | |
5122 | @code{asm} statements can safely be included in naked functions | |
5123 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5124 | basic @code{asm} and C code may appear to work, they cannot be | |
5125 | depended upon to work reliably and are not supported. | |
5126 | @end table | |
5127 | ||
5128 | ||
5129 | @node Epiphany Function Attributes | |
5130 | @subsection Epiphany Function Attributes | |
5131 | ||
5132 | These function attributes are supported by the Epiphany back end: | |
5133 | ||
5134 | @table @code | |
d77de738 | 5135 | @cindex @code{disinterrupt} function attribute, Epiphany |
f33d7a88 | 5136 | @item disinterrupt |
d77de738 ML |
5137 | This attribute causes the compiler to emit |
5138 | instructions to disable interrupts for the duration of the given | |
5139 | function. | |
5140 | ||
d77de738 | 5141 | @cindex @code{forwarder_section} function attribute, Epiphany |
f33d7a88 | 5142 | @item forwarder_section |
d77de738 ML |
5143 | This attribute modifies the behavior of an interrupt handler. |
5144 | The interrupt handler may be in external memory which cannot be | |
5145 | reached by a branch instruction, so generate a local memory trampoline | |
5146 | to transfer control. The single parameter identifies the section where | |
5147 | the trampoline is placed. | |
5148 | ||
d77de738 | 5149 | @cindex @code{interrupt} function attribute, Epiphany |
f33d7a88 | 5150 | @item interrupt |
d77de738 ML |
5151 | Use this attribute to indicate |
5152 | that the specified function is an interrupt handler. The compiler generates | |
5153 | function entry and exit sequences suitable for use in an interrupt handler | |
5154 | when this attribute is present. It may also generate | |
5155 | a special section with code to initialize the interrupt vector table. | |
5156 | ||
5157 | On Epiphany targets one or more optional parameters can be added like this: | |
5158 | ||
5159 | @smallexample | |
5160 | void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); | |
5161 | @end smallexample | |
5162 | ||
5163 | Permissible values for these parameters are: @w{@code{reset}}, | |
5164 | @w{@code{software_exception}}, @w{@code{page_miss}}, | |
5165 | @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, | |
5166 | @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. | |
5167 | Multiple parameters indicate that multiple entries in the interrupt | |
5168 | vector table should be initialized for this function, i.e.@: for each | |
5169 | parameter @w{@var{name}}, a jump to the function is emitted in | |
5170 | the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted | |
5171 | entirely, in which case no interrupt vector table entry is provided. | |
5172 | ||
5173 | Note that interrupts are enabled inside the function | |
5174 | unless the @code{disinterrupt} attribute is also specified. | |
5175 | ||
5176 | The following examples are all valid uses of these attributes on | |
5177 | Epiphany targets: | |
5178 | @smallexample | |
5179 | void __attribute__ ((interrupt)) universal_handler (); | |
5180 | void __attribute__ ((interrupt ("dma1"))) dma1_handler (); | |
5181 | void __attribute__ ((interrupt ("dma0, dma1"))) | |
5182 | universal_dma_handler (); | |
5183 | void __attribute__ ((interrupt ("timer0"), disinterrupt)) | |
5184 | fast_timer_handler (); | |
5185 | void __attribute__ ((interrupt ("dma0, dma1"), | |
5186 | forwarder_section ("tramp"))) | |
5187 | external_dma_handler (); | |
5188 | @end smallexample | |
5189 | ||
d77de738 ML |
5190 | @cindex @code{long_call} function attribute, Epiphany |
5191 | @cindex @code{short_call} function attribute, Epiphany | |
5192 | @cindex indirect calls, Epiphany | |
f33d7a88 AA |
5193 | @item long_call |
5194 | @itemx short_call | |
d77de738 ML |
5195 | These attributes specify how a particular function is called. |
5196 | These attributes override the | |
5197 | @option{-mlong-calls} (@pxref{Adapteva Epiphany Options}) | |
5198 | command-line switch and @code{#pragma long_calls} settings. | |
5199 | @end table | |
5200 | ||
5201 | ||
5202 | @node H8/300 Function Attributes | |
5203 | @subsection H8/300 Function Attributes | |
5204 | ||
5205 | These function attributes are available for H8/300 targets: | |
5206 | ||
5207 | @table @code | |
d77de738 | 5208 | @cindex @code{function_vector} function attribute, H8/300 |
f33d7a88 | 5209 | @item function_vector |
d77de738 ML |
5210 | Use this attribute on the H8/300, H8/300H, and H8S to indicate |
5211 | that the specified function should be called through the function vector. | |
5212 | Calling a function through the function vector reduces code size; however, | |
5213 | the function vector has a limited size (maximum 128 entries on the H8/300 | |
5214 | and 64 entries on the H8/300H and H8S) | |
5215 | and shares space with the interrupt vector. | |
5216 | ||
d77de738 | 5217 | @cindex @code{interrupt_handler} function attribute, H8/300 |
f33d7a88 | 5218 | @item interrupt_handler |
d77de738 ML |
5219 | Use this attribute on the H8/300, H8/300H, and H8S to |
5220 | indicate that the specified function is an interrupt handler. The compiler | |
5221 | generates function entry and exit sequences suitable for use in an | |
5222 | interrupt handler when this attribute is present. | |
5223 | ||
d77de738 ML |
5224 | @cindex @code{saveall} function attribute, H8/300 |
5225 | @cindex save all registers on the H8/300, H8/300H, and H8S | |
f33d7a88 | 5226 | @item saveall |
d77de738 ML |
5227 | Use this attribute on the H8/300, H8/300H, and H8S to indicate that |
5228 | all registers except the stack pointer should be saved in the prologue | |
5229 | regardless of whether they are used or not. | |
5230 | @end table | |
5231 | ||
5232 | @node IA-64 Function Attributes | |
5233 | @subsection IA-64 Function Attributes | |
5234 | ||
5235 | These function attributes are supported on IA-64 targets: | |
5236 | ||
5237 | @table @code | |
d77de738 | 5238 | @cindex @code{syscall_linkage} function attribute, IA-64 |
f33d7a88 | 5239 | @item syscall_linkage |
d77de738 ML |
5240 | This attribute is used to modify the IA-64 calling convention by marking |
5241 | all input registers as live at all function exits. This makes it possible | |
5242 | to restart a system call after an interrupt without having to save/restore | |
5243 | the input registers. This also prevents kernel data from leaking into | |
5244 | application code. | |
5245 | ||
d77de738 | 5246 | @cindex @code{version_id} function attribute, IA-64 |
f33d7a88 | 5247 | @item version_id |
d77de738 ML |
5248 | This IA-64 HP-UX attribute, attached to a global variable or function, renames a |
5249 | symbol to contain a version string, thus allowing for function level | |
5250 | versioning. HP-UX system header files may use function level versioning | |
5251 | for some system calls. | |
5252 | ||
5253 | @smallexample | |
5254 | extern int foo () __attribute__((version_id ("20040821"))); | |
5255 | @end smallexample | |
5256 | ||
5257 | @noindent | |
5258 | Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}. | |
5259 | @end table | |
5260 | ||
5261 | @node M32C Function Attributes | |
5262 | @subsection M32C Function Attributes | |
5263 | ||
5264 | These function attributes are supported by the M32C back end: | |
5265 | ||
5266 | @table @code | |
d77de738 | 5267 | @cindex @code{bank_switch} function attribute, M32C |
f33d7a88 | 5268 | @item bank_switch |
d77de738 ML |
5269 | When added to an interrupt handler with the M32C port, causes the |
5270 | prologue and epilogue to use bank switching to preserve the registers | |
5271 | rather than saving them on the stack. | |
5272 | ||
d77de738 | 5273 | @cindex @code{fast_interrupt} function attribute, M32C |
f33d7a88 | 5274 | @item fast_interrupt |
d77de738 ML |
5275 | Use this attribute on the M32C port to indicate that the specified |
5276 | function is a fast interrupt handler. This is just like the | |
5277 | @code{interrupt} attribute, except that @code{freit} is used to return | |
5278 | instead of @code{reit}. | |
5279 | ||
d77de738 | 5280 | @cindex @code{function_vector} function attribute, M16C/M32C |
f33d7a88 | 5281 | @item function_vector |
d77de738 ML |
5282 | On M16C/M32C targets, the @code{function_vector} attribute declares a |
5283 | special page subroutine call function. Use of this attribute reduces | |
5284 | the code size by 2 bytes for each call generated to the | |
5285 | subroutine. The argument to the attribute is the vector number entry | |
5286 | from the special page vector table which contains the 16 low-order | |
5287 | bits of the subroutine's entry address. Each vector table has special | |
5288 | page number (18 to 255) that is used in @code{jsrs} instructions. | |
5289 | Jump addresses of the routines are generated by adding 0x0F0000 (in | |
5290 | case of M16C targets) or 0xFF0000 (in case of M32C targets), to the | |
5291 | 2-byte addresses set in the vector table. Therefore you need to ensure | |
5292 | that all the special page vector routines should get mapped within the | |
5293 | address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF | |
5294 | (for M32C). | |
5295 | ||
5296 | In the following example 2 bytes are saved for each call to | |
5297 | function @code{foo}. | |
5298 | ||
5299 | @smallexample | |
5300 | void foo (void) __attribute__((function_vector(0x18))); | |
5301 | void foo (void) | |
5302 | @{ | |
5303 | @} | |
5304 | ||
5305 | void bar (void) | |
5306 | @{ | |
5307 | foo(); | |
5308 | @} | |
5309 | @end smallexample | |
5310 | ||
5311 | If functions are defined in one file and are called in another file, | |
5312 | then be sure to write this declaration in both files. | |
5313 | ||
5314 | This attribute is ignored for R8C target. | |
5315 | ||
d77de738 | 5316 | @cindex @code{interrupt} function attribute, M32C |
f33d7a88 | 5317 | @item interrupt |
d77de738 ML |
5318 | Use this attribute to indicate |
5319 | that the specified function is an interrupt handler. The compiler generates | |
5320 | function entry and exit sequences suitable for use in an interrupt handler | |
5321 | when this attribute is present. | |
5322 | @end table | |
5323 | ||
5324 | @node M32R/D Function Attributes | |
5325 | @subsection M32R/D Function Attributes | |
5326 | ||
5327 | These function attributes are supported by the M32R/D back end: | |
5328 | ||
5329 | @table @code | |
d77de738 | 5330 | @cindex @code{interrupt} function attribute, M32R/D |
f33d7a88 | 5331 | @item interrupt |
d77de738 ML |
5332 | Use this attribute to indicate |
5333 | that the specified function is an interrupt handler. The compiler generates | |
5334 | function entry and exit sequences suitable for use in an interrupt handler | |
5335 | when this attribute is present. | |
5336 | ||
d77de738 ML |
5337 | @cindex @code{model} function attribute, M32R/D |
5338 | @cindex function addressability on the M32R/D | |
f33d7a88 | 5339 | @item model (@var{model-name}) |
d77de738 ML |
5340 | |
5341 | On the M32R/D, use this attribute to set the addressability of an | |
5342 | object, and of the code generated for a function. The identifier | |
5343 | @var{model-name} is one of @code{small}, @code{medium}, or | |
5344 | @code{large}, representing each of the code models. | |
5345 | ||
5346 | Small model objects live in the lower 16MB of memory (so that their | |
5347 | addresses can be loaded with the @code{ld24} instruction), and are | |
5348 | callable with the @code{bl} instruction. | |
5349 | ||
5350 | Medium model objects may live anywhere in the 32-bit address space (the | |
5351 | compiler generates @code{seth/add3} instructions to load their addresses), | |
5352 | and are callable with the @code{bl} instruction. | |
5353 | ||
5354 | Large model objects may live anywhere in the 32-bit address space (the | |
5355 | compiler generates @code{seth/add3} instructions to load their addresses), | |
5356 | and may not be reachable with the @code{bl} instruction (the compiler | |
5357 | generates the much slower @code{seth/add3/jl} instruction sequence). | |
5358 | @end table | |
5359 | ||
5360 | @node m68k Function Attributes | |
5361 | @subsection m68k Function Attributes | |
5362 | ||
5363 | These function attributes are supported by the m68k back end: | |
5364 | ||
5365 | @table @code | |
d77de738 ML |
5366 | @cindex @code{interrupt} function attribute, m68k |
5367 | @cindex @code{interrupt_handler} function attribute, m68k | |
f33d7a88 AA |
5368 | @item interrupt |
5369 | @itemx interrupt_handler | |
d77de738 ML |
5370 | Use this attribute to |
5371 | indicate that the specified function is an interrupt handler. The compiler | |
5372 | generates function entry and exit sequences suitable for use in an | |
5373 | interrupt handler when this attribute is present. Either name may be used. | |
5374 | ||
d77de738 | 5375 | @cindex @code{interrupt_thread} function attribute, fido |
f33d7a88 | 5376 | @item interrupt_thread |
d77de738 ML |
5377 | Use this attribute on fido, a subarchitecture of the m68k, to indicate |
5378 | that the specified function is an interrupt handler that is designed | |
5379 | to run as a thread. The compiler omits generate prologue/epilogue | |
5380 | sequences and replaces the return instruction with a @code{sleep} | |
5381 | instruction. This attribute is available only on fido. | |
5382 | @end table | |
5383 | ||
5384 | @node MCORE Function Attributes | |
5385 | @subsection MCORE Function Attributes | |
5386 | ||
5387 | These function attributes are supported by the MCORE back end: | |
5388 | ||
5389 | @table @code | |
d77de738 | 5390 | @cindex @code{naked} function attribute, MCORE |
f33d7a88 | 5391 | @item naked |
d77de738 ML |
5392 | This attribute allows the compiler to construct the |
5393 | requisite function declaration, while allowing the body of the | |
5394 | function to be assembly code. The specified function will not have | |
5395 | prologue/epilogue sequences generated by the compiler. Only basic | |
5396 | @code{asm} statements can safely be included in naked functions | |
5397 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5398 | basic @code{asm} and C code may appear to work, they cannot be | |
5399 | depended upon to work reliably and are not supported. | |
5400 | @end table | |
5401 | ||
d77de738 ML |
5402 | @node MicroBlaze Function Attributes |
5403 | @subsection MicroBlaze Function Attributes | |
5404 | ||
5405 | These function attributes are supported on MicroBlaze targets: | |
5406 | ||
5407 | @table @code | |
d77de738 | 5408 | @cindex @code{save_volatiles} function attribute, MicroBlaze |
f33d7a88 | 5409 | @item save_volatiles |
d77de738 ML |
5410 | Use this attribute to indicate that the function is |
5411 | an interrupt handler. All volatile registers (in addition to non-volatile | |
5412 | registers) are saved in the function prologue. If the function is a leaf | |
5413 | function, only volatiles used by the function are saved. A normal function | |
5414 | return is generated instead of a return from interrupt. | |
5415 | ||
d77de738 ML |
5416 | @cindex @code{break_handler} function attribute, MicroBlaze |
5417 | @cindex break handler functions | |
f33d7a88 | 5418 | @item break_handler |
d77de738 ML |
5419 | Use this attribute to indicate that |
5420 | the specified function is a break handler. The compiler generates function | |
5421 | entry and exit sequences suitable for use in an break handler when this | |
5422 | attribute is present. The return from @code{break_handler} is done through | |
5423 | the @code{rtbd} instead of @code{rtsd}. | |
5424 | ||
5425 | @smallexample | |
5426 | void f () __attribute__ ((break_handler)); | |
5427 | @end smallexample | |
5428 | ||
d77de738 ML |
5429 | @cindex @code{interrupt_handler} function attribute, MicroBlaze |
5430 | @cindex @code{fast_interrupt} function attribute, MicroBlaze | |
f33d7a88 AA |
5431 | @item interrupt_handler |
5432 | @itemx fast_interrupt | |
d77de738 ML |
5433 | These attributes indicate that the specified function is an interrupt |
5434 | handler. Use the @code{fast_interrupt} attribute to indicate handlers | |
5435 | used in low-latency interrupt mode, and @code{interrupt_handler} for | |
5436 | interrupts that do not use low-latency handlers. In both cases, GCC | |
5437 | emits appropriate prologue code and generates a return from the handler | |
5438 | using @code{rtid} instead of @code{rtsd}. | |
5439 | @end table | |
5440 | ||
5441 | @node Microsoft Windows Function Attributes | |
5442 | @subsection Microsoft Windows Function Attributes | |
5443 | ||
5444 | The following attributes are available on Microsoft Windows and Symbian OS | |
5445 | targets. | |
5446 | ||
5447 | @table @code | |
d77de738 ML |
5448 | @cindex @code{dllexport} function attribute |
5449 | @cindex @code{__declspec(dllexport)} | |
f33d7a88 | 5450 | @item dllexport |
d77de738 ML |
5451 | On Microsoft Windows targets and Symbian OS targets the |
5452 | @code{dllexport} attribute causes the compiler to provide a global | |
5453 | pointer to a pointer in a DLL, so that it can be referenced with the | |
5454 | @code{dllimport} attribute. On Microsoft Windows targets, the pointer | |
5455 | name is formed by combining @code{_imp__} and the function or variable | |
5456 | name. | |
5457 | ||
5458 | You can use @code{__declspec(dllexport)} as a synonym for | |
5459 | @code{__attribute__ ((dllexport))} for compatibility with other | |
5460 | compilers. | |
5461 | ||
5462 | On systems that support the @code{visibility} attribute, this | |
5463 | attribute also implies ``default'' visibility. It is an error to | |
5464 | explicitly specify any other visibility. | |
5465 | ||
5466 | GCC's default behavior is to emit all inline functions with the | |
5467 | @code{dllexport} attribute. Since this can cause object file-size bloat, | |
5468 | you can use @option{-fno-keep-inline-dllexport}, which tells GCC to | |
5469 | ignore the attribute for inlined functions unless the | |
5470 | @option{-fkeep-inline-functions} flag is used instead. | |
5471 | ||
5472 | The attribute is ignored for undefined symbols. | |
5473 | ||
5474 | When applied to C++ classes, the attribute marks defined non-inlined | |
5475 | member functions and static data members as exports. Static consts | |
5476 | initialized in-class are not marked unless they are also defined | |
5477 | out-of-class. | |
5478 | ||
5479 | For Microsoft Windows targets there are alternative methods for | |
5480 | including the symbol in the DLL's export table such as using a | |
5481 | @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using | |
5482 | the @option{--export-all} linker flag. | |
5483 | ||
d77de738 ML |
5484 | @cindex @code{dllimport} function attribute |
5485 | @cindex @code{__declspec(dllimport)} | |
f33d7a88 | 5486 | @item dllimport |
d77de738 ML |
5487 | On Microsoft Windows and Symbian OS targets, the @code{dllimport} |
5488 | attribute causes the compiler to reference a function or variable via | |
5489 | a global pointer to a pointer that is set up by the DLL exporting the | |
5490 | symbol. The attribute implies @code{extern}. On Microsoft Windows | |
5491 | targets, the pointer name is formed by combining @code{_imp__} and the | |
5492 | function or variable name. | |
5493 | ||
5494 | You can use @code{__declspec(dllimport)} as a synonym for | |
5495 | @code{__attribute__ ((dllimport))} for compatibility with other | |
5496 | compilers. | |
5497 | ||
5498 | On systems that support the @code{visibility} attribute, this | |
5499 | attribute also implies ``default'' visibility. It is an error to | |
5500 | explicitly specify any other visibility. | |
5501 | ||
5502 | Currently, the attribute is ignored for inlined functions. If the | |
5503 | attribute is applied to a symbol @emph{definition}, an error is reported. | |
5504 | If a symbol previously declared @code{dllimport} is later defined, the | |
5505 | attribute is ignored in subsequent references, and a warning is emitted. | |
5506 | The attribute is also overridden by a subsequent declaration as | |
5507 | @code{dllexport}. | |
5508 | ||
5509 | When applied to C++ classes, the attribute marks non-inlined | |
5510 | member functions and static data members as imports. However, the | |
5511 | attribute is ignored for virtual methods to allow creation of vtables | |
5512 | using thunks. | |
5513 | ||
5514 | On the SH Symbian OS target the @code{dllimport} attribute also has | |
5515 | another affect---it can cause the vtable and run-time type information | |
5516 | for a class to be exported. This happens when the class has a | |
5517 | dllimported constructor or a non-inline, non-pure virtual function | |
5518 | and, for either of those two conditions, the class also has an inline | |
5519 | constructor or destructor and has a key function that is defined in | |
5520 | the current translation unit. | |
5521 | ||
5522 | For Microsoft Windows targets the use of the @code{dllimport} | |
5523 | attribute on functions is not necessary, but provides a small | |
5524 | performance benefit by eliminating a thunk in the DLL@. The use of the | |
5525 | @code{dllimport} attribute on imported variables can be avoided by passing the | |
5526 | @option{--enable-auto-import} switch to the GNU linker. As with | |
5527 | functions, using the attribute for a variable eliminates a thunk in | |
5528 | the DLL@. | |
5529 | ||
5530 | One drawback to using this attribute is that a pointer to a | |
5531 | @emph{variable} marked as @code{dllimport} cannot be used as a constant | |
5532 | address. However, a pointer to a @emph{function} with the | |
5533 | @code{dllimport} attribute can be used as a constant initializer; in | |
5534 | this case, the address of a stub function in the import lib is | |
5535 | referenced. On Microsoft Windows targets, the attribute can be disabled | |
5536 | for functions by setting the @option{-mnop-fun-dllimport} flag. | |
5537 | @end table | |
5538 | ||
5539 | @node MIPS Function Attributes | |
5540 | @subsection MIPS Function Attributes | |
5541 | ||
5542 | These function attributes are supported by the MIPS back end: | |
5543 | ||
5544 | @table @code | |
d77de738 | 5545 | @cindex @code{interrupt} function attribute, MIPS |
f33d7a88 | 5546 | @item interrupt |
d77de738 ML |
5547 | Use this attribute to indicate that the specified function is an interrupt |
5548 | handler. The compiler generates function entry and exit sequences suitable | |
5549 | for use in an interrupt handler when this attribute is present. | |
5550 | An optional argument is supported for the interrupt attribute which allows | |
5551 | the interrupt mode to be described. By default GCC assumes the external | |
5552 | interrupt controller (EIC) mode is in use, this can be explicitly set using | |
5553 | @code{eic}. When interrupts are non-masked then the requested Interrupt | |
5554 | Priority Level (IPL) is copied to the current IPL which has the effect of only | |
5555 | enabling higher priority interrupts. To use vectored interrupt mode use | |
5556 | the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change | |
5557 | the behavior of the non-masked interrupt support and GCC will arrange to mask | |
5558 | all interrupts from sw0 up to and including the specified interrupt vector. | |
5559 | ||
5560 | You can use the following attributes to modify the behavior | |
5561 | of an interrupt handler: | |
5562 | @table @code | |
d77de738 | 5563 | @cindex @code{use_shadow_register_set} function attribute, MIPS |
f33d7a88 | 5564 | @item use_shadow_register_set |
d77de738 ML |
5565 | Assume that the handler uses a shadow register set, instead of |
5566 | the main general-purpose registers. An optional argument @code{intstack} is | |
5567 | supported to indicate that the shadow register set contains a valid stack | |
5568 | pointer. | |
5569 | ||
d77de738 | 5570 | @cindex @code{keep_interrupts_masked} function attribute, MIPS |
f33d7a88 | 5571 | @item keep_interrupts_masked |
d77de738 ML |
5572 | Keep interrupts masked for the whole function. Without this attribute, |
5573 | GCC tries to reenable interrupts for as much of the function as it can. | |
5574 | ||
d77de738 | 5575 | @cindex @code{use_debug_exception_return} function attribute, MIPS |
f33d7a88 | 5576 | @item use_debug_exception_return |
d77de738 ML |
5577 | Return using the @code{deret} instruction. Interrupt handlers that don't |
5578 | have this attribute return using @code{eret} instead. | |
5579 | @end table | |
5580 | ||
5581 | You can use any combination of these attributes, as shown below: | |
5582 | @smallexample | |
5583 | void __attribute__ ((interrupt)) v0 (); | |
5584 | void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); | |
5585 | void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); | |
5586 | void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); | |
5587 | void __attribute__ ((interrupt, use_shadow_register_set, | |
5588 | keep_interrupts_masked)) v4 (); | |
5589 | void __attribute__ ((interrupt, use_shadow_register_set, | |
5590 | use_debug_exception_return)) v5 (); | |
5591 | void __attribute__ ((interrupt, keep_interrupts_masked, | |
5592 | use_debug_exception_return)) v6 (); | |
5593 | void __attribute__ ((interrupt, use_shadow_register_set, | |
5594 | keep_interrupts_masked, | |
5595 | use_debug_exception_return)) v7 (); | |
5596 | void __attribute__ ((interrupt("eic"))) v8 (); | |
5597 | void __attribute__ ((interrupt("vector=hw3"))) v9 (); | |
5598 | @end smallexample | |
5599 | ||
d77de738 ML |
5600 | @cindex indirect calls, MIPS |
5601 | @cindex @code{long_call} function attribute, MIPS | |
5602 | @cindex @code{short_call} function attribute, MIPS | |
5603 | @cindex @code{near} function attribute, MIPS | |
5604 | @cindex @code{far} function attribute, MIPS | |
f33d7a88 AA |
5605 | @item long_call |
5606 | @itemx short_call | |
5607 | @itemx near | |
5608 | @itemx far | |
d77de738 ML |
5609 | These attributes specify how a particular function is called on MIPS@. |
5610 | The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) | |
5611 | command-line switch. The @code{long_call} and @code{far} attributes are | |
5612 | synonyms, and cause the compiler to always call | |
5613 | the function by first loading its address into a register, and then using | |
5614 | the contents of that register. The @code{short_call} and @code{near} | |
5615 | attributes are synonyms, and have the opposite | |
5616 | effect; they specify that non-PIC calls should be made using the more | |
5617 | efficient @code{jal} instruction. | |
5618 | ||
d77de738 ML |
5619 | @cindex @code{mips16} function attribute, MIPS |
5620 | @cindex @code{nomips16} function attribute, MIPS | |
f33d7a88 AA |
5621 | @item mips16 |
5622 | @itemx nomips16 | |
d77de738 ML |
5623 | |
5624 | On MIPS targets, you can use the @code{mips16} and @code{nomips16} | |
5625 | function attributes to locally select or turn off MIPS16 code generation. | |
5626 | A function with the @code{mips16} attribute is emitted as MIPS16 code, | |
5627 | while MIPS16 code generation is disabled for functions with the | |
5628 | @code{nomips16} attribute. These attributes override the | |
5629 | @option{-mips16} and @option{-mno-mips16} options on the command line | |
5630 | (@pxref{MIPS Options}). | |
5631 | ||
5632 | When compiling files containing mixed MIPS16 and non-MIPS16 code, the | |
5633 | preprocessor symbol @code{__mips16} reflects the setting on the command line, | |
5634 | not that within individual functions. Mixed MIPS16 and non-MIPS16 code | |
5635 | may interact badly with some GCC extensions such as @code{__builtin_apply} | |
5636 | (@pxref{Constructing Calls}). | |
5637 | ||
d77de738 ML |
5638 | @cindex @code{micromips} function attribute |
5639 | @cindex @code{nomicromips} function attribute | |
f33d7a88 AA |
5640 | @item micromips, MIPS |
5641 | @itemx nomicromips, MIPS | |
d77de738 ML |
5642 | |
5643 | On MIPS targets, you can use the @code{micromips} and @code{nomicromips} | |
5644 | function attributes to locally select or turn off microMIPS code generation. | |
5645 | A function with the @code{micromips} attribute is emitted as microMIPS code, | |
5646 | while microMIPS code generation is disabled for functions with the | |
5647 | @code{nomicromips} attribute. These attributes override the | |
5648 | @option{-mmicromips} and @option{-mno-micromips} options on the command line | |
5649 | (@pxref{MIPS Options}). | |
5650 | ||
5651 | When compiling files containing mixed microMIPS and non-microMIPS code, the | |
5652 | preprocessor symbol @code{__mips_micromips} reflects the setting on the | |
5653 | command line, | |
5654 | not that within individual functions. Mixed microMIPS and non-microMIPS code | |
5655 | may interact badly with some GCC extensions such as @code{__builtin_apply} | |
5656 | (@pxref{Constructing Calls}). | |
5657 | ||
d77de738 | 5658 | @cindex @code{nocompression} function attribute, MIPS |
f33d7a88 | 5659 | @item nocompression |
d77de738 ML |
5660 | On MIPS targets, you can use the @code{nocompression} function attribute |
5661 | to locally turn off MIPS16 and microMIPS code generation. This attribute | |
5662 | overrides the @option{-mips16} and @option{-mmicromips} options on the | |
5663 | command line (@pxref{MIPS Options}). | |
a3a45f0b JZ |
5664 | |
5665 | @item use_hazard_barrier_return | |
5666 | @cindex @code{use_hazard_barrier_return} function attribute, MIPS | |
5667 | This function attribute instructs the compiler to generate a hazard barrier | |
5668 | return that clears all execution and instruction hazards while returning, | |
5669 | instead of generating a normal return instruction. | |
d77de738 ML |
5670 | @end table |
5671 | ||
5672 | @node MSP430 Function Attributes | |
5673 | @subsection MSP430 Function Attributes | |
5674 | ||
5675 | These function attributes are supported by the MSP430 back end: | |
5676 | ||
5677 | @table @code | |
d77de738 | 5678 | @cindex @code{critical} function attribute, MSP430 |
f33d7a88 | 5679 | @item critical |
d77de738 ML |
5680 | Critical functions disable interrupts upon entry and restore the |
5681 | previous interrupt state upon exit. Critical functions cannot also | |
5682 | have the @code{naked}, @code{reentrant} or @code{interrupt} attributes. | |
5683 | ||
5684 | The MSP430 hardware ensures that interrupts are disabled on entry to | |
5685 | @code{interrupt} functions, and restores the previous interrupt state | |
5686 | on exit. The @code{critical} attribute is therefore redundant on | |
5687 | @code{interrupt} functions. | |
5688 | ||
d77de738 | 5689 | @cindex @code{interrupt} function attribute, MSP430 |
f33d7a88 | 5690 | @item interrupt |
d77de738 ML |
5691 | Use this attribute to indicate |
5692 | that the specified function is an interrupt handler. The compiler generates | |
5693 | function entry and exit sequences suitable for use in an interrupt handler | |
5694 | when this attribute is present. | |
5695 | ||
5696 | You can provide an argument to the interrupt | |
5697 | attribute which specifies a name or number. If the argument is a | |
5698 | number it indicates the slot in the interrupt vector table (0 - 31) to | |
5699 | which this handler should be assigned. If the argument is a name it | |
5700 | is treated as a symbolic name for the vector slot. These names should | |
5701 | match up with appropriate entries in the linker script. By default | |
5702 | the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and | |
5703 | @code{reset} for vector 31 are recognized. | |
5704 | ||
d77de738 | 5705 | @cindex @code{naked} function attribute, MSP430 |
f33d7a88 | 5706 | @item naked |
d77de738 ML |
5707 | This attribute allows the compiler to construct the |
5708 | requisite function declaration, while allowing the body of the | |
5709 | function to be assembly code. The specified function will not have | |
5710 | prologue/epilogue sequences generated by the compiler. Only basic | |
5711 | @code{asm} statements can safely be included in naked functions | |
5712 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5713 | basic @code{asm} and C code may appear to work, they cannot be | |
5714 | depended upon to work reliably and are not supported. | |
5715 | ||
d77de738 | 5716 | @cindex @code{reentrant} function attribute, MSP430 |
f33d7a88 | 5717 | @item reentrant |
d77de738 ML |
5718 | Reentrant functions disable interrupts upon entry and enable them |
5719 | upon exit. Reentrant functions cannot also have the @code{naked} | |
5720 | or @code{critical} attributes. They can have the @code{interrupt} | |
5721 | attribute. | |
5722 | ||
d77de738 | 5723 | @cindex @code{wakeup} function attribute, MSP430 |
f33d7a88 | 5724 | @item wakeup |
d77de738 ML |
5725 | This attribute only applies to interrupt functions. It is silently |
5726 | ignored if applied to a non-interrupt function. A wakeup interrupt | |
5727 | function will rouse the processor from any low-power state that it | |
5728 | might be in when the function exits. | |
5729 | ||
d77de738 ML |
5730 | @cindex @code{lower} function attribute, MSP430 |
5731 | @cindex @code{upper} function attribute, MSP430 | |
5732 | @cindex @code{either} function attribute, MSP430 | |
f33d7a88 AA |
5733 | @item lower |
5734 | @itemx upper | |
5735 | @itemx either | |
d77de738 ML |
5736 | On the MSP430 target these attributes can be used to specify whether |
5737 | the function or variable should be placed into low memory, high | |
5738 | memory, or the placement should be left to the linker to decide. The | |
5739 | attributes are only significant if compiling for the MSP430X | |
5740 | architecture in the large memory model. | |
5741 | ||
5742 | The attributes work in conjunction with a linker script that has been | |
5743 | augmented to specify where to place sections with a @code{.lower} and | |
5744 | a @code{.upper} prefix. So, for example, as well as placing the | |
5745 | @code{.data} section, the script also specifies the placement of a | |
5746 | @code{.lower.data} and a @code{.upper.data} section. The intention | |
5747 | is that @code{lower} sections are placed into a small but easier to | |
5748 | access memory region and the upper sections are placed into a larger, but | |
5749 | slower to access, region. | |
5750 | ||
5751 | The @code{either} attribute is special. It tells the linker to place | |
5752 | the object into the corresponding @code{lower} section if there is | |
5753 | room for it. If there is insufficient room then the object is placed | |
5754 | into the corresponding @code{upper} section instead. Note that the | |
5755 | placement algorithm is not very sophisticated. It does not attempt to | |
5756 | find an optimal packing of the @code{lower} sections. It just makes | |
5757 | one pass over the objects and does the best that it can. Using the | |
5758 | @option{-ffunction-sections} and @option{-fdata-sections} command-line | |
5759 | options can help the packing, however, since they produce smaller, | |
5760 | easier to pack regions. | |
5761 | @end table | |
5762 | ||
5763 | @node NDS32 Function Attributes | |
5764 | @subsection NDS32 Function Attributes | |
5765 | ||
5766 | These function attributes are supported by the NDS32 back end: | |
5767 | ||
5768 | @table @code | |
d77de738 ML |
5769 | @cindex @code{exception} function attribute |
5770 | @cindex exception handler functions, NDS32 | |
f33d7a88 | 5771 | @item exception |
d77de738 ML |
5772 | Use this attribute on the NDS32 target to indicate that the specified function |
5773 | is an exception handler. The compiler will generate corresponding sections | |
5774 | for use in an exception handler. | |
5775 | ||
d77de738 | 5776 | @cindex @code{interrupt} function attribute, NDS32 |
f33d7a88 | 5777 | @item interrupt |
d77de738 ML |
5778 | On NDS32 target, this attribute indicates that the specified function |
5779 | is an interrupt handler. The compiler generates corresponding sections | |
5780 | for use in an interrupt handler. You can use the following attributes | |
5781 | to modify the behavior: | |
5782 | @table @code | |
d77de738 | 5783 | @cindex @code{nested} function attribute, NDS32 |
f33d7a88 | 5784 | @item nested |
d77de738 | 5785 | This interrupt service routine is interruptible. |
d77de738 | 5786 | @cindex @code{not_nested} function attribute, NDS32 |
f33d7a88 | 5787 | @item not_nested |
d77de738 | 5788 | This interrupt service routine is not interruptible. |
d77de738 | 5789 | @cindex @code{nested_ready} function attribute, NDS32 |
f33d7a88 | 5790 | @item nested_ready |
d77de738 ML |
5791 | This interrupt service routine is interruptible after @code{PSW.GIE} |
5792 | (global interrupt enable) is set. This allows interrupt service routine to | |
5793 | finish some short critical code before enabling interrupts. | |
d77de738 | 5794 | @cindex @code{save_all} function attribute, NDS32 |
f33d7a88 | 5795 | @item save_all |
d77de738 ML |
5796 | The system will help save all registers into stack before entering |
5797 | interrupt handler. | |
d77de738 | 5798 | @cindex @code{partial_save} function attribute, NDS32 |
f33d7a88 | 5799 | @item partial_save |
d77de738 ML |
5800 | The system will help save caller registers into stack before entering |
5801 | interrupt handler. | |
5802 | @end table | |
5803 | ||
d77de738 | 5804 | @cindex @code{naked} function attribute, NDS32 |
f33d7a88 | 5805 | @item naked |
d77de738 ML |
5806 | This attribute allows the compiler to construct the |
5807 | requisite function declaration, while allowing the body of the | |
5808 | function to be assembly code. The specified function will not have | |
5809 | prologue/epilogue sequences generated by the compiler. Only basic | |
5810 | @code{asm} statements can safely be included in naked functions | |
5811 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5812 | basic @code{asm} and C code may appear to work, they cannot be | |
5813 | depended upon to work reliably and are not supported. | |
5814 | ||
d77de738 ML |
5815 | @cindex @code{reset} function attribute, NDS32 |
5816 | @cindex reset handler functions | |
f33d7a88 | 5817 | @item reset |
d77de738 ML |
5818 | Use this attribute on the NDS32 target to indicate that the specified function |
5819 | is a reset handler. The compiler will generate corresponding sections | |
5820 | for use in a reset handler. You can use the following attributes | |
5821 | to provide extra exception handling: | |
5822 | @table @code | |
d77de738 | 5823 | @cindex @code{nmi} function attribute, NDS32 |
f33d7a88 | 5824 | @item nmi |
d77de738 | 5825 | Provide a user-defined function to handle NMI exception. |
d77de738 | 5826 | @cindex @code{warm} function attribute, NDS32 |
f33d7a88 | 5827 | @item warm |
d77de738 ML |
5828 | Provide a user-defined function to handle warm reset exception. |
5829 | @end table | |
5830 | @end table | |
5831 | ||
5832 | @node Nios II Function Attributes | |
5833 | @subsection Nios II Function Attributes | |
5834 | ||
5835 | These function attributes are supported by the Nios II back end: | |
5836 | ||
5837 | @table @code | |
d77de738 | 5838 | @cindex @code{target} function attribute |
f33d7a88 | 5839 | @item target (@var{options}) |
d77de738 ML |
5840 | As discussed in @ref{Common Function Attributes}, this attribute |
5841 | allows specification of target-specific compilation options. | |
5842 | ||
5843 | When compiling for Nios II, the following options are allowed: | |
5844 | ||
5845 | @table @samp | |
d77de738 ML |
5846 | @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II |
5847 | @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II | |
f33d7a88 AA |
5848 | @item custom-@var{insn}=@var{N} |
5849 | @itemx no-custom-@var{insn} | |
d77de738 ML |
5850 | Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a |
5851 | custom instruction with encoding @var{N} when generating code that uses | |
5852 | @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of | |
5853 | the custom instruction @var{insn}. | |
5854 | These target attributes correspond to the | |
5855 | @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}} | |
5856 | command-line options, and support the same set of @var{insn} keywords. | |
5857 | @xref{Nios II Options}, for more information. | |
5858 | ||
d77de738 | 5859 | @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II |
f33d7a88 | 5860 | @item custom-fpu-cfg=@var{name} |
d77de738 ML |
5861 | This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}} |
5862 | command-line option, to select a predefined set of custom instructions | |
5863 | named @var{name}. | |
5864 | @xref{Nios II Options}, for more information. | |
5865 | @end table | |
5866 | @end table | |
5867 | ||
5868 | @node Nvidia PTX Function Attributes | |
5869 | @subsection Nvidia PTX Function Attributes | |
5870 | ||
5871 | These function attributes are supported by the Nvidia PTX back end: | |
5872 | ||
5873 | @table @code | |
d77de738 | 5874 | @cindex @code{kernel} attribute, Nvidia PTX |
f33d7a88 | 5875 | @item kernel |
d77de738 ML |
5876 | This attribute indicates that the corresponding function should be compiled |
5877 | as a kernel function, which can be invoked from the host via the CUDA RT | |
5878 | library. | |
5879 | By default functions are only callable only from other PTX functions. | |
5880 | ||
5881 | Kernel functions must have @code{void} return type. | |
5882 | @end table | |
5883 | ||
5884 | @node PowerPC Function Attributes | |
5885 | @subsection PowerPC Function Attributes | |
5886 | ||
5887 | These function attributes are supported by the PowerPC back end: | |
5888 | ||
5889 | @table @code | |
d77de738 ML |
5890 | @cindex indirect calls, PowerPC |
5891 | @cindex @code{longcall} function attribute, PowerPC | |
5892 | @cindex @code{shortcall} function attribute, PowerPC | |
f33d7a88 AA |
5893 | @item longcall |
5894 | @itemx shortcall | |
d77de738 ML |
5895 | The @code{longcall} attribute |
5896 | indicates that the function might be far away from the call site and | |
5897 | require a different (more expensive) calling sequence. The | |
5898 | @code{shortcall} attribute indicates that the function is always close | |
5899 | enough for the shorter calling sequence to be used. These attributes | |
5900 | override both the @option{-mlongcall} switch and | |
5901 | the @code{#pragma longcall} setting. | |
5902 | ||
5903 | @xref{RS/6000 and PowerPC Options}, for more information on whether long | |
5904 | calls are necessary. | |
5905 | ||
d77de738 | 5906 | @cindex @code{target} function attribute |
f33d7a88 | 5907 | @item target (@var{options}) |
d77de738 ML |
5908 | As discussed in @ref{Common Function Attributes}, this attribute |
5909 | allows specification of target-specific compilation options. | |
5910 | ||
5911 | On the PowerPC, the following options are allowed: | |
5912 | ||
5913 | @table @samp | |
f33d7a88 | 5914 | @cindex @code{target("altivec")} function attribute, PowerPC |
d77de738 ML |
5915 | @item altivec |
5916 | @itemx no-altivec | |
d77de738 ML |
5917 | Generate code that uses (does not use) AltiVec instructions. In |
5918 | 32-bit code, you cannot enable AltiVec instructions unless | |
5919 | @option{-mabi=altivec} is used on the command line. | |
5920 | ||
f33d7a88 | 5921 | @cindex @code{target("cmpb")} function attribute, PowerPC |
d77de738 ML |
5922 | @item cmpb |
5923 | @itemx no-cmpb | |
d77de738 ML |
5924 | Generate code that uses (does not use) the compare bytes instruction |
5925 | implemented on the POWER6 processor and other processors that support | |
5926 | the PowerPC V2.05 architecture. | |
5927 | ||
f33d7a88 | 5928 | @cindex @code{target("dlmzb")} function attribute, PowerPC |
d77de738 ML |
5929 | @item dlmzb |
5930 | @itemx no-dlmzb | |
d77de738 ML |
5931 | Generate code that uses (does not use) the string-search @samp{dlmzb} |
5932 | instruction on the IBM 405, 440, 464 and 476 processors. This instruction is | |
5933 | generated by default when targeting those processors. | |
5934 | ||
f33d7a88 | 5935 | @cindex @code{target("fprnd")} function attribute, PowerPC |
d77de738 ML |
5936 | @item fprnd |
5937 | @itemx no-fprnd | |
d77de738 ML |
5938 | Generate code that uses (does not use) the FP round to integer |
5939 | instructions implemented on the POWER5+ processor and other processors | |
5940 | that support the PowerPC V2.03 architecture. | |
5941 | ||
f33d7a88 | 5942 | @cindex @code{target("hard-dfp")} function attribute, PowerPC |
d77de738 ML |
5943 | @item hard-dfp |
5944 | @itemx no-hard-dfp | |
d77de738 ML |
5945 | Generate code that uses (does not use) the decimal floating-point |
5946 | instructions implemented on some POWER processors. | |
5947 | ||
f33d7a88 | 5948 | @cindex @code{target("isel")} function attribute, PowerPC |
d77de738 ML |
5949 | @item isel |
5950 | @itemx no-isel | |
d77de738 ML |
5951 | Generate code that uses (does not use) ISEL instruction. |
5952 | ||
f33d7a88 | 5953 | @cindex @code{target("mfcrf")} function attribute, PowerPC |
d77de738 ML |
5954 | @item mfcrf |
5955 | @itemx no-mfcrf | |
d77de738 ML |
5956 | Generate code that uses (does not use) the move from condition |
5957 | register field instruction implemented on the POWER4 processor and | |
5958 | other processors that support the PowerPC V2.01 architecture. | |
5959 | ||
f33d7a88 | 5960 | @cindex @code{target("mulhw")} function attribute, PowerPC |
d77de738 ML |
5961 | @item mulhw |
5962 | @itemx no-mulhw | |
d77de738 ML |
5963 | Generate code that uses (does not use) the half-word multiply and |
5964 | multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. | |
5965 | These instructions are generated by default when targeting those | |
5966 | processors. | |
5967 | ||
f33d7a88 | 5968 | @cindex @code{target("multiple")} function attribute, PowerPC |
d77de738 ML |
5969 | @item multiple |
5970 | @itemx no-multiple | |
d77de738 ML |
5971 | Generate code that uses (does not use) the load multiple word |
5972 | instructions and the store multiple word instructions. | |
5973 | ||
f33d7a88 | 5974 | @cindex @code{target("update")} function attribute, PowerPC |
d77de738 ML |
5975 | @item update |
5976 | @itemx no-update | |
d77de738 ML |
5977 | Generate code that uses (does not use) the load or store instructions |
5978 | that update the base register to the address of the calculated memory | |
5979 | location. | |
5980 | ||
f33d7a88 | 5981 | @cindex @code{target("popcntb")} function attribute, PowerPC |
d77de738 ML |
5982 | @item popcntb |
5983 | @itemx no-popcntb | |
d77de738 ML |
5984 | Generate code that uses (does not use) the popcount and double-precision |
5985 | FP reciprocal estimate instruction implemented on the POWER5 | |
5986 | processor and other processors that support the PowerPC V2.02 | |
5987 | architecture. | |
5988 | ||
f33d7a88 | 5989 | @cindex @code{target("popcntd")} function attribute, PowerPC |
d77de738 ML |
5990 | @item popcntd |
5991 | @itemx no-popcntd | |
d77de738 ML |
5992 | Generate code that uses (does not use) the popcount instruction |
5993 | implemented on the POWER7 processor and other processors that support | |
5994 | the PowerPC V2.06 architecture. | |
5995 | ||
f33d7a88 | 5996 | @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC |
d77de738 ML |
5997 | @item powerpc-gfxopt |
5998 | @itemx no-powerpc-gfxopt | |
d77de738 ML |
5999 | Generate code that uses (does not use) the optional PowerPC |
6000 | architecture instructions in the Graphics group, including | |
6001 | floating-point select. | |
6002 | ||
f33d7a88 | 6003 | @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC |
d77de738 ML |
6004 | @item powerpc-gpopt |
6005 | @itemx no-powerpc-gpopt | |
d77de738 ML |
6006 | Generate code that uses (does not use) the optional PowerPC |
6007 | architecture instructions in the General Purpose group, including | |
6008 | floating-point square root. | |
6009 | ||
f33d7a88 | 6010 | @cindex @code{target("recip-precision")} function attribute, PowerPC |
d77de738 ML |
6011 | @item recip-precision |
6012 | @itemx no-recip-precision | |
d77de738 ML |
6013 | Assume (do not assume) that the reciprocal estimate instructions |
6014 | provide higher-precision estimates than is mandated by the PowerPC | |
6015 | ABI. | |
6016 | ||
f33d7a88 | 6017 | @cindex @code{target("string")} function attribute, PowerPC |
d77de738 ML |
6018 | @item string |
6019 | @itemx no-string | |
d77de738 ML |
6020 | Generate code that uses (does not use) the load string instructions |
6021 | and the store string word instructions to save multiple registers and | |
6022 | do small block moves. | |
6023 | ||
f33d7a88 | 6024 | @cindex @code{target("vsx")} function attribute, PowerPC |
d77de738 ML |
6025 | @item vsx |
6026 | @itemx no-vsx | |
d77de738 ML |
6027 | Generate code that uses (does not use) vector/scalar (VSX) |
6028 | instructions, and also enable the use of built-in functions that allow | |
6029 | more direct access to the VSX instruction set. In 32-bit code, you | |
6030 | cannot enable VSX or AltiVec instructions unless | |
6031 | @option{-mabi=altivec} is used on the command line. | |
6032 | ||
f33d7a88 | 6033 | @cindex @code{target("friz")} function attribute, PowerPC |
d77de738 ML |
6034 | @item friz |
6035 | @itemx no-friz | |
d77de738 ML |
6036 | Generate (do not generate) the @code{friz} instruction when the |
6037 | @option{-funsafe-math-optimizations} option is used to optimize | |
6038 | rounding a floating-point value to 64-bit integer and back to floating | |
6039 | point. The @code{friz} instruction does not return the same value if | |
6040 | the floating-point number is too large to fit in an integer. | |
6041 | ||
f33d7a88 | 6042 | @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC |
d77de738 ML |
6043 | @item avoid-indexed-addresses |
6044 | @itemx no-avoid-indexed-addresses | |
d77de738 ML |
6045 | Generate code that tries to avoid (not avoid) the use of indexed load |
6046 | or store instructions. | |
6047 | ||
f33d7a88 | 6048 | @cindex @code{target("paired")} function attribute, PowerPC |
d77de738 ML |
6049 | @item paired |
6050 | @itemx no-paired | |
d77de738 ML |
6051 | Generate code that uses (does not use) the generation of PAIRED simd |
6052 | instructions. | |
6053 | ||
f33d7a88 | 6054 | @cindex @code{target("longcall")} function attribute, PowerPC |
d77de738 ML |
6055 | @item longcall |
6056 | @itemx no-longcall | |
d77de738 ML |
6057 | Generate code that assumes (does not assume) that all calls are far |
6058 | away so that a longer more expensive calling sequence is required. | |
6059 | ||
d77de738 | 6060 | @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC |
f33d7a88 | 6061 | @item cpu=@var{CPU} |
d77de738 ML |
6062 | Specify the architecture to generate code for when compiling the |
6063 | function. If you select the @code{target("cpu=power7")} attribute when | |
6064 | generating 32-bit code, VSX and AltiVec instructions are not generated | |
6065 | unless you use the @option{-mabi=altivec} option on the command line. | |
6066 | ||
d77de738 | 6067 | @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC |
f33d7a88 | 6068 | @item tune=@var{TUNE} |
d77de738 ML |
6069 | Specify the architecture to tune for when compiling the function. If |
6070 | you do not specify the @code{target("tune=@var{TUNE}")} attribute and | |
6071 | you do specify the @code{target("cpu=@var{CPU}")} attribute, | |
6072 | compilation tunes for the @var{CPU} architecture, and not the | |
6073 | default tuning specified on the command line. | |
6074 | @end table | |
6075 | ||
6076 | On the PowerPC, the inliner does not inline a | |
6077 | function that has different target options than the caller, unless the | |
6078 | callee has a subset of the target options of the caller. | |
6079 | @end table | |
6080 | ||
6081 | @node RISC-V Function Attributes | |
6082 | @subsection RISC-V Function Attributes | |
6083 | ||
6084 | These function attributes are supported by the RISC-V back end: | |
6085 | ||
6086 | @table @code | |
d77de738 | 6087 | @cindex @code{naked} function attribute, RISC-V |
f33d7a88 | 6088 | @item naked |
d77de738 ML |
6089 | This attribute allows the compiler to construct the |
6090 | requisite function declaration, while allowing the body of the | |
6091 | function to be assembly code. The specified function will not have | |
6092 | prologue/epilogue sequences generated by the compiler. Only basic | |
6093 | @code{asm} statements can safely be included in naked functions | |
6094 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
6095 | basic @code{asm} and C code may appear to work, they cannot be | |
6096 | depended upon to work reliably and are not supported. | |
6097 | ||
d77de738 | 6098 | @cindex @code{interrupt} function attribute, RISC-V |
f33d7a88 | 6099 | @item interrupt |
d77de738 ML |
6100 | Use this attribute to indicate that the specified function is an interrupt |
6101 | handler. The compiler generates function entry and exit sequences suitable | |
6102 | for use in an interrupt handler when this attribute is present. | |
6103 | ||
6104 | You can specify the kind of interrupt to be handled by adding an optional | |
6105 | parameter to the interrupt attribute like this: | |
6106 | ||
6107 | @smallexample | |
6108 | void f (void) __attribute__ ((interrupt ("user"))); | |
6109 | @end smallexample | |
6110 | ||
6111 | Permissible values for this parameter are @code{user}, @code{supervisor}, | |
6112 | and @code{machine}. If there is no parameter, then it defaults to | |
6113 | @code{machine}. | |
6114 | @end table | |
6115 | ||
6116 | @node RL78 Function Attributes | |
6117 | @subsection RL78 Function Attributes | |
6118 | ||
6119 | These function attributes are supported by the RL78 back end: | |
6120 | ||
6121 | @table @code | |
d77de738 ML |
6122 | @cindex @code{interrupt} function attribute, RL78 |
6123 | @cindex @code{brk_interrupt} function attribute, RL78 | |
f33d7a88 AA |
6124 | @item interrupt |
6125 | @itemx brk_interrupt | |
d77de738 ML |
6126 | These attributes indicate |
6127 | that the specified function is an interrupt handler. The compiler generates | |
6128 | function entry and exit sequences suitable for use in an interrupt handler | |
6129 | when this attribute is present. | |
6130 | ||
6131 | Use @code{brk_interrupt} instead of @code{interrupt} for | |
6132 | handlers intended to be used with the @code{BRK} opcode (i.e.@: those | |
6133 | that must end with @code{RETB} instead of @code{RETI}). | |
6134 | ||
d77de738 | 6135 | @cindex @code{naked} function attribute, RL78 |
f33d7a88 | 6136 | @item naked |
d77de738 ML |
6137 | This attribute allows the compiler to construct the |
6138 | requisite function declaration, while allowing the body of the | |
6139 | function to be assembly code. The specified function will not have | |
6140 | prologue/epilogue sequences generated by the compiler. Only basic | |
6141 | @code{asm} statements can safely be included in naked functions | |
6142 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
6143 | basic @code{asm} and C code may appear to work, they cannot be | |
6144 | depended upon to work reliably and are not supported. | |
6145 | @end table | |
6146 | ||
6147 | @node RX Function Attributes | |
6148 | @subsection RX Function Attributes | |
6149 | ||
6150 | These function attributes are supported by the RX back end: | |
6151 | ||
6152 | @table @code | |
d77de738 | 6153 | @cindex @code{fast_interrupt} function attribute, RX |
f33d7a88 | 6154 | @item fast_interrupt |
d77de738 ML |
6155 | Use this attribute on the RX port to indicate that the specified |
6156 | function is a fast interrupt handler. This is just like the | |
6157 | @code{interrupt} attribute, except that @code{freit} is used to return | |
6158 | instead of @code{reit}. | |
6159 | ||
d77de738 | 6160 | @cindex @code{interrupt} function attribute, RX |
f33d7a88 | 6161 | @item interrupt |
d77de738 ML |
6162 | Use this attribute to indicate |
6163 | that the specified function is an interrupt handler. The compiler generates | |
6164 | function entry and exit sequences suitable for use in an interrupt handler | |
6165 | when this attribute is present. | |
6166 | ||
6167 | On RX and RL78 targets, you may specify one or more vector numbers as arguments | |
6168 | to the attribute, as well as naming an alternate table name. | |
6169 | Parameters are handled sequentially, so one handler can be assigned to | |
6170 | multiple entries in multiple tables. One may also pass the magic | |
6171 | string @code{"$default"} which causes the function to be used for any | |
6172 | unfilled slots in the current table. | |
6173 | ||
6174 | This example shows a simple assignment of a function to one vector in | |
6175 | the default table (note that preprocessor macros may be used for | |
6176 | chip-specific symbolic vector names): | |
6177 | @smallexample | |
6178 | void __attribute__ ((interrupt (5))) txd1_handler (); | |
6179 | @end smallexample | |
6180 | ||
6181 | This example assigns a function to two slots in the default table | |
6182 | (using preprocessor macros defined elsewhere) and makes it the default | |
6183 | for the @code{dct} table: | |
6184 | @smallexample | |
6185 | void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default"))) | |
6186 | txd1_handler (); | |
6187 | @end smallexample | |
6188 | ||
d77de738 | 6189 | @cindex @code{naked} function attribute, RX |
f33d7a88 | 6190 | @item naked |
d77de738 ML |
6191 | This attribute allows the compiler to construct the |
6192 | requisite function declaration, while allowing the body of the | |
6193 | function to be assembly code. The specified function will not have | |
6194 | prologue/epilogue sequences generated by the compiler. Only basic | |
6195 | @code{asm} statements can safely be included in naked functions | |
6196 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
6197 | basic @code{asm} and C code may appear to work, they cannot be | |
6198 | depended upon to work reliably and are not supported. | |
6199 | ||
d77de738 | 6200 | @cindex @code{vector} function attribute, RX |
f33d7a88 | 6201 | @item vector |
d77de738 ML |
6202 | This RX attribute is similar to the @code{interrupt} attribute, including its |
6203 | parameters, but does not make the function an interrupt-handler type | |
6204 | function (i.e.@: it retains the normal C function calling ABI). See the | |
6205 | @code{interrupt} attribute for a description of its arguments. | |
6206 | @end table | |
6207 | ||
6208 | @node S/390 Function Attributes | |
6209 | @subsection S/390 Function Attributes | |
6210 | ||
6211 | These function attributes are supported on the S/390: | |
6212 | ||
6213 | @table @code | |
d77de738 | 6214 | @cindex @code{hotpatch} function attribute, S/390 |
f33d7a88 | 6215 | @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label}) |
d77de738 ML |
6216 | |
6217 | On S/390 System z targets, you can use this function attribute to | |
6218 | make GCC generate a ``hot-patching'' function prologue. If the | |
6219 | @option{-mhotpatch=} command-line option is used at the same time, | |
6220 | the @code{hotpatch} attribute takes precedence. The first of the | |
6221 | two arguments specifies the number of halfwords to be added before | |
6222 | the function label. A second argument can be used to specify the | |
6223 | number of halfwords to be added after the function label. For | |
6224 | both arguments the maximum allowed value is 1000000. | |
6225 | ||
6226 | If both arguments are zero, hotpatching is disabled. | |
6227 | ||
d77de738 | 6228 | @cindex @code{target} function attribute |
f33d7a88 | 6229 | @item target (@var{options}) |
d77de738 ML |
6230 | As discussed in @ref{Common Function Attributes}, this attribute |
6231 | allows specification of target-specific compilation options. | |
6232 | ||
6233 | On S/390, the following options are supported: | |
6234 | ||
6235 | @table @samp | |
6236 | @item arch= | |
6237 | @item tune= | |
6238 | @item stack-guard= | |
6239 | @item stack-size= | |
6240 | @item branch-cost= | |
6241 | @item warn-framesize= | |
6242 | @item backchain | |
6243 | @itemx no-backchain | |
6244 | @item hard-dfp | |
6245 | @itemx no-hard-dfp | |
6246 | @item hard-float | |
6247 | @itemx soft-float | |
6248 | @item htm | |
6249 | @itemx no-htm | |
6250 | @item vx | |
6251 | @itemx no-vx | |
6252 | @item packed-stack | |
6253 | @itemx no-packed-stack | |
6254 | @item small-exec | |
6255 | @itemx no-small-exec | |
6256 | @item mvcle | |
6257 | @itemx no-mvcle | |
6258 | @item warn-dynamicstack | |
6259 | @itemx no-warn-dynamicstack | |
6260 | @end table | |
6261 | ||
6262 | The options work exactly like the S/390 specific command line | |
6263 | options (without the prefix @option{-m}) except that they do not | |
6264 | change any feature macros. For example, | |
6265 | ||
6266 | @smallexample | |
6267 | @code{target("no-vx")} | |
6268 | @end smallexample | |
6269 | ||
6270 | does not undefine the @code{__VEC__} macro. | |
6271 | @end table | |
6272 | ||
6273 | @node SH Function Attributes | |
6274 | @subsection SH Function Attributes | |
6275 | ||
6276 | These function attributes are supported on the SH family of processors: | |
6277 | ||
6278 | @table @code | |
d77de738 ML |
6279 | @cindex @code{function_vector} function attribute, SH |
6280 | @cindex calling functions through the function vector on SH2A | |
f33d7a88 | 6281 | @item function_vector |
d77de738 ML |
6282 | On SH2A targets, this attribute declares a function to be called using the |
6283 | TBR relative addressing mode. The argument to this attribute is the entry | |
6284 | number of the same function in a vector table containing all the TBR | |
6285 | relative addressable functions. For correct operation the TBR must be setup | |
6286 | accordingly to point to the start of the vector table before any functions with | |
6287 | this attribute are invoked. Usually a good place to do the initialization is | |
6288 | the startup routine. The TBR relative vector table can have at max 256 function | |
6289 | entries. The jumps to these functions are generated using a SH2A specific, | |
6290 | non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD | |
6291 | from GNU binutils version 2.7 or later for this attribute to work correctly. | |
6292 | ||
6293 | In an application, for a function being called once, this attribute | |
6294 | saves at least 8 bytes of code; and if other successive calls are being | |
6295 | made to the same function, it saves 2 bytes of code per each of these | |
6296 | calls. | |
6297 | ||
d77de738 | 6298 | @cindex @code{interrupt_handler} function attribute, SH |
f33d7a88 | 6299 | @item interrupt_handler |
d77de738 ML |
6300 | Use this attribute to |
6301 | indicate that the specified function is an interrupt handler. The compiler | |
6302 | generates function entry and exit sequences suitable for use in an | |
6303 | interrupt handler when this attribute is present. | |
6304 | ||
d77de738 | 6305 | @cindex @code{nosave_low_regs} function attribute, SH |
f33d7a88 | 6306 | @item nosave_low_regs |
d77de738 ML |
6307 | Use this attribute on SH targets to indicate that an @code{interrupt_handler} |
6308 | function should not save and restore registers R0..R7. This can be used on SH3* | |
6309 | and SH4* targets that have a second R0..R7 register bank for non-reentrant | |
6310 | interrupt handlers. | |
6311 | ||
d77de738 | 6312 | @cindex @code{renesas} function attribute, SH |
f33d7a88 | 6313 | @item renesas |
d77de738 ML |
6314 | On SH targets this attribute specifies that the function or struct follows the |
6315 | Renesas ABI. | |
6316 | ||
d77de738 | 6317 | @cindex @code{resbank} function attribute, SH |
f33d7a88 | 6318 | @item resbank |
d77de738 ML |
6319 | On the SH2A target, this attribute enables the high-speed register |
6320 | saving and restoration using a register bank for @code{interrupt_handler} | |
6321 | routines. Saving to the bank is performed automatically after the CPU | |
6322 | accepts an interrupt that uses a register bank. | |
6323 | ||
6324 | The nineteen 32-bit registers comprising general register R0 to R14, | |
6325 | control register GBR, and system registers MACH, MACL, and PR and the | |
6326 | vector table address offset are saved into a register bank. Register | |
6327 | banks are stacked in first-in last-out (FILO) sequence. Restoration | |
6328 | from the bank is executed by issuing a RESBANK instruction. | |
6329 | ||
d77de738 | 6330 | @cindex @code{sp_switch} function attribute, SH |
f33d7a88 | 6331 | @item sp_switch |
d77de738 ML |
6332 | Use this attribute on the SH to indicate an @code{interrupt_handler} |
6333 | function should switch to an alternate stack. It expects a string | |
6334 | argument that names a global variable holding the address of the | |
6335 | alternate stack. | |
6336 | ||
6337 | @smallexample | |
6338 | void *alt_stack; | |
6339 | void f () __attribute__ ((interrupt_handler, | |
6340 | sp_switch ("alt_stack"))); | |
6341 | @end smallexample | |
6342 | ||
d77de738 | 6343 | @cindex @code{trap_exit} function attribute, SH |
f33d7a88 | 6344 | @item trap_exit |
d77de738 ML |
6345 | Use this attribute on the SH for an @code{interrupt_handler} to return using |
6346 | @code{trapa} instead of @code{rte}. This attribute expects an integer | |
6347 | argument specifying the trap number to be used. | |
6348 | ||
d77de738 | 6349 | @cindex @code{trapa_handler} function attribute, SH |
f33d7a88 | 6350 | @item trapa_handler |
d77de738 ML |
6351 | On SH targets this function attribute is similar to @code{interrupt_handler} |
6352 | but it does not save and restore all registers. | |
6353 | @end table | |
6354 | ||
6355 | @node Symbian OS Function Attributes | |
6356 | @subsection Symbian OS Function Attributes | |
6357 | ||
6358 | @xref{Microsoft Windows Function Attributes}, for discussion of the | |
6359 | @code{dllexport} and @code{dllimport} attributes. | |
6360 | ||
6361 | @node V850 Function Attributes | |
6362 | @subsection V850 Function Attributes | |
6363 | ||
6364 | The V850 back end supports these function attributes: | |
6365 | ||
6366 | @table @code | |
d77de738 ML |
6367 | @cindex @code{interrupt} function attribute, V850 |
6368 | @cindex @code{interrupt_handler} function attribute, V850 | |
f33d7a88 AA |
6369 | @item interrupt |
6370 | @itemx interrupt_handler | |
d77de738 ML |
6371 | Use these attributes to indicate |
6372 | that the specified function is an interrupt handler. The compiler generates | |
6373 | function entry and exit sequences suitable for use in an interrupt handler | |
6374 | when either attribute is present. | |
6375 | @end table | |
6376 | ||
6377 | @node Visium Function Attributes | |
6378 | @subsection Visium Function Attributes | |
6379 | ||
6380 | These function attributes are supported by the Visium back end: | |
6381 | ||
6382 | @table @code | |
d77de738 | 6383 | @cindex @code{interrupt} function attribute, Visium |
f33d7a88 | 6384 | @item interrupt |
d77de738 ML |
6385 | Use this attribute to indicate |
6386 | that the specified function is an interrupt handler. The compiler generates | |
6387 | function entry and exit sequences suitable for use in an interrupt handler | |
6388 | when this attribute is present. | |
6389 | @end table | |
6390 | ||
6391 | @node x86 Function Attributes | |
6392 | @subsection x86 Function Attributes | |
6393 | ||
6394 | These function attributes are supported by the x86 back end: | |
6395 | ||
6396 | @table @code | |
d77de738 ML |
6397 | @cindex @code{cdecl} function attribute, x86-32 |
6398 | @cindex functions that pop the argument stack on x86-32 | |
6399 | @opindex mrtd | |
f33d7a88 | 6400 | @item cdecl |
d77de738 ML |
6401 | On the x86-32 targets, the @code{cdecl} attribute causes the compiler to |
6402 | assume that the calling function pops off the stack space used to | |
6403 | pass arguments. This is | |
6404 | useful to override the effects of the @option{-mrtd} switch. | |
6405 | ||
d77de738 ML |
6406 | @cindex @code{fastcall} function attribute, x86-32 |
6407 | @cindex functions that pop the argument stack on x86-32 | |
f33d7a88 | 6408 | @item fastcall |
d77de738 ML |
6409 | On x86-32 targets, the @code{fastcall} attribute causes the compiler to |
6410 | pass the first argument (if of integral type) in the register ECX and | |
6411 | the second argument (if of integral type) in the register EDX@. Subsequent | |
6412 | and other typed arguments are passed on the stack. The called function | |
6413 | pops the arguments off the stack. If the number of arguments is variable all | |
6414 | arguments are pushed on the stack. | |
6415 | ||
d77de738 ML |
6416 | @cindex @code{thiscall} function attribute, x86-32 |
6417 | @cindex functions that pop the argument stack on x86-32 | |
f33d7a88 | 6418 | @item thiscall |
d77de738 ML |
6419 | On x86-32 targets, the @code{thiscall} attribute causes the compiler to |
6420 | pass the first argument (if of integral type) in the register ECX. | |
6421 | Subsequent and other typed arguments are passed on the stack. The called | |
6422 | function pops the arguments off the stack. | |
6423 | If the number of arguments is variable all arguments are pushed on the | |
6424 | stack. | |
6425 | The @code{thiscall} attribute is intended for C++ non-static member functions. | |
6426 | As a GCC extension, this calling convention can be used for C functions | |
6427 | and for static member methods. | |
6428 | ||
d77de738 ML |
6429 | @cindex @code{ms_abi} function attribute, x86 |
6430 | @cindex @code{sysv_abi} function attribute, x86 | |
f33d7a88 AA |
6431 | @item ms_abi |
6432 | @itemx sysv_abi | |
d77de738 ML |
6433 | |
6434 | On 32-bit and 64-bit x86 targets, you can use an ABI attribute | |
6435 | to indicate which calling convention should be used for a function. The | |
6436 | @code{ms_abi} attribute tells the compiler to use the Microsoft ABI, | |
6437 | while the @code{sysv_abi} attribute tells the compiler to use the System V | |
6438 | ELF ABI, which is used on GNU/Linux and other systems. The default is to use | |
6439 | the Microsoft ABI when targeting Windows. On all other systems, the default | |
6440 | is the System V ELF ABI. | |
6441 | ||
6442 | Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently | |
6443 | requires the @option{-maccumulate-outgoing-args} option. | |
6444 | ||
d77de738 | 6445 | @cindex @code{callee_pop_aggregate_return} function attribute, x86 |
f33d7a88 | 6446 | @item callee_pop_aggregate_return (@var{number}) |
d77de738 ML |
6447 | |
6448 | On x86-32 targets, you can use this attribute to control how | |
6449 | aggregates are returned in memory. If the caller is responsible for | |
6450 | popping the hidden pointer together with the rest of the arguments, specify | |
6451 | @var{number} equal to zero. If callee is responsible for popping the | |
6452 | hidden pointer, specify @var{number} equal to one. | |
6453 | ||
6454 | The default x86-32 ABI assumes that the callee pops the | |
6455 | stack for hidden pointer. However, on x86-32 Microsoft Windows targets, | |
6456 | the compiler assumes that the | |
6457 | caller pops the stack for hidden pointer. | |
6458 | ||
d77de738 | 6459 | @cindex @code{ms_hook_prologue} function attribute, x86 |
f33d7a88 | 6460 | @item ms_hook_prologue |
d77de738 ML |
6461 | |
6462 | On 32-bit and 64-bit x86 targets, you can use | |
6463 | this function attribute to make GCC generate the ``hot-patching'' function | |
6464 | prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 | |
6465 | and newer. | |
6466 | ||
d77de738 | 6467 | @cindex @code{naked} function attribute, x86 |
f33d7a88 | 6468 | @item naked |
d77de738 ML |
6469 | This attribute allows the compiler to construct the |
6470 | requisite function declaration, while allowing the body of the | |
6471 | function to be assembly code. The specified function will not have | |
6472 | prologue/epilogue sequences generated by the compiler. Only basic | |
6473 | @code{asm} statements can safely be included in naked functions | |
6474 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
6475 | basic @code{asm} and C code may appear to work, they cannot be | |
6476 | depended upon to work reliably and are not supported. | |
6477 | ||
d77de738 ML |
6478 | @cindex @code{regparm} function attribute, x86 |
6479 | @cindex functions that are passed arguments in registers on x86-32 | |
f33d7a88 | 6480 | @item regparm (@var{number}) |
d77de738 ML |
6481 | On x86-32 targets, the @code{regparm} attribute causes the compiler to |
6482 | pass arguments number one to @var{number} if they are of integral type | |
6483 | in registers EAX, EDX, and ECX instead of on the stack. Functions that | |
6484 | take a variable number of arguments continue to be passed all of their | |
6485 | arguments on the stack. | |
6486 | ||
6487 | Beware that on some ELF systems this attribute is unsuitable for | |
6488 | global functions in shared libraries with lazy binding (which is the | |
6489 | default). Lazy binding sends the first call via resolving code in | |
6490 | the loader, which might assume EAX, EDX and ECX can be clobbered, as | |
6491 | per the standard calling conventions. Solaris 8 is affected by this. | |
6492 | Systems with the GNU C Library version 2.1 or higher | |
6493 | and FreeBSD are believed to be | |
6494 | safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be | |
6495 | disabled with the linker or the loader if desired, to avoid the | |
6496 | problem.) | |
6497 | ||
d77de738 | 6498 | @cindex @code{sseregparm} function attribute, x86 |
f33d7a88 | 6499 | @item sseregparm |
d77de738 ML |
6500 | On x86-32 targets with SSE support, the @code{sseregparm} attribute |
6501 | causes the compiler to pass up to 3 floating-point arguments in | |
6502 | SSE registers instead of on the stack. Functions that take a | |
6503 | variable number of arguments continue to pass all of their | |
6504 | floating-point arguments on the stack. | |
6505 | ||
d77de738 | 6506 | @cindex @code{force_align_arg_pointer} function attribute, x86 |
f33d7a88 | 6507 | @item force_align_arg_pointer |
d77de738 ML |
6508 | On x86 targets, the @code{force_align_arg_pointer} attribute may be |
6509 | applied to individual function definitions, generating an alternate | |
6510 | prologue and epilogue that realigns the run-time stack if necessary. | |
6511 | This supports mixing legacy codes that run with a 4-byte aligned stack | |
6512 | with modern codes that keep a 16-byte stack for SSE compatibility. | |
6513 | ||
d77de738 ML |
6514 | @cindex @code{stdcall} function attribute, x86-32 |
6515 | @cindex functions that pop the argument stack on x86-32 | |
f33d7a88 | 6516 | @item stdcall |
d77de738 ML |
6517 | On x86-32 targets, the @code{stdcall} attribute causes the compiler to |
6518 | assume that the called function pops off the stack space used to | |
6519 | pass arguments, unless it takes a variable number of arguments. | |
6520 | ||
d77de738 | 6521 | @cindex @code{no_caller_saved_registers} function attribute, x86 |
f33d7a88 | 6522 | @item no_caller_saved_registers |
d77de738 ML |
6523 | Use this attribute to indicate that the specified function has no |
6524 | caller-saved registers. That is, all registers are callee-saved. For | |
6525 | example, this attribute can be used for a function called from an | |
6526 | interrupt handler. The compiler generates proper function entry and | |
6527 | exit sequences to save and restore any modified registers, except for | |
6528 | the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87 | |
6529 | states, the GCC option @option{-mgeneral-regs-only} should be used to | |
6530 | compile functions with @code{no_caller_saved_registers} attribute. | |
6531 | ||
d77de738 | 6532 | @cindex @code{interrupt} function attribute, x86 |
f33d7a88 | 6533 | @item interrupt |
d77de738 ML |
6534 | Use this attribute to indicate that the specified function is an |
6535 | interrupt handler or an exception handler (depending on parameters passed | |
6536 | to the function, explained further). The compiler generates function | |
6537 | entry and exit sequences suitable for use in an interrupt handler when | |
6538 | this attribute is present. The @code{IRET} instruction, instead of the | |
6539 | @code{RET} instruction, is used to return from interrupt handlers. All | |
6540 | registers, except for the EFLAGS register which is restored by the | |
6541 | @code{IRET} instruction, are preserved by the compiler. Since GCC | |
6542 | doesn't preserve SSE, MMX nor x87 states, the GCC option | |
6543 | @option{-mgeneral-regs-only} should be used to compile interrupt and | |
6544 | exception handlers. | |
6545 | ||
6546 | Any interruptible-without-stack-switch code must be compiled with | |
6547 | @option{-mno-red-zone} since interrupt handlers can and will, because | |
6548 | of the hardware design, touch the red zone. | |
6549 | ||
6550 | An interrupt handler must be declared with a mandatory pointer | |
6551 | argument: | |
6552 | ||
6553 | @smallexample | |
6554 | struct interrupt_frame; | |
6555 | ||
6556 | __attribute__ ((interrupt)) | |
6557 | void | |
6558 | f (struct interrupt_frame *frame) | |
6559 | @{ | |
6560 | @} | |
6561 | @end smallexample | |
6562 | ||
6563 | @noindent | |
6564 | and you must define @code{struct interrupt_frame} as described in the | |
6565 | processor's manual. | |
6566 | ||
6567 | Exception handlers differ from interrupt handlers because the system | |
6568 | pushes an error code on the stack. An exception handler declaration is | |
6569 | similar to that for an interrupt handler, but with a different mandatory | |
6570 | function signature. The compiler arranges to pop the error code off the | |
6571 | stack before the @code{IRET} instruction. | |
6572 | ||
6573 | @smallexample | |
6574 | #ifdef __x86_64__ | |
6575 | typedef unsigned long long int uword_t; | |
6576 | #else | |
6577 | typedef unsigned int uword_t; | |
6578 | #endif | |
6579 | ||
6580 | struct interrupt_frame; | |
6581 | ||
6582 | __attribute__ ((interrupt)) | |
6583 | void | |
6584 | f (struct interrupt_frame *frame, uword_t error_code) | |
6585 | @{ | |
6586 | ... | |
6587 | @} | |
6588 | @end smallexample | |
6589 | ||
6590 | Exception handlers should only be used for exceptions that push an error | |
6591 | code; you should use an interrupt handler in other cases. The system | |
6592 | will crash if the wrong kind of handler is used. | |
6593 | ||
d77de738 | 6594 | @cindex @code{target} function attribute |
f33d7a88 | 6595 | @item target (@var{options}) |
d77de738 ML |
6596 | As discussed in @ref{Common Function Attributes}, this attribute |
6597 | allows specification of target-specific compilation options. | |
6598 | ||
6599 | On the x86, the following options are allowed: | |
6600 | @table @samp | |
f33d7a88 | 6601 | @cindex @code{target("3dnow")} function attribute, x86 |
d77de738 ML |
6602 | @item 3dnow |
6603 | @itemx no-3dnow | |
d77de738 ML |
6604 | Enable/disable the generation of the 3DNow!@: instructions. |
6605 | ||
f33d7a88 | 6606 | @cindex @code{target("3dnowa")} function attribute, x86 |
d77de738 ML |
6607 | @item 3dnowa |
6608 | @itemx no-3dnowa | |
d77de738 ML |
6609 | Enable/disable the generation of the enhanced 3DNow!@: instructions. |
6610 | ||
f33d7a88 | 6611 | @cindex @code{target("abm")} function attribute, x86 |
d77de738 ML |
6612 | @item abm |
6613 | @itemx no-abm | |
d77de738 ML |
6614 | Enable/disable the generation of the advanced bit instructions. |
6615 | ||
f33d7a88 | 6616 | @cindex @code{target("adx")} function attribute, x86 |
d77de738 ML |
6617 | @item adx |
6618 | @itemx no-adx | |
d77de738 ML |
6619 | Enable/disable the generation of the ADX instructions. |
6620 | ||
f33d7a88 | 6621 | @cindex @code{target("aes")} function attribute, x86 |
d77de738 ML |
6622 | @item aes |
6623 | @itemx no-aes | |
d77de738 ML |
6624 | Enable/disable the generation of the AES instructions. |
6625 | ||
f33d7a88 | 6626 | @cindex @code{target("avx")} function attribute, x86 |
d77de738 ML |
6627 | @item avx |
6628 | @itemx no-avx | |
d77de738 ML |
6629 | Enable/disable the generation of the AVX instructions. |
6630 | ||
f33d7a88 | 6631 | @cindex @code{target("avx2")} function attribute, x86 |
d77de738 ML |
6632 | @item avx2 |
6633 | @itemx no-avx2 | |
d77de738 ML |
6634 | Enable/disable the generation of the AVX2 instructions. |
6635 | ||
f33d7a88 | 6636 | @cindex @code{target("avx5124fmaps")} function attribute, x86 |
d77de738 ML |
6637 | @item avx5124fmaps |
6638 | @itemx no-avx5124fmaps | |
d77de738 ML |
6639 | Enable/disable the generation of the AVX5124FMAPS instructions. |
6640 | ||
f33d7a88 | 6641 | @cindex @code{target("avx5124vnniw")} function attribute, x86 |
d77de738 ML |
6642 | @item avx5124vnniw |
6643 | @itemx no-avx5124vnniw | |
d77de738 ML |
6644 | Enable/disable the generation of the AVX5124VNNIW instructions. |
6645 | ||
f33d7a88 | 6646 | @cindex @code{target("avx512bitalg")} function attribute, x86 |
d77de738 ML |
6647 | @item avx512bitalg |
6648 | @itemx no-avx512bitalg | |
d77de738 ML |
6649 | Enable/disable the generation of the AVX512BITALG instructions. |
6650 | ||
f33d7a88 | 6651 | @cindex @code{target("avx512bw")} function attribute, x86 |
d77de738 ML |
6652 | @item avx512bw |
6653 | @itemx no-avx512bw | |
d77de738 ML |
6654 | Enable/disable the generation of the AVX512BW instructions. |
6655 | ||
f33d7a88 | 6656 | @cindex @code{target("avx512cd")} function attribute, x86 |
d77de738 ML |
6657 | @item avx512cd |
6658 | @itemx no-avx512cd | |
d77de738 ML |
6659 | Enable/disable the generation of the AVX512CD instructions. |
6660 | ||
f33d7a88 | 6661 | @cindex @code{target("avx512dq")} function attribute, x86 |
d77de738 ML |
6662 | @item avx512dq |
6663 | @itemx no-avx512dq | |
d77de738 ML |
6664 | Enable/disable the generation of the AVX512DQ instructions. |
6665 | ||
f33d7a88 | 6666 | @cindex @code{target("avx512er")} function attribute, x86 |
d77de738 ML |
6667 | @item avx512er |
6668 | @itemx no-avx512er | |
d77de738 ML |
6669 | Enable/disable the generation of the AVX512ER instructions. |
6670 | ||
f33d7a88 | 6671 | @cindex @code{target("avx512f")} function attribute, x86 |
d77de738 ML |
6672 | @item avx512f |
6673 | @itemx no-avx512f | |
d77de738 ML |
6674 | Enable/disable the generation of the AVX512F instructions. |
6675 | ||
f33d7a88 | 6676 | @cindex @code{target("avx512ifma")} function attribute, x86 |
d77de738 ML |
6677 | @item avx512ifma |
6678 | @itemx no-avx512ifma | |
d77de738 ML |
6679 | Enable/disable the generation of the AVX512IFMA instructions. |
6680 | ||
f33d7a88 | 6681 | @cindex @code{target("avx512pf")} function attribute, x86 |
d77de738 ML |
6682 | @item avx512pf |
6683 | @itemx no-avx512pf | |
d77de738 ML |
6684 | Enable/disable the generation of the AVX512PF instructions. |
6685 | ||
f33d7a88 | 6686 | @cindex @code{target("avx512vbmi")} function attribute, x86 |
d77de738 ML |
6687 | @item avx512vbmi |
6688 | @itemx no-avx512vbmi | |
d77de738 ML |
6689 | Enable/disable the generation of the AVX512VBMI instructions. |
6690 | ||
f33d7a88 | 6691 | @cindex @code{target("avx512vbmi2")} function attribute, x86 |
d77de738 ML |
6692 | @item avx512vbmi2 |
6693 | @itemx no-avx512vbmi2 | |
d77de738 ML |
6694 | Enable/disable the generation of the AVX512VBMI2 instructions. |
6695 | ||
f33d7a88 | 6696 | @cindex @code{target("avx512vl")} function attribute, x86 |
d77de738 ML |
6697 | @item avx512vl |
6698 | @itemx no-avx512vl | |
d77de738 ML |
6699 | Enable/disable the generation of the AVX512VL instructions. |
6700 | ||
f33d7a88 | 6701 | @cindex @code{target("avx512vnni")} function attribute, x86 |
d77de738 ML |
6702 | @item avx512vnni |
6703 | @itemx no-avx512vnni | |
d77de738 ML |
6704 | Enable/disable the generation of the AVX512VNNI instructions. |
6705 | ||
f33d7a88 | 6706 | @cindex @code{target("avx512vpopcntdq")} function attribute, x86 |
d77de738 ML |
6707 | @item avx512vpopcntdq |
6708 | @itemx no-avx512vpopcntdq | |
d77de738 ML |
6709 | Enable/disable the generation of the AVX512VPOPCNTDQ instructions. |
6710 | ||
f33d7a88 | 6711 | @cindex @code{target("bmi")} function attribute, x86 |
d77de738 ML |
6712 | @item bmi |
6713 | @itemx no-bmi | |
d77de738 ML |
6714 | Enable/disable the generation of the BMI instructions. |
6715 | ||
f33d7a88 | 6716 | @cindex @code{target("bmi2")} function attribute, x86 |
d77de738 ML |
6717 | @item bmi2 |
6718 | @itemx no-bmi2 | |
d77de738 ML |
6719 | Enable/disable the generation of the BMI2 instructions. |
6720 | ||
f33d7a88 | 6721 | @cindex @code{target("cldemote")} function attribute, x86 |
d77de738 ML |
6722 | @item cldemote |
6723 | @itemx no-cldemote | |
d77de738 ML |
6724 | Enable/disable the generation of the CLDEMOTE instructions. |
6725 | ||
f33d7a88 | 6726 | @cindex @code{target("clflushopt")} function attribute, x86 |
d77de738 ML |
6727 | @item clflushopt |
6728 | @itemx no-clflushopt | |
d77de738 ML |
6729 | Enable/disable the generation of the CLFLUSHOPT instructions. |
6730 | ||
f33d7a88 | 6731 | @cindex @code{target("clwb")} function attribute, x86 |
d77de738 ML |
6732 | @item clwb |
6733 | @itemx no-clwb | |
d77de738 ML |
6734 | Enable/disable the generation of the CLWB instructions. |
6735 | ||
f33d7a88 | 6736 | @cindex @code{target("clzero")} function attribute, x86 |
d77de738 ML |
6737 | @item clzero |
6738 | @itemx no-clzero | |
d77de738 ML |
6739 | Enable/disable the generation of the CLZERO instructions. |
6740 | ||
f33d7a88 | 6741 | @cindex @code{target("crc32")} function attribute, x86 |
d77de738 ML |
6742 | @item crc32 |
6743 | @itemx no-crc32 | |
d77de738 ML |
6744 | Enable/disable the generation of the CRC32 instructions. |
6745 | ||
f33d7a88 | 6746 | @cindex @code{target("cx16")} function attribute, x86 |
d77de738 ML |
6747 | @item cx16 |
6748 | @itemx no-cx16 | |
d77de738 ML |
6749 | Enable/disable the generation of the CMPXCHG16B instructions. |
6750 | ||
d77de738 | 6751 | @cindex @code{target("default")} function attribute, x86 |
f33d7a88 | 6752 | @item default |
d77de738 ML |
6753 | @xref{Function Multiversioning}, where it is used to specify the |
6754 | default function version. | |
6755 | ||
f33d7a88 | 6756 | @cindex @code{target("f16c")} function attribute, x86 |
d77de738 ML |
6757 | @item f16c |
6758 | @itemx no-f16c | |
d77de738 ML |
6759 | Enable/disable the generation of the F16C instructions. |
6760 | ||
f33d7a88 | 6761 | @cindex @code{target("fma")} function attribute, x86 |
d77de738 ML |
6762 | @item fma |
6763 | @itemx no-fma | |
d77de738 ML |
6764 | Enable/disable the generation of the FMA instructions. |
6765 | ||
f33d7a88 | 6766 | @cindex @code{target("fma4")} function attribute, x86 |
d77de738 ML |
6767 | @item fma4 |
6768 | @itemx no-fma4 | |
d77de738 ML |
6769 | Enable/disable the generation of the FMA4 instructions. |
6770 | ||
f33d7a88 | 6771 | @cindex @code{target("fsgsbase")} function attribute, x86 |
d77de738 ML |
6772 | @item fsgsbase |
6773 | @itemx no-fsgsbase | |
d77de738 ML |
6774 | Enable/disable the generation of the FSGSBASE instructions. |
6775 | ||
f33d7a88 | 6776 | @cindex @code{target("fxsr")} function attribute, x86 |
d77de738 ML |
6777 | @item fxsr |
6778 | @itemx no-fxsr | |
d77de738 ML |
6779 | Enable/disable the generation of the FXSR instructions. |
6780 | ||
f33d7a88 | 6781 | @cindex @code{target("gfni")} function attribute, x86 |
d77de738 ML |
6782 | @item gfni |
6783 | @itemx no-gfni | |
d77de738 ML |
6784 | Enable/disable the generation of the GFNI instructions. |
6785 | ||
f33d7a88 | 6786 | @cindex @code{target("hle")} function attribute, x86 |
d77de738 ML |
6787 | @item hle |
6788 | @itemx no-hle | |
d77de738 ML |
6789 | Enable/disable the generation of the HLE instruction prefixes. |
6790 | ||
f33d7a88 | 6791 | @cindex @code{target("lwp")} function attribute, x86 |
d77de738 ML |
6792 | @item lwp |
6793 | @itemx no-lwp | |
d77de738 ML |
6794 | Enable/disable the generation of the LWP instructions. |
6795 | ||
f33d7a88 | 6796 | @cindex @code{target("lzcnt")} function attribute, x86 |
d77de738 ML |
6797 | @item lzcnt |
6798 | @itemx no-lzcnt | |
d77de738 ML |
6799 | Enable/disable the generation of the LZCNT instructions. |
6800 | ||
f33d7a88 | 6801 | @cindex @code{target("mmx")} function attribute, x86 |
d77de738 ML |
6802 | @item mmx |
6803 | @itemx no-mmx | |
d77de738 ML |
6804 | Enable/disable the generation of the MMX instructions. |
6805 | ||
f33d7a88 | 6806 | @cindex @code{target("movbe")} function attribute, x86 |
d77de738 ML |
6807 | @item movbe |
6808 | @itemx no-movbe | |
d77de738 ML |
6809 | Enable/disable the generation of the MOVBE instructions. |
6810 | ||
f33d7a88 | 6811 | @cindex @code{target("movdir64b")} function attribute, x86 |
d77de738 ML |
6812 | @item movdir64b |
6813 | @itemx no-movdir64b | |
d77de738 ML |
6814 | Enable/disable the generation of the MOVDIR64B instructions. |
6815 | ||
f33d7a88 | 6816 | @cindex @code{target("movdiri")} function attribute, x86 |
d77de738 ML |
6817 | @item movdiri |
6818 | @itemx no-movdiri | |
d77de738 ML |
6819 | Enable/disable the generation of the MOVDIRI instructions. |
6820 | ||
f33d7a88 | 6821 | @cindex @code{target("mwait")} function attribute, x86 |
d77de738 ML |
6822 | @item mwait |
6823 | @itemx no-mwait | |
d77de738 ML |
6824 | Enable/disable the generation of the MWAIT and MONITOR instructions. |
6825 | ||
f33d7a88 | 6826 | @cindex @code{target("mwaitx")} function attribute, x86 |
d77de738 ML |
6827 | @item mwaitx |
6828 | @itemx no-mwaitx | |
d77de738 ML |
6829 | Enable/disable the generation of the MWAITX instructions. |
6830 | ||
f33d7a88 | 6831 | @cindex @code{target("pclmul")} function attribute, x86 |
d77de738 ML |
6832 | @item pclmul |
6833 | @itemx no-pclmul | |
d77de738 ML |
6834 | Enable/disable the generation of the PCLMUL instructions. |
6835 | ||
f33d7a88 | 6836 | @cindex @code{target("pconfig")} function attribute, x86 |
d77de738 ML |
6837 | @item pconfig |
6838 | @itemx no-pconfig | |
d77de738 ML |
6839 | Enable/disable the generation of the PCONFIG instructions. |
6840 | ||
f33d7a88 | 6841 | @cindex @code{target("pku")} function attribute, x86 |
d77de738 ML |
6842 | @item pku |
6843 | @itemx no-pku | |
d77de738 ML |
6844 | Enable/disable the generation of the PKU instructions. |
6845 | ||
f33d7a88 | 6846 | @cindex @code{target("popcnt")} function attribute, x86 |
d77de738 ML |
6847 | @item popcnt |
6848 | @itemx no-popcnt | |
d77de738 ML |
6849 | Enable/disable the generation of the POPCNT instruction. |
6850 | ||
f33d7a88 | 6851 | @cindex @code{target("prefetchwt1")} function attribute, x86 |
d77de738 ML |
6852 | @item prefetchwt1 |
6853 | @itemx no-prefetchwt1 | |
d77de738 ML |
6854 | Enable/disable the generation of the PREFETCHWT1 instructions. |
6855 | ||
f33d7a88 | 6856 | @cindex @code{target("prfchw")} function attribute, x86 |
d77de738 ML |
6857 | @item prfchw |
6858 | @itemx no-prfchw | |
d77de738 ML |
6859 | Enable/disable the generation of the PREFETCHW instruction. |
6860 | ||
f33d7a88 | 6861 | @cindex @code{target("ptwrite")} function attribute, x86 |
d77de738 ML |
6862 | @item ptwrite |
6863 | @itemx no-ptwrite | |
d77de738 ML |
6864 | Enable/disable the generation of the PTWRITE instructions. |
6865 | ||
f33d7a88 | 6866 | @cindex @code{target("rdpid")} function attribute, x86 |
d77de738 ML |
6867 | @item rdpid |
6868 | @itemx no-rdpid | |
d77de738 ML |
6869 | Enable/disable the generation of the RDPID instructions. |
6870 | ||
f33d7a88 | 6871 | @cindex @code{target("rdrnd")} function attribute, x86 |
d77de738 ML |
6872 | @item rdrnd |
6873 | @itemx no-rdrnd | |
d77de738 ML |
6874 | Enable/disable the generation of the RDRND instructions. |
6875 | ||
f33d7a88 | 6876 | @cindex @code{target("rdseed")} function attribute, x86 |
d77de738 ML |
6877 | @item rdseed |
6878 | @itemx no-rdseed | |
d77de738 ML |
6879 | Enable/disable the generation of the RDSEED instructions. |
6880 | ||
f33d7a88 | 6881 | @cindex @code{target("rtm")} function attribute, x86 |
d77de738 ML |
6882 | @item rtm |
6883 | @itemx no-rtm | |
d77de738 ML |
6884 | Enable/disable the generation of the RTM instructions. |
6885 | ||
f33d7a88 | 6886 | @cindex @code{target("sahf")} function attribute, x86 |
d77de738 ML |
6887 | @item sahf |
6888 | @itemx no-sahf | |
d77de738 ML |
6889 | Enable/disable the generation of the SAHF instructions. |
6890 | ||
f33d7a88 | 6891 | @cindex @code{target("sgx")} function attribute, x86 |
d77de738 ML |
6892 | @item sgx |
6893 | @itemx no-sgx | |
d77de738 ML |
6894 | Enable/disable the generation of the SGX instructions. |
6895 | ||
f33d7a88 | 6896 | @cindex @code{target("sha")} function attribute, x86 |
d77de738 ML |
6897 | @item sha |
6898 | @itemx no-sha | |
d77de738 ML |
6899 | Enable/disable the generation of the SHA instructions. |
6900 | ||
f33d7a88 | 6901 | @cindex @code{target("shstk")} function attribute, x86 |
d77de738 ML |
6902 | @item shstk |
6903 | @itemx no-shstk | |
d77de738 ML |
6904 | Enable/disable the shadow stack built-in functions from CET. |
6905 | ||
f33d7a88 | 6906 | @cindex @code{target("sse")} function attribute, x86 |
d77de738 ML |
6907 | @item sse |
6908 | @itemx no-sse | |
d77de738 ML |
6909 | Enable/disable the generation of the SSE instructions. |
6910 | ||
f33d7a88 | 6911 | @cindex @code{target("sse2")} function attribute, x86 |
d77de738 ML |
6912 | @item sse2 |
6913 | @itemx no-sse2 | |
d77de738 ML |
6914 | Enable/disable the generation of the SSE2 instructions. |
6915 | ||
f33d7a88 | 6916 | @cindex @code{target("sse3")} function attribute, x86 |
d77de738 ML |
6917 | @item sse3 |
6918 | @itemx no-sse3 | |
d77de738 ML |
6919 | Enable/disable the generation of the SSE3 instructions. |
6920 | ||
f33d7a88 | 6921 | @cindex @code{target("sse4")} function attribute, x86 |
d77de738 ML |
6922 | @item sse4 |
6923 | @itemx no-sse4 | |
d77de738 ML |
6924 | Enable/disable the generation of the SSE4 instructions (both SSE4.1 |
6925 | and SSE4.2). | |
6926 | ||
f33d7a88 | 6927 | @cindex @code{target("sse4.1")} function attribute, x86 |
d77de738 ML |
6928 | @item sse4.1 |
6929 | @itemx no-sse4.1 | |
d77de738 ML |
6930 | Enable/disable the generation of the SSE4.1 instructions. |
6931 | ||
f33d7a88 | 6932 | @cindex @code{target("sse4.2")} function attribute, x86 |
d77de738 ML |
6933 | @item sse4.2 |
6934 | @itemx no-sse4.2 | |
d77de738 ML |
6935 | Enable/disable the generation of the SSE4.2 instructions. |
6936 | ||
f33d7a88 | 6937 | @cindex @code{target("sse4a")} function attribute, x86 |
d77de738 ML |
6938 | @item sse4a |
6939 | @itemx no-sse4a | |
d77de738 ML |
6940 | Enable/disable the generation of the SSE4A instructions. |
6941 | ||
f33d7a88 | 6942 | @cindex @code{target("ssse3")} function attribute, x86 |
d77de738 ML |
6943 | @item ssse3 |
6944 | @itemx no-ssse3 | |
d77de738 ML |
6945 | Enable/disable the generation of the SSSE3 instructions. |
6946 | ||
f33d7a88 | 6947 | @cindex @code{target("tbm")} function attribute, x86 |
d77de738 ML |
6948 | @item tbm |
6949 | @itemx no-tbm | |
d77de738 ML |
6950 | Enable/disable the generation of the TBM instructions. |
6951 | ||
f33d7a88 | 6952 | @cindex @code{target("vaes")} function attribute, x86 |
d77de738 ML |
6953 | @item vaes |
6954 | @itemx no-vaes | |
d77de738 ML |
6955 | Enable/disable the generation of the VAES instructions. |
6956 | ||
f33d7a88 | 6957 | @cindex @code{target("vpclmulqdq")} function attribute, x86 |
d77de738 ML |
6958 | @item vpclmulqdq |
6959 | @itemx no-vpclmulqdq | |
d77de738 ML |
6960 | Enable/disable the generation of the VPCLMULQDQ instructions. |
6961 | ||
f33d7a88 | 6962 | @cindex @code{target("waitpkg")} function attribute, x86 |
d77de738 ML |
6963 | @item waitpkg |
6964 | @itemx no-waitpkg | |
d77de738 ML |
6965 | Enable/disable the generation of the WAITPKG instructions. |
6966 | ||
f33d7a88 | 6967 | @cindex @code{target("wbnoinvd")} function attribute, x86 |
d77de738 ML |
6968 | @item wbnoinvd |
6969 | @itemx no-wbnoinvd | |
d77de738 ML |
6970 | Enable/disable the generation of the WBNOINVD instructions. |
6971 | ||
f33d7a88 | 6972 | @cindex @code{target("xop")} function attribute, x86 |
d77de738 ML |
6973 | @item xop |
6974 | @itemx no-xop | |
d77de738 ML |
6975 | Enable/disable the generation of the XOP instructions. |
6976 | ||
f33d7a88 | 6977 | @cindex @code{target("xsave")} function attribute, x86 |
d77de738 ML |
6978 | @item xsave |
6979 | @itemx no-xsave | |
d77de738 ML |
6980 | Enable/disable the generation of the XSAVE instructions. |
6981 | ||
f33d7a88 | 6982 | @cindex @code{target("xsavec")} function attribute, x86 |
d77de738 ML |
6983 | @item xsavec |
6984 | @itemx no-xsavec | |
d77de738 ML |
6985 | Enable/disable the generation of the XSAVEC instructions. |
6986 | ||
f33d7a88 | 6987 | @cindex @code{target("xsaveopt")} function attribute, x86 |
d77de738 ML |
6988 | @item xsaveopt |
6989 | @itemx no-xsaveopt | |
d77de738 ML |
6990 | Enable/disable the generation of the XSAVEOPT instructions. |
6991 | ||
f33d7a88 | 6992 | @cindex @code{target("xsaves")} function attribute, x86 |
d77de738 ML |
6993 | @item xsaves |
6994 | @itemx no-xsaves | |
d77de738 ML |
6995 | Enable/disable the generation of the XSAVES instructions. |
6996 | ||
f33d7a88 | 6997 | @cindex @code{target("amx-tile")} function attribute, x86 |
d77de738 ML |
6998 | @item amx-tile |
6999 | @itemx no-amx-tile | |
d77de738 ML |
7000 | Enable/disable the generation of the AMX-TILE instructions. |
7001 | ||
f33d7a88 | 7002 | @cindex @code{target("amx-int8")} function attribute, x86 |
d77de738 ML |
7003 | @item amx-int8 |
7004 | @itemx no-amx-int8 | |
d77de738 ML |
7005 | Enable/disable the generation of the AMX-INT8 instructions. |
7006 | ||
f33d7a88 | 7007 | @cindex @code{target("amx-bf16")} function attribute, x86 |
d77de738 ML |
7008 | @item amx-bf16 |
7009 | @itemx no-amx-bf16 | |
d77de738 ML |
7010 | Enable/disable the generation of the AMX-BF16 instructions. |
7011 | ||
f33d7a88 | 7012 | @cindex @code{target("uintr")} function attribute, x86 |
d77de738 ML |
7013 | @item uintr |
7014 | @itemx no-uintr | |
d77de738 ML |
7015 | Enable/disable the generation of the UINTR instructions. |
7016 | ||
f33d7a88 | 7017 | @cindex @code{target("hreset")} function attribute, x86 |
d77de738 ML |
7018 | @item hreset |
7019 | @itemx no-hreset | |
d77de738 ML |
7020 | Enable/disable the generation of the HRESET instruction. |
7021 | ||
f33d7a88 | 7022 | @cindex @code{target("kl")} function attribute, x86 |
d77de738 ML |
7023 | @item kl |
7024 | @itemx no-kl | |
d77de738 ML |
7025 | Enable/disable the generation of the KEYLOCKER instructions. |
7026 | ||
f33d7a88 | 7027 | @cindex @code{target("widekl")} function attribute, x86 |
d77de738 ML |
7028 | @item widekl |
7029 | @itemx no-widekl | |
d77de738 ML |
7030 | Enable/disable the generation of the WIDEKL instructions. |
7031 | ||
f33d7a88 | 7032 | @cindex @code{target("avxvnni")} function attribute, x86 |
d77de738 ML |
7033 | @item avxvnni |
7034 | @itemx no-avxvnni | |
d77de738 ML |
7035 | Enable/disable the generation of the AVXVNNI instructions. |
7036 | ||
f33d7a88 | 7037 | @cindex @code{target("avxifma")} function attribute, x86 |
d77de738 ML |
7038 | @item avxifma |
7039 | @itemx no-avxifma | |
d77de738 ML |
7040 | Enable/disable the generation of the AVXIFMA instructions. |
7041 | ||
f33d7a88 | 7042 | @cindex @code{target("avxvnniint8")} function attribute, x86 |
d77de738 ML |
7043 | @item avxvnniint8 |
7044 | @itemx no-avxvnniint8 | |
d77de738 ML |
7045 | Enable/disable the generation of the AVXVNNIINT8 instructions. |
7046 | ||
f33d7a88 | 7047 | @cindex @code{target("avxneconvert")} function attribute, x86 |
d77de738 ML |
7048 | @item avxneconvert |
7049 | @itemx no-avxneconvert | |
d77de738 ML |
7050 | Enable/disable the generation of the AVXNECONVERT instructions. |
7051 | ||
f33d7a88 | 7052 | @cindex @code{target("cmpccxadd")} function attribute, x86 |
d77de738 ML |
7053 | @item cmpccxadd |
7054 | @itemx no-cmpccxadd | |
d77de738 ML |
7055 | Enable/disable the generation of the CMPccXADD instructions. |
7056 | ||
f33d7a88 | 7057 | @cindex @code{target("amx-fp16")} function attribute, x86 |
d77de738 ML |
7058 | @item amx-fp16 |
7059 | @itemx no-amx-fp16 | |
d77de738 ML |
7060 | Enable/disable the generation of the AMX-FP16 instructions. |
7061 | ||
f33d7a88 | 7062 | @cindex @code{target("prefetchi")} function attribute, x86 |
d77de738 ML |
7063 | @item prefetchi |
7064 | @itemx no-prefetchi | |
d77de738 ML |
7065 | Enable/disable the generation of the PREFETCHI instructions. |
7066 | ||
f33d7a88 | 7067 | @cindex @code{target("raoint")} function attribute, x86 |
d77de738 ML |
7068 | @item raoint |
7069 | @itemx no-raoint | |
d77de738 ML |
7070 | Enable/disable the generation of the RAOINT instructions. |
7071 | ||
f33d7a88 | 7072 | @cindex @code{target("cld")} function attribute, x86 |
d77de738 ML |
7073 | @item cld |
7074 | @itemx no-cld | |
d77de738 ML |
7075 | Enable/disable the generation of the CLD before string moves. |
7076 | ||
f33d7a88 | 7077 | @cindex @code{target("fancy-math-387")} function attribute, x86 |
d77de738 ML |
7078 | @item fancy-math-387 |
7079 | @itemx no-fancy-math-387 | |
d77de738 ML |
7080 | Enable/disable the generation of the @code{sin}, @code{cos}, and |
7081 | @code{sqrt} instructions on the 387 floating-point unit. | |
7082 | ||
f33d7a88 | 7083 | @cindex @code{target("ieee-fp")} function attribute, x86 |
d77de738 ML |
7084 | @item ieee-fp |
7085 | @itemx no-ieee-fp | |
d77de738 ML |
7086 | Enable/disable the generation of floating point that depends on IEEE arithmetic. |
7087 | ||
f33d7a88 | 7088 | @cindex @code{target("inline-all-stringops")} function attribute, x86 |
d77de738 ML |
7089 | @item inline-all-stringops |
7090 | @itemx no-inline-all-stringops | |
d77de738 ML |
7091 | Enable/disable inlining of string operations. |
7092 | ||
f33d7a88 | 7093 | @cindex @code{target("inline-stringops-dynamically")} function attribute, x86 |
d77de738 ML |
7094 | @item inline-stringops-dynamically |
7095 | @itemx no-inline-stringops-dynamically | |
d77de738 ML |
7096 | Enable/disable the generation of the inline code to do small string |
7097 | operations and calling the library routines for large operations. | |
7098 | ||
f33d7a88 | 7099 | @cindex @code{target("align-stringops")} function attribute, x86 |
d77de738 ML |
7100 | @item align-stringops |
7101 | @itemx no-align-stringops | |
d77de738 ML |
7102 | Do/do not align destination of inlined string operations. |
7103 | ||
f33d7a88 | 7104 | @cindex @code{target("recip")} function attribute, x86 |
d77de738 ML |
7105 | @item recip |
7106 | @itemx no-recip | |
d77de738 ML |
7107 | Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS |
7108 | instructions followed an additional Newton-Raphson step instead of | |
7109 | doing a floating-point division. | |
7110 | ||
d77de738 | 7111 | @cindex @code{target("general-regs-only")} function attribute, x86 |
f33d7a88 | 7112 | @item general-regs-only |
d77de738 ML |
7113 | Generate code which uses only the general registers. |
7114 | ||
d77de738 | 7115 | @cindex @code{target("arch=@var{ARCH}")} function attribute, x86 |
f33d7a88 | 7116 | @item arch=@var{ARCH} |
d77de738 ML |
7117 | Specify the architecture to generate code for in compiling the function. |
7118 | ||
d77de738 | 7119 | @cindex @code{target("tune=@var{TUNE}")} function attribute, x86 |
f33d7a88 | 7120 | @item tune=@var{TUNE} |
d77de738 ML |
7121 | Specify the architecture to tune for in compiling the function. |
7122 | ||
d77de738 | 7123 | @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86 |
f33d7a88 | 7124 | @item fpmath=@var{FPMATH} |
d77de738 ML |
7125 | Specify which floating-point unit to use. You must specify the |
7126 | @code{target("fpmath=sse,387")} option as | |
7127 | @code{target("fpmath=sse+387")} because the comma would separate | |
7128 | different options. | |
7129 | ||
d77de738 | 7130 | @cindex @code{prefer-vector-width} function attribute, x86 |
f33d7a88 | 7131 | @item prefer-vector-width=@var{OPT} |
d77de738 ML |
7132 | On x86 targets, the @code{prefer-vector-width} attribute informs the |
7133 | compiler to use @var{OPT}-bit vector width in instructions | |
7134 | instead of the default on the selected platform. | |
7135 | ||
7136 | Valid @var{OPT} values are: | |
7137 | ||
7138 | @table @samp | |
7139 | @item none | |
7140 | No extra limitations applied to GCC other than defined by the selected platform. | |
7141 | ||
7142 | @item 128 | |
7143 | Prefer 128-bit vector width for instructions. | |
7144 | ||
7145 | @item 256 | |
7146 | Prefer 256-bit vector width for instructions. | |
7147 | ||
7148 | @item 512 | |
7149 | Prefer 512-bit vector width for instructions. | |
7150 | @end table | |
7151 | ||
7152 | On the x86, the inliner does not inline a | |
7153 | function that has different target options than the caller, unless the | |
7154 | callee has a subset of the target options of the caller. For example | |
7155 | a function declared with @code{target("sse3")} can inline a function | |
7156 | with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. | |
7157 | @end table | |
7158 | ||
d77de738 | 7159 | @cindex @code{indirect_branch} function attribute, x86 |
f33d7a88 | 7160 | @item indirect_branch("@var{choice}") |
d77de738 ML |
7161 | On x86 targets, the @code{indirect_branch} attribute causes the compiler |
7162 | to convert indirect call and jump with @var{choice}. @samp{keep} | |
7163 | keeps indirect call and jump unmodified. @samp{thunk} converts indirect | |
7164 | call and jump to call and return thunk. @samp{thunk-inline} converts | |
7165 | indirect call and jump to inlined call and return thunk. | |
7166 | @samp{thunk-extern} converts indirect call and jump to external call | |
7167 | and return thunk provided in a separate object file. | |
7168 | ||
d77de738 | 7169 | @cindex @code{function_return} function attribute, x86 |
f33d7a88 | 7170 | @item function_return("@var{choice}") |
d77de738 ML |
7171 | On x86 targets, the @code{function_return} attribute causes the compiler |
7172 | to convert function return with @var{choice}. @samp{keep} keeps function | |
7173 | return unmodified. @samp{thunk} converts function return to call and | |
7174 | return thunk. @samp{thunk-inline} converts function return to inlined | |
7175 | call and return thunk. @samp{thunk-extern} converts function return to | |
7176 | external call and return thunk provided in a separate object file. | |
7177 | ||
d77de738 | 7178 | @cindex @code{nocf_check} function attribute |
f33d7a88 | 7179 | @item nocf_check |
d77de738 ML |
7180 | The @code{nocf_check} attribute on a function is used to inform the |
7181 | compiler that the function's prologue should not be instrumented when | |
7182 | compiled with the @option{-fcf-protection=branch} option. The | |
7183 | compiler assumes that the function's address is a valid target for a | |
7184 | control-flow transfer. | |
7185 | ||
7186 | The @code{nocf_check} attribute on a type of pointer to function is | |
7187 | used to inform the compiler that a call through the pointer should | |
7188 | not be instrumented when compiled with the | |
7189 | @option{-fcf-protection=branch} option. The compiler assumes | |
7190 | that the function's address from the pointer is a valid target for | |
7191 | a control-flow transfer. A direct function call through a function | |
7192 | name is assumed to be a safe call thus direct calls are not | |
7193 | instrumented by the compiler. | |
7194 | ||
7195 | The @code{nocf_check} attribute is applied to an object's type. | |
7196 | In case of assignment of a function address or a function pointer to | |
7197 | another pointer, the attribute is not carried over from the right-hand | |
7198 | object's type; the type of left-hand object stays unchanged. The | |
7199 | compiler checks for @code{nocf_check} attribute mismatch and reports | |
7200 | a warning in case of mismatch. | |
7201 | ||
7202 | @smallexample | |
7203 | @{ | |
7204 | int foo (void) __attribute__(nocf_check); | |
7205 | void (*foo1)(void) __attribute__(nocf_check); | |
7206 | void (*foo2)(void); | |
7207 | ||
7208 | /* foo's address is assumed to be valid. */ | |
7209 | int | |
7210 | foo (void) | |
7211 | ||
7212 | /* This call site is not checked for control-flow | |
7213 | validity. */ | |
7214 | (*foo1)(); | |
7215 | ||
7216 | /* A warning is issued about attribute mismatch. */ | |
7217 | foo1 = foo2; | |
7218 | ||
7219 | /* This call site is still not checked. */ | |
7220 | (*foo1)(); | |
7221 | ||
7222 | /* This call site is checked. */ | |
7223 | (*foo2)(); | |
7224 | ||
7225 | /* A warning is issued about attribute mismatch. */ | |
7226 | foo2 = foo1; | |
7227 | ||
7228 | /* This call site is still checked. */ | |
7229 | (*foo2)(); | |
7230 | ||
7231 | return 0; | |
7232 | @} | |
7233 | @end smallexample | |
7234 | ||
d77de738 | 7235 | @cindex @code{cf_check} function attribute, x86 |
f33d7a88 | 7236 | @item cf_check |
d77de738 ML |
7237 | |
7238 | The @code{cf_check} attribute on a function is used to inform the | |
7239 | compiler that ENDBR instruction should be placed at the function | |
7240 | entry when @option{-fcf-protection=branch} is enabled. | |
7241 | ||
d77de738 | 7242 | @cindex @code{indirect_return} function attribute, x86 |
f33d7a88 | 7243 | @item indirect_return |
d77de738 ML |
7244 | |
7245 | The @code{indirect_return} attribute can be applied to a function, | |
7246 | as well as variable or type of function pointer to inform the | |
7247 | compiler that the function may return via indirect branch. | |
7248 | ||
d77de738 | 7249 | @cindex @code{fentry_name} function attribute, x86 |
f33d7a88 | 7250 | @item fentry_name("@var{name}") |
d77de738 ML |
7251 | On x86 targets, the @code{fentry_name} attribute sets the function to |
7252 | call on function entry when function instrumentation is enabled | |
7253 | with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte | |
7254 | nop sequence is generated. | |
7255 | ||
d77de738 | 7256 | @cindex @code{fentry_section} function attribute, x86 |
f33d7a88 | 7257 | @item fentry_section("@var{name}") |
d77de738 ML |
7258 | On x86 targets, the @code{fentry_section} attribute sets the name |
7259 | of the section to record function entry instrumentation calls in when | |
7260 | enabled with @option{-pg -mrecord-mcount} | |
7261 | ||
d77de738 ML |
7262 | @cindex @code{nodirect_extern_access} function attribute |
7263 | @opindex mno-direct-extern-access | |
f33d7a88 | 7264 | @item nodirect_extern_access |
d77de738 ML |
7265 | This attribute, attached to a global variable or function, is the |
7266 | counterpart to option @option{-mno-direct-extern-access}. | |
7267 | ||
7268 | @end table | |
7269 | ||
7270 | @node Xstormy16 Function Attributes | |
7271 | @subsection Xstormy16 Function Attributes | |
7272 | ||
7273 | These function attributes are supported by the Xstormy16 back end: | |
7274 | ||
7275 | @table @code | |
d77de738 | 7276 | @cindex @code{interrupt} function attribute, Xstormy16 |
f33d7a88 | 7277 | @item interrupt |
d77de738 ML |
7278 | Use this attribute to indicate |
7279 | that the specified function is an interrupt handler. The compiler generates | |
7280 | function entry and exit sequences suitable for use in an interrupt handler | |
7281 | when this attribute is present. | |
7282 | @end table | |
7283 | ||
7284 | @node Variable Attributes | |
7285 | @section Specifying Attributes of Variables | |
7286 | @cindex attribute of variables | |
7287 | @cindex variable attributes | |
7288 | ||
7289 | The keyword @code{__attribute__} allows you to specify special properties | |
7290 | of variables, function parameters, or structure, union, and, in C++, class | |
7291 | members. This @code{__attribute__} keyword is followed by an attribute | |
7292 | specification enclosed in double parentheses. Some attributes are currently | |
7293 | defined generically for variables. Other attributes are defined for | |
7294 | variables on particular target systems. Other attributes are available | |
7295 | for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}), | |
7296 | enumerators (@pxref{Enumerator Attributes}), statements | |
7297 | (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). | |
7298 | Other front ends might define more attributes | |
7299 | (@pxref{C++ Extensions,,Extensions to the C++ Language}). | |
7300 | ||
7301 | @xref{Attribute Syntax}, for details of the exact syntax for using | |
7302 | attributes. | |
7303 | ||
7304 | @menu | |
7305 | * Common Variable Attributes:: | |
7306 | * ARC Variable Attributes:: | |
7307 | * AVR Variable Attributes:: | |
7308 | * Blackfin Variable Attributes:: | |
7309 | * H8/300 Variable Attributes:: | |
7310 | * IA-64 Variable Attributes:: | |
7311 | * LoongArch Variable Attributes:: | |
7312 | * M32R/D Variable Attributes:: | |
d77de738 ML |
7313 | * Microsoft Windows Variable Attributes:: |
7314 | * MSP430 Variable Attributes:: | |
7315 | * Nvidia PTX Variable Attributes:: | |
7316 | * PowerPC Variable Attributes:: | |
7317 | * RL78 Variable Attributes:: | |
7318 | * V850 Variable Attributes:: | |
7319 | * x86 Variable Attributes:: | |
7320 | * Xstormy16 Variable Attributes:: | |
7321 | @end menu | |
7322 | ||
7323 | @node Common Variable Attributes | |
7324 | @subsection Common Variable Attributes | |
7325 | ||
7326 | The following attributes are supported on most targets. | |
7327 | ||
7328 | @table @code | |
7329 | ||
d77de738 | 7330 | @cindex @code{alias} variable attribute |
f33d7a88 | 7331 | @item alias ("@var{target}") |
d77de738 ML |
7332 | The @code{alias} variable attribute causes the declaration to be emitted |
7333 | as an alias for another symbol known as an @dfn{alias target}. Except | |
7334 | for top-level qualifiers the alias target must have the same type as | |
7335 | the alias. For instance, the following | |
7336 | ||
7337 | @smallexample | |
7338 | int var_target; | |
7339 | extern int __attribute__ ((alias ("var_target"))) var_alias; | |
7340 | @end smallexample | |
7341 | ||
7342 | @noindent | |
7343 | defines @code{var_alias} to be an alias for the @code{var_target} variable. | |
7344 | ||
7345 | It is an error if the alias target is not defined in the same translation | |
7346 | unit as the alias. | |
7347 | ||
7348 | Note that in the absence of the attribute GCC assumes that distinct | |
7349 | declarations with external linkage denote distinct objects. Using both | |
7350 | the alias and the alias target to access the same object is undefined | |
7351 | in a translation unit without a declaration of the alias with the attribute. | |
7352 | ||
7353 | This attribute requires assembler and object file support, and may not be | |
7354 | available on all targets. | |
7355 | ||
7356 | @cindex @code{aligned} variable attribute | |
7357 | @item aligned | |
7358 | @itemx aligned (@var{alignment}) | |
7359 | The @code{aligned} attribute specifies a minimum alignment for the variable | |
7360 | or structure field, measured in bytes. When specified, @var{alignment} must | |
7361 | be an integer constant power of 2. Specifying no @var{alignment} argument | |
7362 | implies the maximum alignment for the target, which is often, but by no | |
7363 | means always, 8 or 16 bytes. | |
7364 | ||
7365 | For example, the declaration: | |
7366 | ||
7367 | @smallexample | |
7368 | int x __attribute__ ((aligned (16))) = 0; | |
7369 | @end smallexample | |
7370 | ||
7371 | @noindent | |
7372 | causes the compiler to allocate the global variable @code{x} on a | |
7373 | 16-byte boundary. On a 68040, this could be used in conjunction with | |
7374 | an @code{asm} expression to access the @code{move16} instruction which | |
7375 | requires 16-byte aligned operands. | |
7376 | ||
7377 | You can also specify the alignment of structure fields. For example, to | |
7378 | create a double-word aligned @code{int} pair, you could write: | |
7379 | ||
7380 | @smallexample | |
7381 | struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; | |
7382 | @end smallexample | |
7383 | ||
7384 | @noindent | |
7385 | This is an alternative to creating a union with a @code{double} member, | |
7386 | which forces the union to be double-word aligned. | |
7387 | ||
7388 | As in the preceding examples, you can explicitly specify the alignment | |
7389 | (in bytes) that you wish the compiler to use for a given variable or | |
7390 | structure field. Alternatively, you can leave out the alignment factor | |
7391 | and just ask the compiler to align a variable or field to the | |
7392 | default alignment for the target architecture you are compiling for. | |
7393 | The default alignment is sufficient for all scalar types, but may not be | |
7394 | enough for all vector types on a target that supports vector operations. | |
7395 | The default alignment is fixed for a particular target ABI. | |
7396 | ||
7397 | GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, | |
7398 | which is the largest alignment ever used for any data type on the | |
7399 | target machine you are compiling for. For example, you could write: | |
7400 | ||
7401 | @smallexample | |
7402 | short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); | |
7403 | @end smallexample | |
7404 | ||
7405 | The compiler automatically sets the alignment for the declared | |
7406 | variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can | |
7407 | often make copy operations more efficient, because the compiler can | |
7408 | use whatever instructions copy the biggest chunks of memory when | |
7409 | performing copies to or from the variables or fields that you have | |
7410 | aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} | |
7411 | may change depending on command-line options. | |
7412 | ||
7413 | When used on a struct, or struct member, the @code{aligned} attribute can | |
7414 | only increase the alignment; in order to decrease it, the @code{packed} | |
7415 | attribute must be specified as well. When used as part of a typedef, the | |
7416 | @code{aligned} attribute can both increase and decrease alignment, and | |
7417 | specifying the @code{packed} attribute generates a warning. | |
7418 | ||
7419 | Note that the effectiveness of @code{aligned} attributes for static | |
7420 | variables may be limited by inherent limitations in the system linker | |
7421 | and/or object file format. On some systems, the linker is | |
7422 | only able to arrange for variables to be aligned up to a certain maximum | |
7423 | alignment. (For some linkers, the maximum supported alignment may | |
7424 | be very very small.) If your linker is only able to align variables | |
7425 | up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} | |
7426 | in an @code{__attribute__} still only provides you with 8-byte | |
7427 | alignment. See your linker documentation for further information. | |
7428 | ||
7429 | Stack variables are not affected by linker restrictions; GCC can properly | |
7430 | align them on any target. | |
7431 | ||
7432 | The @code{aligned} attribute can also be used for functions | |
7433 | (@pxref{Common Function Attributes}.) | |
7434 | ||
7435 | @cindex @code{warn_if_not_aligned} variable attribute | |
7436 | @item warn_if_not_aligned (@var{alignment}) | |
7437 | This attribute specifies a threshold for the structure field, measured | |
7438 | in bytes. If the structure field is aligned below the threshold, a | |
7439 | warning will be issued. For example, the declaration: | |
7440 | ||
7441 | @smallexample | |
7442 | struct foo | |
7443 | @{ | |
7444 | int i1; | |
7445 | int i2; | |
7446 | unsigned long long x __attribute__ ((warn_if_not_aligned (16))); | |
7447 | @}; | |
7448 | @end smallexample | |
7449 | ||
7450 | @noindent | |
7451 | causes the compiler to issue an warning on @code{struct foo}, like | |
7452 | @samp{warning: alignment 8 of 'struct foo' is less than 16}. | |
7453 | The compiler also issues a warning, like @samp{warning: 'x' offset | |
7454 | 8 in 'struct foo' isn't aligned to 16}, when the structure field has | |
7455 | the misaligned offset: | |
7456 | ||
7457 | @smallexample | |
7458 | struct __attribute__ ((aligned (16))) foo | |
7459 | @{ | |
7460 | int i1; | |
7461 | int i2; | |
7462 | unsigned long long x __attribute__ ((warn_if_not_aligned (16))); | |
7463 | @}; | |
7464 | @end smallexample | |
7465 | ||
7466 | This warning can be disabled by @option{-Wno-if-not-aligned}. | |
7467 | The @code{warn_if_not_aligned} attribute can also be used for types | |
7468 | (@pxref{Common Type Attributes}.) | |
7469 | ||
7470 | @cindex @code{strict_flex_array} variable attribute | |
7471 | @item strict_flex_array (@var{level}) | |
7472 | The @code{strict_flex_array} attribute should be attached to the trailing | |
7473 | array field of a structure. It controls when to treat the trailing array | |
7474 | field of a structure as a flexible array member for the purposes of accessing | |
7475 | the elements of such an array. | |
7476 | @var{level} must be an integer betwen 0 to 3. | |
7477 | ||
7478 | @var{level}=0 is the least strict level, all trailing arrays of structures | |
7479 | are treated as flexible array members. @var{level}=3 is the strictest level, | |
7480 | only when the trailing array is declared as a flexible array member per C99 | |
7481 | standard onwards (@samp{[]}), it is treated as a flexible array member. | |
7482 | ||
7483 | There are two more levels in between 0 and 3, which are provided to support | |
7484 | older codes that use GCC zero-length array extension (@samp{[0]}) or one-element | |
7485 | array as flexible array members (@samp{[1]}): | |
7486 | When @var{level} is 1, the trailing array is treated as a flexible array member | |
7487 | when it is declared as either @samp{[]}, @samp{[0]}, or @samp{[1]}; | |
7488 | When @var{level} is 2, the trailing array is treated as a flexible array member | |
7489 | when it is declared as either @samp{[]}, or @samp{[0]}. | |
7490 | ||
7491 | This attribute can be used with or without the @option{-fstrict-flex-arrays}. | |
7492 | When both the attribute and the option present at the same time, the level of | |
7493 | the strictness for the specific trailing array field is determined by the | |
7494 | attribute. | |
7495 | ||
f33d7a88 | 7496 | @cindex @code{alloc_size} variable attribute |
d77de738 ML |
7497 | @item alloc_size (@var{position}) |
7498 | @itemx alloc_size (@var{position-1}, @var{position-2}) | |
d77de738 ML |
7499 | The @code{alloc_size} variable attribute may be applied to the declaration |
7500 | of a pointer to a function that returns a pointer and takes at least one | |
7501 | argument of an integer type. It indicates that the returned pointer points | |
7502 | to an object whose size is given by the function argument at @var{position}, | |
7503 | or by the product of the arguments at @var{position-1} and @var{position-2}. | |
7504 | Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other | |
7505 | sizes are diagnosed when detected. GCC uses this information to improve | |
7506 | the results of @code{__builtin_object_size}. | |
7507 | ||
7508 | For instance, the following declarations | |
7509 | ||
7510 | @smallexample | |
7511 | typedef __attribute__ ((alloc_size (1, 2))) void* | |
7512 | (*calloc_ptr) (size_t, size_t); | |
7513 | typedef __attribute__ ((alloc_size (1))) void* | |
7514 | (*malloc_ptr) (size_t); | |
7515 | @end smallexample | |
7516 | ||
7517 | @noindent | |
7518 | specify that @code{calloc_ptr} is a pointer of a function that, like | |
7519 | the standard C function @code{calloc}, returns an object whose size | |
7520 | is given by the product of arguments 1 and 2, and similarly, that | |
7521 | @code{malloc_ptr}, like the standard C function @code{malloc}, | |
7522 | returns an object whose size is given by argument 1 to the function. | |
7523 | ||
d77de738 | 7524 | @cindex @code{cleanup} variable attribute |
f33d7a88 | 7525 | @item cleanup (@var{cleanup_function}) |
d77de738 ML |
7526 | The @code{cleanup} attribute runs a function when the variable goes |
7527 | out of scope. This attribute can only be applied to auto function | |
7528 | scope variables; it may not be applied to parameters or variables | |
7529 | with static storage duration. The function must take one parameter, | |
7530 | a pointer to a type compatible with the variable. The return value | |
7531 | of the function (if any) is ignored. | |
7532 | ||
7533 | If @option{-fexceptions} is enabled, then @var{cleanup_function} | |
7534 | is run during the stack unwinding that happens during the | |
7535 | processing of the exception. Note that the @code{cleanup} attribute | |
7536 | does not allow the exception to be caught, only to perform an action. | |
7537 | It is undefined what happens if @var{cleanup_function} does not | |
7538 | return normally. | |
7539 | ||
d77de738 ML |
7540 | @cindex @code{common} variable attribute |
7541 | @cindex @code{nocommon} variable attribute | |
7542 | @opindex fcommon | |
7543 | @opindex fno-common | |
f33d7a88 AA |
7544 | @item common |
7545 | @itemx nocommon | |
d77de738 ML |
7546 | The @code{common} attribute requests GCC to place a variable in |
7547 | ``common'' storage. The @code{nocommon} attribute requests the | |
7548 | opposite---to allocate space for it directly. | |
7549 | ||
7550 | These attributes override the default chosen by the | |
7551 | @option{-fno-common} and @option{-fcommon} flags respectively. | |
7552 | ||
f33d7a88 | 7553 | @cindex @code{copy} variable attribute |
d77de738 ML |
7554 | @item copy |
7555 | @itemx copy (@var{variable}) | |
d77de738 ML |
7556 | The @code{copy} attribute applies the set of attributes with which |
7557 | @var{variable} has been declared to the declaration of the variable | |
7558 | to which the attribute is applied. The attribute is designed for | |
7559 | libraries that define aliases that are expected to specify the same | |
7560 | set of attributes as the aliased symbols. The @code{copy} attribute | |
7561 | can be used with variables, functions or types. However, the kind | |
7562 | of symbol to which the attribute is applied (either varible or | |
7563 | function) must match the kind of symbol to which the argument refers. | |
7564 | The @code{copy} attribute copies only syntactic and semantic attributes | |
7565 | but not attributes that affect a symbol's linkage or visibility such as | |
7566 | @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} | |
7567 | attribute is also not copied. @xref{Common Function Attributes}. | |
7568 | @xref{Common Type Attributes}. | |
7569 | ||
f33d7a88 | 7570 | @cindex @code{deprecated} variable attribute |
d77de738 ML |
7571 | @item deprecated |
7572 | @itemx deprecated (@var{msg}) | |
d77de738 ML |
7573 | The @code{deprecated} attribute results in a warning if the variable |
7574 | is used anywhere in the source file. This is useful when identifying | |
7575 | variables that are expected to be removed in a future version of a | |
7576 | program. The warning also includes the location of the declaration | |
7577 | of the deprecated variable, to enable users to easily find further | |
7578 | information about why the variable is deprecated, or what they should | |
7579 | do instead. Note that the warning only occurs for uses: | |
7580 | ||
7581 | @smallexample | |
7582 | extern int old_var __attribute__ ((deprecated)); | |
7583 | extern int old_var; | |
7584 | int new_fn () @{ return old_var; @} | |
7585 | @end smallexample | |
7586 | ||
7587 | @noindent | |
7588 | results in a warning on line 3 but not line 2. The optional @var{msg} | |
7589 | argument, which must be a string, is printed in the warning if | |
7590 | present. | |
7591 | ||
7592 | The @code{deprecated} attribute can also be used for functions and | |
7593 | types (@pxref{Common Function Attributes}, | |
7594 | @pxref{Common Type Attributes}). | |
7595 | ||
7596 | The message attached to the attribute is affected by the setting of | |
7597 | the @option{-fmessage-length} option. | |
7598 | ||
f33d7a88 | 7599 | @cindex @code{unavailable} variable attribute |
d77de738 ML |
7600 | @item unavailable |
7601 | @itemx unavailable (@var{msg}) | |
d77de738 ML |
7602 | The @code{unavailable} attribute indicates that the variable so marked |
7603 | is not available, if it is used anywhere in the source file. It behaves | |
7604 | in the same manner as the @code{deprecated} attribute except that the | |
7605 | compiler will emit an error rather than a warning. | |
7606 | ||
7607 | It is expected that items marked as @code{deprecated} will eventually be | |
7608 | withdrawn from interfaces, and then become unavailable. This attribute | |
7609 | allows for marking them appropriately. | |
7610 | ||
7611 | The @code{unavailable} attribute can also be used for functions and | |
7612 | types (@pxref{Common Function Attributes}, | |
7613 | @pxref{Common Type Attributes}). | |
7614 | ||
d77de738 | 7615 | @cindex @code{mode} variable attribute |
f33d7a88 | 7616 | @item mode (@var{mode}) |
d77de738 ML |
7617 | This attribute specifies the data type for the declaration---whichever |
7618 | type corresponds to the mode @var{mode}. This in effect lets you | |
7619 | request an integer or floating-point type according to its width. | |
7620 | ||
7621 | @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, | |
7622 | for a list of the possible keywords for @var{mode}. | |
7623 | You may also specify a mode of @code{byte} or @code{__byte__} to | |
7624 | indicate the mode corresponding to a one-byte integer, @code{word} or | |
7625 | @code{__word__} for the mode of a one-word integer, and @code{pointer} | |
7626 | or @code{__pointer__} for the mode used to represent pointers. | |
7627 | ||
d77de738 | 7628 | @cindex @code{nonstring} variable attribute |
f33d7a88 | 7629 | @item nonstring |
d77de738 ML |
7630 | The @code{nonstring} variable attribute specifies that an object or member |
7631 | declaration with type array of @code{char}, @code{signed char}, or | |
7632 | @code{unsigned char}, or pointer to such a type is intended to store | |
7633 | character arrays that do not necessarily contain a terminating @code{NUL}. | |
7634 | This is useful in detecting uses of such arrays or pointers with functions | |
7635 | that expect @code{NUL}-terminated strings, and to avoid warnings when such | |
7636 | an array or pointer is used as an argument to a bounded string manipulation | |
7637 | function such as @code{strncpy}. For example, without the attribute, GCC | |
7638 | will issue a warning for the @code{strncpy} call below because it may | |
7639 | truncate the copy without appending the terminating @code{NUL} character. | |
7640 | Using the attribute makes it possible to suppress the warning. However, | |
7641 | when the array is declared with the attribute the call to @code{strlen} is | |
7642 | diagnosed because when the array doesn't contain a @code{NUL}-terminated | |
7643 | string the call is undefined. To copy, compare, of search non-string | |
7644 | character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, | |
7645 | and other functions that operate on arrays of bytes. In addition, | |
7646 | calling @code{strnlen} and @code{strndup} with such arrays is safe | |
7647 | provided a suitable bound is specified, and not diagnosed. | |
7648 | ||
7649 | @smallexample | |
7650 | struct Data | |
7651 | @{ | |
7652 | char name [32] __attribute__ ((nonstring)); | |
7653 | @}; | |
7654 | ||
7655 | int f (struct Data *pd, const char *s) | |
7656 | @{ | |
7657 | strncpy (pd->name, s, sizeof pd->name); | |
7658 | @dots{} | |
7659 | return strlen (pd->name); // unsafe, gets a warning | |
7660 | @} | |
7661 | @end smallexample | |
7662 | ||
d77de738 | 7663 | @cindex @code{packed} variable attribute |
f33d7a88 | 7664 | @item packed |
d77de738 ML |
7665 | The @code{packed} attribute specifies that a structure member should have |
7666 | the smallest possible alignment---one bit for a bit-field and one byte | |
7667 | otherwise, unless a larger value is specified with the @code{aligned} | |
7668 | attribute. The attribute does not apply to non-member objects. | |
7669 | ||
7670 | For example in the structure below, the member array @code{x} is packed | |
7671 | so that it immediately follows @code{a} with no intervening padding: | |
7672 | ||
7673 | @smallexample | |
7674 | struct foo | |
7675 | @{ | |
7676 | char a; | |
7677 | int x[2] __attribute__ ((packed)); | |
7678 | @}; | |
7679 | @end smallexample | |
7680 | ||
7681 | @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the | |
7682 | @code{packed} attribute on bit-fields of type @code{char}. This has | |
7683 | been fixed in GCC 4.4 but the change can lead to differences in the | |
7684 | structure layout. See the documentation of | |
7685 | @option{-Wpacked-bitfield-compat} for more information. | |
7686 | ||
d77de738 | 7687 | @cindex @code{section} variable attribute |
f33d7a88 | 7688 | @item section ("@var{section-name}") |
d77de738 ML |
7689 | Normally, the compiler places the objects it generates in sections like |
7690 | @code{data} and @code{bss}. Sometimes, however, you need additional sections, | |
7691 | or you need certain particular variables to appear in special sections, | |
7692 | for example to map to special hardware. The @code{section} | |
7693 | attribute specifies that a variable (or function) lives in a particular | |
7694 | section. For example, this small program uses several specific section names: | |
7695 | ||
7696 | @smallexample | |
7697 | struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; | |
7698 | struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; | |
7699 | char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; | |
7700 | int init_data __attribute__ ((section ("INITDATA"))); | |
7701 | ||
7702 | main() | |
7703 | @{ | |
7704 | /* @r{Initialize stack pointer} */ | |
7705 | init_sp (stack + sizeof (stack)); | |
7706 | ||
7707 | /* @r{Initialize initialized data} */ | |
7708 | memcpy (&init_data, &data, &edata - &data); | |
7709 | ||
7710 | /* @r{Turn on the serial ports} */ | |
7711 | init_duart (&a); | |
7712 | init_duart (&b); | |
7713 | @} | |
7714 | @end smallexample | |
7715 | ||
7716 | @noindent | |
7717 | Use the @code{section} attribute with | |
7718 | @emph{global} variables and not @emph{local} variables, | |
7719 | as shown in the example. | |
7720 | ||
7721 | You may use the @code{section} attribute with initialized or | |
7722 | uninitialized global variables but the linker requires | |
7723 | each object be defined once, with the exception that uninitialized | |
7724 | variables tentatively go in the @code{common} (or @code{bss}) section | |
7725 | and can be multiply ``defined''. Using the @code{section} attribute | |
7726 | changes what section the variable goes into and may cause the | |
7727 | linker to issue an error if an uninitialized variable has multiple | |
7728 | definitions. You can force a variable to be initialized with the | |
7729 | @option{-fno-common} flag or the @code{nocommon} attribute. | |
7730 | ||
7731 | Some file formats do not support arbitrary sections so the @code{section} | |
7732 | attribute is not available on all platforms. | |
7733 | If you need to map the entire contents of a module to a particular | |
7734 | section, consider using the facilities of the linker instead. | |
7735 | ||
d77de738 | 7736 | @cindex @code{tls_model} variable attribute |
f33d7a88 | 7737 | @item tls_model ("@var{tls_model}") |
d77de738 ML |
7738 | The @code{tls_model} attribute sets thread-local storage model |
7739 | (@pxref{Thread-Local}) of a particular @code{__thread} variable, | |
7740 | overriding @option{-ftls-model=} command-line switch on a per-variable | |
7741 | basis. | |
7742 | The @var{tls_model} argument should be one of @code{global-dynamic}, | |
7743 | @code{local-dynamic}, @code{initial-exec} or @code{local-exec}. | |
7744 | ||
7745 | Not all targets support this attribute. | |
7746 | ||
d77de738 | 7747 | @cindex @code{unused} variable attribute |
f33d7a88 | 7748 | @item unused |
d77de738 ML |
7749 | This attribute, attached to a variable or structure field, means that |
7750 | the variable or field is meant to be possibly unused. GCC does not | |
7751 | produce a warning for this variable or field. | |
7752 | ||
d77de738 | 7753 | @cindex @code{used} variable attribute |
f33d7a88 | 7754 | @item used |
d77de738 ML |
7755 | This attribute, attached to a variable with static storage, means that |
7756 | the variable must be emitted even if it appears that the variable is not | |
7757 | referenced. | |
7758 | ||
7759 | When applied to a static data member of a C++ class template, the | |
7760 | attribute also means that the member is instantiated if the | |
7761 | class itself is instantiated. | |
7762 | ||
d77de738 | 7763 | @cindex @code{retain} variable attribute |
f33d7a88 | 7764 | @item retain |
d77de738 ML |
7765 | For ELF targets that support the GNU or FreeBSD OSABIs, this attribute |
7766 | will save the variable from linker garbage collection. To support | |
7767 | this behavior, variables that have not been placed in specific sections | |
7768 | (e.g. by the @code{section} attribute, or the @code{-fdata-sections} option), | |
7769 | will be placed in new, unique sections. | |
7770 | ||
7771 | This additional functionality requires Binutils version 2.36 or later. | |
7772 | ||
d77de738 | 7773 | @cindex @code{uninitialized} variable attribute |
f33d7a88 | 7774 | @item uninitialized |
d77de738 ML |
7775 | This attribute, attached to a variable with automatic storage, means that |
7776 | the variable should not be automatically initialized by the compiler when | |
7777 | the option @code{-ftrivial-auto-var-init} presents. | |
7778 | ||
7779 | With the option @code{-ftrivial-auto-var-init}, all the automatic variables | |
7780 | that do not have explicit initializers will be initialized by the compiler. | |
7781 | These additional compiler initializations might incur run-time overhead, | |
7782 | sometimes dramatically. This attribute can be used to mark some variables | |
7783 | to be excluded from such automatical initialization in order to reduce runtime | |
7784 | overhead. | |
7785 | ||
7786 | This attribute has no effect when the option @code{-ftrivial-auto-var-init} | |
7787 | does not present. | |
7788 | ||
d77de738 | 7789 | @cindex @code{vector_size} variable attribute |
f33d7a88 | 7790 | @item vector_size (@var{bytes}) |
d77de738 ML |
7791 | This attribute specifies the vector size for the type of the declared |
7792 | variable, measured in bytes. The type to which it applies is known as | |
7793 | the @dfn{base type}. The @var{bytes} argument must be a positive | |
7794 | power-of-two multiple of the base type size. For example, the declaration: | |
7795 | ||
7796 | @smallexample | |
7797 | int foo __attribute__ ((vector_size (16))); | |
7798 | @end smallexample | |
7799 | ||
7800 | @noindent | |
7801 | causes the compiler to set the mode for @code{foo}, to be 16 bytes, | |
7802 | divided into @code{int} sized units. Assuming a 32-bit @code{int}, | |
7803 | @code{foo}'s type is a vector of four units of four bytes each, and | |
7804 | the corresponding mode of @code{foo} is @code{V4SI}. | |
7805 | @xref{Vector Extensions}, for details of manipulating vector variables. | |
7806 | ||
7807 | This attribute is only applicable to integral and floating scalars, | |
7808 | although arrays, pointers, and function return values are allowed in | |
7809 | conjunction with this construct. | |
7810 | ||
7811 | Aggregates with this attribute are invalid, even if they are of the same | |
7812 | size as a corresponding scalar. For example, the declaration: | |
7813 | ||
7814 | @smallexample | |
7815 | struct S @{ int a; @}; | |
7816 | struct S __attribute__ ((vector_size (16))) foo; | |
7817 | @end smallexample | |
7818 | ||
7819 | @noindent | |
7820 | is invalid even if the size of the structure is the same as the size of | |
7821 | the @code{int}. | |
7822 | ||
d77de738 | 7823 | @cindex @code{visibility} variable attribute |
f33d7a88 | 7824 | @item visibility ("@var{visibility_type}") |
d77de738 ML |
7825 | This attribute affects the linkage of the declaration to which it is attached. |
7826 | The @code{visibility} attribute is described in | |
7827 | @ref{Common Function Attributes}. | |
7828 | ||
d77de738 | 7829 | @cindex @code{weak} variable attribute |
f33d7a88 | 7830 | @item weak |
d77de738 ML |
7831 | The @code{weak} attribute is described in |
7832 | @ref{Common Function Attributes}. | |
7833 | ||
d77de738 | 7834 | @cindex @code{noinit} variable attribute |
f33d7a88 | 7835 | @item noinit |
d77de738 ML |
7836 | Any data with the @code{noinit} attribute will not be initialized by |
7837 | the C runtime startup code, or the program loader. Not initializing | |
7838 | data in this way can reduce program startup times. | |
7839 | ||
7840 | This attribute is specific to ELF targets and relies on the linker | |
7841 | script to place sections with the @code{.noinit} prefix in the right | |
7842 | location. | |
7843 | ||
d77de738 | 7844 | @cindex @code{persistent} variable attribute |
f33d7a88 | 7845 | @item persistent |
d77de738 ML |
7846 | Any data with the @code{persistent} attribute will not be initialized by |
7847 | the C runtime startup code, but will be initialized by the program | |
7848 | loader. This enables the value of the variable to @samp{persist} | |
7849 | between processor resets. | |
7850 | ||
7851 | This attribute is specific to ELF targets and relies on the linker | |
7852 | script to place the sections with the @code{.persistent} prefix in the | |
7853 | right location. Specifically, some type of non-volatile, writeable | |
7854 | memory is required. | |
7855 | ||
d77de738 | 7856 | @cindex @code{objc_nullability} variable attribute |
f33d7a88 | 7857 | @item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)} |
d77de738 ML |
7858 | This attribute applies to pointer variables only. It allows marking the |
7859 | pointer with one of four possible values describing the conditions under | |
7860 | which the pointer might have a @code{nil} value. In most cases, the | |
7861 | attribute is intended to be an internal representation for property and | |
7862 | method nullability (specified by language keywords); it is not recommended | |
7863 | to use it directly. | |
7864 | ||
7865 | When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is | |
7866 | known about the conditions in which the pointer might be @code{nil}. Making | |
7867 | this state specific serves to avoid false positives in diagnostics. | |
7868 | ||
7869 | When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has | |
7870 | no meaning if it is @code{nil} and thus the compiler is free to emit | |
7871 | diagnostics if it can be determined that the value will be @code{nil}. | |
7872 | ||
7873 | When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might | |
7874 | be @code{nil} and carry meaning as such. | |
7875 | ||
7876 | When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in | |
7877 | the context of property attribute lists) this describes the case in which a | |
7878 | property setter may take the value @code{nil} (which perhaps causes the | |
7879 | property to be reset in some manner to a default) but for which the property | |
7880 | getter will never validly return @code{nil}. | |
7881 | ||
7882 | @end table | |
7883 | ||
7884 | @node ARC Variable Attributes | |
7885 | @subsection ARC Variable Attributes | |
7886 | ||
7887 | @table @code | |
d77de738 | 7888 | @cindex @code{aux} variable attribute, ARC |
f33d7a88 | 7889 | @item aux |
d77de738 ML |
7890 | The @code{aux} attribute is used to directly access the ARC's |
7891 | auxiliary register space from C. The auxilirary register number is | |
7892 | given via attribute argument. | |
7893 | ||
7894 | @end table | |
7895 | ||
7896 | @node AVR Variable Attributes | |
7897 | @subsection AVR Variable Attributes | |
7898 | ||
7899 | @table @code | |
d77de738 | 7900 | @cindex @code{progmem} variable attribute, AVR |
f33d7a88 | 7901 | @item progmem |
d77de738 ML |
7902 | The @code{progmem} attribute is used on the AVR to place read-only |
7903 | data in the non-volatile program memory (flash). The @code{progmem} | |
7904 | attribute accomplishes this by putting respective variables into a | |
7905 | section whose name starts with @code{.progmem}. | |
7906 | ||
7907 | This attribute works similar to the @code{section} attribute | |
7908 | but adds additional checking. | |
7909 | ||
7910 | @table @asis | |
7911 | @item @bullet{} Ordinary AVR cores with 32 general purpose registers: | |
7912 | @code{progmem} affects the location | |
7913 | of the data but not how this data is accessed. | |
7914 | In order to read data located with the @code{progmem} attribute | |
7915 | (inline) assembler must be used. | |
7916 | @smallexample | |
1be72408 | 7917 | /* Use custom macros from AVR-LibC */ |
d77de738 ML |
7918 | #include <avr/pgmspace.h> |
7919 | ||
7920 | /* Locate var in flash memory */ | |
7921 | const int var[2] PROGMEM = @{ 1, 2 @}; | |
7922 | ||
7923 | int read_var (int i) | |
7924 | @{ | |
7925 | /* Access var[] by accessor macro from avr/pgmspace.h */ | |
7926 | return (int) pgm_read_word (& var[i]); | |
7927 | @} | |
7928 | @end smallexample | |
7929 | ||
7930 | AVR is a Harvard architecture processor and data and read-only data | |
7931 | normally resides in the data memory (RAM). | |
7932 | ||
7933 | See also the @ref{AVR Named Address Spaces} section for | |
7934 | an alternate way to locate and access data in flash memory. | |
7935 | ||
7936 | @item @bullet{} AVR cores with flash memory visible in the RAM address range: | |
7937 | On such devices, there is no need for attribute @code{progmem} or | |
7938 | @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all. | |
7939 | Just use standard C / C++. The compiler will generate @code{LD*} | |
7940 | instructions. As flash memory is visible in the RAM address range, | |
7941 | and the default linker script does @emph{not} locate @code{.rodata} in | |
7942 | RAM, no special features are needed in order not to waste RAM for | |
7943 | read-only data or to read from flash. You might even get slightly better | |
7944 | performance by | |
7945 | avoiding @code{progmem} and @code{__flash}. This applies to devices from | |
7946 | families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for | |
7947 | an overview. | |
7948 | ||
7949 | @item @bullet{} Reduced AVR Tiny cores like ATtiny40: | |
7950 | The compiler adds @code{0x4000} | |
7951 | to the addresses of objects and declarations in @code{progmem} and locates | |
7952 | the objects in flash memory, namely in section @code{.progmem.data}. | |
7953 | The offset is needed because the flash memory is visible in the RAM | |
7954 | address space starting at address @code{0x4000}. | |
7955 | ||
7956 | Data in @code{progmem} can be accessed by means of ordinary C@tie{}code, | |
7957 | no special functions or macros are needed. | |
7958 | ||
7959 | @smallexample | |
7960 | /* var is located in flash memory */ | |
7961 | extern const int var[2] __attribute__((progmem)); | |
7962 | ||
7963 | int read_var (int i) | |
7964 | @{ | |
7965 | return var[i]; | |
7966 | @} | |
7967 | @end smallexample | |
7968 | ||
7969 | Please notice that on these devices, there is no need for @code{progmem} | |
7970 | at all. | |
7971 | ||
7972 | @end table | |
7973 | ||
f33d7a88 | 7974 | @cindex @code{io} variable attribute, AVR |
d77de738 ML |
7975 | @item io |
7976 | @itemx io (@var{addr}) | |
d77de738 ML |
7977 | Variables with the @code{io} attribute are used to address |
7978 | memory-mapped peripherals in the io address range. | |
7979 | If an address is specified, the variable | |
7980 | is assigned that address, and the value is interpreted as an | |
7981 | address in the data address space. | |
7982 | Example: | |
7983 | ||
7984 | @smallexample | |
7985 | volatile int porta __attribute__((io (0x22))); | |
7986 | @end smallexample | |
7987 | ||
7988 | The address specified in the address in the data address range. | |
7989 | ||
7990 | Otherwise, the variable it is not assigned an address, but the | |
7991 | compiler will still use in/out instructions where applicable, | |
7992 | assuming some other module assigns an address in the io address range. | |
7993 | Example: | |
7994 | ||
7995 | @smallexample | |
7996 | extern volatile int porta __attribute__((io)); | |
7997 | @end smallexample | |
7998 | ||
f33d7a88 | 7999 | @cindex @code{io_low} variable attribute, AVR |
d77de738 ML |
8000 | @item io_low |
8001 | @itemx io_low (@var{addr}) | |
d77de738 ML |
8002 | This is like the @code{io} attribute, but additionally it informs the |
8003 | compiler that the object lies in the lower half of the I/O area, | |
8004 | allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} | |
8005 | instructions. | |
8006 | ||
f33d7a88 | 8007 | @cindex @code{address} variable attribute, AVR |
d77de738 ML |
8008 | @item address |
8009 | @itemx address (@var{addr}) | |
d77de738 ML |
8010 | Variables with the @code{address} attribute are used to address |
8011 | memory-mapped peripherals that may lie outside the io address range. | |
8012 | ||
8013 | @smallexample | |
8014 | volatile int porta __attribute__((address (0x600))); | |
8015 | @end smallexample | |
8016 | ||
d77de738 | 8017 | @cindex @code{absdata} variable attribute, AVR |
f33d7a88 | 8018 | @item absdata |
d77de738 ML |
8019 | Variables in static storage and with the @code{absdata} attribute can |
8020 | be accessed by the @code{LDS} and @code{STS} instructions which take | |
8021 | absolute addresses. | |
8022 | ||
8023 | @itemize @bullet | |
8024 | @item | |
8025 | This attribute is only supported for the reduced AVR Tiny core | |
8026 | like ATtiny40. | |
8027 | ||
8028 | @item | |
8029 | You must make sure that respective data is located in the | |
8030 | address range @code{0x40}@dots{}@code{0xbf} accessible by | |
8031 | @code{LDS} and @code{STS}. One way to achieve this as an | |
8032 | appropriate linker description file. | |
8033 | ||
8034 | @item | |
8035 | If the location does not fit the address range of @code{LDS} | |
8036 | and @code{STS}, there is currently (Binutils 2.26) just an unspecific | |
8037 | warning like | |
8038 | @quotation | |
8039 | @code{module.cc:(.text+0x1c): warning: internal error: out of range error} | |
8040 | @end quotation | |
8041 | ||
8042 | @end itemize | |
8043 | ||
8044 | See also the @option{-mabsdata} @ref{AVR Options,command-line option}. | |
8045 | ||
8046 | @end table | |
8047 | ||
8048 | @node Blackfin Variable Attributes | |
8049 | @subsection Blackfin Variable Attributes | |
8050 | ||
8051 | Three attributes are currently defined for the Blackfin. | |
8052 | ||
8053 | @table @code | |
d77de738 ML |
8054 | @cindex @code{l1_data} variable attribute, Blackfin |
8055 | @cindex @code{l1_data_A} variable attribute, Blackfin | |
8056 | @cindex @code{l1_data_B} variable attribute, Blackfin | |
f33d7a88 AA |
8057 | @item l1_data |
8058 | @itemx l1_data_A | |
8059 | @itemx l1_data_B | |
d77de738 ML |
8060 | Use these attributes on the Blackfin to place the variable into L1 Data SRAM. |
8061 | Variables with @code{l1_data} attribute are put into the specific section | |
8062 | named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into | |
8063 | the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} | |
8064 | attribute are put into the specific section named @code{.l1.data.B}. | |
8065 | ||
d77de738 | 8066 | @cindex @code{l2} variable attribute, Blackfin |
f33d7a88 | 8067 | @item l2 |
d77de738 ML |
8068 | Use this attribute on the Blackfin to place the variable into L2 SRAM. |
8069 | Variables with @code{l2} attribute are put into the specific section | |
8070 | named @code{.l2.data}. | |
8071 | @end table | |
8072 | ||
8073 | @node H8/300 Variable Attributes | |
8074 | @subsection H8/300 Variable Attributes | |
8075 | ||
8076 | These variable attributes are available for H8/300 targets: | |
8077 | ||
8078 | @table @code | |
d77de738 ML |
8079 | @cindex @code{eightbit_data} variable attribute, H8/300 |
8080 | @cindex eight-bit data on the H8/300, H8/300H, and H8S | |
f33d7a88 | 8081 | @item eightbit_data |
d77de738 ML |
8082 | Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified |
8083 | variable should be placed into the eight-bit data section. | |
8084 | The compiler generates more efficient code for certain operations | |
8085 | on data in the eight-bit data area. Note the eight-bit data area is limited to | |
8086 | 256 bytes of data. | |
8087 | ||
8088 | You must use GAS and GLD from GNU binutils version 2.7 or later for | |
8089 | this attribute to work correctly. | |
8090 | ||
d77de738 ML |
8091 | @cindex @code{tiny_data} variable attribute, H8/300 |
8092 | @cindex tiny data section on the H8/300H and H8S | |
f33d7a88 | 8093 | @item tiny_data |
d77de738 ML |
8094 | Use this attribute on the H8/300H and H8S to indicate that the specified |
8095 | variable should be placed into the tiny data section. | |
8096 | The compiler generates more efficient code for loads and stores | |
8097 | on data in the tiny data section. Note the tiny data area is limited to | |
8098 | slightly under 32KB of data. | |
8099 | ||
8100 | @end table | |
8101 | ||
8102 | @node IA-64 Variable Attributes | |
8103 | @subsection IA-64 Variable Attributes | |
8104 | ||
8105 | The IA-64 back end supports the following variable attribute: | |
8106 | ||
8107 | @table @code | |
d77de738 | 8108 | @cindex @code{model} variable attribute, IA-64 |
f33d7a88 | 8109 | @item model (@var{model-name}) |
d77de738 ML |
8110 | |
8111 | On IA-64, use this attribute to set the addressability of an object. | |
8112 | At present, the only supported identifier for @var{model-name} is | |
8113 | @code{small}, indicating addressability via ``small'' (22-bit) | |
8114 | addresses (so that their addresses can be loaded with the @code{addl} | |
8115 | instruction). Caveat: such addressing is by definition not position | |
8116 | independent and hence this attribute must not be used for objects | |
8117 | defined by shared libraries. | |
8118 | ||
8119 | @end table | |
8120 | ||
8121 | @node LoongArch Variable Attributes | |
8122 | @subsection LoongArch Variable Attributes | |
8123 | ||
8124 | One attribute is currently defined for the LoongArch. | |
8125 | ||
8126 | @table @code | |
d77de738 | 8127 | @cindex @code{model} variable attribute, LoongArch |
f33d7a88 | 8128 | @item model("@var{name}") |
d77de738 ML |
8129 | Use this attribute on the LoongArch to use a different code model for |
8130 | addressing this variable, than the code model specified by the global | |
8131 | @option{-mcmodel} option. This attribute is mostly useful if a | |
8132 | @code{section} attribute and/or a linker script will locate this object | |
8133 | specially. Currently the only supported values of @var{name} are | |
8134 | @code{normal} and @code{extreme}. | |
8135 | @end table | |
8136 | ||
8137 | @node M32R/D Variable Attributes | |
8138 | @subsection M32R/D Variable Attributes | |
8139 | ||
8140 | One attribute is currently defined for the M32R/D@. | |
8141 | ||
8142 | @table @code | |
d77de738 ML |
8143 | @cindex @code{model-name} variable attribute, M32R/D |
8144 | @cindex variable addressability on the M32R/D | |
f33d7a88 | 8145 | @item model (@var{model-name}) |
d77de738 ML |
8146 | Use this attribute on the M32R/D to set the addressability of an object. |
8147 | The identifier @var{model-name} is one of @code{small}, @code{medium}, | |
8148 | or @code{large}, representing each of the code models. | |
8149 | ||
8150 | Small model objects live in the lower 16MB of memory (so that their | |
8151 | addresses can be loaded with the @code{ld24} instruction). | |
8152 | ||
8153 | Medium and large model objects may live anywhere in the 32-bit address space | |
8154 | (the compiler generates @code{seth/add3} instructions to load their | |
8155 | addresses). | |
8156 | @end table | |
8157 | ||
d77de738 ML |
8158 | @node Microsoft Windows Variable Attributes |
8159 | @subsection Microsoft Windows Variable Attributes | |
8160 | ||
8161 | You can use these attributes on Microsoft Windows targets. | |
8162 | @ref{x86 Variable Attributes} for additional Windows compatibility | |
8163 | attributes available on all x86 targets. | |
8164 | ||
8165 | @table @code | |
d77de738 ML |
8166 | @cindex @code{dllimport} variable attribute |
8167 | @cindex @code{dllexport} variable attribute | |
f33d7a88 AA |
8168 | @item dllimport |
8169 | @itemx dllexport | |
d77de738 ML |
8170 | The @code{dllimport} and @code{dllexport} attributes are described in |
8171 | @ref{Microsoft Windows Function Attributes}. | |
8172 | ||
d77de738 | 8173 | @cindex @code{selectany} variable attribute |
f33d7a88 | 8174 | @item selectany |
d77de738 ML |
8175 | The @code{selectany} attribute causes an initialized global variable to |
8176 | have link-once semantics. When multiple definitions of the variable are | |
8177 | encountered by the linker, the first is selected and the remainder are | |
8178 | discarded. Following usage by the Microsoft compiler, the linker is told | |
8179 | @emph{not} to warn about size or content differences of the multiple | |
8180 | definitions. | |
8181 | ||
8182 | Although the primary usage of this attribute is for POD types, the | |
8183 | attribute can also be applied to global C++ objects that are initialized | |
8184 | by a constructor. In this case, the static initialization and destruction | |
8185 | code for the object is emitted in each translation defining the object, | |
8186 | but the calls to the constructor and destructor are protected by a | |
8187 | link-once guard variable. | |
8188 | ||
8189 | The @code{selectany} attribute is only available on Microsoft Windows | |
8190 | targets. You can use @code{__declspec (selectany)} as a synonym for | |
8191 | @code{__attribute__ ((selectany))} for compatibility with other | |
8192 | compilers. | |
8193 | ||
d77de738 | 8194 | @cindex @code{shared} variable attribute |
f33d7a88 | 8195 | @item shared |
d77de738 ML |
8196 | On Microsoft Windows, in addition to putting variable definitions in a named |
8197 | section, the section can also be shared among all running copies of an | |
8198 | executable or DLL@. For example, this small program defines shared data | |
8199 | by putting it in a named section @code{shared} and marking the section | |
8200 | shareable: | |
8201 | ||
8202 | @smallexample | |
8203 | int foo __attribute__((section ("shared"), shared)) = 0; | |
8204 | ||
8205 | int | |
8206 | main() | |
8207 | @{ | |
8208 | /* @r{Read and write foo. All running | |
8209 | copies see the same value.} */ | |
8210 | return 0; | |
8211 | @} | |
8212 | @end smallexample | |
8213 | ||
8214 | @noindent | |
8215 | You may only use the @code{shared} attribute along with @code{section} | |
8216 | attribute with a fully-initialized global definition because of the way | |
8217 | linkers work. See @code{section} attribute for more information. | |
8218 | ||
8219 | The @code{shared} attribute is only available on Microsoft Windows@. | |
8220 | ||
8221 | @end table | |
8222 | ||
8223 | @node MSP430 Variable Attributes | |
8224 | @subsection MSP430 Variable Attributes | |
8225 | ||
8226 | @table @code | |
d77de738 ML |
8227 | @cindex @code{upper} variable attribute, MSP430 |
8228 | @cindex @code{either} variable attribute, MSP430 | |
f33d7a88 AA |
8229 | @item upper |
8230 | @itemx either | |
d77de738 ML |
8231 | These attributes are the same as the MSP430 function attributes of the |
8232 | same name (@pxref{MSP430 Function Attributes}). | |
8233 | ||
d77de738 | 8234 | @cindex @code{lower} variable attribute, MSP430 |
f33d7a88 | 8235 | @item lower |
d77de738 ML |
8236 | This option behaves mostly the same as the MSP430 function attribute of the |
8237 | same name (@pxref{MSP430 Function Attributes}), but it has some additional | |
8238 | functionality. | |
8239 | ||
8240 | If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or | |
8241 | the @code{section} attribute is applied to a variable, the compiler will | |
8242 | generate 430X instructions to handle it. This is because the compiler has | |
8243 | to assume that the variable could get placed in the upper memory region | |
8244 | (above address 0xFFFF). Marking the variable with the @code{lower} attribute | |
8245 | informs the compiler that the variable will be placed in lower memory so it | |
8246 | is safe to use 430 instructions to handle it. | |
8247 | ||
8248 | In the case of the @code{section} attribute, the section name given | |
8249 | will be used, and the @code{.lower} prefix will not be added. | |
8250 | ||
8251 | @end table | |
8252 | ||
8253 | @node Nvidia PTX Variable Attributes | |
8254 | @subsection Nvidia PTX Variable Attributes | |
8255 | ||
8256 | These variable attributes are supported by the Nvidia PTX back end: | |
8257 | ||
8258 | @table @code | |
d77de738 | 8259 | @cindex @code{shared} attribute, Nvidia PTX |
f33d7a88 | 8260 | @item shared |
d77de738 ML |
8261 | Use this attribute to place a variable in the @code{.shared} memory space. |
8262 | This memory space is private to each cooperative thread array; only threads | |
8263 | within one thread block refer to the same instance of the variable. | |
8264 | The runtime does not initialize variables in this memory space. | |
8265 | @end table | |
8266 | ||
8267 | @node PowerPC Variable Attributes | |
8268 | @subsection PowerPC Variable Attributes | |
8269 | ||
8270 | Three attributes currently are defined for PowerPC configurations: | |
8271 | @code{altivec}, @code{ms_struct} and @code{gcc_struct}. | |
8272 | ||
8273 | @cindex @code{ms_struct} variable attribute, PowerPC | |
8274 | @cindex @code{gcc_struct} variable attribute, PowerPC | |
8275 | For full documentation of the struct attributes please see the | |
8276 | documentation in @ref{x86 Variable Attributes}. | |
8277 | ||
8278 | @cindex @code{altivec} variable attribute, PowerPC | |
8279 | For documentation of @code{altivec} attribute please see the | |
8280 | documentation in @ref{PowerPC Type Attributes}. | |
8281 | ||
8282 | @node RL78 Variable Attributes | |
8283 | @subsection RL78 Variable Attributes | |
8284 | ||
8285 | @cindex @code{saddr} variable attribute, RL78 | |
8286 | The RL78 back end supports the @code{saddr} variable attribute. This | |
8287 | specifies placement of the corresponding variable in the SADDR area, | |
8288 | which can be accessed more efficiently than the default memory region. | |
8289 | ||
8290 | @node V850 Variable Attributes | |
8291 | @subsection V850 Variable Attributes | |
8292 | ||
8293 | These variable attributes are supported by the V850 back end: | |
8294 | ||
8295 | @table @code | |
8296 | ||
d77de738 | 8297 | @cindex @code{sda} variable attribute, V850 |
f33d7a88 | 8298 | @item sda |
d77de738 ML |
8299 | Use this attribute to explicitly place a variable in the small data area, |
8300 | which can hold up to 64 kilobytes. | |
8301 | ||
d77de738 | 8302 | @cindex @code{tda} variable attribute, V850 |
f33d7a88 | 8303 | @item tda |
d77de738 ML |
8304 | Use this attribute to explicitly place a variable in the tiny data area, |
8305 | which can hold up to 256 bytes in total. | |
8306 | ||
d77de738 | 8307 | @cindex @code{zda} variable attribute, V850 |
f33d7a88 | 8308 | @item zda |
d77de738 ML |
8309 | Use this attribute to explicitly place a variable in the first 32 kilobytes |
8310 | of memory. | |
8311 | @end table | |
8312 | ||
8313 | @node x86 Variable Attributes | |
8314 | @subsection x86 Variable Attributes | |
8315 | ||
8316 | Two attributes are currently defined for x86 configurations: | |
8317 | @code{ms_struct} and @code{gcc_struct}. | |
8318 | ||
8319 | @table @code | |
d77de738 ML |
8320 | @cindex @code{ms_struct} variable attribute, x86 |
8321 | @cindex @code{gcc_struct} variable attribute, x86 | |
f33d7a88 AA |
8322 | @item ms_struct |
8323 | @itemx gcc_struct | |
d77de738 ML |
8324 | |
8325 | If @code{packed} is used on a structure, or if bit-fields are used, | |
8326 | it may be that the Microsoft ABI lays out the structure differently | |
8327 | than the way GCC normally does. Particularly when moving packed | |
8328 | data between functions compiled with GCC and the native Microsoft compiler | |
8329 | (either via function call or as data in a file), it may be necessary to access | |
8330 | either format. | |
8331 | ||
8332 | The @code{ms_struct} and @code{gcc_struct} attributes correspond | |
8333 | to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} | |
8334 | command-line options, respectively; | |
8335 | see @ref{x86 Options}, for details of how structure layout is affected. | |
8336 | @xref{x86 Type Attributes}, for information about the corresponding | |
8337 | attributes on types. | |
8338 | ||
8339 | @end table | |
8340 | ||
8341 | @node Xstormy16 Variable Attributes | |
8342 | @subsection Xstormy16 Variable Attributes | |
8343 | ||
8344 | One attribute is currently defined for xstormy16 configurations: | |
8345 | @code{below100}. | |
8346 | ||
8347 | @table @code | |
d77de738 | 8348 | @cindex @code{below100} variable attribute, Xstormy16 |
f33d7a88 | 8349 | @item below100 |
d77de738 ML |
8350 | |
8351 | If a variable has the @code{below100} attribute (@code{BELOW100} is | |
8352 | allowed also), GCC places the variable in the first 0x100 bytes of | |
8353 | memory and use special opcodes to access it. Such variables are | |
8354 | placed in either the @code{.bss_below100} section or the | |
8355 | @code{.data_below100} section. | |
8356 | ||
8357 | @end table | |
8358 | ||
8359 | @node Type Attributes | |
8360 | @section Specifying Attributes of Types | |
8361 | @cindex attribute of types | |
8362 | @cindex type attributes | |
8363 | ||
8364 | The keyword @code{__attribute__} allows you to specify various special | |
8365 | properties of types. Some type attributes apply only to structure and | |
8366 | union types, and in C++, also class types, while others can apply to | |
8367 | any type defined via a @code{typedef} declaration. Unless otherwise | |
8368 | specified, the same restrictions and effects apply to attributes regardless | |
8369 | of whether a type is a trivial structure or a C++ class with user-defined | |
8370 | constructors, destructors, or a copy assignment. | |
8371 | ||
8372 | Other attributes are defined for functions (@pxref{Function Attributes}), | |
8373 | labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator | |
8374 | Attributes}), statements (@pxref{Statement Attributes}), and for variables | |
8375 | (@pxref{Variable Attributes}). | |
8376 | ||
8377 | The @code{__attribute__} keyword is followed by an attribute specification | |
8378 | enclosed in double parentheses. | |
8379 | ||
8380 | You may specify type attributes in an enum, struct or union type | |
8381 | declaration or definition by placing them immediately after the | |
8382 | @code{struct}, @code{union} or @code{enum} keyword. You can also place | |
8383 | them just past the closing curly brace of the definition, but this is less | |
8384 | preferred because logically the type should be fully defined at | |
8385 | the closing brace. | |
8386 | ||
8387 | You can also include type attributes in a @code{typedef} declaration. | |
8388 | @xref{Attribute Syntax}, for details of the exact syntax for using | |
8389 | attributes. | |
8390 | ||
8391 | @menu | |
8392 | * Common Type Attributes:: | |
8393 | * ARC Type Attributes:: | |
8394 | * ARM Type Attributes:: | |
8395 | * BPF Type Attributes:: | |
d77de738 ML |
8396 | * PowerPC Type Attributes:: |
8397 | * x86 Type Attributes:: | |
8398 | @end menu | |
8399 | ||
8400 | @node Common Type Attributes | |
8401 | @subsection Common Type Attributes | |
8402 | ||
8403 | The following type attributes are supported on most targets. | |
8404 | ||
8405 | @table @code | |
8406 | @cindex @code{aligned} type attribute | |
8407 | @item aligned | |
8408 | @itemx aligned (@var{alignment}) | |
8409 | The @code{aligned} attribute specifies a minimum alignment (in bytes) for | |
8410 | variables of the specified type. When specified, @var{alignment} must be | |
8411 | a power of 2. Specifying no @var{alignment} argument implies the maximum | |
8412 | alignment for the target, which is often, but by no means always, 8 or 16 | |
8413 | bytes. For example, the declarations: | |
8414 | ||
8415 | @smallexample | |
8416 | struct __attribute__ ((aligned (8))) S @{ short f[3]; @}; | |
8417 | typedef int more_aligned_int __attribute__ ((aligned (8))); | |
8418 | @end smallexample | |
8419 | ||
8420 | @noindent | |
8421 | force the compiler to ensure (as far as it can) that each variable whose | |
8422 | type is @code{struct S} or @code{more_aligned_int} is allocated and | |
8423 | aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all | |
8424 | variables of type @code{struct S} aligned to 8-byte boundaries allows | |
8425 | the compiler to use the @code{ldd} and @code{std} (doubleword load and | |
8426 | store) instructions when copying one variable of type @code{struct S} to | |
8427 | another, thus improving run-time efficiency. | |
8428 | ||
8429 | Note that the alignment of any given @code{struct} or @code{union} type | |
8430 | is required by the ISO C standard to be at least a perfect multiple of | |
8431 | the lowest common multiple of the alignments of all of the members of | |
8432 | the @code{struct} or @code{union} in question. This means that you @emph{can} | |
8433 | effectively adjust the alignment of a @code{struct} or @code{union} | |
8434 | type by attaching an @code{aligned} attribute to any one of the members | |
8435 | of such a type, but the notation illustrated in the example above is a | |
8436 | more obvious, intuitive, and readable way to request the compiler to | |
8437 | adjust the alignment of an entire @code{struct} or @code{union} type. | |
8438 | ||
8439 | As in the preceding example, you can explicitly specify the alignment | |
8440 | (in bytes) that you wish the compiler to use for a given @code{struct} | |
8441 | or @code{union} type. Alternatively, you can leave out the alignment factor | |
8442 | and just ask the compiler to align a type to the maximum | |
8443 | useful alignment for the target machine you are compiling for. For | |
8444 | example, you could write: | |
8445 | ||
8446 | @smallexample | |
8447 | struct __attribute__ ((aligned)) S @{ short f[3]; @}; | |
8448 | @end smallexample | |
8449 | ||
8450 | Whenever you leave out the alignment factor in an @code{aligned} | |
8451 | attribute specification, the compiler automatically sets the alignment | |
8452 | for the type to the largest alignment that is ever used for any data | |
8453 | type on the target machine you are compiling for. Doing this can often | |
8454 | make copy operations more efficient, because the compiler can use | |
8455 | whatever instructions copy the biggest chunks of memory when performing | |
8456 | copies to or from the variables that have types that you have aligned | |
8457 | this way. | |
8458 | ||
8459 | In the example above, if the size of each @code{short} is 2 bytes, then | |
8460 | the size of the entire @code{struct S} type is 6 bytes. The smallest | |
8461 | power of two that is greater than or equal to that is 8, so the | |
8462 | compiler sets the alignment for the entire @code{struct S} type to 8 | |
8463 | bytes. | |
8464 | ||
8465 | Note that although you can ask the compiler to select a time-efficient | |
8466 | alignment for a given type and then declare only individual stand-alone | |
8467 | objects of that type, the compiler's ability to select a time-efficient | |
8468 | alignment is primarily useful only when you plan to create arrays of | |
8469 | variables having the relevant (efficiently aligned) type. If you | |
8470 | declare or use arrays of variables of an efficiently-aligned type, then | |
8471 | it is likely that your program also does pointer arithmetic (or | |
8472 | subscripting, which amounts to the same thing) on pointers to the | |
8473 | relevant type, and the code that the compiler generates for these | |
8474 | pointer arithmetic operations is often more efficient for | |
8475 | efficiently-aligned types than for other types. | |
8476 | ||
8477 | Note that the effectiveness of @code{aligned} attributes may be limited | |
8478 | by inherent limitations in your linker. On many systems, the linker is | |
8479 | only able to arrange for variables to be aligned up to a certain maximum | |
8480 | alignment. (For some linkers, the maximum supported alignment may | |
8481 | be very very small.) If your linker is only able to align variables | |
8482 | up to a maximum of 8-byte alignment, then specifying @code{aligned (16)} | |
8483 | in an @code{__attribute__} still only provides you with 8-byte | |
8484 | alignment. See your linker documentation for further information. | |
8485 | ||
8486 | When used on a struct, or struct member, the @code{aligned} attribute can | |
8487 | only increase the alignment; in order to decrease it, the @code{packed} | |
8488 | attribute must be specified as well. When used as part of a typedef, the | |
8489 | @code{aligned} attribute can both increase and decrease alignment, and | |
8490 | specifying the @code{packed} attribute generates a warning. | |
8491 | ||
8492 | @cindex @code{warn_if_not_aligned} type attribute | |
8493 | @item warn_if_not_aligned (@var{alignment}) | |
8494 | This attribute specifies a threshold for the structure field, measured | |
8495 | in bytes. If the structure field is aligned below the threshold, a | |
8496 | warning will be issued. For example, the declaration: | |
8497 | ||
8498 | @smallexample | |
8499 | typedef unsigned long long __u64 | |
8500 | __attribute__((aligned (4), warn_if_not_aligned (8))); | |
8501 | ||
8502 | struct foo | |
8503 | @{ | |
8504 | int i1; | |
8505 | int i2; | |
8506 | __u64 x; | |
8507 | @}; | |
8508 | @end smallexample | |
8509 | ||
8510 | @noindent | |
8511 | causes the compiler to issue an warning on @code{struct foo}, like | |
8512 | @samp{warning: alignment 4 of 'struct foo' is less than 8}. | |
8513 | It is used to define @code{struct foo} in such a way that | |
8514 | @code{struct foo} has the same layout and the structure field @code{x} | |
8515 | has the same alignment when @code{__u64} is aligned at either 4 or | |
8516 | 8 bytes. Align @code{struct foo} to 8 bytes: | |
8517 | ||
8518 | @smallexample | |
8519 | struct __attribute__ ((aligned (8))) foo | |
8520 | @{ | |
8521 | int i1; | |
8522 | int i2; | |
8523 | __u64 x; | |
8524 | @}; | |
8525 | @end smallexample | |
8526 | ||
8527 | @noindent | |
8528 | silences the warning. The compiler also issues a warning, like | |
8529 | @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8}, | |
8530 | when the structure field has the misaligned offset: | |
8531 | ||
8532 | @smallexample | |
8533 | struct __attribute__ ((aligned (8))) foo | |
8534 | @{ | |
8535 | int i1; | |
8536 | int i2; | |
8537 | int i3; | |
8538 | __u64 x; | |
8539 | @}; | |
8540 | @end smallexample | |
8541 | ||
8542 | This warning can be disabled by @option{-Wno-if-not-aligned}. | |
8543 | ||
f33d7a88 | 8544 | @cindex @code{alloc_size} type attribute |
d77de738 ML |
8545 | @item alloc_size (@var{position}) |
8546 | @itemx alloc_size (@var{position-1}, @var{position-2}) | |
d77de738 ML |
8547 | The @code{alloc_size} type attribute may be applied to the definition |
8548 | of a type of a function that returns a pointer and takes at least one | |
8549 | argument of an integer type. It indicates that the returned pointer | |
8550 | points to an object whose size is given by the function argument at | |
8551 | @var{position-1}, or by the product of the arguments at @var{position-1} | |
8552 | and @var{position-2}. Meaningful sizes are positive values less than | |
8553 | @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses | |
8554 | this information to improve the results of @code{__builtin_object_size}. | |
8555 | ||
8556 | For instance, the following declarations | |
8557 | ||
8558 | @smallexample | |
8559 | typedef __attribute__ ((alloc_size (1, 2))) void* | |
8560 | calloc_type (size_t, size_t); | |
8561 | typedef __attribute__ ((alloc_size (1))) void* | |
8562 | malloc_type (size_t); | |
8563 | @end smallexample | |
8564 | ||
8565 | @noindent | |
8566 | specify that @code{calloc_type} is a type of a function that, like | |
8567 | the standard C function @code{calloc}, returns an object whose size | |
8568 | is given by the product of arguments 1 and 2, and that | |
8569 | @code{malloc_type}, like the standard C function @code{malloc}, | |
8570 | returns an object whose size is given by argument 1 to the function. | |
8571 | ||
f33d7a88 | 8572 | @cindex @code{copy} type attribute |
d77de738 ML |
8573 | @item copy |
8574 | @itemx copy (@var{expression}) | |
d77de738 ML |
8575 | The @code{copy} attribute applies the set of attributes with which |
8576 | the type of the @var{expression} has been declared to the declaration | |
8577 | of the type to which the attribute is applied. The attribute is | |
8578 | designed for libraries that define aliases that are expected to | |
8579 | specify the same set of attributes as the aliased symbols. | |
8580 | The @code{copy} attribute can be used with types, variables, or | |
8581 | functions. However, the kind of symbol to which the attribute is | |
8582 | applied (either varible or function) must match the kind of symbol | |
8583 | to which the argument refers. | |
8584 | The @code{copy} attribute copies only syntactic and semantic attributes | |
8585 | but not attributes that affect a symbol's linkage or visibility such as | |
8586 | @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} | |
8587 | attribute is also not copied. @xref{Common Function Attributes}. | |
8588 | @xref{Common Variable Attributes}. | |
8589 | ||
8590 | For example, suppose @code{struct A} below is defined in some third | |
8591 | party library header to have the alignment requirement @code{N} and | |
8592 | to force a warning whenever a variable of the type is not so aligned | |
8593 | due to attribute @code{packed}. Specifying the @code{copy} attribute | |
8594 | on the definition on the unrelated @code{struct B} has the effect of | |
8595 | copying all relevant attributes from the type referenced by the pointer | |
8596 | expression to @code{struct B}. | |
8597 | ||
8598 | @smallexample | |
8599 | struct __attribute__ ((aligned (N), warn_if_not_aligned (N))) | |
8600 | A @{ /* @r{@dots{}} */ @}; | |
8601 | struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @}; | |
8602 | @end smallexample | |
8603 | ||
f33d7a88 | 8604 | @cindex @code{deprecated} type attribute |
d77de738 ML |
8605 | @item deprecated |
8606 | @itemx deprecated (@var{msg}) | |
d77de738 ML |
8607 | The @code{deprecated} attribute results in a warning if the type |
8608 | is used anywhere in the source file. This is useful when identifying | |
8609 | types that are expected to be removed in a future version of a program. | |
8610 | If possible, the warning also includes the location of the declaration | |
8611 | of the deprecated type, to enable users to easily find further | |
8612 | information about why the type is deprecated, or what they should do | |
8613 | instead. Note that the warnings only occur for uses and then only | |
8614 | if the type is being applied to an identifier that itself is not being | |
8615 | declared as deprecated. | |
8616 | ||
8617 | @smallexample | |
8618 | typedef int T1 __attribute__ ((deprecated)); | |
8619 | T1 x; | |
8620 | typedef T1 T2; | |
8621 | T2 y; | |
8622 | typedef T1 T3 __attribute__ ((deprecated)); | |
8623 | T3 z __attribute__ ((deprecated)); | |
8624 | @end smallexample | |
8625 | ||
8626 | @noindent | |
8627 | results in a warning on line 2 and 3 but not lines 4, 5, or 6. No | |
8628 | warning is issued for line 4 because T2 is not explicitly | |
8629 | deprecated. Line 5 has no warning because T3 is explicitly | |
8630 | deprecated. Similarly for line 6. The optional @var{msg} | |
8631 | argument, which must be a string, is printed in the warning if | |
8632 | present. Control characters in the string will be replaced with | |
8633 | escape sequences, and if the @option{-fmessage-length} option is set | |
8634 | to 0 (its default value) then any newline characters will be ignored. | |
8635 | ||
8636 | The @code{deprecated} attribute can also be used for functions and | |
8637 | variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) | |
8638 | ||
8639 | The message attached to the attribute is affected by the setting of | |
8640 | the @option{-fmessage-length} option. | |
8641 | ||
f33d7a88 | 8642 | @cindex @code{unavailable} type attribute |
d77de738 ML |
8643 | @item unavailable |
8644 | @itemx unavailable (@var{msg}) | |
d77de738 ML |
8645 | The @code{unavailable} attribute behaves in the same manner as the |
8646 | @code{deprecated} one, but emits an error rather than a warning. It is | |
8647 | used to indicate that a (perhaps previously @code{deprecated}) type is | |
8648 | no longer usable. | |
8649 | ||
8650 | The @code{unavailable} attribute can also be used for functions and | |
8651 | variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) | |
8652 | ||
d77de738 | 8653 | @cindex @code{designated_init} type attribute |
f33d7a88 | 8654 | @item designated_init |
d77de738 ML |
8655 | This attribute may only be applied to structure types. It indicates |
8656 | that any initialization of an object of this type must use designated | |
8657 | initializers rather than positional initializers. The intent of this | |
8658 | attribute is to allow the programmer to indicate that a structure's | |
8659 | layout may change, and that therefore relying on positional | |
8660 | initialization will result in future breakage. | |
8661 | ||
8662 | GCC emits warnings based on this attribute by default; use | |
8663 | @option{-Wno-designated-init} to suppress them. | |
8664 | ||
d77de738 | 8665 | @cindex @code{may_alias} type attribute |
f33d7a88 | 8666 | @item may_alias |
d77de738 ML |
8667 | Accesses through pointers to types with this attribute are not subject |
8668 | to type-based alias analysis, but are instead assumed to be able to alias | |
8669 | any other type of objects. | |
8670 | In the context of section 6.5 paragraph 7 of the C99 standard, | |
8671 | an lvalue expression | |
8672 | dereferencing such a pointer is treated like having a character type. | |
8673 | See @option{-fstrict-aliasing} for more information on aliasing issues. | |
8674 | This extension exists to support some vector APIs, in which pointers to | |
8675 | one vector type are permitted to alias pointers to a different vector type. | |
8676 | ||
8677 | Note that an object of a type with this attribute does not have any | |
8678 | special semantics. | |
8679 | ||
8680 | Example of use: | |
8681 | ||
8682 | @smallexample | |
8683 | typedef short __attribute__ ((__may_alias__)) short_a; | |
8684 | ||
8685 | int | |
8686 | main (void) | |
8687 | @{ | |
8688 | int a = 0x12345678; | |
8689 | short_a *b = (short_a *) &a; | |
8690 | ||
8691 | b[1] = 0; | |
8692 | ||
8693 | if (a == 0x12345678) | |
8694 | abort(); | |
8695 | ||
8696 | exit(0); | |
8697 | @} | |
8698 | @end smallexample | |
8699 | ||
8700 | @noindent | |
8701 | If you replaced @code{short_a} with @code{short} in the variable | |
8702 | declaration, the above program would abort when compiled with | |
8703 | @option{-fstrict-aliasing}, which is on by default at @option{-O2} or | |
8704 | above. | |
8705 | ||
d77de738 | 8706 | @cindex @code{mode} type attribute |
f33d7a88 | 8707 | @item mode (@var{mode}) |
d77de738 ML |
8708 | This attribute specifies the data type for the declaration---whichever |
8709 | type corresponds to the mode @var{mode}. This in effect lets you | |
8710 | request an integer or floating-point type according to its width. | |
8711 | ||
8712 | @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, | |
8713 | for a list of the possible keywords for @var{mode}. | |
8714 | You may also specify a mode of @code{byte} or @code{__byte__} to | |
8715 | indicate the mode corresponding to a one-byte integer, @code{word} or | |
8716 | @code{__word__} for the mode of a one-word integer, and @code{pointer} | |
8717 | or @code{__pointer__} for the mode used to represent pointers. | |
8718 | ||
d77de738 | 8719 | @cindex @code{packed} type attribute |
f33d7a88 | 8720 | @item packed |
d77de738 ML |
8721 | This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class} |
8722 | type definition, specifies that each of its members (other than zero-width | |
8723 | bit-fields) is placed to minimize the memory required. This is equivalent | |
8724 | to specifying the @code{packed} attribute on each of the members. | |
8725 | ||
8726 | @opindex fshort-enums | |
8727 | When attached to an @code{enum} definition, the @code{packed} attribute | |
8728 | indicates that the smallest integral type should be used. | |
8729 | Specifying the @option{-fshort-enums} flag on the command line | |
8730 | is equivalent to specifying the @code{packed} | |
8731 | attribute on all @code{enum} definitions. | |
8732 | ||
8733 | In the following example @code{struct my_packed_struct}'s members are | |
8734 | packed closely together, but the internal layout of its @code{s} member | |
8735 | is not packed---to do that, @code{struct my_unpacked_struct} needs to | |
8736 | be packed too. | |
8737 | ||
8738 | @smallexample | |
8739 | struct my_unpacked_struct | |
8740 | @{ | |
8741 | char c; | |
8742 | int i; | |
8743 | @}; | |
8744 | ||
8745 | struct __attribute__ ((__packed__)) my_packed_struct | |
8746 | @{ | |
8747 | char c; | |
8748 | int i; | |
8749 | struct my_unpacked_struct s; | |
8750 | @}; | |
8751 | @end smallexample | |
8752 | ||
8753 | You may only specify the @code{packed} attribute on the definition | |
8754 | of an @code{enum}, @code{struct}, @code{union}, or @code{class}, | |
8755 | not on a @code{typedef} that does not also define the enumerated type, | |
8756 | structure, union, or class. | |
8757 | ||
d77de738 | 8758 | @cindex @code{scalar_storage_order} type attribute |
f33d7a88 | 8759 | @item scalar_storage_order ("@var{endianness}") |
d77de738 ML |
8760 | When attached to a @code{union} or a @code{struct}, this attribute sets |
8761 | the storage order, aka endianness, of the scalar fields of the type, as | |
8762 | well as the array fields whose component is scalar. The supported | |
8763 | endiannesses are @code{big-endian} and @code{little-endian}. The attribute | |
8764 | has no effects on fields which are themselves a @code{union}, a @code{struct} | |
8765 | or an array whose component is a @code{union} or a @code{struct}, and it is | |
8766 | possible for these fields to have a different scalar storage order than the | |
8767 | enclosing type. | |
8768 | ||
8769 | Note that neither pointer nor vector fields are considered scalar fields in | |
8770 | this context, so the attribute has no effects on these fields. | |
8771 | ||
8772 | This attribute is supported only for targets that use a uniform default | |
8773 | scalar storage order (fortunately, most of them), i.e.@: targets that store | |
8774 | the scalars either all in big-endian or all in little-endian. | |
8775 | ||
8776 | Additional restrictions are enforced for types with the reverse scalar | |
8777 | storage order with regard to the scalar storage order of the target: | |
8778 | ||
8779 | @itemize | |
8780 | @item Taking the address of a scalar field of a @code{union} or a | |
8781 | @code{struct} with reverse scalar storage order is not permitted and yields | |
8782 | an error. | |
8783 | @item Taking the address of an array field, whose component is scalar, of | |
8784 | a @code{union} or a @code{struct} with reverse scalar storage order is | |
8785 | permitted but yields a warning, unless @option{-Wno-scalar-storage-order} | |
8786 | is specified. | |
8787 | @item Taking the address of a @code{union} or a @code{struct} with reverse | |
8788 | scalar storage order is permitted. | |
8789 | @end itemize | |
8790 | ||
8791 | These restrictions exist because the storage order attribute is lost when | |
8792 | the address of a scalar or the address of an array with scalar component is | |
8793 | taken, so storing indirectly through this address generally does not work. | |
8794 | The second case is nevertheless allowed to be able to perform a block copy | |
8795 | from or to the array. | |
8796 | ||
8797 | Moreover, the use of type punning or aliasing to toggle the storage order | |
8798 | is not supported; that is to say, if a given scalar object can be accessed | |
8799 | through distinct types that assign a different storage order to it, then the | |
8800 | behavior is undefined. | |
8801 | ||
d77de738 | 8802 | @cindex @code{transparent_union} type attribute |
f33d7a88 | 8803 | @item transparent_union |
d77de738 ML |
8804 | |
8805 | This attribute, attached to a @code{union} type definition, indicates | |
8806 | that any function parameter having that union type causes calls to that | |
8807 | function to be treated in a special way. | |
8808 | ||
8809 | First, the argument corresponding to a transparent union type can be of | |
8810 | any type in the union; no cast is required. Also, if the union contains | |
8811 | a pointer type, the corresponding argument can be a null pointer | |
8812 | constant or a void pointer expression; and if the union contains a void | |
8813 | pointer type, the corresponding argument can be any pointer expression. | |
8814 | If the union member type is a pointer, qualifiers like @code{const} on | |
8815 | the referenced type must be respected, just as with normal pointer | |
8816 | conversions. | |
8817 | ||
8818 | Second, the argument is passed to the function using the calling | |
8819 | conventions of the first member of the transparent union, not the calling | |
8820 | conventions of the union itself. All members of the union must have the | |
8821 | same machine representation; this is necessary for this argument passing | |
8822 | to work properly. | |
8823 | ||
8824 | Transparent unions are designed for library functions that have multiple | |
8825 | interfaces for compatibility reasons. For example, suppose the | |
8826 | @code{wait} function must accept either a value of type @code{int *} to | |
8827 | comply with POSIX, or a value of type @code{union wait *} to comply with | |
8828 | the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, | |
8829 | @code{wait} would accept both kinds of arguments, but it would also | |
8830 | accept any other pointer type and this would make argument type checking | |
8831 | less useful. Instead, @code{<sys/wait.h>} might define the interface | |
8832 | as follows: | |
8833 | ||
8834 | @smallexample | |
8835 | typedef union __attribute__ ((__transparent_union__)) | |
8836 | @{ | |
8837 | int *__ip; | |
8838 | union wait *__up; | |
8839 | @} wait_status_ptr_t; | |
8840 | ||
8841 | pid_t wait (wait_status_ptr_t); | |
8842 | @end smallexample | |
8843 | ||
8844 | @noindent | |
8845 | This interface allows either @code{int *} or @code{union wait *} | |
8846 | arguments to be passed, using the @code{int *} calling convention. | |
8847 | The program can call @code{wait} with arguments of either type: | |
8848 | ||
8849 | @smallexample | |
8850 | int w1 () @{ int w; return wait (&w); @} | |
8851 | int w2 () @{ union wait w; return wait (&w); @} | |
8852 | @end smallexample | |
8853 | ||
8854 | @noindent | |
8855 | With this interface, @code{wait}'s implementation might look like this: | |
8856 | ||
8857 | @smallexample | |
8858 | pid_t wait (wait_status_ptr_t p) | |
8859 | @{ | |
8860 | return waitpid (-1, p.__ip, 0); | |
8861 | @} | |
8862 | @end smallexample | |
8863 | ||
d77de738 | 8864 | @cindex @code{unused} type attribute |
f33d7a88 | 8865 | @item unused |
d77de738 ML |
8866 | When attached to a type (including a @code{union} or a @code{struct}), |
8867 | this attribute means that variables of that type are meant to appear | |
8868 | possibly unused. GCC does not produce a warning for any variables of | |
8869 | that type, even if the variable appears to do nothing. This is often | |
8870 | the case with lock or thread classes, which are usually defined and then | |
8871 | not referenced, but contain constructors and destructors that have | |
8872 | nontrivial bookkeeping functions. | |
8873 | ||
d77de738 | 8874 | @cindex @code{vector_size} type attribute |
f33d7a88 | 8875 | @item vector_size (@var{bytes}) |
d77de738 ML |
8876 | This attribute specifies the vector size for the type, measured in bytes. |
8877 | The type to which it applies is known as the @dfn{base type}. The @var{bytes} | |
8878 | argument must be a positive power-of-two multiple of the base type size. For | |
8879 | example, the following declarations: | |
8880 | ||
8881 | @smallexample | |
8882 | typedef __attribute__ ((vector_size (32))) int int_vec32_t ; | |
8883 | typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t; | |
8884 | typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3]; | |
8885 | @end smallexample | |
8886 | ||
8887 | @noindent | |
8888 | define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int} | |
8889 | sized units. With @code{int} having a size of 4 bytes, the type defines | |
8890 | a vector of eight units, four bytes each. The mode of variables of type | |
8891 | @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined | |
8892 | to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be | |
8893 | an array of three such vectors. @xref{Vector Extensions}, for details of | |
8894 | manipulating objects of vector types. | |
8895 | ||
8896 | This attribute is only applicable to integral and floating scalar types. | |
8897 | In function declarations the attribute applies to the function return | |
8898 | type. | |
8899 | ||
8900 | For example, the following: | |
8901 | @smallexample | |
8902 | __attribute__ ((vector_size (16))) float get_flt_vec16 (void); | |
8903 | @end smallexample | |
8904 | declares @code{get_flt_vec16} to be a function returning a 16-byte vector | |
8905 | with the base type @code{float}. | |
8906 | ||
d77de738 | 8907 | @cindex @code{visibility} type attribute |
f33d7a88 | 8908 | @item visibility |
d77de738 ML |
8909 | In C++, attribute visibility (@pxref{Function Attributes}) can also be |
8910 | applied to class, struct, union and enum types. Unlike other type | |
8911 | attributes, the attribute must appear between the initial keyword and | |
8912 | the name of the type; it cannot appear after the body of the type. | |
8913 | ||
8914 | Note that the type visibility is applied to vague linkage entities | |
8915 | associated with the class (vtable, typeinfo node, etc.). In | |
8916 | particular, if a class is thrown as an exception in one shared object | |
8917 | and caught in another, the class must have default visibility. | |
8918 | Otherwise the two shared objects are unable to use the same | |
8919 | typeinfo node and exception handling will break. | |
8920 | ||
d77de738 | 8921 | @cindex @code{objc_root_class} type attribute |
f33d7a88 | 8922 | @item objc_root_class @r{(Objective-C and Objective-C++ only)} |
d77de738 ML |
8923 | This attribute marks a class as being a root class, and thus allows |
8924 | the compiler to elide any warnings about a missing superclass and to | |
8925 | make additional checks for mandatory methods as needed. | |
8926 | ||
8927 | @end table | |
8928 | ||
8929 | To specify multiple attributes, separate them by commas within the | |
8930 | double parentheses: for example, @samp{__attribute__ ((aligned (16), | |
8931 | packed))}. | |
8932 | ||
8933 | @node ARC Type Attributes | |
8934 | @subsection ARC Type Attributes | |
8935 | ||
8936 | @cindex @code{uncached} type attribute, ARC | |
8937 | Declaring objects with @code{uncached} allows you to exclude | |
8938 | data-cache participation in load and store operations on those objects | |
8939 | without involving the additional semantic implications of | |
8940 | @code{volatile}. The @code{.di} instruction suffix is used for all | |
8941 | loads and stores of data declared @code{uncached}. | |
8942 | ||
8943 | @node ARM Type Attributes | |
8944 | @subsection ARM Type Attributes | |
8945 | ||
8946 | @cindex @code{notshared} type attribute, ARM | |
8947 | On those ARM targets that support @code{dllimport} (such as Symbian | |
8948 | OS), you can use the @code{notshared} attribute to indicate that the | |
8949 | virtual table and other similar data for a class should not be | |
8950 | exported from a DLL@. For example: | |
8951 | ||
8952 | @smallexample | |
8953 | class __declspec(notshared) C @{ | |
8954 | public: | |
8955 | __declspec(dllimport) C(); | |
8956 | virtual void f(); | |
8957 | @} | |
8958 | ||
8959 | __declspec(dllexport) | |
8960 | C::C() @{@} | |
8961 | @end smallexample | |
8962 | ||
8963 | @noindent | |
8964 | In this code, @code{C::C} is exported from the current DLL, but the | |
8965 | virtual table for @code{C} is not exported. (You can use | |
8966 | @code{__attribute__} instead of @code{__declspec} if you prefer, but | |
8967 | most Symbian OS code uses @code{__declspec}.) | |
8968 | ||
8969 | @node BPF Type Attributes | |
8970 | @subsection BPF Type Attributes | |
8971 | ||
8972 | @cindex @code{preserve_access_index} type attribute, BPF | |
8973 | BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a | |
8974 | @code{struct} or @code{union} type definition, indicates that CO-RE | |
8975 | relocation information should be generated for any access to a variable | |
8976 | of that type. The behavior is equivalent to the programmer manually | |
8977 | wrapping every such access with @code{__builtin_preserve_access_index}. | |
8978 | ||
8979 | ||
d77de738 ML |
8980 | @node PowerPC Type Attributes |
8981 | @subsection PowerPC Type Attributes | |
8982 | ||
8983 | Three attributes currently are defined for PowerPC configurations: | |
8984 | @code{altivec}, @code{ms_struct} and @code{gcc_struct}. | |
8985 | ||
8986 | @cindex @code{ms_struct} type attribute, PowerPC | |
8987 | @cindex @code{gcc_struct} type attribute, PowerPC | |
8988 | For full documentation of the @code{ms_struct} and @code{gcc_struct} | |
8989 | attributes please see the documentation in @ref{x86 Type Attributes}. | |
8990 | ||
8991 | @cindex @code{altivec} type attribute, PowerPC | |
8992 | The @code{altivec} attribute allows one to declare AltiVec vector data | |
8993 | types supported by the AltiVec Programming Interface Manual. The | |
8994 | attribute requires an argument to specify one of three vector types: | |
8995 | @code{vector__}, @code{pixel__} (always followed by unsigned short), | |
8996 | and @code{bool__} (always followed by unsigned). | |
8997 | ||
8998 | @smallexample | |
8999 | __attribute__((altivec(vector__))) | |
9000 | __attribute__((altivec(pixel__))) unsigned short | |
9001 | __attribute__((altivec(bool__))) unsigned | |
9002 | @end smallexample | |
9003 | ||
9004 | These attributes mainly are intended to support the @code{__vector}, | |
9005 | @code{__pixel}, and @code{__bool} AltiVec keywords. | |
9006 | ||
9007 | @node x86 Type Attributes | |
9008 | @subsection x86 Type Attributes | |
9009 | ||
9010 | Two attributes are currently defined for x86 configurations: | |
9011 | @code{ms_struct} and @code{gcc_struct}. | |
9012 | ||
9013 | @table @code | |
9014 | ||
d77de738 ML |
9015 | @cindex @code{ms_struct} type attribute, x86 |
9016 | @cindex @code{gcc_struct} type attribute, x86 | |
f33d7a88 AA |
9017 | @item ms_struct |
9018 | @itemx gcc_struct | |
d77de738 ML |
9019 | |
9020 | If @code{packed} is used on a structure, or if bit-fields are used | |
9021 | it may be that the Microsoft ABI packs them differently | |
9022 | than GCC normally packs them. Particularly when moving packed | |
9023 | data between functions compiled with GCC and the native Microsoft compiler | |
9024 | (either via function call or as data in a file), it may be necessary to access | |
9025 | either format. | |
9026 | ||
9027 | The @code{ms_struct} and @code{gcc_struct} attributes correspond | |
9028 | to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} | |
9029 | command-line options, respectively; | |
9030 | see @ref{x86 Options}, for details of how structure layout is affected. | |
9031 | @xref{x86 Variable Attributes}, for information about the corresponding | |
9032 | attributes on variables. | |
9033 | ||
9034 | @end table | |
9035 | ||
9036 | @node Label Attributes | |
9037 | @section Label Attributes | |
9038 | @cindex Label Attributes | |
9039 | ||
9040 | GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for | |
9041 | details of the exact syntax for using attributes. Other attributes are | |
9042 | available for functions (@pxref{Function Attributes}), variables | |
9043 | (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}), | |
9044 | statements (@pxref{Statement Attributes}), and for types | |
9045 | (@pxref{Type Attributes}). A label attribute followed | |
9046 | by a declaration appertains to the label and not the declaration. | |
9047 | ||
9048 | This example uses the @code{cold} label attribute to indicate the | |
9049 | @code{ErrorHandling} branch is unlikely to be taken and that the | |
9050 | @code{ErrorHandling} label is unused: | |
9051 | ||
9052 | @smallexample | |
9053 | ||
9054 | asm goto ("some asm" : : : : NoError); | |
9055 | ||
9056 | /* This branch (the fall-through from the asm) is less commonly used */ | |
9057 | ErrorHandling: | |
9058 | __attribute__((cold, unused)); /* Semi-colon is required here */ | |
9059 | printf("error\n"); | |
9060 | return 0; | |
9061 | ||
9062 | NoError: | |
9063 | printf("no error\n"); | |
9064 | return 1; | |
9065 | @end smallexample | |
9066 | ||
9067 | @table @code | |
d77de738 | 9068 | @cindex @code{unused} label attribute |
f33d7a88 | 9069 | @item unused |
d77de738 ML |
9070 | This feature is intended for program-generated code that may contain |
9071 | unused labels, but which is compiled with @option{-Wall}. It is | |
9072 | not normally appropriate to use in it human-written code, though it | |
9073 | could be useful in cases where the code that jumps to the label is | |
9074 | contained within an @code{#ifdef} conditional. | |
9075 | ||
d77de738 | 9076 | @cindex @code{hot} label attribute |
f33d7a88 | 9077 | @item hot |
d77de738 ML |
9078 | The @code{hot} attribute on a label is used to inform the compiler that |
9079 | the path following the label is more likely than paths that are not so | |
9080 | annotated. This attribute is used in cases where @code{__builtin_expect} | |
9081 | cannot be used, for instance with computed goto or @code{asm goto}. | |
9082 | ||
d77de738 | 9083 | @cindex @code{cold} label attribute |
f33d7a88 | 9084 | @item cold |
d77de738 ML |
9085 | The @code{cold} attribute on labels is used to inform the compiler that |
9086 | the path following the label is unlikely to be executed. This attribute | |
9087 | is used in cases where @code{__builtin_expect} cannot be used, for instance | |
9088 | with computed goto or @code{asm goto}. | |
9089 | ||
9090 | @end table | |
9091 | ||
9092 | @node Enumerator Attributes | |
9093 | @section Enumerator Attributes | |
9094 | @cindex Enumerator Attributes | |
9095 | ||
9096 | GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for | |
9097 | details of the exact syntax for using attributes. Other attributes are | |
9098 | available for functions (@pxref{Function Attributes}), variables | |
9099 | (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements | |
9100 | (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). | |
9101 | ||
9102 | This example uses the @code{deprecated} enumerator attribute to indicate the | |
9103 | @code{oldval} enumerator is deprecated: | |
9104 | ||
9105 | @smallexample | |
9106 | enum E @{ | |
9107 | oldval __attribute__((deprecated)), | |
9108 | newval | |
9109 | @}; | |
9110 | ||
9111 | int | |
9112 | fn (void) | |
9113 | @{ | |
9114 | return oldval; | |
9115 | @} | |
9116 | @end smallexample | |
9117 | ||
9118 | @table @code | |
d77de738 | 9119 | @cindex @code{deprecated} enumerator attribute |
f33d7a88 | 9120 | @item deprecated |
d77de738 ML |
9121 | The @code{deprecated} attribute results in a warning if the enumerator |
9122 | is used anywhere in the source file. This is useful when identifying | |
9123 | enumerators that are expected to be removed in a future version of a | |
9124 | program. The warning also includes the location of the declaration | |
9125 | of the deprecated enumerator, to enable users to easily find further | |
9126 | information about why the enumerator is deprecated, or what they should | |
9127 | do instead. Note that the warnings only occurs for uses. | |
9128 | ||
d77de738 | 9129 | @cindex @code{unavailable} enumerator attribute |
f33d7a88 | 9130 | @item unavailable |
d77de738 ML |
9131 | The @code{unavailable} attribute results in an error if the enumerator |
9132 | is used anywhere in the source file. In other respects it behaves in the | |
9133 | same manner as the @code{deprecated} attribute. | |
9134 | ||
9135 | @end table | |
9136 | ||
9137 | @node Statement Attributes | |
9138 | @section Statement Attributes | |
9139 | @cindex Statement Attributes | |
9140 | ||
9141 | GCC allows attributes to be set on null statements. @xref{Attribute Syntax}, | |
9142 | for details of the exact syntax for using attributes. Other attributes are | |
9143 | available for functions (@pxref{Function Attributes}), variables | |
9144 | (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators | |
9145 | (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}). | |
9146 | ||
9147 | @table @code | |
d77de738 | 9148 | @cindex @code{fallthrough} statement attribute |
f33d7a88 | 9149 | @item fallthrough |
d77de738 ML |
9150 | The @code{fallthrough} attribute with a null statement serves as a |
9151 | fallthrough statement. It hints to the compiler that a statement | |
9152 | that falls through to another case label, or user-defined label | |
9153 | in a switch statement is intentional and thus the | |
9154 | @option{-Wimplicit-fallthrough} warning must not trigger. The | |
9155 | fallthrough attribute may appear at most once in each attribute | |
9156 | list, and may not be mixed with other attributes. It can only | |
9157 | be used in a switch statement (the compiler will issue an error | |
9158 | otherwise), after a preceding statement and before a logically | |
9159 | succeeding case label, or user-defined label. | |
9160 | ||
9161 | This example uses the @code{fallthrough} statement attribute to indicate that | |
9162 | the @option{-Wimplicit-fallthrough} warning should not be emitted: | |
9163 | ||
9164 | @smallexample | |
9165 | switch (cond) | |
9166 | @{ | |
9167 | case 1: | |
9168 | bar (1); | |
9169 | __attribute__((fallthrough)); | |
9170 | case 2: | |
9171 | @dots{} | |
9172 | @} | |
9173 | @end smallexample | |
9174 | ||
d77de738 | 9175 | @cindex @code{assume} statement attribute |
f33d7a88 | 9176 | @item assume |
d77de738 ML |
9177 | The @code{assume} attribute with a null statement serves as portable |
9178 | assumption. It should have a single argument, a conditional expression, | |
9179 | which is not evaluated. If the argument would evaluate to true | |
9180 | at the point where it appears, it has no effect, otherwise there | |
9181 | is undefined behavior. This is a GNU variant of the ISO C++23 | |
9182 | standard @code{assume} attribute, but it can be used in any version of | |
9183 | both C and C++. | |
9184 | ||
9185 | @smallexample | |
9186 | int | |
9187 | foo (int x, int y) | |
9188 | @{ | |
9189 | __attribute__((assume(x == 42))); | |
9190 | __attribute__((assume(++y == 43))); | |
9191 | return x + y; | |
9192 | @} | |
9193 | @end smallexample | |
9194 | ||
9195 | @code{y} is not actually incremented and the compiler can but does not | |
9196 | have to optimize it to just @code{return 42 + 42;}. | |
9197 | ||
9198 | @end table | |
9199 | ||
9200 | @node Attribute Syntax | |
9201 | @section Attribute Syntax | |
9202 | @cindex attribute syntax | |
9203 | ||
9204 | This section describes the syntax with which @code{__attribute__} may be | |
9205 | used, and the constructs to which attribute specifiers bind, for the C | |
9206 | language. Some details may vary for C++ and Objective-C@. Because of | |
d9922e4b | 9207 | limitations in the grammar for attributes, some forms described here |
d77de738 ML |
9208 | may not be successfully parsed in all cases. |
9209 | ||
9210 | There are some problems with the semantics of attributes in C++. For | |
9211 | example, there are no manglings for attributes, although they may affect | |
9212 | code generation, so problems may arise when attributed types are used in | |
9213 | conjunction with templates or overloading. Similarly, @code{typeid} | |
9214 | does not distinguish between types with different attributes. Support | |
9215 | for attributes in C++ may be restricted in future to attributes on | |
9216 | declarations only, but not on nested declarators. | |
9217 | ||
9218 | @xref{Function Attributes}, for details of the semantics of attributes | |
9219 | applying to functions. @xref{Variable Attributes}, for details of the | |
9220 | semantics of attributes applying to variables. @xref{Type Attributes}, | |
9221 | for details of the semantics of attributes applying to structure, union | |
9222 | and enumerated types. | |
9223 | @xref{Label Attributes}, for details of the semantics of attributes | |
9224 | applying to labels. | |
9225 | @xref{Enumerator Attributes}, for details of the semantics of attributes | |
9226 | applying to enumerators. | |
9227 | @xref{Statement Attributes}, for details of the semantics of attributes | |
9228 | applying to statements. | |
9229 | ||
9230 | An @dfn{attribute specifier} is of the form | |
9231 | @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} | |
9232 | is a possibly empty comma-separated sequence of @dfn{attributes}, where | |
9233 | each attribute is one of the following: | |
9234 | ||
9235 | @itemize @bullet | |
9236 | @item | |
9237 | Empty. Empty attributes are ignored. | |
9238 | ||
9239 | @item | |
9240 | An attribute name | |
9241 | (which may be an identifier such as @code{unused}, or a reserved | |
9242 | word such as @code{const}). | |
9243 | ||
9244 | @item | |
9245 | An attribute name followed by a parenthesized list of | |
9246 | parameters for the attribute. | |
9247 | These parameters take one of the following forms: | |
9248 | ||
9249 | @itemize @bullet | |
9250 | @item | |
9251 | An identifier. For example, @code{mode} attributes use this form. | |
9252 | ||
9253 | @item | |
9254 | An identifier followed by a comma and a non-empty comma-separated list | |
9255 | of expressions. For example, @code{format} attributes use this form. | |
9256 | ||
9257 | @item | |
9258 | A possibly empty comma-separated list of expressions. For example, | |
9259 | @code{format_arg} attributes use this form with the list being a single | |
9260 | integer constant expression, and @code{alias} attributes use this form | |
9261 | with the list being a single string constant. | |
9262 | @end itemize | |
9263 | @end itemize | |
9264 | ||
9265 | An @dfn{attribute specifier list} is a sequence of one or more attribute | |
9266 | specifiers, not separated by any other tokens. | |
9267 | ||
9268 | You may optionally specify attribute names with @samp{__} | |
9269 | preceding and following the name. | |
9270 | This allows you to use them in header files without | |
9271 | being concerned about a possible macro of the same name. For example, | |
9272 | you may use the attribute name @code{__noreturn__} instead of @code{noreturn}. | |
9273 | ||
9274 | ||
9275 | @subsubheading Label Attributes | |
9276 | ||
9277 | In GNU C, an attribute specifier list may appear after the colon following a | |
9278 | label, other than a @code{case} or @code{default} label. GNU C++ only permits | |
9279 | attributes on labels if the attribute specifier is immediately | |
9280 | followed by a semicolon (i.e., the label applies to an empty | |
9281 | statement). If the semicolon is missing, C++ label attributes are | |
9282 | ambiguous, as it is permissible for a declaration, which could begin | |
9283 | with an attribute list, to be labelled in C++. Declarations cannot be | |
9284 | labelled in C90 or C99, so the ambiguity does not arise there. | |
9285 | ||
9286 | @subsubheading Enumerator Attributes | |
9287 | ||
9288 | In GNU C, an attribute specifier list may appear as part of an enumerator. | |
9289 | The attribute goes after the enumeration constant, before @code{=}, if | |
9290 | present. The optional attribute in the enumerator appertains to the | |
9291 | enumeration constant. It is not possible to place the attribute after | |
9292 | the constant expression, if present. | |
9293 | ||
9294 | @subsubheading Statement Attributes | |
9295 | In GNU C, an attribute specifier list may appear as part of a null | |
9296 | statement. The attribute goes before the semicolon. | |
9297 | ||
9298 | @subsubheading Type Attributes | |
9299 | ||
9300 | An attribute specifier list may appear as part of a @code{struct}, | |
9301 | @code{union} or @code{enum} specifier. It may go either immediately | |
9302 | after the @code{struct}, @code{union} or @code{enum} keyword, or after | |
9303 | the closing brace. The former syntax is preferred. | |
9304 | Where attribute specifiers follow the closing brace, they are considered | |
9305 | to relate to the structure, union or enumerated type defined, not to any | |
9306 | enclosing declaration the type specifier appears in, and the type | |
9307 | defined is not complete until after the attribute specifiers. | |
9308 | @c Otherwise, there would be the following problems: a shift/reduce | |
9309 | @c conflict between attributes binding the struct/union/enum and | |
9310 | @c binding to the list of specifiers/qualifiers; and "aligned" | |
9311 | @c attributes could use sizeof for the structure, but the size could be | |
9312 | @c changed later by "packed" attributes. | |
9313 | ||
9314 | ||
9315 | @subsubheading All other attributes | |
9316 | ||
9317 | Otherwise, an attribute specifier appears as part of a declaration, | |
9318 | counting declarations of unnamed parameters and type names, and relates | |
9319 | to that declaration (which may be nested in another declaration, for | |
9320 | example in the case of a parameter declaration), or to a particular declarator | |
9321 | within a declaration. Where an | |
9322 | attribute specifier is applied to a parameter declared as a function or | |
9323 | an array, it should apply to the function or array rather than the | |
9324 | pointer to which the parameter is implicitly converted, but this is not | |
9325 | yet correctly implemented. | |
9326 | ||
9327 | Any list of specifiers and qualifiers at the start of a declaration may | |
9328 | contain attribute specifiers, whether or not such a list may in that | |
9329 | context contain storage class specifiers. (Some attributes, however, | |
9330 | are essentially in the nature of storage class specifiers, and only make | |
9331 | sense where storage class specifiers may be used; for example, | |
9332 | @code{section}.) There is one necessary limitation to this syntax: the | |
9333 | first old-style parameter declaration in a function definition cannot | |
9334 | begin with an attribute specifier, because such an attribute applies to | |
9335 | the function instead by syntax described below (which, however, is not | |
9336 | yet implemented in this case). In some other cases, attribute | |
9337 | specifiers are permitted by this grammar but not yet supported by the | |
9338 | compiler. All attribute specifiers in this place relate to the | |
9339 | declaration as a whole. In the obsolescent usage where a type of | |
9340 | @code{int} is implied by the absence of type specifiers, such a list of | |
9341 | specifiers and qualifiers may be an attribute specifier list with no | |
9342 | other specifiers or qualifiers. | |
9343 | ||
9344 | At present, the first parameter in a function prototype must have some | |
9345 | type specifier that is not an attribute specifier; this resolves an | |
9346 | ambiguity in the interpretation of @code{void f(int | |
9347 | (__attribute__((foo)) x))}, but is subject to change. At present, if | |
9348 | the parentheses of a function declarator contain only attributes then | |
9349 | those attributes are ignored, rather than yielding an error or warning | |
9350 | or implying a single parameter of type int, but this is subject to | |
9351 | change. | |
9352 | ||
9353 | An attribute specifier list may appear immediately before a declarator | |
9354 | (other than the first) in a comma-separated list of declarators in a | |
9355 | declaration of more than one identifier using a single list of | |
9356 | specifiers and qualifiers. Such attribute specifiers apply | |
9357 | only to the identifier before whose declarator they appear. For | |
9358 | example, in | |
9359 | ||
9360 | @smallexample | |
9361 | __attribute__((noreturn)) void d0 (void), | |
9362 | __attribute__((format(printf, 1, 2))) d1 (const char *, ...), | |
9363 | d2 (void); | |
9364 | @end smallexample | |
9365 | ||
9366 | @noindent | |
9367 | the @code{noreturn} attribute applies to all the functions | |
9368 | declared; the @code{format} attribute only applies to @code{d1}. | |
9369 | ||
9370 | An attribute specifier list may appear immediately before the comma, | |
9371 | @code{=} or semicolon terminating the declaration of an identifier other | |
9372 | than a function definition. Such attribute specifiers apply | |
9373 | to the declared object or function. Where an | |
9374 | assembler name for an object or function is specified (@pxref{Asm | |
9375 | Labels}), the attribute must follow the @code{asm} | |
9376 | specification. | |
9377 | ||
9378 | An attribute specifier list may, in future, be permitted to appear after | |
9379 | the declarator in a function definition (before any old-style parameter | |
9380 | declarations or the function body). | |
9381 | ||
9382 | Attribute specifiers may be mixed with type qualifiers appearing inside | |
9383 | the @code{[]} of a parameter array declarator, in the C99 construct by | |
9384 | which such qualifiers are applied to the pointer to which the array is | |
9385 | implicitly converted. Such attribute specifiers apply to the pointer, | |
9386 | not to the array, but at present this is not implemented and they are | |
9387 | ignored. | |
9388 | ||
9389 | An attribute specifier list may appear at the start of a nested | |
9390 | declarator. At present, there are some limitations in this usage: the | |
9391 | attributes correctly apply to the declarator, but for most individual | |
9392 | attributes the semantics this implies are not implemented. | |
9393 | When attribute specifiers follow the @code{*} of a pointer | |
9394 | declarator, they may be mixed with any type qualifiers present. | |
9395 | The following describes the formal semantics of this syntax. It makes the | |
9396 | most sense if you are familiar with the formal specification of | |
9397 | declarators in the ISO C standard. | |
9398 | ||
9399 | Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T | |
9400 | D1}, where @code{T} contains declaration specifiers that specify a type | |
9401 | @var{Type} (such as @code{int}) and @code{D1} is a declarator that | |
9402 | contains an identifier @var{ident}. The type specified for @var{ident} | |
9403 | for derived declarators whose type does not include an attribute | |
9404 | specifier is as in the ISO C standard. | |
9405 | ||
9406 | If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, | |
9407 | and the declaration @code{T D} specifies the type | |
9408 | ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then | |
9409 | @code{T D1} specifies the type ``@var{derived-declarator-type-list} | |
9410 | @var{attribute-specifier-list} @var{Type}'' for @var{ident}. | |
9411 | ||
9412 | If @code{D1} has the form @code{* | |
9413 | @var{type-qualifier-and-attribute-specifier-list} D}, and the | |
9414 | declaration @code{T D} specifies the type | |
9415 | ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then | |
9416 | @code{T D1} specifies the type ``@var{derived-declarator-type-list} | |
9417 | @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for | |
9418 | @var{ident}. | |
9419 | ||
9420 | For example, | |
9421 | ||
9422 | @smallexample | |
9423 | void (__attribute__((noreturn)) ****f) (void); | |
9424 | @end smallexample | |
9425 | ||
9426 | @noindent | |
9427 | specifies the type ``pointer to pointer to pointer to pointer to | |
9428 | non-returning function returning @code{void}''. As another example, | |
9429 | ||
9430 | @smallexample | |
9431 | char *__attribute__((aligned(8))) *f; | |
9432 | @end smallexample | |
9433 | ||
9434 | @noindent | |
9435 | specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. | |
9436 | Note again that this does not work with most attributes; for example, | |
9437 | the usage of @samp{aligned} and @samp{noreturn} attributes given above | |
9438 | is not yet supported. | |
9439 | ||
9440 | For compatibility with existing code written for compiler versions that | |
9441 | did not implement attributes on nested declarators, some laxity is | |
9442 | allowed in the placing of attributes. If an attribute that only applies | |
9443 | to types is applied to a declaration, it is treated as applying to | |
9444 | the type of that declaration. If an attribute that only applies to | |
9445 | declarations is applied to the type of a declaration, it is treated | |
9446 | as applying to that declaration; and, for compatibility with code | |
9447 | placing the attributes immediately before the identifier declared, such | |
9448 | an attribute applied to a function return type is treated as | |
9449 | applying to the function type, and such an attribute applied to an array | |
9450 | element type is treated as applying to the array type. If an | |
9451 | attribute that only applies to function types is applied to a | |
9452 | pointer-to-function type, it is treated as applying to the pointer | |
9453 | target type; if such an attribute is applied to a function return type | |
9454 | that is not a pointer-to-function type, it is treated as applying | |
9455 | to the function type. | |
9456 | ||
9457 | @node Function Prototypes | |
9458 | @section Prototypes and Old-Style Function Definitions | |
9459 | @cindex function prototype declarations | |
9460 | @cindex old-style function definitions | |
9461 | @cindex promotion of formal parameters | |
9462 | ||
9463 | GNU C extends ISO C to allow a function prototype to override a later | |
9464 | old-style non-prototype definition. Consider the following example: | |
9465 | ||
9466 | @smallexample | |
9467 | /* @r{Use prototypes unless the compiler is old-fashioned.} */ | |
9468 | #ifdef __STDC__ | |
9469 | #define P(x) x | |
9470 | #else | |
9471 | #define P(x) () | |
9472 | #endif | |
9473 | ||
9474 | /* @r{Prototype function declaration.} */ | |
9475 | int isroot P((uid_t)); | |
9476 | ||
9477 | /* @r{Old-style function definition.} */ | |
9478 | int | |
9479 | isroot (x) /* @r{??? lossage here ???} */ | |
9480 | uid_t x; | |
9481 | @{ | |
9482 | return x == 0; | |
9483 | @} | |
9484 | @end smallexample | |
9485 | ||
9486 | Suppose the type @code{uid_t} happens to be @code{short}. ISO C does | |
9487 | not allow this example, because subword arguments in old-style | |
9488 | non-prototype definitions are promoted. Therefore in this example the | |
9489 | function definition's argument is really an @code{int}, which does not | |
9490 | match the prototype argument type of @code{short}. | |
9491 | ||
9492 | This restriction of ISO C makes it hard to write code that is portable | |
9493 | to traditional C compilers, because the programmer does not know | |
9494 | whether the @code{uid_t} type is @code{short}, @code{int}, or | |
9495 | @code{long}. Therefore, in cases like these GNU C allows a prototype | |
9496 | to override a later old-style definition. More precisely, in GNU C, a | |
9497 | function prototype argument type overrides the argument type specified | |
9498 | by a later old-style definition if the former type is the same as the | |
9499 | latter type before promotion. Thus in GNU C the above example is | |
9500 | equivalent to the following: | |
9501 | ||
9502 | @smallexample | |
9503 | int isroot (uid_t); | |
9504 | ||
9505 | int | |
9506 | isroot (uid_t x) | |
9507 | @{ | |
9508 | return x == 0; | |
9509 | @} | |
9510 | @end smallexample | |
9511 | ||
9512 | @noindent | |
9513 | GNU C++ does not support old-style function definitions, so this | |
9514 | extension is irrelevant. | |
9515 | ||
9516 | @node C++ Comments | |
9517 | @section C++ Style Comments | |
9518 | @cindex @code{//} | |
9519 | @cindex C++ comments | |
9520 | @cindex comments, C++ style | |
9521 | ||
9522 | In GNU C, you may use C++ style comments, which start with @samp{//} and | |
9523 | continue until the end of the line. Many other C implementations allow | |
9524 | such comments, and they are included in the 1999 C standard. However, | |
9525 | C++ style comments are not recognized if you specify an @option{-std} | |
9526 | option specifying a version of ISO C before C99, or @option{-ansi} | |
9527 | (equivalent to @option{-std=c90}). | |
9528 | ||
9529 | @node Dollar Signs | |
9530 | @section Dollar Signs in Identifier Names | |
9531 | @cindex $ | |
9532 | @cindex dollar signs in identifier names | |
9533 | @cindex identifier names, dollar signs in | |
9534 | ||
9535 | In GNU C, you may normally use dollar signs in identifier names. | |
9536 | This is because many traditional C implementations allow such identifiers. | |
9537 | However, dollar signs in identifiers are not supported on a few target | |
9538 | machines, typically because the target assembler does not allow them. | |
9539 | ||
9540 | @node Character Escapes | |
9541 | @section The Character @key{ESC} in Constants | |
9542 | ||
9543 | You can use the sequence @samp{\e} in a string or character constant to | |
9544 | stand for the ASCII character @key{ESC}. | |
9545 | ||
9546 | @node Alignment | |
9547 | @section Determining the Alignment of Functions, Types or Variables | |
9548 | @cindex alignment | |
9549 | @cindex type alignment | |
9550 | @cindex variable alignment | |
9551 | ||
9552 | The keyword @code{__alignof__} determines the alignment requirement of | |
9553 | a function, object, or a type, or the minimum alignment usually required | |
9554 | by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}. | |
9555 | ||
9556 | For example, if the target machine requires a @code{double} value to be | |
9557 | aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. | |
9558 | This is true on many RISC machines. On more traditional machine | |
9559 | designs, @code{__alignof__ (double)} is 4 or even 2. | |
9560 | ||
9561 | Some machines never actually require alignment; they allow references to any | |
9562 | data type even at an odd address. For these machines, @code{__alignof__} | |
9563 | reports the smallest alignment that GCC gives the data type, usually as | |
9564 | mandated by the target ABI. | |
9565 | ||
9566 | If the operand of @code{__alignof__} is an lvalue rather than a type, | |
9567 | its value is the required alignment for its type, taking into account | |
9568 | any minimum alignment specified by attribute @code{aligned} | |
9569 | (@pxref{Common Variable Attributes}). For example, after this | |
9570 | declaration: | |
9571 | ||
9572 | @smallexample | |
9573 | struct foo @{ int x; char y; @} foo1; | |
9574 | @end smallexample | |
9575 | ||
9576 | @noindent | |
9577 | the value of @code{__alignof__ (foo1.y)} is 1, even though its actual | |
9578 | alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. | |
9579 | It is an error to ask for the alignment of an incomplete type other | |
9580 | than @code{void}. | |
9581 | ||
9582 | If the operand of the @code{__alignof__} expression is a function, | |
9583 | the expression evaluates to the alignment of the function which may | |
9584 | be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). | |
9585 | ||
9586 | @node Inline | |
9587 | @section An Inline Function is As Fast As a Macro | |
9588 | @cindex inline functions | |
9589 | @cindex integrating function code | |
9590 | @cindex open coding | |
9591 | @cindex macros, inline alternative | |
9592 | ||
9593 | By declaring a function inline, you can direct GCC to make | |
9594 | calls to that function faster. One way GCC can achieve this is to | |
9595 | integrate that function's code into the code for its callers. This | |
9596 | makes execution faster by eliminating the function-call overhead; in | |
9597 | addition, if any of the actual argument values are constant, their | |
9598 | known values may permit simplifications at compile time so that not | |
9599 | all of the inline function's code needs to be included. The effect on | |
9600 | code size is less predictable; object code may be larger or smaller | |
9601 | with function inlining, depending on the particular case. You can | |
9602 | also direct GCC to try to integrate all ``simple enough'' functions | |
9603 | into their callers with the option @option{-finline-functions}. | |
9604 | ||
9605 | GCC implements three different semantics of declaring a function | |
9606 | inline. One is available with @option{-std=gnu89} or | |
9607 | @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present | |
9608 | on all inline declarations, another when | |
9609 | @option{-std=c99}, | |
9610 | @option{-std=gnu99} or an option for a later C version is used | |
9611 | (without @option{-fgnu89-inline}), and the third | |
9612 | is used when compiling C++. | |
9613 | ||
9614 | To declare a function inline, use the @code{inline} keyword in its | |
9615 | declaration, like this: | |
9616 | ||
9617 | @smallexample | |
9618 | static inline int | |
9619 | inc (int *a) | |
9620 | @{ | |
9621 | return (*a)++; | |
9622 | @} | |
9623 | @end smallexample | |
9624 | ||
9625 | If you are writing a header file to be included in ISO C90 programs, write | |
9626 | @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. | |
9627 | ||
9628 | The three types of inlining behave similarly in two important cases: | |
9629 | when the @code{inline} keyword is used on a @code{static} function, | |
9630 | like the example above, and when a function is first declared without | |
9631 | using the @code{inline} keyword and then is defined with | |
9632 | @code{inline}, like this: | |
9633 | ||
9634 | @smallexample | |
9635 | extern int inc (int *a); | |
9636 | inline int | |
9637 | inc (int *a) | |
9638 | @{ | |
9639 | return (*a)++; | |
9640 | @} | |
9641 | @end smallexample | |
9642 | ||
9643 | In both of these common cases, the program behaves the same as if you | |
9644 | had not used the @code{inline} keyword, except for its speed. | |
9645 | ||
9646 | @cindex inline functions, omission of | |
9647 | @opindex fkeep-inline-functions | |
9648 | When a function is both inline and @code{static}, if all calls to the | |
9649 | function are integrated into the caller, and the function's address is | |
9650 | never used, then the function's own assembler code is never referenced. | |
9651 | In this case, GCC does not actually output assembler code for the | |
9652 | function, unless you specify the option @option{-fkeep-inline-functions}. | |
9653 | If there is a nonintegrated call, then the function is compiled to | |
9654 | assembler code as usual. The function must also be compiled as usual if | |
9655 | the program refers to its address, because that cannot be inlined. | |
9656 | ||
9657 | @opindex Winline | |
9658 | Note that certain usages in a function definition can make it unsuitable | |
9659 | for inline substitution. Among these usages are: variadic functions, | |
9660 | use of @code{alloca}, use of computed goto (@pxref{Labels as Values}), | |
9661 | use of nonlocal goto, use of nested functions, use of @code{setjmp}, use | |
9662 | of @code{__builtin_longjmp} and use of @code{__builtin_return} or | |
9663 | @code{__builtin_apply_args}. Using @option{-Winline} warns when a | |
9664 | function marked @code{inline} could not be substituted, and gives the | |
9665 | reason for the failure. | |
9666 | ||
9667 | @cindex automatic @code{inline} for C++ member fns | |
9668 | @cindex @code{inline} automatic for C++ member fns | |
9669 | @cindex member fns, automatically @code{inline} | |
9670 | @cindex C++ member fns, automatically @code{inline} | |
9671 | @opindex fno-default-inline | |
9672 | As required by ISO C++, GCC considers member functions defined within | |
9673 | the body of a class to be marked inline even if they are | |
9674 | not explicitly declared with the @code{inline} keyword. You can | |
9675 | override this with @option{-fno-default-inline}; @pxref{C++ Dialect | |
9676 | Options,,Options Controlling C++ Dialect}. | |
9677 | ||
9678 | GCC does not inline any functions when not optimizing unless you specify | |
9679 | the @samp{always_inline} attribute for the function, like this: | |
9680 | ||
9681 | @smallexample | |
9682 | /* @r{Prototype.} */ | |
9683 | inline void foo (const char) __attribute__((always_inline)); | |
9684 | @end smallexample | |
9685 | ||
9686 | The remainder of this section is specific to GNU C90 inlining. | |
9687 | ||
9688 | @cindex non-static inline function | |
9689 | When an inline function is not @code{static}, then the compiler must assume | |
9690 | that there may be calls from other source files; since a global symbol can | |
9691 | be defined only once in any program, the function must not be defined in | |
9692 | the other source files, so the calls therein cannot be integrated. | |
9693 | Therefore, a non-@code{static} inline function is always compiled on its | |
9694 | own in the usual fashion. | |
9695 | ||
9696 | If you specify both @code{inline} and @code{extern} in the function | |
9697 | definition, then the definition is used only for inlining. In no case | |
9698 | is the function compiled on its own, not even if you refer to its | |
9699 | address explicitly. Such an address becomes an external reference, as | |
9700 | if you had only declared the function, and had not defined it. | |
9701 | ||
9702 | This combination of @code{inline} and @code{extern} has almost the | |
9703 | effect of a macro. The way to use it is to put a function definition in | |
9704 | a header file with these keywords, and put another copy of the | |
9705 | definition (lacking @code{inline} and @code{extern}) in a library file. | |
9706 | The definition in the header file causes most calls to the function | |
9707 | to be inlined. If any uses of the function remain, they refer to | |
9708 | the single copy in the library. | |
9709 | ||
9710 | @node Volatiles | |
9711 | @section When is a Volatile Object Accessed? | |
9712 | @cindex accessing volatiles | |
9713 | @cindex volatile read | |
9714 | @cindex volatile write | |
9715 | @cindex volatile access | |
9716 | ||
9717 | C has the concept of volatile objects. These are normally accessed by | |
9718 | pointers and used for accessing hardware or inter-thread | |
9719 | communication. The standard encourages compilers to refrain from | |
9720 | optimizations concerning accesses to volatile objects, but leaves it | |
9721 | implementation defined as to what constitutes a volatile access. The | |
9722 | minimum requirement is that at a sequence point all previous accesses | |
9723 | to volatile objects have stabilized and no subsequent accesses have | |
9724 | occurred. Thus an implementation is free to reorder and combine | |
9725 | volatile accesses that occur between sequence points, but cannot do | |
9726 | so for accesses across a sequence point. The use of volatile does | |
9727 | not allow you to violate the restriction on updating objects multiple | |
9728 | times between two sequence points. | |
9729 | ||
9730 | Accesses to non-volatile objects are not ordered with respect to | |
9731 | volatile accesses. You cannot use a volatile object as a memory | |
9732 | barrier to order a sequence of writes to non-volatile memory. For | |
9733 | instance: | |
9734 | ||
9735 | @smallexample | |
9736 | int *ptr = @var{something}; | |
9737 | volatile int vobj; | |
9738 | *ptr = @var{something}; | |
9739 | vobj = 1; | |
9740 | @end smallexample | |
9741 | ||
9742 | @noindent | |
9743 | Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed | |
9744 | that the write to @var{*ptr} occurs by the time the update | |
9745 | of @var{vobj} happens. If you need this guarantee, you must use | |
9746 | a stronger memory barrier such as: | |
9747 | ||
9748 | @smallexample | |
9749 | int *ptr = @var{something}; | |
9750 | volatile int vobj; | |
9751 | *ptr = @var{something}; | |
9752 | asm volatile ("" : : : "memory"); | |
9753 | vobj = 1; | |
9754 | @end smallexample | |
9755 | ||
9756 | A scalar volatile object is read when it is accessed in a void context: | |
9757 | ||
9758 | @smallexample | |
9759 | volatile int *src = @var{somevalue}; | |
9760 | *src; | |
9761 | @end smallexample | |
9762 | ||
9763 | Such expressions are rvalues, and GCC implements this as a | |
9764 | read of the volatile object being pointed to. | |
9765 | ||
9766 | Assignments are also expressions and have an rvalue. However when | |
9767 | assigning to a scalar volatile, the volatile object is not reread, | |
9768 | regardless of whether the assignment expression's rvalue is used or | |
9769 | not. If the assignment's rvalue is used, the value is that assigned | |
9770 | to the volatile object. For instance, there is no read of @var{vobj} | |
9771 | in all the following cases: | |
9772 | ||
9773 | @smallexample | |
9774 | int obj; | |
9775 | volatile int vobj; | |
9776 | vobj = @var{something}; | |
9777 | obj = vobj = @var{something}; | |
9778 | obj ? vobj = @var{onething} : vobj = @var{anotherthing}; | |
9779 | obj = (@var{something}, vobj = @var{anotherthing}); | |
9780 | @end smallexample | |
9781 | ||
9782 | If you need to read the volatile object after an assignment has | |
9783 | occurred, you must use a separate expression with an intervening | |
9784 | sequence point. | |
9785 | ||
9786 | As bit-fields are not individually addressable, volatile bit-fields may | |
9787 | be implicitly read when written to, or when adjacent bit-fields are | |
9788 | accessed. Bit-field operations may be optimized such that adjacent | |
9789 | bit-fields are only partially accessed, if they straddle a storage unit | |
9790 | boundary. For these reasons it is unwise to use volatile bit-fields to | |
9791 | access hardware. | |
9792 | ||
9793 | @node Using Assembly Language with C | |
9794 | @section How to Use Inline Assembly Language in C Code | |
9795 | @cindex @code{asm} keyword | |
9796 | @cindex assembly language in C | |
9797 | @cindex inline assembly language | |
9798 | @cindex mixing assembly language and C | |
9799 | ||
9800 | The @code{asm} keyword allows you to embed assembler instructions | |
9801 | within C code. GCC provides two forms of inline @code{asm} | |
9802 | statements. A @dfn{basic @code{asm}} statement is one with no | |
9803 | operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}} | |
9804 | statement (@pxref{Extended Asm}) includes one or more operands. | |
9805 | The extended form is preferred for mixing C and assembly language | |
9806 | within a function, but to include assembly language at | |
9807 | top level you must use basic @code{asm}. | |
9808 | ||
9809 | You can also use the @code{asm} keyword to override the assembler name | |
9810 | for a C symbol, or to place a C variable in a specific register. | |
9811 | ||
9812 | @menu | |
9813 | * Basic Asm:: Inline assembler without operands. | |
9814 | * Extended Asm:: Inline assembler with operands. | |
9815 | * Constraints:: Constraints for @code{asm} operands | |
9816 | * Asm Labels:: Specifying the assembler name to use for a C symbol. | |
9817 | * Explicit Register Variables:: Defining variables residing in specified | |
9818 | registers. | |
9819 | * Size of an asm:: How GCC calculates the size of an @code{asm} block. | |
9820 | @end menu | |
9821 | ||
9822 | @node Basic Asm | |
9823 | @subsection Basic Asm --- Assembler Instructions Without Operands | |
9824 | @cindex basic @code{asm} | |
9825 | @cindex assembly language in C, basic | |
9826 | ||
9827 | A basic @code{asm} statement has the following syntax: | |
9828 | ||
9829 | @example | |
9830 | asm @var{asm-qualifiers} ( @var{AssemblerInstructions} ) | |
9831 | @end example | |
9832 | ||
9833 | For the C language, the @code{asm} keyword is a GNU extension. | |
9834 | When writing C code that can be compiled with @option{-ansi} and the | |
9835 | @option{-std} options that select C dialects without GNU extensions, use | |
9836 | @code{__asm__} instead of @code{asm} (@pxref{Alternate Keywords}). For | |
9837 | the C++ language, @code{asm} is a standard keyword, but @code{__asm__} | |
9838 | can be used for code compiled with @option{-fno-asm}. | |
9839 | ||
9840 | @subsubheading Qualifiers | |
9841 | @table @code | |
9842 | @item volatile | |
9843 | The optional @code{volatile} qualifier has no effect. | |
9844 | All basic @code{asm} blocks are implicitly volatile. | |
9845 | ||
9846 | @item inline | |
9847 | If you use the @code{inline} qualifier, then for inlining purposes the size | |
9848 | of the @code{asm} statement is taken as the smallest size possible (@pxref{Size | |
9849 | of an asm}). | |
9850 | @end table | |
9851 | ||
9852 | @subsubheading Parameters | |
9853 | @table @var | |
9854 | ||
9855 | @item AssemblerInstructions | |
9856 | This is a literal string that specifies the assembler code. The string can | |
9857 | contain any instructions recognized by the assembler, including directives. | |
9858 | GCC does not parse the assembler instructions themselves and | |
9859 | does not know what they mean or even whether they are valid assembler input. | |
9860 | ||
9861 | You may place multiple assembler instructions together in a single @code{asm} | |
9862 | string, separated by the characters normally used in assembly code for the | |
9863 | system. A combination that works in most places is a newline to break the | |
9864 | line, plus a tab character (written as @samp{\n\t}). | |
9865 | Some assemblers allow semicolons as a line separator. However, | |
9866 | note that some assembler dialects use semicolons to start a comment. | |
9867 | @end table | |
9868 | ||
9869 | @subsubheading Remarks | |
9870 | Using extended @code{asm} (@pxref{Extended Asm}) typically produces | |
9871 | smaller, safer, and more efficient code, and in most cases it is a | |
9872 | better solution than basic @code{asm}. However, there are two | |
9873 | situations where only basic @code{asm} can be used: | |
9874 | ||
9875 | @itemize @bullet | |
9876 | @item | |
9877 | Extended @code{asm} statements have to be inside a C | |
9878 | function, so to write inline assembly language at file scope (``top-level''), | |
9879 | outside of C functions, you must use basic @code{asm}. | |
9880 | You can use this technique to emit assembler directives, | |
9881 | define assembly language macros that can be invoked elsewhere in the file, | |
9882 | or write entire functions in assembly language. | |
9883 | Basic @code{asm} statements outside of functions may not use any | |
9884 | qualifiers. | |
9885 | ||
9886 | @item | |
9887 | Functions declared | |
9888 | with the @code{naked} attribute also require basic @code{asm} | |
9889 | (@pxref{Function Attributes}). | |
9890 | @end itemize | |
9891 | ||
9892 | Safely accessing C data and calling functions from basic @code{asm} is more | |
9893 | complex than it may appear. To access C data, it is better to use extended | |
9894 | @code{asm}. | |
9895 | ||
9896 | Do not expect a sequence of @code{asm} statements to remain perfectly | |
9897 | consecutive after compilation. If certain instructions need to remain | |
9898 | consecutive in the output, put them in a single multi-instruction @code{asm} | |
9899 | statement. Note that GCC's optimizers can move @code{asm} statements | |
9900 | relative to other code, including across jumps. | |
9901 | ||
9902 | @code{asm} statements may not perform jumps into other @code{asm} statements. | |
9903 | GCC does not know about these jumps, and therefore cannot take | |
9904 | account of them when deciding how to optimize. Jumps from @code{asm} to C | |
9905 | labels are only supported in extended @code{asm}. | |
9906 | ||
9907 | Under certain circumstances, GCC may duplicate (or remove duplicates of) your | |
9908 | assembly code when optimizing. This can lead to unexpected duplicate | |
9909 | symbol errors during compilation if your assembly code defines symbols or | |
9910 | labels. | |
9911 | ||
9912 | @strong{Warning:} The C standards do not specify semantics for @code{asm}, | |
9913 | making it a potential source of incompatibilities between compilers. These | |
9914 | incompatibilities may not produce compiler warnings/errors. | |
9915 | ||
9916 | GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which | |
9917 | means there is no way to communicate to the compiler what is happening | |
9918 | inside them. GCC has no visibility of symbols in the @code{asm} and may | |
9919 | discard them as unreferenced. It also does not know about side effects of | |
9920 | the assembler code, such as modifications to memory or registers. Unlike | |
9921 | some compilers, GCC assumes that no changes to general purpose registers | |
9922 | occur. This assumption may change in a future release. | |
9923 | ||
9924 | To avoid complications from future changes to the semantics and the | |
9925 | compatibility issues between compilers, consider replacing basic @code{asm} | |
9926 | with extended @code{asm}. See | |
9927 | @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert | |
9928 | from basic asm to extended asm} for information about how to perform this | |
9929 | conversion. | |
9930 | ||
9931 | The compiler copies the assembler instructions in a basic @code{asm} | |
9932 | verbatim to the assembly language output file, without | |
9933 | processing dialects or any of the @samp{%} operators that are available with | |
9934 | extended @code{asm}. This results in minor differences between basic | |
9935 | @code{asm} strings and extended @code{asm} templates. For example, to refer to | |
9936 | registers you might use @samp{%eax} in basic @code{asm} and | |
9937 | @samp{%%eax} in extended @code{asm}. | |
9938 | ||
9939 | On targets such as x86 that support multiple assembler dialects, | |
9940 | all basic @code{asm} blocks use the assembler dialect specified by the | |
9941 | @option{-masm} command-line option (@pxref{x86 Options}). | |
9942 | Basic @code{asm} provides no | |
9943 | mechanism to provide different assembler strings for different dialects. | |
9944 | ||
9945 | For basic @code{asm} with non-empty assembler string GCC assumes | |
9946 | the assembler block does not change any general purpose registers, | |
9947 | but it may read or write any globally accessible variable. | |
9948 | ||
9949 | Here is an example of basic @code{asm} for i386: | |
9950 | ||
9951 | @example | |
9952 | /* Note that this code will not compile with -masm=intel */ | |
9953 | #define DebugBreak() asm("int $3") | |
9954 | @end example | |
9955 | ||
9956 | @node Extended Asm | |
9957 | @subsection Extended Asm - Assembler Instructions with C Expression Operands | |
9958 | @cindex extended @code{asm} | |
9959 | @cindex assembly language in C, extended | |
9960 | ||
9961 | With extended @code{asm} you can read and write C variables from | |
9962 | assembler and perform jumps from assembler code to C labels. | |
9963 | Extended @code{asm} syntax uses colons (@samp{:}) to delimit | |
9964 | the operand parameters after the assembler template: | |
9965 | ||
9966 | @example | |
9967 | asm @var{asm-qualifiers} ( @var{AssemblerTemplate} | |
9968 | : @var{OutputOperands} | |
9969 | @r{[} : @var{InputOperands} | |
9970 | @r{[} : @var{Clobbers} @r{]} @r{]}) | |
9971 | ||
9972 | asm @var{asm-qualifiers} ( @var{AssemblerTemplate} | |
9973 | : @var{OutputOperands} | |
9974 | : @var{InputOperands} | |
9975 | : @var{Clobbers} | |
9976 | : @var{GotoLabels}) | |
9977 | @end example | |
9978 | where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the | |
9979 | first form, not). | |
9980 | ||
9981 | The @code{asm} keyword is a GNU extension. | |
9982 | When writing code that can be compiled with @option{-ansi} and the | |
9983 | various @option{-std} options, use @code{__asm__} instead of | |
9984 | @code{asm} (@pxref{Alternate Keywords}). | |
9985 | ||
9986 | @subsubheading Qualifiers | |
9987 | @table @code | |
9988 | ||
9989 | @item volatile | |
9990 | The typical use of extended @code{asm} statements is to manipulate input | |
9991 | values to produce output values. However, your @code{asm} statements may | |
9992 | also produce side effects. If so, you may need to use the @code{volatile} | |
9993 | qualifier to disable certain optimizations. @xref{Volatile}. | |
9994 | ||
9995 | @item inline | |
9996 | If you use the @code{inline} qualifier, then for inlining purposes the size | |
9997 | of the @code{asm} statement is taken as the smallest size possible | |
9998 | (@pxref{Size of an asm}). | |
9999 | ||
10000 | @item goto | |
10001 | This qualifier informs the compiler that the @code{asm} statement may | |
10002 | perform a jump to one of the labels listed in the @var{GotoLabels}. | |
10003 | @xref{GotoLabels}. | |
10004 | @end table | |
10005 | ||
10006 | @subsubheading Parameters | |
10007 | @table @var | |
10008 | @item AssemblerTemplate | |
10009 | This is a literal string that is the template for the assembler code. It is a | |
10010 | combination of fixed text and tokens that refer to the input, output, | |
10011 | and goto parameters. @xref{AssemblerTemplate}. | |
10012 | ||
10013 | @item OutputOperands | |
10014 | A comma-separated list of the C variables modified by the instructions in the | |
10015 | @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}. | |
10016 | ||
10017 | @item InputOperands | |
10018 | A comma-separated list of C expressions read by the instructions in the | |
10019 | @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}. | |
10020 | ||
10021 | @item Clobbers | |
10022 | A comma-separated list of registers or other values changed by the | |
10023 | @var{AssemblerTemplate}, beyond those listed as outputs. | |
10024 | An empty list is permitted. @xref{Clobbers and Scratch Registers}. | |
10025 | ||
10026 | @item GotoLabels | |
10027 | When you are using the @code{goto} form of @code{asm}, this section contains | |
10028 | the list of all C labels to which the code in the | |
10029 | @var{AssemblerTemplate} may jump. | |
10030 | @xref{GotoLabels}. | |
10031 | ||
10032 | @code{asm} statements may not perform jumps into other @code{asm} statements, | |
10033 | only to the listed @var{GotoLabels}. | |
10034 | GCC's optimizers do not know about other jumps; therefore they cannot take | |
10035 | account of them when deciding how to optimize. | |
10036 | @end table | |
10037 | ||
10038 | The total number of input + output + goto operands is limited to 30. | |
10039 | ||
10040 | @subsubheading Remarks | |
10041 | The @code{asm} statement allows you to include assembly instructions directly | |
10042 | within C code. This may help you to maximize performance in time-sensitive | |
10043 | code or to access assembly instructions that are not readily available to C | |
10044 | programs. | |
10045 | ||
10046 | Note that extended @code{asm} statements must be inside a function. Only | |
10047 | basic @code{asm} may be outside functions (@pxref{Basic Asm}). | |
10048 | Functions declared with the @code{naked} attribute also require basic | |
10049 | @code{asm} (@pxref{Function Attributes}). | |
10050 | ||
10051 | While the uses of @code{asm} are many and varied, it may help to think of an | |
10052 | @code{asm} statement as a series of low-level instructions that convert input | |
10053 | parameters to output parameters. So a simple (if not particularly useful) | |
10054 | example for i386 using @code{asm} might look like this: | |
10055 | ||
10056 | @example | |
10057 | int src = 1; | |
10058 | int dst; | |
10059 | ||
10060 | asm ("mov %1, %0\n\t" | |
10061 | "add $1, %0" | |
10062 | : "=r" (dst) | |
10063 | : "r" (src)); | |
10064 | ||
10065 | printf("%d\n", dst); | |
10066 | @end example | |
10067 | ||
10068 | This code copies @code{src} to @code{dst} and add 1 to @code{dst}. | |
10069 | ||
10070 | @anchor{Volatile} | |
10071 | @subsubsection Volatile | |
10072 | @cindex volatile @code{asm} | |
10073 | @cindex @code{asm} volatile | |
10074 | ||
10075 | GCC's optimizers sometimes discard @code{asm} statements if they determine | |
10076 | there is no need for the output variables. Also, the optimizers may move | |
10077 | code out of loops if they believe that the code will always return the same | |
10078 | result (i.e.@: none of its input values change between calls). Using the | |
10079 | @code{volatile} qualifier disables these optimizations. @code{asm} statements | |
10080 | that have no output operands and @code{asm goto} statements, | |
10081 | are implicitly volatile. | |
10082 | ||
10083 | This i386 code demonstrates a case that does not use (or require) the | |
10084 | @code{volatile} qualifier. If it is performing assertion checking, this code | |
10085 | uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is | |
10086 | unreferenced by any code. As a result, the optimizers can discard the | |
10087 | @code{asm} statement, which in turn removes the need for the entire | |
10088 | @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it | |
10089 | isn't needed you allow the optimizers to produce the most efficient code | |
10090 | possible. | |
10091 | ||
10092 | @example | |
10093 | void DoCheck(uint32_t dwSomeValue) | |
10094 | @{ | |
10095 | uint32_t dwRes; | |
10096 | ||
10097 | // Assumes dwSomeValue is not zero. | |
10098 | asm ("bsfl %1,%0" | |
10099 | : "=r" (dwRes) | |
10100 | : "r" (dwSomeValue) | |
10101 | : "cc"); | |
10102 | ||
10103 | assert(dwRes > 3); | |
10104 | @} | |
10105 | @end example | |
10106 | ||
10107 | The next example shows a case where the optimizers can recognize that the input | |
10108 | (@code{dwSomeValue}) never changes during the execution of the function and can | |
10109 | therefore move the @code{asm} outside the loop to produce more efficient code. | |
10110 | Again, using the @code{volatile} qualifier disables this type of optimization. | |
10111 | ||
10112 | @example | |
10113 | void do_print(uint32_t dwSomeValue) | |
10114 | @{ | |
10115 | uint32_t dwRes; | |
10116 | ||
10117 | for (uint32_t x=0; x < 5; x++) | |
10118 | @{ | |
10119 | // Assumes dwSomeValue is not zero. | |
10120 | asm ("bsfl %1,%0" | |
10121 | : "=r" (dwRes) | |
10122 | : "r" (dwSomeValue) | |
10123 | : "cc"); | |
10124 | ||
10125 | printf("%u: %u %u\n", x, dwSomeValue, dwRes); | |
10126 | @} | |
10127 | @} | |
10128 | @end example | |
10129 | ||
10130 | The following example demonstrates a case where you need to use the | |
10131 | @code{volatile} qualifier. | |
10132 | It uses the x86 @code{rdtsc} instruction, which reads | |
10133 | the computer's time-stamp counter. Without the @code{volatile} qualifier, | |
10134 | the optimizers might assume that the @code{asm} block will always return the | |
10135 | same value and therefore optimize away the second call. | |
10136 | ||
10137 | @example | |
10138 | uint64_t msr; | |
10139 | ||
10140 | asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. | |
10141 | "shl $32, %%rdx\n\t" // Shift the upper bits left. | |
10142 | "or %%rdx, %0" // 'Or' in the lower bits. | |
10143 | : "=a" (msr) | |
10144 | : | |
10145 | : "rdx"); | |
10146 | ||
10147 | printf("msr: %llx\n", msr); | |
10148 | ||
10149 | // Do other work... | |
10150 | ||
10151 | // Reprint the timestamp | |
10152 | asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. | |
10153 | "shl $32, %%rdx\n\t" // Shift the upper bits left. | |
10154 | "or %%rdx, %0" // 'Or' in the lower bits. | |
10155 | : "=a" (msr) | |
10156 | : | |
10157 | : "rdx"); | |
10158 | ||
10159 | printf("msr: %llx\n", msr); | |
10160 | @end example | |
10161 | ||
10162 | GCC's optimizers do not treat this code like the non-volatile code in the | |
10163 | earlier examples. They do not move it out of loops or omit it on the | |
10164 | assumption that the result from a previous call is still valid. | |
10165 | ||
10166 | Note that the compiler can move even @code{volatile asm} instructions relative | |
10167 | to other code, including across jump instructions. For example, on many | |
10168 | targets there is a system register that controls the rounding mode of | |
10169 | floating-point operations. Setting it with a @code{volatile asm} statement, | |
10170 | as in the following PowerPC example, does not work reliably. | |
10171 | ||
10172 | @example | |
10173 | asm volatile("mtfsf 255, %0" : : "f" (fpenv)); | |
10174 | sum = x + y; | |
10175 | @end example | |
10176 | ||
10177 | The compiler may move the addition back before the @code{volatile asm} | |
10178 | statement. To make it work as expected, add an artificial dependency to | |
10179 | the @code{asm} by referencing a variable in the subsequent code, for | |
10180 | example: | |
10181 | ||
10182 | @example | |
10183 | asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv)); | |
10184 | sum = x + y; | |
10185 | @end example | |
10186 | ||
10187 | Under certain circumstances, GCC may duplicate (or remove duplicates of) your | |
10188 | assembly code when optimizing. This can lead to unexpected duplicate symbol | |
10189 | errors during compilation if your @code{asm} code defines symbols or labels. | |
10190 | Using @samp{%=} | |
10191 | (@pxref{AssemblerTemplate}) may help resolve this problem. | |
10192 | ||
10193 | @anchor{AssemblerTemplate} | |
10194 | @subsubsection Assembler Template | |
10195 | @cindex @code{asm} assembler template | |
10196 | ||
10197 | An assembler template is a literal string containing assembler instructions. | |
10198 | The compiler replaces tokens in the template that refer | |
10199 | to inputs, outputs, and goto labels, | |
10200 | and then outputs the resulting string to the assembler. The | |
10201 | string can contain any instructions recognized by the assembler, including | |
10202 | directives. GCC does not parse the assembler instructions | |
10203 | themselves and does not know what they mean or even whether they are valid | |
10204 | assembler input. However, it does count the statements | |
10205 | (@pxref{Size of an asm}). | |
10206 | ||
10207 | You may place multiple assembler instructions together in a single @code{asm} | |
10208 | string, separated by the characters normally used in assembly code for the | |
10209 | system. A combination that works in most places is a newline to break the | |
10210 | line, plus a tab character to move to the instruction field (written as | |
10211 | @samp{\n\t}). | |
10212 | Some assemblers allow semicolons as a line separator. However, note | |
10213 | that some assembler dialects use semicolons to start a comment. | |
10214 | ||
10215 | Do not expect a sequence of @code{asm} statements to remain perfectly | |
10216 | consecutive after compilation, even when you are using the @code{volatile} | |
10217 | qualifier. If certain instructions need to remain consecutive in the output, | |
10218 | put them in a single multi-instruction @code{asm} statement. | |
10219 | ||
10220 | Accessing data from C programs without using input/output operands (such as | |
10221 | by using global symbols directly from the assembler template) may not work as | |
10222 | expected. Similarly, calling functions directly from an assembler template | |
10223 | requires a detailed understanding of the target assembler and ABI. | |
10224 | ||
10225 | Since GCC does not parse the assembler template, | |
10226 | it has no visibility of any | |
10227 | symbols it references. This may result in GCC discarding those symbols as | |
10228 | unreferenced unless they are also listed as input, output, or goto operands. | |
10229 | ||
10230 | @subsubheading Special format strings | |
10231 | ||
10232 | In addition to the tokens described by the input, output, and goto operands, | |
10233 | these tokens have special meanings in the assembler template: | |
10234 | ||
10235 | @table @samp | |
10236 | @item %% | |
10237 | Outputs a single @samp{%} into the assembler code. | |
10238 | ||
10239 | @item %= | |
10240 | Outputs a number that is unique to each instance of the @code{asm} | |
10241 | statement in the entire compilation. This option is useful when creating local | |
10242 | labels and referring to them multiple times in a single template that | |
10243 | generates multiple assembler instructions. | |
10244 | ||
10245 | @item %@{ | |
10246 | @itemx %| | |
10247 | @itemx %@} | |
10248 | Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively) | |
10249 | into the assembler code. When unescaped, these characters have special | |
10250 | meaning to indicate multiple assembler dialects, as described below. | |
10251 | @end table | |
10252 | ||
10253 | @subsubheading Multiple assembler dialects in @code{asm} templates | |
10254 | ||
10255 | On targets such as x86, GCC supports multiple assembler dialects. | |
10256 | The @option{-masm} option controls which dialect GCC uses as its | |
10257 | default for inline assembler. The target-specific documentation for the | |
10258 | @option{-masm} option contains the list of supported dialects, as well as the | |
10259 | default dialect if the option is not specified. This information may be | |
10260 | important to understand, since assembler code that works correctly when | |
10261 | compiled using one dialect will likely fail if compiled using another. | |
10262 | @xref{x86 Options}. | |
10263 | ||
10264 | If your code needs to support multiple assembler dialects (for example, if | |
10265 | you are writing public headers that need to support a variety of compilation | |
10266 | options), use constructs of this form: | |
10267 | ||
10268 | @example | |
10269 | @{ dialect0 | dialect1 | dialect2... @} | |
10270 | @end example | |
10271 | ||
10272 | This construct outputs @code{dialect0} | |
10273 | when using dialect #0 to compile the code, | |
10274 | @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the | |
10275 | braces than the number of dialects the compiler supports, the construct | |
10276 | outputs nothing. | |
10277 | ||
10278 | For example, if an x86 compiler supports two dialects | |
10279 | (@samp{att}, @samp{intel}), an | |
10280 | assembler template such as this: | |
10281 | ||
10282 | @example | |
10283 | "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2" | |
10284 | @end example | |
10285 | ||
10286 | @noindent | |
10287 | is equivalent to one of | |
10288 | ||
10289 | @example | |
10290 | "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */} | |
10291 | "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */} | |
10292 | @end example | |
10293 | ||
10294 | Using that same compiler, this code: | |
10295 | ||
10296 | @example | |
10297 | "xchg@{l@}\t@{%%@}ebx, %1" | |
10298 | @end example | |
10299 | ||
10300 | @noindent | |
10301 | corresponds to either | |
10302 | ||
10303 | @example | |
10304 | "xchgl\t%%ebx, %1" @r{/* att dialect */} | |
10305 | "xchg\tebx, %1" @r{/* intel dialect */} | |
10306 | @end example | |
10307 | ||
10308 | There is no support for nesting dialect alternatives. | |
10309 | ||
10310 | @anchor{OutputOperands} | |
10311 | @subsubsection Output Operands | |
10312 | @cindex @code{asm} output operands | |
10313 | ||
10314 | An @code{asm} statement has zero or more output operands indicating the names | |
10315 | of C variables modified by the assembler code. | |
10316 | ||
10317 | In this i386 example, @code{old} (referred to in the template string as | |
10318 | @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset} | |
10319 | (@code{%2}) is an input: | |
10320 | ||
10321 | @example | |
10322 | bool old; | |
10323 | ||
10324 | __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base. | |
10325 | "sbb %0,%0" // Use the CF to calculate old. | |
10326 | : "=r" (old), "+rm" (*Base) | |
10327 | : "Ir" (Offset) | |
10328 | : "cc"); | |
10329 | ||
10330 | return old; | |
10331 | @end example | |
10332 | ||
10333 | Operands are separated by commas. Each operand has this format: | |
10334 | ||
10335 | @example | |
10336 | @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename}) | |
10337 | @end example | |
10338 | ||
10339 | @table @var | |
10340 | @item asmSymbolicName | |
10341 | Specifies a symbolic name for the operand. | |
10342 | Reference the name in the assembler template | |
10343 | by enclosing it in square brackets | |
10344 | (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement | |
10345 | that contains the definition. Any valid C variable name is acceptable, | |
10346 | including names already defined in the surrounding code. No two operands | |
10347 | within the same @code{asm} statement can use the same symbolic name. | |
10348 | ||
10349 | When not using an @var{asmSymbolicName}, use the (zero-based) position | |
10350 | of the operand | |
10351 | in the list of operands in the assembler template. For example if there are | |
10352 | three output operands, use @samp{%0} in the template to refer to the first, | |
10353 | @samp{%1} for the second, and @samp{%2} for the third. | |
10354 | ||
10355 | @item constraint | |
10356 | A string constant specifying constraints on the placement of the operand; | |
10357 | @xref{Constraints}, for details. | |
10358 | ||
10359 | Output constraints must begin with either @samp{=} (a variable overwriting an | |
10360 | existing value) or @samp{+} (when reading and writing). When using | |
10361 | @samp{=}, do not assume the location contains the existing value | |
10362 | on entry to the @code{asm}, except | |
10363 | when the operand is tied to an input; @pxref{InputOperands,,Input Operands}. | |
10364 | ||
10365 | After the prefix, there must be one or more additional constraints | |
10366 | (@pxref{Constraints}) that describe where the value resides. Common | |
10367 | constraints include @samp{r} for register and @samp{m} for memory. | |
10368 | When you list more than one possible location (for example, @code{"=rm"}), | |
10369 | the compiler chooses the most efficient one based on the current context. | |
10370 | If you list as many alternates as the @code{asm} statement allows, you permit | |
10371 | the optimizers to produce the best possible code. | |
10372 | If you must use a specific register, but your Machine Constraints do not | |
10373 | provide sufficient control to select the specific register you want, | |
10374 | local register variables may provide a solution (@pxref{Local Register | |
10375 | Variables}). | |
10376 | ||
10377 | @item cvariablename | |
10378 | Specifies a C lvalue expression to hold the output, typically a variable name. | |
10379 | The enclosing parentheses are a required part of the syntax. | |
10380 | ||
10381 | @end table | |
10382 | ||
10383 | When the compiler selects the registers to use to | |
10384 | represent the output operands, it does not use any of the clobbered registers | |
10385 | (@pxref{Clobbers and Scratch Registers}). | |
10386 | ||
10387 | Output operand expressions must be lvalues. The compiler cannot check whether | |
10388 | the operands have data types that are reasonable for the instruction being | |
10389 | executed. For output expressions that are not directly addressable (for | |
10390 | example a bit-field), the constraint must allow a register. In that case, GCC | |
10391 | uses the register as the output of the @code{asm}, and then stores that | |
10392 | register into the output. | |
10393 | ||
10394 | Operands using the @samp{+} constraint modifier count as two operands | |
10395 | (that is, both as input and output) towards the total maximum of 30 operands | |
10396 | per @code{asm} statement. | |
10397 | ||
10398 | Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output | |
10399 | operands that must not overlap an input. Otherwise, | |
10400 | GCC may allocate the output operand in the same register as an unrelated | |
10401 | input operand, on the assumption that the assembler code consumes its | |
10402 | inputs before producing outputs. This assumption may be false if the assembler | |
10403 | code actually consists of more than one instruction. | |
10404 | ||
10405 | The same problem can occur if one output parameter (@var{a}) allows a register | |
10406 | constraint and another output parameter (@var{b}) allows a memory constraint. | |
10407 | The code generated by GCC to access the memory address in @var{b} can contain | |
10408 | registers which @emph{might} be shared by @var{a}, and GCC considers those | |
10409 | registers to be inputs to the asm. As above, GCC assumes that such input | |
10410 | registers are consumed before any outputs are written. This assumption may | |
10411 | result in incorrect behavior if the @code{asm} statement writes to @var{a} | |
10412 | before using | |
10413 | @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a} | |
10414 | ensures that modifying @var{a} does not affect the address referenced by | |
10415 | @var{b}. Otherwise, the location of @var{b} | |
10416 | is undefined if @var{a} is modified before using @var{b}. | |
10417 | ||
10418 | @code{asm} supports operand modifiers on operands (for example @samp{%k2} | |
b5ea0f07 LC |
10419 | instead of simply @samp{%2}). @ref{GenericOperandmodifiers, |
10420 | Generic Operand modifiers} lists the modifiers that are available | |
10421 | on all targets. Other modifiers are hardware dependent. | |
10422 | For example, the list of supported modifiers for x86 is found at | |
d77de738 ML |
10423 | @ref{x86Operandmodifiers,x86 Operand modifiers}. |
10424 | ||
10425 | If the C code that follows the @code{asm} makes no use of any of the output | |
10426 | operands, use @code{volatile} for the @code{asm} statement to prevent the | |
10427 | optimizers from discarding the @code{asm} statement as unneeded | |
10428 | (see @ref{Volatile}). | |
10429 | ||
10430 | This code makes no use of the optional @var{asmSymbolicName}. Therefore it | |
10431 | references the first output operand as @code{%0} (were there a second, it | |
10432 | would be @code{%1}, etc). The number of the first input operand is one greater | |
10433 | than that of the last output operand. In this i386 example, that makes | |
10434 | @code{Mask} referenced as @code{%1}: | |
10435 | ||
10436 | @example | |
10437 | uint32_t Mask = 1234; | |
10438 | uint32_t Index; | |
10439 | ||
10440 | asm ("bsfl %1, %0" | |
10441 | : "=r" (Index) | |
10442 | : "r" (Mask) | |
10443 | : "cc"); | |
10444 | @end example | |
10445 | ||
10446 | That code overwrites the variable @code{Index} (@samp{=}), | |
10447 | placing the value in a register (@samp{r}). | |
10448 | Using the generic @samp{r} constraint instead of a constraint for a specific | |
10449 | register allows the compiler to pick the register to use, which can result | |
10450 | in more efficient code. This may not be possible if an assembler instruction | |
10451 | requires a specific register. | |
10452 | ||
10453 | The following i386 example uses the @var{asmSymbolicName} syntax. | |
10454 | It produces the | |
10455 | same result as the code above, but some may consider it more readable or more | |
10456 | maintainable since reordering index numbers is not necessary when adding or | |
10457 | removing operands. The names @code{aIndex} and @code{aMask} | |
10458 | are only used in this example to emphasize which | |
10459 | names get used where. | |
10460 | It is acceptable to reuse the names @code{Index} and @code{Mask}. | |
10461 | ||
10462 | @example | |
10463 | uint32_t Mask = 1234; | |
10464 | uint32_t Index; | |
10465 | ||
10466 | asm ("bsfl %[aMask], %[aIndex]" | |
10467 | : [aIndex] "=r" (Index) | |
10468 | : [aMask] "r" (Mask) | |
10469 | : "cc"); | |
10470 | @end example | |
10471 | ||
10472 | Here are some more examples of output operands. | |
10473 | ||
10474 | @example | |
10475 | uint32_t c = 1; | |
10476 | uint32_t d; | |
10477 | uint32_t *e = &c; | |
10478 | ||
10479 | asm ("mov %[e], %[d]" | |
10480 | : [d] "=rm" (d) | |
10481 | : [e] "rm" (*e)); | |
10482 | @end example | |
10483 | ||
10484 | Here, @code{d} may either be in a register or in memory. Since the compiler | |
10485 | might already have the current value of the @code{uint32_t} location | |
10486 | pointed to by @code{e} | |
10487 | in a register, you can enable it to choose the best location | |
10488 | for @code{d} by specifying both constraints. | |
10489 | ||
10490 | @anchor{FlagOutputOperands} | |
10491 | @subsubsection Flag Output Operands | |
10492 | @cindex @code{asm} flag output operands | |
10493 | ||
10494 | Some targets have a special register that holds the ``flags'' for the | |
10495 | result of an operation or comparison. Normally, the contents of that | |
10496 | register are either unmodifed by the asm, or the @code{asm} statement is | |
10497 | considered to clobber the contents. | |
10498 | ||
10499 | On some targets, a special form of output operand exists by which | |
10500 | conditions in the flags register may be outputs of the asm. The set of | |
10501 | conditions supported are target specific, but the general rule is that | |
10502 | the output variable must be a scalar integer, and the value is boolean. | |
10503 | When supported, the target defines the preprocessor symbol | |
10504 | @code{__GCC_ASM_FLAG_OUTPUTS__}. | |
10505 | ||
10506 | Because of the special nature of the flag output operands, the constraint | |
10507 | may not include alternatives. | |
10508 | ||
10509 | Most often, the target has only one flags register, and thus is an implied | |
10510 | operand of many instructions. In this case, the operand should not be | |
10511 | referenced within the assembler template via @code{%0} etc, as there's | |
10512 | no corresponding text in the assembly language. | |
10513 | ||
10514 | @table @asis | |
10515 | @item ARM | |
10516 | @itemx AArch64 | |
10517 | The flag output constraints for the ARM family are of the form | |
10518 | @samp{=@@cc@var{cond}} where @var{cond} is one of the standard | |
10519 | conditions defined in the ARM ARM for @code{ConditionHolds}. | |
10520 | ||
10521 | @table @code | |
10522 | @item eq | |
10523 | Z flag set, or equal | |
10524 | @item ne | |
10525 | Z flag clear or not equal | |
10526 | @item cs | |
10527 | @itemx hs | |
10528 | C flag set or unsigned greater than equal | |
10529 | @item cc | |
10530 | @itemx lo | |
10531 | C flag clear or unsigned less than | |
10532 | @item mi | |
10533 | N flag set or ``minus'' | |
10534 | @item pl | |
10535 | N flag clear or ``plus'' | |
10536 | @item vs | |
10537 | V flag set or signed overflow | |
10538 | @item vc | |
10539 | V flag clear | |
10540 | @item hi | |
10541 | unsigned greater than | |
10542 | @item ls | |
10543 | unsigned less than equal | |
10544 | @item ge | |
10545 | signed greater than equal | |
10546 | @item lt | |
10547 | signed less than | |
10548 | @item gt | |
10549 | signed greater than | |
10550 | @item le | |
10551 | signed less than equal | |
10552 | @end table | |
10553 | ||
10554 | The flag output constraints are not supported in thumb1 mode. | |
10555 | ||
10556 | @item x86 family | |
10557 | The flag output constraints for the x86 family are of the form | |
10558 | @samp{=@@cc@var{cond}} where @var{cond} is one of the standard | |
10559 | conditions defined in the ISA manual for @code{j@var{cc}} or | |
10560 | @code{set@var{cc}}. | |
10561 | ||
10562 | @table @code | |
10563 | @item a | |
10564 | ``above'' or unsigned greater than | |
10565 | @item ae | |
10566 | ``above or equal'' or unsigned greater than or equal | |
10567 | @item b | |
10568 | ``below'' or unsigned less than | |
10569 | @item be | |
10570 | ``below or equal'' or unsigned less than or equal | |
10571 | @item c | |
10572 | carry flag set | |
10573 | @item e | |
10574 | @itemx z | |
10575 | ``equal'' or zero flag set | |
10576 | @item g | |
10577 | signed greater than | |
10578 | @item ge | |
10579 | signed greater than or equal | |
10580 | @item l | |
10581 | signed less than | |
10582 | @item le | |
10583 | signed less than or equal | |
10584 | @item o | |
10585 | overflow flag set | |
10586 | @item p | |
10587 | parity flag set | |
10588 | @item s | |
10589 | sign flag set | |
10590 | @item na | |
10591 | @itemx nae | |
10592 | @itemx nb | |
10593 | @itemx nbe | |
10594 | @itemx nc | |
10595 | @itemx ne | |
10596 | @itemx ng | |
10597 | @itemx nge | |
10598 | @itemx nl | |
10599 | @itemx nle | |
10600 | @itemx no | |
10601 | @itemx np | |
10602 | @itemx ns | |
10603 | @itemx nz | |
10604 | ``not'' @var{flag}, or inverted versions of those above | |
10605 | @end table | |
10606 | ||
10607 | @end table | |
10608 | ||
10609 | @anchor{InputOperands} | |
10610 | @subsubsection Input Operands | |
10611 | @cindex @code{asm} input operands | |
10612 | @cindex @code{asm} expressions | |
10613 | ||
10614 | Input operands make values from C variables and expressions available to the | |
10615 | assembly code. | |
10616 | ||
10617 | Operands are separated by commas. Each operand has this format: | |
10618 | ||
10619 | @example | |
10620 | @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression}) | |
10621 | @end example | |
10622 | ||
10623 | @table @var | |
10624 | @item asmSymbolicName | |
10625 | Specifies a symbolic name for the operand. | |
10626 | Reference the name in the assembler template | |
10627 | by enclosing it in square brackets | |
10628 | (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement | |
10629 | that contains the definition. Any valid C variable name is acceptable, | |
10630 | including names already defined in the surrounding code. No two operands | |
10631 | within the same @code{asm} statement can use the same symbolic name. | |
10632 | ||
10633 | When not using an @var{asmSymbolicName}, use the (zero-based) position | |
10634 | of the operand | |
10635 | in the list of operands in the assembler template. For example if there are | |
10636 | two output operands and three inputs, | |
10637 | use @samp{%2} in the template to refer to the first input operand, | |
10638 | @samp{%3} for the second, and @samp{%4} for the third. | |
10639 | ||
10640 | @item constraint | |
10641 | A string constant specifying constraints on the placement of the operand; | |
10642 | @xref{Constraints}, for details. | |
10643 | ||
10644 | Input constraint strings may not begin with either @samp{=} or @samp{+}. | |
10645 | When you list more than one possible location (for example, @samp{"irm"}), | |
10646 | the compiler chooses the most efficient one based on the current context. | |
10647 | If you must use a specific register, but your Machine Constraints do not | |
10648 | provide sufficient control to select the specific register you want, | |
10649 | local register variables may provide a solution (@pxref{Local Register | |
10650 | Variables}). | |
10651 | ||
10652 | Input constraints can also be digits (for example, @code{"0"}). This indicates | |
10653 | that the specified input must be in the same place as the output constraint | |
10654 | at the (zero-based) index in the output constraint list. | |
10655 | When using @var{asmSymbolicName} syntax for the output operands, | |
10656 | you may use these names (enclosed in brackets @samp{[]}) instead of digits. | |
10657 | ||
10658 | @item cexpression | |
10659 | This is the C variable or expression being passed to the @code{asm} statement | |
10660 | as input. The enclosing parentheses are a required part of the syntax. | |
10661 | ||
10662 | @end table | |
10663 | ||
10664 | When the compiler selects the registers to use to represent the input | |
10665 | operands, it does not use any of the clobbered registers | |
10666 | (@pxref{Clobbers and Scratch Registers}). | |
10667 | ||
10668 | If there are no output operands but there are input operands, place two | |
10669 | consecutive colons where the output operands would go: | |
10670 | ||
10671 | @example | |
10672 | __asm__ ("some instructions" | |
10673 | : /* No outputs. */ | |
10674 | : "r" (Offset / 8)); | |
10675 | @end example | |
10676 | ||
10677 | @strong{Warning:} Do @emph{not} modify the contents of input-only operands | |
10678 | (except for inputs tied to outputs). The compiler assumes that on exit from | |
10679 | the @code{asm} statement these operands contain the same values as they | |
10680 | had before executing the statement. | |
10681 | It is @emph{not} possible to use clobbers | |
10682 | to inform the compiler that the values in these inputs are changing. One | |
10683 | common work-around is to tie the changing input variable to an output variable | |
10684 | that never gets used. Note, however, that if the code that follows the | |
10685 | @code{asm} statement makes no use of any of the output operands, the GCC | |
10686 | optimizers may discard the @code{asm} statement as unneeded | |
10687 | (see @ref{Volatile}). | |
10688 | ||
10689 | @code{asm} supports operand modifiers on operands (for example @samp{%k2} | |
b5ea0f07 LC |
10690 | instead of simply @samp{%2}). @ref{GenericOperandmodifiers, |
10691 | Generic Operand modifiers} lists the modifiers that are available | |
10692 | on all targets. Other modifiers are hardware dependent. | |
10693 | For example, the list of supported modifiers for x86 is found at | |
d77de738 ML |
10694 | @ref{x86Operandmodifiers,x86 Operand modifiers}. |
10695 | ||
10696 | In this example using the fictitious @code{combine} instruction, the | |
10697 | constraint @code{"0"} for input operand 1 says that it must occupy the same | |
10698 | location as output operand 0. Only input operands may use numbers in | |
10699 | constraints, and they must each refer to an output operand. Only a number (or | |
10700 | the symbolic assembler name) in the constraint can guarantee that one operand | |
10701 | is in the same place as another. The mere fact that @code{foo} is the value of | |
10702 | both operands is not enough to guarantee that they are in the same place in | |
10703 | the generated assembler code. | |
10704 | ||
10705 | @example | |
10706 | asm ("combine %2, %0" | |
10707 | : "=r" (foo) | |
10708 | : "0" (foo), "g" (bar)); | |
10709 | @end example | |
10710 | ||
10711 | Here is an example using symbolic names. | |
10712 | ||
10713 | @example | |
10714 | asm ("cmoveq %1, %2, %[result]" | |
10715 | : [result] "=r"(result) | |
10716 | : "r" (test), "r" (new), "[result]" (old)); | |
10717 | @end example | |
10718 | ||
10719 | @anchor{Clobbers and Scratch Registers} | |
10720 | @subsubsection Clobbers and Scratch Registers | |
10721 | @cindex @code{asm} clobbers | |
10722 | @cindex @code{asm} scratch registers | |
10723 | ||
10724 | While the compiler is aware of changes to entries listed in the output | |
10725 | operands, the inline @code{asm} code may modify more than just the outputs. For | |
10726 | example, calculations may require additional registers, or the processor may | |
10727 | overwrite a register as a side effect of a particular assembler instruction. | |
10728 | In order to inform the compiler of these changes, list them in the clobber | |
10729 | list. Clobber list items are either register names or the special clobbers | |
10730 | (listed below). Each clobber list item is a string constant | |
10731 | enclosed in double quotes and separated by commas. | |
10732 | ||
10733 | Clobber descriptions may not in any way overlap with an input or output | |
10734 | operand. For example, you may not have an operand describing a register class | |
10735 | with one member when listing that register in the clobber list. Variables | |
10736 | declared to live in specific registers (@pxref{Explicit Register | |
10737 | Variables}) and used | |
10738 | as @code{asm} input or output operands must have no part mentioned in the | |
10739 | clobber description. In particular, there is no way to specify that input | |
10740 | operands get modified without also specifying them as output operands. | |
10741 | ||
10742 | When the compiler selects which registers to use to represent input and output | |
10743 | operands, it does not use any of the clobbered registers. As a result, | |
10744 | clobbered registers are available for any use in the assembler code. | |
10745 | ||
10746 | Another restriction is that the clobber list should not contain the | |
10747 | stack pointer register. This is because the compiler requires the | |
10748 | value of the stack pointer to be the same after an @code{asm} | |
10749 | statement as it was on entry to the statement. However, previous | |
10750 | versions of GCC did not enforce this rule and allowed the stack | |
10751 | pointer to appear in the list, with unclear semantics. This behavior | |
10752 | is deprecated and listing the stack pointer may become an error in | |
10753 | future versions of GCC@. | |
10754 | ||
10755 | Here is a realistic example for the VAX showing the use of clobbered | |
10756 | registers: | |
10757 | ||
10758 | @example | |
10759 | asm volatile ("movc3 %0, %1, %2" | |
10760 | : /* No outputs. */ | |
10761 | : "g" (from), "g" (to), "g" (count) | |
10762 | : "r0", "r1", "r2", "r3", "r4", "r5", "memory"); | |
10763 | @end example | |
10764 | ||
10765 | Also, there are two special clobber arguments: | |
10766 | ||
10767 | @table @code | |
10768 | @item "cc" | |
10769 | The @code{"cc"} clobber indicates that the assembler code modifies the flags | |
10770 | register. On some machines, GCC represents the condition codes as a specific | |
10771 | hardware register; @code{"cc"} serves to name this register. | |
10772 | On other machines, condition code handling is different, | |
10773 | and specifying @code{"cc"} has no effect. But | |
10774 | it is valid no matter what the target. | |
10775 | ||
10776 | @item "memory" | |
10777 | The @code{"memory"} clobber tells the compiler that the assembly code | |
10778 | performs memory | |
10779 | reads or writes to items other than those listed in the input and output | |
10780 | operands (for example, accessing the memory pointed to by one of the input | |
10781 | parameters). To ensure memory contains correct values, GCC may need to flush | |
10782 | specific register values to memory before executing the @code{asm}. Further, | |
10783 | the compiler does not assume that any values read from memory before an | |
10784 | @code{asm} remain unchanged after that @code{asm}; it reloads them as | |
10785 | needed. | |
10786 | Using the @code{"memory"} clobber effectively forms a read/write | |
10787 | memory barrier for the compiler. | |
10788 | ||
10789 | Note that this clobber does not prevent the @emph{processor} from doing | |
10790 | speculative reads past the @code{asm} statement. To prevent that, you need | |
10791 | processor-specific fence instructions. | |
10792 | ||
10793 | @end table | |
10794 | ||
10795 | Flushing registers to memory has performance implications and may be | |
10796 | an issue for time-sensitive code. You can provide better information | |
10797 | to GCC to avoid this, as shown in the following examples. At a | |
10798 | minimum, aliasing rules allow GCC to know what memory @emph{doesn't} | |
10799 | need to be flushed. | |
10800 | ||
10801 | Here is a fictitious sum of squares instruction, that takes two | |
10802 | pointers to floating point values in memory and produces a floating | |
10803 | point register output. | |
10804 | Notice that @code{x}, and @code{y} both appear twice in the @code{asm} | |
10805 | parameters, once to specify memory accessed, and once to specify a | |
10806 | base register used by the @code{asm}. You won't normally be wasting a | |
10807 | register by doing this as GCC can use the same register for both | |
10808 | purposes. However, it would be foolish to use both @code{%1} and | |
10809 | @code{%3} for @code{x} in this @code{asm} and expect them to be the | |
10810 | same. In fact, @code{%3} may well not be a register. It might be a | |
10811 | symbolic memory reference to the object pointed to by @code{x}. | |
10812 | ||
10813 | @smallexample | |
10814 | asm ("sumsq %0, %1, %2" | |
10815 | : "+f" (result) | |
10816 | : "r" (x), "r" (y), "m" (*x), "m" (*y)); | |
10817 | @end smallexample | |
10818 | ||
10819 | Here is a fictitious @code{*z++ = *x++ * *y++} instruction. | |
10820 | Notice that the @code{x}, @code{y} and @code{z} pointer registers | |
10821 | must be specified as input/output because the @code{asm} modifies | |
10822 | them. | |
10823 | ||
10824 | @smallexample | |
10825 | asm ("vecmul %0, %1, %2" | |
10826 | : "+r" (z), "+r" (x), "+r" (y), "=m" (*z) | |
10827 | : "m" (*x), "m" (*y)); | |
10828 | @end smallexample | |
10829 | ||
10830 | An x86 example where the string memory argument is of unknown length. | |
10831 | ||
10832 | @smallexample | |
10833 | asm("repne scasb" | |
10834 | : "=c" (count), "+D" (p) | |
10835 | : "m" (*(const char (*)[]) p), "0" (-1), "a" (0)); | |
10836 | @end smallexample | |
10837 | ||
10838 | If you know the above will only be reading a ten byte array then you | |
10839 | could instead use a memory input like: | |
10840 | @code{"m" (*(const char (*)[10]) p)}. | |
10841 | ||
10842 | Here is an example of a PowerPC vector scale implemented in assembly, | |
10843 | complete with vector and condition code clobbers, and some initialized | |
10844 | offset registers that are unchanged by the @code{asm}. | |
10845 | ||
10846 | @smallexample | |
10847 | void | |
10848 | dscal (size_t n, double *x, double alpha) | |
10849 | @{ | |
10850 | asm ("/* lots of asm here */" | |
10851 | : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x) | |
10852 | : "d" (alpha), "b" (32), "b" (48), "b" (64), | |
10853 | "b" (80), "b" (96), "b" (112) | |
10854 | : "cr0", | |
10855 | "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39", | |
10856 | "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"); | |
10857 | @} | |
10858 | @end smallexample | |
10859 | ||
10860 | Rather than allocating fixed registers via clobbers to provide scratch | |
10861 | registers for an @code{asm} statement, an alternative is to define a | |
10862 | variable and make it an early-clobber output as with @code{a2} and | |
10863 | @code{a3} in the example below. This gives the compiler register | |
10864 | allocator more freedom. You can also define a variable and make it an | |
10865 | output tied to an input as with @code{a0} and @code{a1}, tied | |
10866 | respectively to @code{ap} and @code{lda}. Of course, with tied | |
10867 | outputs your @code{asm} can't use the input value after modifying the | |
10868 | output register since they are one and the same register. What's | |
10869 | more, if you omit the early-clobber on the output, it is possible that | |
10870 | GCC might allocate the same register to another of the inputs if GCC | |
10871 | could prove they had the same value on entry to the @code{asm}. This | |
10872 | is why @code{a1} has an early-clobber. Its tied input, @code{lda} | |
10873 | might conceivably be known to have the value 16 and without an | |
10874 | early-clobber share the same register as @code{%11}. On the other | |
10875 | hand, @code{ap} can't be the same as any of the other inputs, so an | |
10876 | early-clobber on @code{a0} is not needed. It is also not desirable in | |
10877 | this case. An early-clobber on @code{a0} would cause GCC to allocate | |
10878 | a separate register for the @code{"m" (*(const double (*)[]) ap)} | |
10879 | input. Note that tying an input to an output is the way to set up an | |
10880 | initialized temporary register modified by an @code{asm} statement. | |
10881 | An input not tied to an output is assumed by GCC to be unchanged, for | |
10882 | example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might | |
10883 | use that register in following code if the value 16 happened to be | |
10884 | needed. You can even use a normal @code{asm} output for a scratch if | |
10885 | all inputs that might share the same register are consumed before the | |
10886 | scratch is used. The VSX registers clobbered by the @code{asm} | |
10887 | statement could have used this technique except for GCC's limit on the | |
10888 | number of @code{asm} parameters. | |
10889 | ||
10890 | @smallexample | |
10891 | static void | |
10892 | dgemv_kernel_4x4 (long n, const double *ap, long lda, | |
10893 | const double *x, double *y, double alpha) | |
10894 | @{ | |
10895 | double *a0; | |
10896 | double *a1; | |
10897 | double *a2; | |
10898 | double *a3; | |
10899 | ||
10900 | __asm__ | |
10901 | ( | |
10902 | /* lots of asm here */ | |
10903 | "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n" | |
10904 | "#a0=%3 a1=%4 a2=%5 a3=%6" | |
10905 | : | |
10906 | "+m" (*(double (*)[n]) y), | |
10907 | "+&r" (n), // 1 | |
10908 | "+b" (y), // 2 | |
10909 | "=b" (a0), // 3 | |
10910 | "=&b" (a1), // 4 | |
10911 | "=&b" (a2), // 5 | |
10912 | "=&b" (a3) // 6 | |
10913 | : | |
10914 | "m" (*(const double (*)[n]) x), | |
10915 | "m" (*(const double (*)[]) ap), | |
10916 | "d" (alpha), // 9 | |
10917 | "r" (x), // 10 | |
10918 | "b" (16), // 11 | |
10919 | "3" (ap), // 12 | |
10920 | "4" (lda) // 13 | |
10921 | : | |
10922 | "cr0", | |
10923 | "vs32","vs33","vs34","vs35","vs36","vs37", | |
10924 | "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47" | |
10925 | ); | |
10926 | @} | |
10927 | @end smallexample | |
10928 | ||
10929 | @anchor{GotoLabels} | |
10930 | @subsubsection Goto Labels | |
10931 | @cindex @code{asm} goto labels | |
10932 | ||
10933 | @code{asm goto} allows assembly code to jump to one or more C labels. The | |
10934 | @var{GotoLabels} section in an @code{asm goto} statement contains | |
10935 | a comma-separated | |
10936 | list of all C labels to which the assembler code may jump. GCC assumes that | |
10937 | @code{asm} execution falls through to the next statement (if this is not the | |
10938 | case, consider using the @code{__builtin_unreachable} intrinsic after the | |
10939 | @code{asm} statement). Optimization of @code{asm goto} may be improved by | |
10940 | using the @code{hot} and @code{cold} label attributes (@pxref{Label | |
10941 | Attributes}). | |
10942 | ||
10943 | If the assembler code does modify anything, use the @code{"memory"} clobber | |
10944 | to force the | |
10945 | optimizers to flush all register values to memory and reload them if | |
10946 | necessary after the @code{asm} statement. | |
10947 | ||
10948 | Also note that an @code{asm goto} statement is always implicitly | |
10949 | considered volatile. | |
10950 | ||
10951 | Be careful when you set output operands inside @code{asm goto} only on | |
10952 | some possible control flow paths. If you don't set up the output on | |
10953 | given path and never use it on this path, it is okay. Otherwise, you | |
10954 | should use @samp{+} constraint modifier meaning that the operand is | |
10955 | input and output one. With this modifier you will have the correct | |
10956 | values on all possible paths from the @code{asm goto}. | |
10957 | ||
10958 | To reference a label in the assembler template, prefix it with | |
10959 | @samp{%l} (lowercase @samp{L}) followed by its (zero-based) position | |
10960 | in @var{GotoLabels} plus the number of input and output operands. | |
10961 | Output operand with constraint modifier @samp{+} is counted as two | |
10962 | operands because it is considered as one output and one input operand. | |
10963 | For example, if the @code{asm} has three inputs, one output operand | |
10964 | with constraint modifier @samp{+} and one output operand with | |
10965 | constraint modifier @samp{=} and references two labels, refer to the | |
10966 | first label as @samp{%l6} and the second as @samp{%l7}). | |
10967 | ||
10968 | Alternately, you can reference labels using the actual C label name | |
10969 | enclosed in brackets. For example, to reference a label named | |
10970 | @code{carry}, you can use @samp{%l[carry]}. The label must still be | |
10971 | listed in the @var{GotoLabels} section when using this approach. It | |
10972 | is better to use the named references for labels as in this case you | |
10973 | can avoid counting input and output operands and special treatment of | |
10974 | output operands with constraint modifier @samp{+}. | |
10975 | ||
10976 | Here is an example of @code{asm goto} for i386: | |
10977 | ||
10978 | @example | |
10979 | asm goto ( | |
10980 | "btl %1, %0\n\t" | |
10981 | "jc %l2" | |
10982 | : /* No outputs. */ | |
10983 | : "r" (p1), "r" (p2) | |
10984 | : "cc" | |
10985 | : carry); | |
10986 | ||
10987 | return 0; | |
10988 | ||
10989 | carry: | |
10990 | return 1; | |
10991 | @end example | |
10992 | ||
10993 | The following example shows an @code{asm goto} that uses a memory clobber. | |
10994 | ||
10995 | @example | |
10996 | int frob(int x) | |
10997 | @{ | |
10998 | int y; | |
10999 | asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" | |
11000 | : /* No outputs. */ | |
11001 | : "r"(x), "r"(&y) | |
11002 | : "r5", "memory" | |
11003 | : error); | |
11004 | return y; | |
11005 | error: | |
11006 | return -1; | |
11007 | @} | |
11008 | @end example | |
11009 | ||
11010 | The following example shows an @code{asm goto} that uses an output. | |
11011 | ||
11012 | @example | |
11013 | int foo(int count) | |
11014 | @{ | |
11015 | asm goto ("dec %0; jb %l[stop]" | |
11016 | : "+r" (count) | |
11017 | : | |
11018 | : | |
11019 | : stop); | |
11020 | return count; | |
11021 | stop: | |
11022 | return 0; | |
11023 | @} | |
11024 | @end example | |
11025 | ||
11026 | The following artificial example shows an @code{asm goto} that sets | |
11027 | up an output only on one path inside the @code{asm goto}. Usage of | |
11028 | constraint modifier @code{=} instead of @code{+} would be wrong as | |
11029 | @code{factor} is used on all paths from the @code{asm goto}. | |
11030 | ||
11031 | @example | |
11032 | int foo(int inp) | |
11033 | @{ | |
11034 | int factor = 0; | |
11035 | asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0" | |
11036 | : "+r" (factor) | |
11037 | : "r" (inp) | |
11038 | : | |
11039 | : lab); | |
11040 | lab: | |
11041 | return inp * factor; /* return 2 * inp or 0 if inp < 10 */ | |
11042 | @} | |
11043 | @end example | |
11044 | ||
b5ea0f07 LC |
11045 | @anchor{GenericOperandmodifiers} |
11046 | @subsubsection Generic Operand Modifiers | |
11047 | @noindent | |
11048 | The following table shows the modifiers supported by all targets and their effects: | |
11049 | ||
4ace81b6 | 11050 | @multitable @columnfractions 0.15 0.7 0.15 |
b5ea0f07 LC |
11051 | @headitem Modifier @tab Description @tab Example |
11052 | @item @code{c} | |
11053 | @tab Require a constant operand and print the constant expression with no punctuation. | |
11054 | @tab @code{%c0} | |
11055 | @item @code{n} | |
11056 | @tab Like @samp{%c} except that the value of the constant is negated before printing. | |
11057 | @tab @code{%n0} | |
11058 | @item @code{a} | |
11059 | @tab Substitute a memory reference, with the actual operand treated as the address. | |
11060 | This may be useful when outputting a ``load address'' instruction, because | |
11061 | often the assembler syntax for such an instruction requires you to write the | |
11062 | operand as if it were a memory reference. | |
11063 | @tab @code{%a0} | |
11064 | @item @code{l} | |
11065 | @tab Print the label name with no punctuation. | |
11066 | @tab @code{%l0} | |
11067 | @end multitable | |
11068 | ||
d77de738 ML |
11069 | @anchor{x86Operandmodifiers} |
11070 | @subsubsection x86 Operand Modifiers | |
11071 | ||
11072 | References to input, output, and goto operands in the assembler template | |
11073 | of extended @code{asm} statements can use | |
11074 | modifiers to affect the way the operands are formatted in | |
11075 | the code output to the assembler. For example, the | |
11076 | following code uses the @samp{h} and @samp{b} modifiers for x86: | |
11077 | ||
11078 | @example | |
11079 | uint16_t num; | |
11080 | asm volatile ("xchg %h0, %b0" : "+a" (num) ); | |
11081 | @end example | |
11082 | ||
11083 | @noindent | |
11084 | These modifiers generate this assembler code: | |
11085 | ||
11086 | @example | |
11087 | xchg %ah, %al | |
11088 | @end example | |
11089 | ||
11090 | The rest of this discussion uses the following code for illustrative purposes. | |
11091 | ||
11092 | @example | |
11093 | int main() | |
11094 | @{ | |
11095 | int iInt = 1; | |
11096 | ||
11097 | top: | |
11098 | ||
11099 | asm volatile goto ("some assembler instructions here" | |
11100 | : /* No outputs. */ | |
11101 | : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42) | |
11102 | : /* No clobbers. */ | |
11103 | : top); | |
11104 | @} | |
11105 | @end example | |
11106 | ||
11107 | With no modifiers, this is what the output from the operands would be | |
11108 | for the @samp{att} and @samp{intel} dialects of assembler: | |
11109 | ||
11110 | @multitable {Operand} {$.L2} {OFFSET FLAT:.L2} | |
11111 | @headitem Operand @tab @samp{att} @tab @samp{intel} | |
11112 | @item @code{%0} | |
11113 | @tab @code{%eax} | |
11114 | @tab @code{eax} | |
11115 | @item @code{%1} | |
11116 | @tab @code{$2} | |
11117 | @tab @code{2} | |
11118 | @item @code{%3} | |
11119 | @tab @code{$.L3} | |
11120 | @tab @code{OFFSET FLAT:.L3} | |
11121 | @item @code{%4} | |
11122 | @tab @code{$8} | |
11123 | @tab @code{8} | |
11124 | @item @code{%5} | |
11125 | @tab @code{%xmm0} | |
11126 | @tab @code{xmm0} | |
11127 | @item @code{%7} | |
11128 | @tab @code{$0} | |
11129 | @tab @code{0} | |
11130 | @end multitable | |
11131 | ||
11132 | The table below shows the list of supported modifiers and their effects. | |
11133 | ||
11134 | @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}} | |
11135 | @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel} | |
11136 | @item @code{A} | |
11137 | @tab Print an absolute memory reference. | |
11138 | @tab @code{%A0} | |
11139 | @tab @code{*%rax} | |
11140 | @tab @code{rax} | |
11141 | @item @code{b} | |
11142 | @tab Print the QImode name of the register. | |
11143 | @tab @code{%b0} | |
11144 | @tab @code{%al} | |
11145 | @tab @code{al} | |
11146 | @item @code{B} | |
11147 | @tab print the opcode suffix of b. | |
11148 | @tab @code{%B0} | |
11149 | @tab @code{b} | |
11150 | @tab | |
11151 | @item @code{c} | |
11152 | @tab Require a constant operand and print the constant expression with no punctuation. | |
11153 | @tab @code{%c1} | |
11154 | @tab @code{2} | |
11155 | @tab @code{2} | |
11156 | @item @code{d} | |
11157 | @tab print duplicated register operand for AVX instruction. | |
11158 | @tab @code{%d5} | |
11159 | @tab @code{%xmm0, %xmm0} | |
11160 | @tab @code{xmm0, xmm0} | |
11161 | @item @code{E} | |
11162 | @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit. | |
11163 | Otherwise mode is unspecified (VOIDmode). | |
11164 | @tab @code{%E1} | |
11165 | @tab @code{%(rax)} | |
11166 | @tab @code{[rax]} | |
11167 | @item @code{g} | |
11168 | @tab Print the V16SFmode name of the register. | |
11169 | @tab @code{%g0} | |
11170 | @tab @code{%zmm0} | |
11171 | @tab @code{zmm0} | |
11172 | @item @code{h} | |
11173 | @tab Print the QImode name for a ``high'' register. | |
11174 | @tab @code{%h0} | |
11175 | @tab @code{%ah} | |
11176 | @tab @code{ah} | |
11177 | @item @code{H} | |
11178 | @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the | |
11179 | high 8 bytes of SSE values. For a memref in (%rax), it generates | |
11180 | @tab @code{%H0} | |
11181 | @tab @code{8(%rax)} | |
11182 | @tab @code{8[rax]} | |
11183 | @item @code{k} | |
11184 | @tab Print the SImode name of the register. | |
11185 | @tab @code{%k0} | |
11186 | @tab @code{%eax} | |
11187 | @tab @code{eax} | |
11188 | @item @code{l} | |
11189 | @tab Print the label name with no punctuation. | |
11190 | @tab @code{%l3} | |
11191 | @tab @code{.L3} | |
11192 | @tab @code{.L3} | |
11193 | @item @code{L} | |
11194 | @tab print the opcode suffix of l. | |
11195 | @tab @code{%L0} | |
11196 | @tab @code{l} | |
11197 | @tab | |
11198 | @item @code{N} | |
11199 | @tab print maskz. | |
11200 | @tab @code{%N7} | |
11201 | @tab @code{@{z@}} | |
11202 | @tab @code{@{z@}} | |
11203 | @item @code{p} | |
11204 | @tab Print raw symbol name (without syntax-specific prefixes). | |
11205 | @tab @code{%p2} | |
11206 | @tab @code{42} | |
11207 | @tab @code{42} | |
11208 | @item @code{P} | |
11209 | @tab If used for a function, print the PLT suffix and generate PIC code. | |
11210 | For example, emit @code{foo@@PLT} instead of 'foo' for the function | |
11211 | foo(). If used for a constant, drop all syntax-specific prefixes and | |
11212 | issue the bare constant. See @code{p} above. | |
11213 | @item @code{q} | |
11214 | @tab Print the DImode name of the register. | |
11215 | @tab @code{%q0} | |
11216 | @tab @code{%rax} | |
11217 | @tab @code{rax} | |
11218 | @item @code{Q} | |
11219 | @tab print the opcode suffix of q. | |
11220 | @tab @code{%Q0} | |
11221 | @tab @code{q} | |
11222 | @tab | |
11223 | @item @code{R} | |
11224 | @tab print embedded rounding and sae. | |
11225 | @tab @code{%R4} | |
11226 | @tab @code{@{rn-sae@}, } | |
11227 | @tab @code{, @{rn-sae@}} | |
11228 | @item @code{r} | |
11229 | @tab print only sae. | |
11230 | @tab @code{%r4} | |
11231 | @tab @code{@{sae@}, } | |
11232 | @tab @code{, @{sae@}} | |
11233 | @item @code{s} | |
11234 | @tab print a shift double count, followed by the assemblers argument | |
11235 | delimiterprint the opcode suffix of s. | |
11236 | @tab @code{%s1} | |
11237 | @tab @code{$2, } | |
11238 | @tab @code{2, } | |
11239 | @item @code{S} | |
11240 | @tab print the opcode suffix of s. | |
11241 | @tab @code{%S0} | |
11242 | @tab @code{s} | |
11243 | @tab | |
11244 | @item @code{t} | |
11245 | @tab print the V8SFmode name of the register. | |
11246 | @tab @code{%t5} | |
11247 | @tab @code{%ymm0} | |
11248 | @tab @code{ymm0} | |
11249 | @item @code{T} | |
11250 | @tab print the opcode suffix of t. | |
11251 | @tab @code{%T0} | |
11252 | @tab @code{t} | |
11253 | @tab | |
11254 | @item @code{V} | |
11255 | @tab print naked full integer register name without %. | |
11256 | @tab @code{%V0} | |
11257 | @tab @code{eax} | |
11258 | @tab @code{eax} | |
11259 | @item @code{w} | |
11260 | @tab Print the HImode name of the register. | |
11261 | @tab @code{%w0} | |
11262 | @tab @code{%ax} | |
11263 | @tab @code{ax} | |
11264 | @item @code{W} | |
11265 | @tab print the opcode suffix of w. | |
11266 | @tab @code{%W0} | |
11267 | @tab @code{w} | |
11268 | @tab | |
11269 | @item @code{x} | |
11270 | @tab print the V4SFmode name of the register. | |
11271 | @tab @code{%x5} | |
11272 | @tab @code{%xmm0} | |
11273 | @tab @code{xmm0} | |
11274 | @item @code{y} | |
11275 | @tab print "st(0)" instead of "st" as a register. | |
11276 | @tab @code{%y6} | |
11277 | @tab @code{%st(0)} | |
11278 | @tab @code{st(0)} | |
11279 | @item @code{z} | |
11280 | @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}). | |
11281 | @tab @code{%z0} | |
11282 | @tab @code{l} | |
11283 | @tab | |
11284 | @item @code{Z} | |
11285 | @tab Like @code{z}, with special suffixes for x87 instructions. | |
11286 | @end multitable | |
11287 | ||
11288 | ||
11289 | @anchor{x86floatingpointasmoperands} | |
11290 | @subsubsection x86 Floating-Point @code{asm} Operands | |
11291 | ||
11292 | On x86 targets, there are several rules on the usage of stack-like registers | |
11293 | in the operands of an @code{asm}. These rules apply only to the operands | |
11294 | that are stack-like registers: | |
11295 | ||
11296 | @enumerate | |
11297 | @item | |
11298 | Given a set of input registers that die in an @code{asm}, it is | |
11299 | necessary to know which are implicitly popped by the @code{asm}, and | |
11300 | which must be explicitly popped by GCC@. | |
11301 | ||
11302 | An input register that is implicitly popped by the @code{asm} must be | |
11303 | explicitly clobbered, unless it is constrained to match an | |
11304 | output operand. | |
11305 | ||
11306 | @item | |
11307 | For any input register that is implicitly popped by an @code{asm}, it is | |
11308 | necessary to know how to adjust the stack to compensate for the pop. | |
11309 | If any non-popped input is closer to the top of the reg-stack than | |
11310 | the implicitly popped register, it would not be possible to know what the | |
11311 | stack looked like---it's not clear how the rest of the stack ``slides | |
11312 | up''. | |
11313 | ||
11314 | All implicitly popped input registers must be closer to the top of | |
11315 | the reg-stack than any input that is not implicitly popped. | |
11316 | ||
11317 | It is possible that if an input dies in an @code{asm}, the compiler might | |
11318 | use the input register for an output reload. Consider this example: | |
11319 | ||
11320 | @smallexample | |
11321 | asm ("foo" : "=t" (a) : "f" (b)); | |
11322 | @end smallexample | |
11323 | ||
11324 | @noindent | |
11325 | This code says that input @code{b} is not popped by the @code{asm}, and that | |
11326 | the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one | |
11327 | deeper after the @code{asm} than it was before. But, it is possible that | |
11328 | reload may think that it can use the same register for both the input and | |
11329 | the output. | |
11330 | ||
11331 | To prevent this from happening, | |
11332 | if any input operand uses the @samp{f} constraint, all output register | |
11333 | constraints must use the @samp{&} early-clobber modifier. | |
11334 | ||
11335 | The example above is correctly written as: | |
11336 | ||
11337 | @smallexample | |
11338 | asm ("foo" : "=&t" (a) : "f" (b)); | |
11339 | @end smallexample | |
11340 | ||
11341 | @item | |
11342 | Some operands need to be in particular places on the stack. All | |
11343 | output operands fall in this category---GCC has no other way to | |
11344 | know which registers the outputs appear in unless you indicate | |
11345 | this in the constraints. | |
11346 | ||
11347 | Output operands must specifically indicate which register an output | |
11348 | appears in after an @code{asm}. @samp{=f} is not allowed: the operand | |
11349 | constraints must select a class with a single register. | |
11350 | ||
11351 | @item | |
11352 | Output operands may not be ``inserted'' between existing stack registers. | |
11353 | Since no 387 opcode uses a read/write operand, all output operands | |
11354 | are dead before the @code{asm}, and are pushed by the @code{asm}. | |
11355 | It makes no sense to push anywhere but the top of the reg-stack. | |
11356 | ||
11357 | Output operands must start at the top of the reg-stack: output | |
11358 | operands may not ``skip'' a register. | |
11359 | ||
11360 | @item | |
11361 | Some @code{asm} statements may need extra stack space for internal | |
11362 | calculations. This can be guaranteed by clobbering stack registers | |
11363 | unrelated to the inputs and outputs. | |
11364 | ||
11365 | @end enumerate | |
11366 | ||
11367 | This @code{asm} | |
11368 | takes one input, which is internally popped, and produces two outputs. | |
11369 | ||
11370 | @smallexample | |
11371 | asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); | |
11372 | @end smallexample | |
11373 | ||
11374 | @noindent | |
11375 | This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode, | |
11376 | and replaces them with one output. The @code{st(1)} clobber is necessary | |
11377 | for the compiler to know that @code{fyl2xp1} pops both inputs. | |
11378 | ||
11379 | @smallexample | |
11380 | asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); | |
11381 | @end smallexample | |
11382 | ||
11383 | @anchor{msp430Operandmodifiers} | |
11384 | @subsubsection MSP430 Operand Modifiers | |
11385 | ||
11386 | The list below describes the supported modifiers and their effects for MSP430. | |
11387 | ||
11388 | @multitable @columnfractions .10 .90 | |
11389 | @headitem Modifier @tab Description | |
11390 | @item @code{A} @tab Select low 16-bits of the constant/register/memory operand. | |
11391 | @item @code{B} @tab Select high 16-bits of the constant/register/memory | |
11392 | operand. | |
11393 | @item @code{C} @tab Select bits 32-47 of the constant/register/memory operand. | |
11394 | @item @code{D} @tab Select bits 48-63 of the constant/register/memory operand. | |
11395 | @item @code{H} @tab Equivalent to @code{B} (for backwards compatibility). | |
11396 | @item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant | |
11397 | value. | |
11398 | @item @code{J} @tab Print an integer without a @code{#} prefix. | |
11399 | @item @code{L} @tab Equivalent to @code{A} (for backwards compatibility). | |
11400 | @item @code{O} @tab Offset of the current frame from the top of the stack. | |
11401 | @item @code{Q} @tab Use the @code{A} instruction postfix. | |
11402 | @item @code{R} @tab Inverse of condition code, for unsigned comparisons. | |
11403 | @item @code{W} @tab Subtract 16 from the constant value. | |
11404 | @item @code{X} @tab Use the @code{X} instruction postfix. | |
11405 | @item @code{Y} @tab Subtract 4 from the constant value. | |
11406 | @item @code{Z} @tab Subtract 1 from the constant value. | |
11407 | @item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the | |
11408 | instruction, depending on the mode. | |
11409 | @item @code{d} @tab Offset 1 byte of a memory reference or constant value. | |
11410 | @item @code{e} @tab Offset 3 bytes of a memory reference or constant value. | |
11411 | @item @code{f} @tab Offset 5 bytes of a memory reference or constant value. | |
11412 | @item @code{g} @tab Offset 7 bytes of a memory reference or constant value. | |
11413 | @item @code{p} @tab Print the value of 2, raised to the power of the given | |
11414 | constant. Used to select the specified bit position. | |
11415 | @item @code{r} @tab Inverse of condition code, for signed comparisons. | |
11416 | @item @code{x} @tab Equivialent to @code{X}, but only for pointers. | |
11417 | @end multitable | |
11418 | ||
b5ea0f07 LC |
11419 | @anchor{loongarchOperandmodifiers} |
11420 | @subsubsection LoongArch Operand Modifiers | |
11421 | ||
11422 | The list below describes the supported modifiers and their effects for LoongArch. | |
11423 | ||
11424 | @multitable @columnfractions .10 .90 | |
11425 | @headitem Modifier @tab Description | |
11426 | @item @code{d} @tab Same as @code{c}. | |
11427 | @item @code{i} @tab Print the character ''@code{i}'' if the operand is not a register. | |
11428 | @item @code{m} @tab Same as @code{c}, but the printed value is @code{operand - 1}. | |
11429 | @item @code{X} @tab Print a constant integer operand in hexadecimal. | |
11430 | @item @code{z} @tab Print the operand in its unmodified form, followed by a comma. | |
11431 | @end multitable | |
11432 | ||
11433 | ||
d77de738 ML |
11434 | @lowersections |
11435 | @include md.texi | |
11436 | @raisesections | |
11437 | ||
11438 | @node Asm Labels | |
11439 | @subsection Controlling Names Used in Assembler Code | |
11440 | @cindex assembler names for identifiers | |
11441 | @cindex names used in assembler code | |
11442 | @cindex identifiers, names in assembler code | |
11443 | ||
11444 | You can specify the name to be used in the assembler code for a C | |
11445 | function or variable by writing the @code{asm} (or @code{__asm__}) | |
11446 | keyword after the declarator. | |
11447 | It is up to you to make sure that the assembler names you choose do not | |
11448 | conflict with any other assembler symbols, or reference registers. | |
11449 | ||
11450 | @subsubheading Assembler names for data | |
11451 | ||
11452 | This sample shows how to specify the assembler name for data: | |
11453 | ||
11454 | @smallexample | |
11455 | int foo asm ("myfoo") = 2; | |
11456 | @end smallexample | |
11457 | ||
11458 | @noindent | |
11459 | This specifies that the name to be used for the variable @code{foo} in | |
11460 | the assembler code should be @samp{myfoo} rather than the usual | |
11461 | @samp{_foo}. | |
11462 | ||
11463 | On systems where an underscore is normally prepended to the name of a C | |
11464 | variable, this feature allows you to define names for the | |
11465 | linker that do not start with an underscore. | |
11466 | ||
11467 | GCC does not support using this feature with a non-static local variable | |
11468 | since such variables do not have assembler names. If you are | |
11469 | trying to put the variable in a particular register, see | |
11470 | @ref{Explicit Register Variables}. | |
11471 | ||
11472 | @subsubheading Assembler names for functions | |
11473 | ||
11474 | To specify the assembler name for functions, write a declaration for the | |
11475 | function before its definition and put @code{asm} there, like this: | |
11476 | ||
11477 | @smallexample | |
11478 | int func (int x, int y) asm ("MYFUNC"); | |
11479 | ||
11480 | int func (int x, int y) | |
11481 | @{ | |
11482 | /* @r{@dots{}} */ | |
11483 | @end smallexample | |
11484 | ||
11485 | @noindent | |
11486 | This specifies that the name to be used for the function @code{func} in | |
11487 | the assembler code should be @code{MYFUNC}. | |
11488 | ||
11489 | @node Explicit Register Variables | |
11490 | @subsection Variables in Specified Registers | |
11491 | @anchor{Explicit Reg Vars} | |
11492 | @cindex explicit register variables | |
11493 | @cindex variables in specified registers | |
11494 | @cindex specified registers | |
11495 | ||
11496 | GNU C allows you to associate specific hardware registers with C | |
11497 | variables. In almost all cases, allowing the compiler to assign | |
11498 | registers produces the best code. However under certain unusual | |
11499 | circumstances, more precise control over the variable storage is | |
11500 | required. | |
11501 | ||
11502 | Both global and local variables can be associated with a register. The | |
11503 | consequences of performing this association are very different between | |
11504 | the two, as explained in the sections below. | |
11505 | ||
11506 | @menu | |
11507 | * Global Register Variables:: Variables declared at global scope. | |
11508 | * Local Register Variables:: Variables declared within a function. | |
11509 | @end menu | |
11510 | ||
11511 | @node Global Register Variables | |
11512 | @subsubsection Defining Global Register Variables | |
11513 | @anchor{Global Reg Vars} | |
11514 | @cindex global register variables | |
11515 | @cindex registers, global variables in | |
11516 | @cindex registers, global allocation | |
11517 | ||
11518 | You can define a global register variable and associate it with a specified | |
11519 | register like this: | |
11520 | ||
11521 | @smallexample | |
11522 | register int *foo asm ("r12"); | |
11523 | @end smallexample | |
11524 | ||
11525 | @noindent | |
11526 | Here @code{r12} is the name of the register that should be used. Note that | |
11527 | this is the same syntax used for defining local register variables, but for | |
11528 | a global variable the declaration appears outside a function. The | |
11529 | @code{register} keyword is required, and cannot be combined with | |
11530 | @code{static}. The register name must be a valid register name for the | |
11531 | target platform. | |
11532 | ||
11533 | Do not use type qualifiers such as @code{const} and @code{volatile}, as | |
11534 | the outcome may be contrary to expectations. In particular, using the | |
11535 | @code{volatile} qualifier does not fully prevent the compiler from | |
11536 | optimizing accesses to the register. | |
11537 | ||
11538 | Registers are a scarce resource on most systems and allowing the | |
11539 | compiler to manage their usage usually results in the best code. However, | |
11540 | under special circumstances it can make sense to reserve some globally. | |
11541 | For example this may be useful in programs such as programming language | |
11542 | interpreters that have a couple of global variables that are accessed | |
11543 | very often. | |
11544 | ||
11545 | After defining a global register variable, for the current compilation | |
11546 | unit: | |
11547 | ||
11548 | @itemize @bullet | |
11549 | @item If the register is a call-saved register, call ABI is affected: | |
11550 | the register will not be restored in function epilogue sequences after | |
11551 | the variable has been assigned. Therefore, functions cannot safely | |
11552 | return to callers that assume standard ABI. | |
11553 | @item Conversely, if the register is a call-clobbered register, making | |
11554 | calls to functions that use standard ABI may lose contents of the variable. | |
11555 | Such calls may be created by the compiler even if none are evident in | |
11556 | the original program, for example when libgcc functions are used to | |
11557 | make up for unavailable instructions. | |
11558 | @item Accesses to the variable may be optimized as usual and the register | |
11559 | remains available for allocation and use in any computations, provided that | |
11560 | observable values of the variable are not affected. | |
11561 | @item If the variable is referenced in inline assembly, the type of access | |
11562 | must be provided to the compiler via constraints (@pxref{Constraints}). | |
11563 | Accesses from basic asms are not supported. | |
11564 | @end itemize | |
11565 | ||
11566 | Note that these points @emph{only} apply to code that is compiled with the | |
11567 | definition. The behavior of code that is merely linked in (for example | |
11568 | code from libraries) is not affected. | |
11569 | ||
11570 | If you want to recompile source files that do not actually use your global | |
11571 | register variable so they do not use the specified register for any other | |
11572 | purpose, you need not actually add the global register declaration to | |
11573 | their source code. It suffices to specify the compiler option | |
11574 | @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the | |
11575 | register. | |
11576 | ||
11577 | @subsubheading Declaring the variable | |
11578 | ||
11579 | Global register variables cannot have initial values, because an | |
11580 | executable file has no means to supply initial contents for a register. | |
11581 | ||
11582 | When selecting a register, choose one that is normally saved and | |
11583 | restored by function calls on your machine. This ensures that code | |
11584 | which is unaware of this reservation (such as library routines) will | |
11585 | restore it before returning. | |
11586 | ||
11587 | On machines with register windows, be sure to choose a global | |
11588 | register that is not affected magically by the function call mechanism. | |
11589 | ||
11590 | @subsubheading Using the variable | |
11591 | ||
11592 | @cindex @code{qsort}, and global register variables | |
11593 | When calling routines that are not aware of the reservation, be | |
11594 | cautious if those routines call back into code which uses them. As an | |
11595 | example, if you call the system library version of @code{qsort}, it may | |
11596 | clobber your registers during execution, but (if you have selected | |
11597 | appropriate registers) it will restore them before returning. However | |
11598 | it will @emph{not} restore them before calling @code{qsort}'s comparison | |
11599 | function. As a result, global values will not reliably be available to | |
11600 | the comparison function unless the @code{qsort} function itself is rebuilt. | |
11601 | ||
11602 | Similarly, it is not safe to access the global register variables from signal | |
11603 | handlers or from more than one thread of control. Unless you recompile | |
11604 | them specially for the task at hand, the system library routines may | |
11605 | temporarily use the register for other things. Furthermore, since the register | |
11606 | is not reserved exclusively for the variable, accessing it from handlers of | |
11607 | asynchronous signals may observe unrelated temporary values residing in the | |
11608 | register. | |
11609 | ||
11610 | @cindex register variable after @code{longjmp} | |
11611 | @cindex global register after @code{longjmp} | |
11612 | @cindex value after @code{longjmp} | |
11613 | @findex longjmp | |
11614 | @findex setjmp | |
11615 | On most machines, @code{longjmp} restores to each global register | |
11616 | variable the value it had at the time of the @code{setjmp}. On some | |
11617 | machines, however, @code{longjmp} does not change the value of global | |
11618 | register variables. To be portable, the function that called @code{setjmp} | |
11619 | should make other arrangements to save the values of the global register | |
11620 | variables, and to restore them in a @code{longjmp}. This way, the same | |
11621 | thing happens regardless of what @code{longjmp} does. | |
11622 | ||
11623 | @node Local Register Variables | |
11624 | @subsubsection Specifying Registers for Local Variables | |
11625 | @anchor{Local Reg Vars} | |
11626 | @cindex local variables, specifying registers | |
11627 | @cindex specifying registers for local variables | |
11628 | @cindex registers for local variables | |
11629 | ||
11630 | You can define a local register variable and associate it with a specified | |
11631 | register like this: | |
11632 | ||
11633 | @smallexample | |
11634 | register int *foo asm ("r12"); | |
11635 | @end smallexample | |
11636 | ||
11637 | @noindent | |
11638 | Here @code{r12} is the name of the register that should be used. Note | |
11639 | that this is the same syntax used for defining global register variables, | |
11640 | but for a local variable the declaration appears within a function. The | |
11641 | @code{register} keyword is required, and cannot be combined with | |
11642 | @code{static}. The register name must be a valid register name for the | |
11643 | target platform. | |
11644 | ||
11645 | Do not use type qualifiers such as @code{const} and @code{volatile}, as | |
11646 | the outcome may be contrary to expectations. In particular, when the | |
11647 | @code{const} qualifier is used, the compiler may substitute the | |
11648 | variable with its initializer in @code{asm} statements, which may cause | |
11649 | the corresponding operand to appear in a different register. | |
11650 | ||
11651 | As with global register variables, it is recommended that you choose | |
11652 | a register that is normally saved and restored by function calls on your | |
11653 | machine, so that calls to library routines will not clobber it. | |
11654 | ||
11655 | The only supported use for this feature is to specify registers | |
11656 | for input and output operands when calling Extended @code{asm} | |
11657 | (@pxref{Extended Asm}). This may be necessary if the constraints for a | |
11658 | particular machine don't provide sufficient control to select the desired | |
11659 | register. To force an operand into a register, create a local variable | |
11660 | and specify the register name after the variable's declaration. Then use | |
11661 | the local variable for the @code{asm} operand and specify any constraint | |
11662 | letter that matches the register: | |
11663 | ||
11664 | @smallexample | |
11665 | register int *p1 asm ("r0") = @dots{}; | |
11666 | register int *p2 asm ("r1") = @dots{}; | |
11667 | register int *result asm ("r0"); | |
11668 | asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); | |
11669 | @end smallexample | |
11670 | ||
11671 | @emph{Warning:} In the above example, be aware that a register (for example | |
11672 | @code{r0}) can be call-clobbered by subsequent code, including function | |
11673 | calls and library calls for arithmetic operators on other variables (for | |
11674 | example the initialization of @code{p2}). In this case, use temporary | |
11675 | variables for expressions between the register assignments: | |
11676 | ||
11677 | @smallexample | |
11678 | int t1 = @dots{}; | |
11679 | register int *p1 asm ("r0") = @dots{}; | |
11680 | register int *p2 asm ("r1") = t1; | |
11681 | register int *result asm ("r0"); | |
11682 | asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); | |
11683 | @end smallexample | |
11684 | ||
11685 | Defining a register variable does not reserve the register. Other than | |
11686 | when invoking the Extended @code{asm}, the contents of the specified | |
11687 | register are not guaranteed. For this reason, the following uses | |
11688 | are explicitly @emph{not} supported. If they appear to work, it is only | |
11689 | happenstance, and may stop working as intended due to (seemingly) | |
11690 | unrelated changes in surrounding code, or even minor changes in the | |
11691 | optimization of a future version of gcc: | |
11692 | ||
11693 | @itemize @bullet | |
11694 | @item Passing parameters to or from Basic @code{asm} | |
11695 | @item Passing parameters to or from Extended @code{asm} without using input | |
11696 | or output operands. | |
11697 | @item Passing parameters to or from routines written in assembler (or | |
11698 | other languages) using non-standard calling conventions. | |
11699 | @end itemize | |
11700 | ||
11701 | Some developers use Local Register Variables in an attempt to improve | |
11702 | gcc's allocation of registers, especially in large functions. In this | |
11703 | case the register name is essentially a hint to the register allocator. | |
11704 | While in some instances this can generate better code, improvements are | |
11705 | subject to the whims of the allocator/optimizers. Since there are no | |
11706 | guarantees that your improvements won't be lost, this usage of Local | |
11707 | Register Variables is discouraged. | |
11708 | ||
11709 | On the MIPS platform, there is related use for local register variables | |
11710 | with slightly different characteristics (@pxref{MIPS Coprocessors,, | |
11711 | Defining coprocessor specifics for MIPS targets, gccint, | |
11712 | GNU Compiler Collection (GCC) Internals}). | |
11713 | ||
11714 | @node Size of an asm | |
11715 | @subsection Size of an @code{asm} | |
11716 | ||
11717 | Some targets require that GCC track the size of each instruction used | |
11718 | in order to generate correct code. Because the final length of the | |
11719 | code produced by an @code{asm} statement is only known by the | |
11720 | assembler, GCC must make an estimate as to how big it will be. It | |
11721 | does this by counting the number of instructions in the pattern of the | |
11722 | @code{asm} and multiplying that by the length of the longest | |
11723 | instruction supported by that processor. (When working out the number | |
11724 | of instructions, it assumes that any occurrence of a newline or of | |
11725 | whatever statement separator character is supported by the assembler --- | |
11726 | typically @samp{;} --- indicates the end of an instruction.) | |
11727 | ||
11728 | Normally, GCC's estimate is adequate to ensure that correct | |
11729 | code is generated, but it is possible to confuse the compiler if you use | |
11730 | pseudo instructions or assembler macros that expand into multiple real | |
11731 | instructions, or if you use assembler directives that expand to more | |
11732 | space in the object file than is needed for a single instruction. | |
11733 | If this happens then the assembler may produce a diagnostic saying that | |
11734 | a label is unreachable. | |
11735 | ||
11736 | @cindex @code{asm inline} | |
11737 | This size is also used for inlining decisions. If you use @code{asm inline} | |
11738 | instead of just @code{asm}, then for inlining purposes the size of the asm | |
11739 | is taken as the minimum size, ignoring how many instructions GCC thinks it is. | |
11740 | ||
11741 | @node Alternate Keywords | |
11742 | @section Alternate Keywords | |
11743 | @cindex alternate keywords | |
11744 | @cindex keywords, alternate | |
11745 | ||
11746 | @option{-ansi} and the various @option{-std} options disable certain | |
11747 | keywords. This causes trouble when you want to use GNU C extensions, or | |
11748 | a general-purpose header file that should be usable by all programs, | |
11749 | including ISO C programs. The keywords @code{asm}, @code{typeof} and | |
11750 | @code{inline} are not available in programs compiled with | |
11751 | @option{-ansi} or @option{-std} (although @code{inline} can be used in a | |
11752 | program compiled with @option{-std=c99} or a later standard). The | |
11753 | ISO C99 keyword | |
11754 | @code{restrict} is only available when @option{-std=gnu99} (which will | |
11755 | eventually be the default) or @option{-std=c99} (or the equivalent | |
11756 | @option{-std=iso9899:1999}), or an option for a later standard | |
11757 | version, is used. | |
11758 | ||
11759 | The way to solve these problems is to put @samp{__} at the beginning and | |
11760 | end of each problematical keyword. For example, use @code{__asm__} | |
11761 | instead of @code{asm}, and @code{__inline__} instead of @code{inline}. | |
11762 | ||
11763 | Other C compilers won't accept these alternative keywords; if you want to | |
11764 | compile with another compiler, you can define the alternate keywords as | |
11765 | macros to replace them with the customary keywords. It looks like this: | |
11766 | ||
11767 | @smallexample | |
11768 | #ifndef __GNUC__ | |
11769 | #define __asm__ asm | |
11770 | #endif | |
11771 | @end smallexample | |
11772 | ||
11773 | @findex __extension__ | |
11774 | @opindex pedantic | |
11775 | @option{-pedantic} and other options cause warnings for many GNU C extensions. | |
11776 | You can | |
11777 | prevent such warnings within one expression by writing | |
11778 | @code{__extension__} before the expression. @code{__extension__} has no | |
11779 | effect aside from this. | |
11780 | ||
11781 | @node Incomplete Enums | |
11782 | @section Incomplete @code{enum} Types | |
11783 | ||
11784 | You can define an @code{enum} tag without specifying its possible values. | |
11785 | This results in an incomplete type, much like what you get if you write | |
11786 | @code{struct foo} without describing the elements. A later declaration | |
11787 | that does specify the possible values completes the type. | |
11788 | ||
11789 | You cannot allocate variables or storage using the type while it is | |
11790 | incomplete. However, you can work with pointers to that type. | |
11791 | ||
11792 | This extension may not be very useful, but it makes the handling of | |
11793 | @code{enum} more consistent with the way @code{struct} and @code{union} | |
11794 | are handled. | |
11795 | ||
11796 | This extension is not supported by GNU C++. | |
11797 | ||
11798 | @node Function Names | |
11799 | @section Function Names as Strings | |
11800 | @cindex @code{__func__} identifier | |
11801 | @cindex @code{__FUNCTION__} identifier | |
11802 | @cindex @code{__PRETTY_FUNCTION__} identifier | |
11803 | ||
11804 | GCC provides three magic constants that hold the name of the current | |
11805 | function as a string. In C++11 and later modes, all three are treated | |
11806 | as constant expressions and can be used in @code{constexpr} constexts. | |
11807 | The first of these constants is @code{__func__}, which is part of | |
11808 | the C99 standard: | |
11809 | ||
11810 | The identifier @code{__func__} is implicitly declared by the translator | |
11811 | as if, immediately following the opening brace of each function | |
11812 | definition, the declaration | |
11813 | ||
11814 | @smallexample | |
11815 | static const char __func__[] = "function-name"; | |
11816 | @end smallexample | |
11817 | ||
11818 | @noindent | |
11819 | appeared, where function-name is the name of the lexically-enclosing | |
11820 | function. This name is the unadorned name of the function. As an | |
11821 | extension, at file (or, in C++, namespace scope), @code{__func__} | |
11822 | evaluates to the empty string. | |
11823 | ||
11824 | @code{__FUNCTION__} is another name for @code{__func__}, provided for | |
11825 | backward compatibility with old versions of GCC. | |
11826 | ||
11827 | In C, @code{__PRETTY_FUNCTION__} is yet another name for | |
11828 | @code{__func__}, except that at file scope (or, in C++, namespace scope), | |
11829 | it evaluates to the string @code{"top level"}. In addition, in C++, | |
11830 | @code{__PRETTY_FUNCTION__} contains the signature of the function as | |
11831 | well as its bare name. For example, this program: | |
11832 | ||
11833 | @smallexample | |
11834 | extern "C" int printf (const char *, ...); | |
11835 | ||
11836 | class a @{ | |
11837 | public: | |
11838 | void sub (int i) | |
11839 | @{ | |
11840 | printf ("__FUNCTION__ = %s\n", __FUNCTION__); | |
11841 | printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); | |
11842 | @} | |
11843 | @}; | |
11844 | ||
11845 | int | |
11846 | main (void) | |
11847 | @{ | |
11848 | a ax; | |
11849 | ax.sub (0); | |
11850 | return 0; | |
11851 | @} | |
11852 | @end smallexample | |
11853 | ||
11854 | @noindent | |
11855 | gives this output: | |
11856 | ||
11857 | @smallexample | |
11858 | __FUNCTION__ = sub | |
11859 | __PRETTY_FUNCTION__ = void a::sub(int) | |
11860 | @end smallexample | |
11861 | ||
11862 | These identifiers are variables, not preprocessor macros, and may not | |
11863 | be used to initialize @code{char} arrays or be concatenated with string | |
11864 | literals. | |
11865 | ||
11866 | @node Return Address | |
11867 | @section Getting the Return or Frame Address of a Function | |
11868 | ||
11869 | These functions may be used to get information about the callers of a | |
11870 | function. | |
11871 | ||
f25efe50 | 11872 | @defbuiltin{{void *} __builtin_return_address (unsigned int @var{level})} |
d77de738 ML |
11873 | This function returns the return address of the current function, or of |
11874 | one of its callers. The @var{level} argument is number of frames to | |
11875 | scan up the call stack. A value of @code{0} yields the return address | |
11876 | of the current function, a value of @code{1} yields the return address | |
11877 | of the caller of the current function, and so forth. When inlining | |
11878 | the expected behavior is that the function returns the address of | |
11879 | the function that is returned to. To work around this behavior use | |
11880 | the @code{noinline} function attribute. | |
11881 | ||
11882 | The @var{level} argument must be a constant integer. | |
11883 | ||
11884 | On some machines it may be impossible to determine the return address of | |
11885 | any function other than the current one; in such cases, or when the top | |
11886 | of the stack has been reached, this function returns an unspecified | |
11887 | value. In addition, @code{__builtin_frame_address} may be used | |
11888 | to determine if the top of the stack has been reached. | |
11889 | ||
11890 | Additional post-processing of the returned value may be needed, see | |
11891 | @code{__builtin_extract_return_addr}. | |
11892 | ||
11893 | The stored representation of the return address in memory may be different | |
11894 | from the address returned by @code{__builtin_return_address}. For example, | |
11895 | on AArch64 the stored address may be mangled with return address signing | |
11896 | whereas the address returned by @code{__builtin_return_address} is not. | |
11897 | ||
11898 | Calling this function with a nonzero argument can have unpredictable | |
11899 | effects, including crashing the calling program. As a result, calls | |
11900 | that are considered unsafe are diagnosed when the @option{-Wframe-address} | |
11901 | option is in effect. Such calls should only be made in debugging | |
11902 | situations. | |
11903 | ||
11904 | On targets where code addresses are representable as @code{void *}, | |
11905 | @smallexample | |
11906 | void *addr = __builtin_extract_return_addr (__builtin_return_address (0)); | |
11907 | @end smallexample | |
11908 | gives the code address where the current function would return. For example, | |
11909 | such an address may be used with @code{dladdr} or other interfaces that work | |
11910 | with code addresses. | |
f25efe50 | 11911 | @enddefbuiltin |
d77de738 | 11912 | |
f25efe50 | 11913 | @defbuiltin{{void *} __builtin_extract_return_addr (void *@var{addr})} |
d77de738 ML |
11914 | The address as returned by @code{__builtin_return_address} may have to be fed |
11915 | through this function to get the actual encoded address. For example, on the | |
11916 | 31-bit S/390 platform the highest bit has to be masked out, or on SPARC | |
11917 | platforms an offset has to be added for the true next instruction to be | |
11918 | executed. | |
11919 | ||
11920 | If no fixup is needed, this function simply passes through @var{addr}. | |
f25efe50 | 11921 | @enddefbuiltin |
d77de738 | 11922 | |
f25efe50 | 11923 | @defbuiltin{{void *} __builtin_frob_return_addr (void *@var{addr})} |
d77de738 | 11924 | This function does the reverse of @code{__builtin_extract_return_addr}. |
f25efe50 | 11925 | @enddefbuiltin |
d77de738 | 11926 | |
f25efe50 | 11927 | @defbuiltin{{void *} __builtin_frame_address (unsigned int @var{level})} |
d77de738 ML |
11928 | This function is similar to @code{__builtin_return_address}, but it |
11929 | returns the address of the function frame rather than the return address | |
11930 | of the function. Calling @code{__builtin_frame_address} with a value of | |
11931 | @code{0} yields the frame address of the current function, a value of | |
11932 | @code{1} yields the frame address of the caller of the current function, | |
11933 | and so forth. | |
11934 | ||
11935 | The frame is the area on the stack that holds local variables and saved | |
11936 | registers. The frame address is normally the address of the first word | |
11937 | pushed on to the stack by the function. However, the exact definition | |
11938 | depends upon the processor and the calling convention. If the processor | |
11939 | has a dedicated frame pointer register, and the function has a frame, | |
11940 | then @code{__builtin_frame_address} returns the value of the frame | |
11941 | pointer register. | |
11942 | ||
11943 | On some machines it may be impossible to determine the frame address of | |
11944 | any function other than the current one; in such cases, or when the top | |
11945 | of the stack has been reached, this function returns @code{0} if | |
11946 | the first frame pointer is properly initialized by the startup code. | |
11947 | ||
11948 | Calling this function with a nonzero argument can have unpredictable | |
11949 | effects, including crashing the calling program. As a result, calls | |
11950 | that are considered unsafe are diagnosed when the @option{-Wframe-address} | |
11951 | option is in effect. Such calls should only be made in debugging | |
11952 | situations. | |
f25efe50 | 11953 | @enddefbuiltin |
d77de738 ML |
11954 | |
11955 | @node Vector Extensions | |
11956 | @section Using Vector Instructions through Built-in Functions | |
11957 | ||
11958 | On some targets, the instruction set contains SIMD vector instructions which | |
11959 | operate on multiple values contained in one large register at the same time. | |
11960 | For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used | |
11961 | this way. | |
11962 | ||
11963 | The first step in using these extensions is to provide the necessary data | |
11964 | types. This should be done using an appropriate @code{typedef}: | |
11965 | ||
11966 | @smallexample | |
11967 | typedef int v4si __attribute__ ((vector_size (16))); | |
11968 | @end smallexample | |
11969 | ||
11970 | @noindent | |
11971 | The @code{int} type specifies the @dfn{base type}, while the attribute specifies | |
11972 | the vector size for the variable, measured in bytes. For example, the | |
11973 | declaration above causes the compiler to set the mode for the @code{v4si} | |
11974 | type to be 16 bytes wide and divided into @code{int} sized units. For | |
11975 | a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the | |
11976 | corresponding mode of @code{foo} is @acronym{V4SI}. | |
11977 | ||
11978 | The @code{vector_size} attribute is only applicable to integral and | |
11979 | floating scalars, although arrays, pointers, and function return values | |
11980 | are allowed in conjunction with this construct. Only sizes that are | |
11981 | positive power-of-two multiples of the base type size are currently allowed. | |
11982 | ||
11983 | All the basic integer types can be used as base types, both as signed | |
11984 | and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, | |
11985 | @code{long long}. In addition, @code{float} and @code{double} can be | |
11986 | used to build floating-point vector types. | |
11987 | ||
11988 | Specifying a combination that is not valid for the current architecture | |
11989 | causes GCC to synthesize the instructions using a narrower mode. | |
11990 | For example, if you specify a variable of type @code{V4SI} and your | |
11991 | architecture does not allow for this specific SIMD type, GCC | |
11992 | produces code that uses 4 @code{SIs}. | |
11993 | ||
11994 | The types defined in this manner can be used with a subset of normal C | |
11995 | operations. Currently, GCC allows using the following operators | |
11996 | on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. | |
11997 | ||
11998 | The operations behave like C++ @code{valarrays}. Addition is defined as | |
11999 | the addition of the corresponding elements of the operands. For | |
12000 | example, in the code below, each of the 4 elements in @var{a} is | |
12001 | added to the corresponding 4 elements in @var{b} and the resulting | |
12002 | vector is stored in @var{c}. | |
12003 | ||
12004 | @smallexample | |
12005 | typedef int v4si __attribute__ ((vector_size (16))); | |
12006 | ||
12007 | v4si a, b, c; | |
12008 | ||
12009 | c = a + b; | |
12010 | @end smallexample | |
12011 | ||
12012 | Subtraction, multiplication, division, and the logical operations | |
12013 | operate in a similar manner. Likewise, the result of using the unary | |
12014 | minus or complement operators on a vector type is a vector whose | |
12015 | elements are the negative or complemented values of the corresponding | |
12016 | elements in the operand. | |
12017 | ||
12018 | It is possible to use shifting operators @code{<<}, @code{>>} on | |
12019 | integer-type vectors. The operation is defined as following: @code{@{a0, | |
12020 | a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, | |
12021 | @dots{}, an >> bn@}}@. Vector operands must have the same number of | |
12022 | elements. | |
12023 | ||
12024 | For convenience, it is allowed to use a binary vector operation | |
12025 | where one operand is a scalar. In that case the compiler transforms | |
12026 | the scalar operand into a vector where each element is the scalar from | |
12027 | the operation. The transformation happens only if the scalar could be | |
12028 | safely converted to the vector-element type. | |
12029 | Consider the following code. | |
12030 | ||
12031 | @smallexample | |
12032 | typedef int v4si __attribute__ ((vector_size (16))); | |
12033 | ||
12034 | v4si a, b, c; | |
12035 | long l; | |
12036 | ||
12037 | a = b + 1; /* a = b + @{1,1,1,1@}; */ | |
12038 | a = 2 * b; /* a = @{2,2,2,2@} * b; */ | |
12039 | ||
12040 | a = l + a; /* Error, cannot convert long to int. */ | |
12041 | @end smallexample | |
12042 | ||
12043 | Vectors can be subscripted as if the vector were an array with | |
12044 | the same number of elements and base type. Out of bound accesses | |
12045 | invoke undefined behavior at run time. Warnings for out of bound | |
12046 | accesses for vector subscription can be enabled with | |
12047 | @option{-Warray-bounds}. | |
12048 | ||
12049 | Vector comparison is supported with standard comparison | |
12050 | operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be | |
12051 | vector expressions of integer-type or real-type. Comparison between | |
12052 | integer-type vectors and real-type vectors are not supported. The | |
12053 | result of the comparison is a vector of the same width and number of | |
12054 | elements as the comparison operands with a signed integral element | |
12055 | type. | |
12056 | ||
12057 | Vectors are compared element-wise producing 0 when comparison is false | |
12058 | and -1 (constant of the appropriate type where all bits are set) | |
12059 | otherwise. Consider the following example. | |
12060 | ||
12061 | @smallexample | |
12062 | typedef int v4si __attribute__ ((vector_size (16))); | |
12063 | ||
12064 | v4si a = @{1,2,3,4@}; | |
12065 | v4si b = @{3,2,1,4@}; | |
12066 | v4si c; | |
12067 | ||
12068 | c = a > b; /* The result would be @{0, 0,-1, 0@} */ | |
12069 | c = a == b; /* The result would be @{0,-1, 0,-1@} */ | |
12070 | @end smallexample | |
12071 | ||
12072 | In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where | |
12073 | @code{b} and @code{c} are vectors of the same type and @code{a} is an | |
12074 | integer vector with the same number of elements of the same size as @code{b} | |
12075 | and @code{c}, computes all three arguments and creates a vector | |
12076 | @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in | |
12077 | OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. | |
12078 | As in the case of binary operations, this syntax is also accepted when | |
12079 | one of @code{b} or @code{c} is a scalar that is then transformed into a | |
12080 | vector. If both @code{b} and @code{c} are scalars and the type of | |
12081 | @code{true?b:c} has the same size as the element type of @code{a}, then | |
12082 | @code{b} and @code{c} are converted to a vector type whose elements have | |
12083 | this type and with the same number of elements as @code{a}. | |
12084 | ||
12085 | In C++, the logic operators @code{!, &&, ||} are available for vectors. | |
12086 | @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to | |
12087 | @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. | |
12088 | For mixed operations between a scalar @code{s} and a vector @code{v}, | |
12089 | @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is | |
12090 | short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. | |
12091 | ||
12092 | @findex __builtin_shuffle | |
12093 | Vector shuffling is available using functions | |
12094 | @code{__builtin_shuffle (vec, mask)} and | |
12095 | @code{__builtin_shuffle (vec0, vec1, mask)}. | |
12096 | Both functions construct a permutation of elements from one or two | |
12097 | vectors and return a vector of the same type as the input vector(s). | |
12098 | The @var{mask} is an integral vector with the same width (@var{W}) | |
12099 | and element count (@var{N}) as the output vector. | |
12100 | ||
12101 | The elements of the input vectors are numbered in memory ordering of | |
12102 | @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The | |
12103 | elements of @var{mask} are considered modulo @var{N} in the single-operand | |
12104 | case and modulo @math{2*@var{N}} in the two-operand case. | |
12105 | ||
12106 | Consider the following example, | |
12107 | ||
12108 | @smallexample | |
12109 | typedef int v4si __attribute__ ((vector_size (16))); | |
12110 | ||
12111 | v4si a = @{1,2,3,4@}; | |
12112 | v4si b = @{5,6,7,8@}; | |
12113 | v4si mask1 = @{0,1,1,3@}; | |
12114 | v4si mask2 = @{0,4,2,5@}; | |
12115 | v4si res; | |
12116 | ||
12117 | res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ | |
12118 | res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ | |
12119 | @end smallexample | |
12120 | ||
12121 | Note that @code{__builtin_shuffle} is intentionally semantically | |
12122 | compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. | |
12123 | ||
12124 | You can declare variables and use them in function calls and returns, as | |
12125 | well as in assignments and some casts. You can specify a vector type as | |
12126 | a return type for a function. Vector types can also be used as function | |
12127 | arguments. It is possible to cast from one vector type to another, | |
12128 | provided they are of the same size (in fact, you can also cast vectors | |
12129 | to and from other datatypes of the same size). | |
12130 | ||
12131 | You cannot operate between vectors of different lengths or different | |
12132 | signedness without a cast. | |
12133 | ||
12134 | @findex __builtin_shufflevector | |
12135 | Vector shuffling is available using the | |
12136 | @code{__builtin_shufflevector (vec1, vec2, index...)} | |
12137 | function. @var{vec1} and @var{vec2} must be expressions with | |
12138 | vector type with a compatible element type. The result of | |
12139 | @code{__builtin_shufflevector} is a vector with the same element type | |
12140 | as @var{vec1} and @var{vec2} but that has an element count equal to | |
12141 | the number of indices specified. | |
12142 | ||
12143 | The @var{index} arguments are a list of integers that specify the | |
12144 | elements indices of the first two vectors that should be extracted and | |
12145 | returned in a new vector. These element indices are numbered sequentially | |
12146 | starting with the first vector, continuing into the second vector. | |
12147 | An index of -1 can be used to indicate that the corresponding element in | |
12148 | the returned vector is a don't care and can be freely chosen to optimized | |
12149 | the generated code sequence performing the shuffle operation. | |
12150 | ||
12151 | Consider the following example, | |
12152 | @smallexample | |
12153 | typedef int v4si __attribute__ ((vector_size (16))); | |
12154 | typedef int v8si __attribute__ ((vector_size (32))); | |
12155 | ||
12156 | v8si a = @{1,-2,3,-4,5,-6,7,-8@}; | |
12157 | v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */ | |
12158 | v4si c = @{-2,-4,-6,-8@}; | |
12159 | v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */ | |
12160 | @end smallexample | |
12161 | ||
12162 | @findex __builtin_convertvector | |
12163 | Vector conversion is available using the | |
12164 | @code{__builtin_convertvector (vec, vectype)} | |
12165 | function. @var{vec} must be an expression with integral or floating | |
12166 | vector type and @var{vectype} an integral or floating vector type with the | |
12167 | same number of elements. The result has @var{vectype} type and value of | |
12168 | a C cast of every element of @var{vec} to the element type of @var{vectype}. | |
12169 | ||
12170 | Consider the following example, | |
12171 | @smallexample | |
12172 | typedef int v4si __attribute__ ((vector_size (16))); | |
12173 | typedef float v4sf __attribute__ ((vector_size (16))); | |
12174 | typedef double v4df __attribute__ ((vector_size (32))); | |
12175 | typedef unsigned long long v4di __attribute__ ((vector_size (32))); | |
12176 | ||
12177 | v4si a = @{1,-2,3,-4@}; | |
12178 | v4sf b = @{1.5f,-2.5f,3.f,7.f@}; | |
12179 | v4di c = @{1ULL,5ULL,0ULL,10ULL@}; | |
12180 | v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */ | |
12181 | /* Equivalent of: | |
12182 | v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */ | |
12183 | v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */ | |
12184 | v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */ | |
12185 | v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */ | |
12186 | v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */ | |
12187 | @end smallexample | |
12188 | ||
12189 | @cindex vector types, using with x86 intrinsics | |
12190 | Sometimes it is desirable to write code using a mix of generic vector | |
12191 | operations (for clarity) and machine-specific vector intrinsics (to | |
12192 | access vector instructions that are not exposed via generic built-ins). | |
12193 | On x86, intrinsic functions for integer vectors typically use the same | |
12194 | vector type @code{__m128i} irrespective of how they interpret the vector, | |
12195 | making it necessary to cast their arguments and return values from/to | |
12196 | other vector types. In C, you can make use of a @code{union} type: | |
12197 | @c In C++ such type punning via a union is not allowed by the language | |
12198 | @smallexample | |
12199 | #include <immintrin.h> | |
12200 | ||
12201 | typedef unsigned char u8x16 __attribute__ ((vector_size (16))); | |
12202 | typedef unsigned int u32x4 __attribute__ ((vector_size (16))); | |
12203 | ||
12204 | typedef union @{ | |
12205 | __m128i mm; | |
12206 | u8x16 u8; | |
12207 | u32x4 u32; | |
12208 | @} v128; | |
12209 | @end smallexample | |
12210 | ||
12211 | @noindent | |
12212 | for variables that can be used with both built-in operators and x86 | |
12213 | intrinsics: | |
12214 | ||
12215 | @smallexample | |
12216 | v128 x, y = @{ 0 @}; | |
12217 | memcpy (&x, ptr, sizeof x); | |
12218 | y.u8 += 0x80; | |
12219 | x.mm = _mm_adds_epu8 (x.mm, y.mm); | |
12220 | x.u32 &= 0xffffff; | |
12221 | ||
12222 | /* Instead of a variable, a compound literal may be used to pass the | |
12223 | return value of an intrinsic call to a function expecting the union: */ | |
12224 | v128 foo (v128); | |
12225 | x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); | |
12226 | @c This could be done implicitly with __attribute__((transparent_union)), | |
12227 | @c but GCC does not accept it for unions of vector types (PR 88955). | |
12228 | @end smallexample | |
12229 | ||
12230 | @node Offsetof | |
12231 | @section Support for @code{offsetof} | |
12232 | @findex __builtin_offsetof | |
12233 | ||
12234 | GCC implements for both C and C++ a syntactic extension to implement | |
12235 | the @code{offsetof} macro. | |
12236 | ||
12237 | @smallexample | |
12238 | primary: | |
12239 | "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" | |
12240 | ||
12241 | offsetof_member_designator: | |
12242 | @code{identifier} | |
12243 | | offsetof_member_designator "." @code{identifier} | |
12244 | | offsetof_member_designator "[" @code{expr} "]" | |
12245 | @end smallexample | |
12246 | ||
12247 | This extension is sufficient such that | |
12248 | ||
12249 | @smallexample | |
12250 | #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) | |
12251 | @end smallexample | |
12252 | ||
12253 | @noindent | |
12254 | is a suitable definition of the @code{offsetof} macro. In C++, @var{type} | |
12255 | may be dependent. In either case, @var{member} may consist of a single | |
12256 | identifier, or a sequence of member accesses and array references. | |
12257 | ||
12258 | @node __sync Builtins | |
12259 | @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access | |
12260 | ||
12261 | The following built-in functions | |
12262 | are intended to be compatible with those described | |
12263 | in the @cite{Intel Itanium Processor-specific Application Binary Interface}, | |
12264 | section 7.4. As such, they depart from normal GCC practice by not using | |
12265 | the @samp{__builtin_} prefix and also by being overloaded so that they | |
12266 | work on multiple types. | |
12267 | ||
12268 | The definition given in the Intel documentation allows only for the use of | |
12269 | the types @code{int}, @code{long}, @code{long long} or their unsigned | |
12270 | counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in | |
12271 | size other than the C type @code{_Bool} or the C++ type @code{bool}. | |
12272 | Operations on pointer arguments are performed as if the operands were | |
12273 | of the @code{uintptr_t} type. That is, they are not scaled by the size | |
12274 | of the type to which the pointer points. | |
12275 | ||
12276 | These functions are implemented in terms of the @samp{__atomic} | |
12277 | builtins (@pxref{__atomic Builtins}). They should not be used for new | |
12278 | code which should use the @samp{__atomic} builtins instead. | |
12279 | ||
12280 | Not all operations are supported by all target processors. If a particular | |
12281 | operation cannot be implemented on the target processor, a warning is | |
12282 | generated and a call to an external function is generated. The external | |
12283 | function carries the same name as the built-in version, | |
12284 | with an additional suffix | |
12285 | @samp{_@var{n}} where @var{n} is the size of the data type. | |
12286 | ||
12287 | @c ??? Should we have a mechanism to suppress this warning? This is almost | |
12288 | @c useful for implementing the operation under the control of an external | |
12289 | @c mutex. | |
12290 | ||
12291 | In most cases, these built-in functions are considered a @dfn{full barrier}. | |
12292 | That is, | |
12293 | no memory operand is moved across the operation, either forward or | |
12294 | backward. Further, instructions are issued as necessary to prevent the | |
12295 | processor from speculating loads across the operation and from queuing stores | |
12296 | after the operation. | |
12297 | ||
12298 | All of the routines are described in the Intel documentation to take | |
12299 | ``an optional list of variables protected by the memory barrier''. It's | |
12300 | not clear what is meant by that; it could mean that @emph{only} the | |
12301 | listed variables are protected, or it could mean a list of additional | |
12302 | variables to be protected. The list is ignored by GCC which treats it as | |
12303 | empty. GCC interprets an empty list as meaning that all globally | |
12304 | accessible variables should be protected. | |
12305 | ||
f25efe50 AA |
12306 | @defbuiltin{@var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)} |
12307 | @defbuiltinx{@var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)} | |
12308 | @defbuiltinx{@var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)} | |
12309 | @defbuiltinx{@var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)} | |
12310 | @defbuiltinx{@var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)} | |
12311 | @defbuiltinx{@var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)} | |
d77de738 ML |
12312 | These built-in functions perform the operation suggested by the name, and |
12313 | returns the value that had previously been in memory. That is, operations | |
12314 | on integer operands have the following semantics. Operations on pointer | |
12315 | arguments are performed as if the operands were of the @code{uintptr_t} | |
12316 | type. That is, they are not scaled by the size of the type to which | |
12317 | the pointer points. | |
12318 | ||
12319 | @smallexample | |
12320 | @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} | |
12321 | @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand | |
12322 | @end smallexample | |
12323 | ||
12324 | The object pointed to by the first argument must be of integer or pointer | |
12325 | type. It must not be a boolean type. | |
12326 | ||
12327 | @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} | |
12328 | as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. | |
f25efe50 AA |
12329 | @enddefbuiltin |
12330 | ||
12331 | @defbuiltin{@var{type} __sync_add_and_fetch (@var{type} *ptr, @ | |
12332 | @var{type} value, ...)} | |
12333 | @defbuiltinx{@var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)} | |
12334 | @defbuiltinx{@var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)} | |
12335 | @defbuiltinx{@var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)} | |
12336 | @defbuiltinx{@var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)} | |
12337 | @defbuiltinx{@var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)} | |
d77de738 ML |
12338 | These built-in functions perform the operation suggested by the name, and |
12339 | return the new value. That is, operations on integer operands have | |
12340 | the following semantics. Operations on pointer operands are performed as | |
12341 | if the operand's type were @code{uintptr_t}. | |
12342 | ||
12343 | @smallexample | |
12344 | @{ *ptr @var{op}= value; return *ptr; @} | |
12345 | @{ *ptr = ~(*ptr & value); return *ptr; @} // nand | |
12346 | @end smallexample | |
12347 | ||
12348 | The same constraints on arguments apply as for the corresponding | |
12349 | @code{__sync_op_and_fetch} built-in functions. | |
12350 | ||
12351 | @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} | |
12352 | as @code{*ptr = ~(*ptr & value)} instead of | |
12353 | @code{*ptr = ~*ptr & value}. | |
f25efe50 | 12354 | @enddefbuiltin |
d77de738 | 12355 | |
f25efe50 AA |
12356 | @defbuiltin{bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)} |
12357 | @defbuiltinx{@var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)} | |
d77de738 ML |
12358 | These built-in functions perform an atomic compare and swap. |
12359 | That is, if the current | |
12360 | value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into | |
12361 | @code{*@var{ptr}}. | |
12362 | ||
12363 | The ``bool'' version returns @code{true} if the comparison is successful and | |
12364 | @var{newval} is written. The ``val'' version returns the contents | |
12365 | of @code{*@var{ptr}} before the operation. | |
f25efe50 | 12366 | @enddefbuiltin |
d77de738 | 12367 | |
f25efe50 | 12368 | @defbuiltin{void __sync_synchronize (...)} |
d77de738 | 12369 | This built-in function issues a full memory barrier. |
f25efe50 | 12370 | @enddefbuiltin |
d77de738 | 12371 | |
f25efe50 | 12372 | @defbuiltin{@var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)} |
d77de738 ML |
12373 | This built-in function, as described by Intel, is not a traditional test-and-set |
12374 | operation, but rather an atomic exchange operation. It writes @var{value} | |
12375 | into @code{*@var{ptr}}, and returns the previous contents of | |
12376 | @code{*@var{ptr}}. | |
12377 | ||
12378 | Many targets have only minimal support for such locks, and do not support | |
12379 | a full exchange operation. In this case, a target may support reduced | |
12380 | functionality here by which the @emph{only} valid value to store is the | |
12381 | immediate constant 1. The exact value actually stored in @code{*@var{ptr}} | |
12382 | is implementation defined. | |
12383 | ||
12384 | This built-in function is not a full barrier, | |
12385 | but rather an @dfn{acquire barrier}. | |
12386 | This means that references after the operation cannot move to (or be | |
12387 | speculated to) before the operation, but previous memory stores may not | |
12388 | be globally visible yet, and previous memory loads may not yet be | |
12389 | satisfied. | |
f25efe50 | 12390 | @enddefbuiltin |
d77de738 | 12391 | |
f25efe50 | 12392 | @defbuiltin{void __sync_lock_release (@var{type} *ptr, ...)} |
d77de738 ML |
12393 | This built-in function releases the lock acquired by |
12394 | @code{__sync_lock_test_and_set}. | |
12395 | Normally this means writing the constant 0 to @code{*@var{ptr}}. | |
12396 | ||
12397 | This built-in function is not a full barrier, | |
12398 | but rather a @dfn{release barrier}. | |
12399 | This means that all previous memory stores are globally visible, and all | |
12400 | previous memory loads have been satisfied, but following memory reads | |
12401 | are not prevented from being speculated to before the barrier. | |
f25efe50 | 12402 | @enddefbuiltin |
d77de738 ML |
12403 | |
12404 | @node __atomic Builtins | |
12405 | @section Built-in Functions for Memory Model Aware Atomic Operations | |
12406 | ||
12407 | The following built-in functions approximately match the requirements | |
12408 | for the C++11 memory model. They are all | |
12409 | identified by being prefixed with @samp{__atomic} and most are | |
12410 | overloaded so that they work with multiple types. | |
12411 | ||
12412 | These functions are intended to replace the legacy @samp{__sync} | |
12413 | builtins. The main difference is that the memory order that is requested | |
12414 | is a parameter to the functions. New code should always use the | |
12415 | @samp{__atomic} builtins rather than the @samp{__sync} builtins. | |
12416 | ||
12417 | Note that the @samp{__atomic} builtins assume that programs will | |
12418 | conform to the C++11 memory model. In particular, they assume | |
12419 | that programs are free of data races. See the C++11 standard for | |
12420 | detailed requirements. | |
12421 | ||
12422 | The @samp{__atomic} builtins can be used with any integral scalar or | |
12423 | pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral | |
12424 | types are also allowed if @samp{__int128} (@pxref{__int128}) is | |
12425 | supported by the architecture. | |
12426 | ||
12427 | The four non-arithmetic functions (load, store, exchange, and | |
12428 | compare_exchange) all have a generic version as well. This generic | |
12429 | version works on any data type. It uses the lock-free built-in function | |
12430 | if the specific data type size makes that possible; otherwise, an | |
12431 | external call is left to be resolved at run time. This external call is | |
12432 | the same format with the addition of a @samp{size_t} parameter inserted | |
12433 | as the first parameter indicating the size of the object being pointed to. | |
12434 | All objects must be the same size. | |
12435 | ||
12436 | There are 6 different memory orders that can be specified. These map | |
12437 | to the C++11 memory orders with the same names, see the C++11 standard | |
12438 | or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki | |
12439 | on atomic synchronization} for detailed definitions. Individual | |
12440 | targets may also support additional memory orders for use on specific | |
12441 | architectures. Refer to the target documentation for details of | |
12442 | these. | |
12443 | ||
12444 | An atomic operation can both constrain code motion and | |
12445 | be mapped to hardware instructions for synchronization between threads | |
12446 | (e.g., a fence). To which extent this happens is controlled by the | |
12447 | memory orders, which are listed here in approximately ascending order of | |
12448 | strength. The description of each memory order is only meant to roughly | |
12449 | illustrate the effects and is not a specification; see the C++11 | |
12450 | memory model for precise semantics. | |
12451 | ||
12452 | @table @code | |
12453 | @item __ATOMIC_RELAXED | |
12454 | Implies no inter-thread ordering constraints. | |
12455 | @item __ATOMIC_CONSUME | |
12456 | This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE} | |
12457 | memory order because of a deficiency in C++11's semantics for | |
12458 | @code{memory_order_consume}. | |
12459 | @item __ATOMIC_ACQUIRE | |
12460 | Creates an inter-thread happens-before constraint from the release (or | |
12461 | stronger) semantic store to this acquire load. Can prevent hoisting | |
12462 | of code to before the operation. | |
12463 | @item __ATOMIC_RELEASE | |
12464 | Creates an inter-thread happens-before constraint to acquire (or stronger) | |
12465 | semantic loads that read from this release store. Can prevent sinking | |
12466 | of code to after the operation. | |
12467 | @item __ATOMIC_ACQ_REL | |
12468 | Combines the effects of both @code{__ATOMIC_ACQUIRE} and | |
12469 | @code{__ATOMIC_RELEASE}. | |
12470 | @item __ATOMIC_SEQ_CST | |
12471 | Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations. | |
12472 | @end table | |
12473 | ||
12474 | Note that in the C++11 memory model, @emph{fences} (e.g., | |
12475 | @samp{__atomic_thread_fence}) take effect in combination with other | |
12476 | atomic operations on specific memory locations (e.g., atomic loads); | |
12477 | operations on specific memory locations do not necessarily affect other | |
12478 | operations in the same way. | |
12479 | ||
12480 | Target architectures are encouraged to provide their own patterns for | |
12481 | each of the atomic built-in functions. If no target is provided, the original | |
12482 | non-memory model set of @samp{__sync} atomic built-in functions are | |
12483 | used, along with any required synchronization fences surrounding it in | |
12484 | order to achieve the proper behavior. Execution in this case is subject | |
12485 | to the same restrictions as those built-in functions. | |
12486 | ||
12487 | If there is no pattern or mechanism to provide a lock-free instruction | |
12488 | sequence, a call is made to an external routine with the same parameters | |
12489 | to be resolved at run time. | |
12490 | ||
12491 | When implementing patterns for these built-in functions, the memory order | |
12492 | parameter can be ignored as long as the pattern implements the most | |
12493 | restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory | |
12494 | orders execute correctly with this memory order but they may not execute as | |
12495 | efficiently as they could with a more appropriate implementation of the | |
12496 | relaxed requirements. | |
12497 | ||
12498 | Note that the C++11 standard allows for the memory order parameter to be | |
12499 | determined at run time rather than at compile time. These built-in | |
12500 | functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather | |
12501 | than invoke a runtime library call or inline a switch statement. This is | |
12502 | standard compliant, safe, and the simplest approach for now. | |
12503 | ||
12504 | The memory order parameter is a signed int, but only the lower 16 bits are | |
12505 | reserved for the memory order. The remainder of the signed int is reserved | |
12506 | for target use and should be 0. Use of the predefined atomic values | |
12507 | ensures proper usage. | |
12508 | ||
f25efe50 | 12509 | @defbuiltin{@var{type} __atomic_load_n (@var{type} *ptr, int memorder)} |
d77de738 ML |
12510 | This built-in function implements an atomic load operation. It returns the |
12511 | contents of @code{*@var{ptr}}. | |
12512 | ||
12513 | The valid memory order variants are | |
12514 | @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, | |
12515 | and @code{__ATOMIC_CONSUME}. | |
12516 | ||
f25efe50 | 12517 | @enddefbuiltin |
d77de738 | 12518 | |
f25efe50 | 12519 | @defbuiltin{void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)} |
d77de738 ML |
12520 | This is the generic version of an atomic load. It returns the |
12521 | contents of @code{*@var{ptr}} in @code{*@var{ret}}. | |
12522 | ||
f25efe50 | 12523 | @enddefbuiltin |
d77de738 | 12524 | |
f25efe50 | 12525 | @defbuiltin{void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)} |
d77de738 ML |
12526 | This built-in function implements an atomic store operation. It writes |
12527 | @code{@var{val}} into @code{*@var{ptr}}. | |
12528 | ||
12529 | The valid memory order variants are | |
12530 | @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. | |
12531 | ||
f25efe50 | 12532 | @enddefbuiltin |
d77de738 | 12533 | |
f25efe50 | 12534 | @defbuiltin{void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)} |
d77de738 ML |
12535 | This is the generic version of an atomic store. It stores the value |
12536 | of @code{*@var{val}} into @code{*@var{ptr}}. | |
12537 | ||
f25efe50 | 12538 | @enddefbuiltin |
d77de738 | 12539 | |
f25efe50 | 12540 | @defbuiltin{@var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)} |
d77de738 ML |
12541 | This built-in function implements an atomic exchange operation. It writes |
12542 | @var{val} into @code{*@var{ptr}}, and returns the previous contents of | |
12543 | @code{*@var{ptr}}. | |
12544 | ||
12545 | All memory order variants are valid. | |
12546 | ||
f25efe50 | 12547 | @enddefbuiltin |
d77de738 | 12548 | |
f25efe50 | 12549 | @defbuiltin{void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)} |
d77de738 ML |
12550 | This is the generic version of an atomic exchange. It stores the |
12551 | contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value | |
12552 | of @code{*@var{ptr}} is copied into @code{*@var{ret}}. | |
12553 | ||
f25efe50 | 12554 | @enddefbuiltin |
d77de738 | 12555 | |
f25efe50 | 12556 | @defbuiltin{bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memorder, int failure_memorder)} |
d77de738 ML |
12557 | This built-in function implements an atomic compare and exchange operation. |
12558 | This compares the contents of @code{*@var{ptr}} with the contents of | |
12559 | @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} | |
12560 | operation that writes @var{desired} into @code{*@var{ptr}}. If they are not | |
12561 | equal, the operation is a @emph{read} and the current contents of | |
12562 | @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true} | |
12563 | for weak compare_exchange, which may fail spuriously, and @code{false} for | |
12564 | the strong variation, which never fails spuriously. Many targets | |
12565 | only offer the strong variation and ignore the parameter. When in doubt, use | |
12566 | the strong variation. | |
12567 | ||
12568 | If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned | |
12569 | and memory is affected according to the | |
12570 | memory order specified by @var{success_memorder}. There are no | |
12571 | restrictions on what memory order can be used here. | |
12572 | ||
12573 | Otherwise, @code{false} is returned and memory is affected according | |
12574 | to @var{failure_memorder}. This memory order cannot be | |
12575 | @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a | |
12576 | stronger order than that specified by @var{success_memorder}. | |
12577 | ||
f25efe50 | 12578 | @enddefbuiltin |
d77de738 | 12579 | |
f25efe50 | 12580 | @defbuiltin{bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memorder, int failure_memorder)} |
d77de738 ML |
12581 | This built-in function implements the generic version of |
12582 | @code{__atomic_compare_exchange}. The function is virtually identical to | |
12583 | @code{__atomic_compare_exchange_n}, except the desired value is also a | |
12584 | pointer. | |
12585 | ||
f25efe50 | 12586 | @enddefbuiltin |
d77de738 | 12587 | |
f25efe50 AA |
12588 | @defbuiltin{@var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)} |
12589 | @defbuiltinx{@var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)} | |
12590 | @defbuiltinx{@var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)} | |
12591 | @defbuiltinx{@var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)} | |
12592 | @defbuiltinx{@var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)} | |
12593 | @defbuiltinx{@var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)} | |
d77de738 ML |
12594 | These built-in functions perform the operation suggested by the name, and |
12595 | return the result of the operation. Operations on pointer arguments are | |
12596 | performed as if the operands were of the @code{uintptr_t} type. That is, | |
12597 | they are not scaled by the size of the type to which the pointer points. | |
12598 | ||
12599 | @smallexample | |
12600 | @{ *ptr @var{op}= val; return *ptr; @} | |
12601 | @{ *ptr = ~(*ptr & val); return *ptr; @} // nand | |
12602 | @end smallexample | |
12603 | ||
12604 | The object pointed to by the first argument must be of integer or pointer | |
12605 | type. It must not be a boolean type. All memory orders are valid. | |
12606 | ||
f25efe50 | 12607 | @enddefbuiltin |
d77de738 | 12608 | |
f25efe50 AA |
12609 | @defbuiltin{@var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)} |
12610 | @defbuiltinx{@var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)} | |
12611 | @defbuiltinx{@var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)} | |
12612 | @defbuiltinx{@var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)} | |
12613 | @defbuiltinx{@var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)} | |
12614 | @defbuiltinx{@var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)} | |
d77de738 ML |
12615 | These built-in functions perform the operation suggested by the name, and |
12616 | return the value that had previously been in @code{*@var{ptr}}. Operations | |
12617 | on pointer arguments are performed as if the operands were of | |
12618 | the @code{uintptr_t} type. That is, they are not scaled by the size of | |
12619 | the type to which the pointer points. | |
12620 | ||
12621 | @smallexample | |
12622 | @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} | |
12623 | @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand | |
12624 | @end smallexample | |
12625 | ||
12626 | The same constraints on arguments apply as for the corresponding | |
12627 | @code{__atomic_op_fetch} built-in functions. All memory orders are valid. | |
12628 | ||
f25efe50 | 12629 | @enddefbuiltin |
d77de738 | 12630 | |
f25efe50 | 12631 | @defbuiltin{bool __atomic_test_and_set (void *ptr, int memorder)} |
d77de738 ML |
12632 | |
12633 | This built-in function performs an atomic test-and-set operation on | |
12634 | the byte at @code{*@var{ptr}}. The byte is set to some implementation | |
12635 | defined nonzero ``set'' value and the return value is @code{true} if and only | |
12636 | if the previous contents were ``set''. | |
12637 | It should be only used for operands of type @code{bool} or @code{char}. For | |
12638 | other types only part of the value may be set. | |
12639 | ||
12640 | All memory orders are valid. | |
12641 | ||
f25efe50 | 12642 | @enddefbuiltin |
d77de738 | 12643 | |
f25efe50 | 12644 | @defbuiltin{void __atomic_clear (bool *ptr, int memorder)} |
d77de738 ML |
12645 | |
12646 | This built-in function performs an atomic clear operation on | |
12647 | @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. | |
12648 | It should be only used for operands of type @code{bool} or @code{char} and | |
12649 | in conjunction with @code{__atomic_test_and_set}. | |
12650 | For other types it may only clear partially. If the type is not @code{bool} | |
12651 | prefer using @code{__atomic_store}. | |
12652 | ||
12653 | The valid memory order variants are | |
12654 | @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and | |
12655 | @code{__ATOMIC_RELEASE}. | |
12656 | ||
f25efe50 | 12657 | @enddefbuiltin |
d77de738 | 12658 | |
f25efe50 | 12659 | @defbuiltin{void __atomic_thread_fence (int memorder)} |
d77de738 ML |
12660 | |
12661 | This built-in function acts as a synchronization fence between threads | |
12662 | based on the specified memory order. | |
12663 | ||
12664 | All memory orders are valid. | |
12665 | ||
f25efe50 | 12666 | @enddefbuiltin |
d77de738 | 12667 | |
f25efe50 | 12668 | @defbuiltin{void __atomic_signal_fence (int memorder)} |
d77de738 ML |
12669 | |
12670 | This built-in function acts as a synchronization fence between a thread | |
12671 | and signal handlers based in the same thread. | |
12672 | ||
12673 | All memory orders are valid. | |
12674 | ||
f25efe50 | 12675 | @enddefbuiltin |
d77de738 | 12676 | |
f25efe50 | 12677 | @defbuiltin{bool __atomic_always_lock_free (size_t size, void *ptr)} |
d77de738 ML |
12678 | |
12679 | This built-in function returns @code{true} if objects of @var{size} bytes always | |
12680 | generate lock-free atomic instructions for the target architecture. | |
12681 | @var{size} must resolve to a compile-time constant and the result also | |
12682 | resolves to a compile-time constant. | |
12683 | ||
12684 | @var{ptr} is an optional pointer to the object that may be used to determine | |
12685 | alignment. A value of 0 indicates typical alignment should be used. The | |
12686 | compiler may also ignore this parameter. | |
12687 | ||
12688 | @smallexample | |
12689 | if (__atomic_always_lock_free (sizeof (long long), 0)) | |
12690 | @end smallexample | |
12691 | ||
f25efe50 | 12692 | @enddefbuiltin |
d77de738 | 12693 | |
f25efe50 | 12694 | @defbuiltin{bool __atomic_is_lock_free (size_t size, void *ptr)} |
d77de738 ML |
12695 | |
12696 | This built-in function returns @code{true} if objects of @var{size} bytes always | |
12697 | generate lock-free atomic instructions for the target architecture. If | |
12698 | the built-in function is not known to be lock-free, a call is made to a | |
12699 | runtime routine named @code{__atomic_is_lock_free}. | |
12700 | ||
12701 | @var{ptr} is an optional pointer to the object that may be used to determine | |
12702 | alignment. A value of 0 indicates typical alignment should be used. The | |
12703 | compiler may also ignore this parameter. | |
f25efe50 | 12704 | @enddefbuiltin |
d77de738 ML |
12705 | |
12706 | @node Integer Overflow Builtins | |
12707 | @section Built-in Functions to Perform Arithmetic with Overflow Checking | |
12708 | ||
12709 | The following built-in functions allow performing simple arithmetic operations | |
12710 | together with checking whether the operations overflowed. | |
12711 | ||
f25efe50 AA |
12712 | @defbuiltin{bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)} |
12713 | @defbuiltinx{bool __builtin_sadd_overflow (int a, int b, int *res)} | |
12714 | @defbuiltinx{bool __builtin_saddl_overflow (long int a, long int b, long int *res)} | |
12715 | @defbuiltinx{bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)} | |
12716 | @defbuiltinx{bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)} | |
12717 | @defbuiltinx{bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)} | |
12718 | @defbuiltinx{bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)} | |
d77de738 ML |
12719 | |
12720 | These built-in functions promote the first two operands into infinite precision signed | |
12721 | type and perform addition on those promoted operands. The result is then | |
12722 | cast to the type the third pointer argument points to and stored there. | |
12723 | If the stored result is equal to the infinite precision result, the built-in | |
12724 | functions return @code{false}, otherwise they return @code{true}. As the addition is | |
12725 | performed in infinite signed precision, these built-in functions have fully defined | |
12726 | behavior for all argument values. | |
12727 | ||
12728 | The first built-in function allows arbitrary integral types for operands and | |
12729 | the result type must be pointer to some integral type other than enumerated or | |
12730 | boolean type, the rest of the built-in functions have explicit integer types. | |
12731 | ||
12732 | The compiler will attempt to use hardware instructions to implement | |
12733 | these built-in functions where possible, like conditional jump on overflow | |
12734 | after addition, conditional jump on carry etc. | |
12735 | ||
f25efe50 | 12736 | @enddefbuiltin |
d77de738 | 12737 | |
f25efe50 AA |
12738 | @defbuiltin{bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)} |
12739 | @defbuiltinx{bool __builtin_ssub_overflow (int a, int b, int *res)} | |
12740 | @defbuiltinx{bool __builtin_ssubl_overflow (long int a, long int b, long int *res)} | |
12741 | @defbuiltinx{bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)} | |
12742 | @defbuiltinx{bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)} | |
12743 | @defbuiltinx{bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)} | |
12744 | @defbuiltinx{bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)} | |
d77de738 ML |
12745 | |
12746 | These built-in functions are similar to the add overflow checking built-in | |
12747 | functions above, except they perform subtraction, subtract the second argument | |
12748 | from the first one, instead of addition. | |
12749 | ||
f25efe50 | 12750 | @enddefbuiltin |
d77de738 | 12751 | |
f25efe50 AA |
12752 | @defbuiltin{bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)} |
12753 | @defbuiltinx{bool __builtin_smul_overflow (int a, int b, int *res)} | |
12754 | @defbuiltinx{bool __builtin_smull_overflow (long int a, long int b, long int *res)} | |
12755 | @defbuiltinx{bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)} | |
12756 | @defbuiltinx{bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)} | |
12757 | @defbuiltinx{bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)} | |
12758 | @defbuiltinx{bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)} | |
d77de738 ML |
12759 | |
12760 | These built-in functions are similar to the add overflow checking built-in | |
12761 | functions above, except they perform multiplication, instead of addition. | |
12762 | ||
f25efe50 | 12763 | @enddefbuiltin |
d77de738 ML |
12764 | |
12765 | The following built-in functions allow checking if simple arithmetic operation | |
12766 | would overflow. | |
12767 | ||
f25efe50 AA |
12768 | @defbuiltin{bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)} |
12769 | @defbuiltinx{bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)} | |
12770 | @defbuiltinx{bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)} | |
d77de738 ML |
12771 | |
12772 | These built-in functions are similar to @code{__builtin_add_overflow}, | |
12773 | @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that | |
12774 | they don't store the result of the arithmetic operation anywhere and the | |
12775 | last argument is not a pointer, but some expression with integral type other | |
12776 | than enumerated or boolean type. | |
12777 | ||
12778 | The built-in functions promote the first two operands into infinite precision signed type | |
12779 | and perform addition on those promoted operands. The result is then | |
12780 | cast to the type of the third argument. If the cast result is equal to the infinite | |
12781 | precision result, the built-in functions return @code{false}, otherwise they return @code{true}. | |
12782 | The value of the third argument is ignored, just the side effects in the third argument | |
12783 | are evaluated, and no integral argument promotions are performed on the last argument. | |
12784 | If the third argument is a bit-field, the type used for the result cast has the | |
12785 | precision and signedness of the given bit-field, rather than precision and signedness | |
12786 | of the underlying type. | |
12787 | ||
12788 | For example, the following macro can be used to portably check, at | |
12789 | compile-time, whether or not adding two constant integers will overflow, | |
12790 | and perform the addition only when it is known to be safe and not to trigger | |
12791 | a @option{-Woverflow} warning. | |
12792 | ||
12793 | @smallexample | |
12794 | #define INT_ADD_OVERFLOW_P(a, b) \ | |
12795 | __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) | |
12796 | ||
12797 | enum @{ | |
12798 | A = INT_MAX, B = 3, | |
12799 | C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, | |
12800 | D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) | |
12801 | @}; | |
12802 | @end smallexample | |
12803 | ||
12804 | The compiler will attempt to use hardware instructions to implement | |
12805 | these built-in functions where possible, like conditional jump on overflow | |
12806 | after addition, conditional jump on carry etc. | |
12807 | ||
f25efe50 | 12808 | @enddefbuiltin |
d77de738 ML |
12809 | |
12810 | @node x86 specific memory model extensions for transactional memory | |
12811 | @section x86-Specific Memory Model Extensions for Transactional Memory | |
12812 | ||
12813 | The x86 architecture supports additional memory ordering flags | |
12814 | to mark critical sections for hardware lock elision. | |
12815 | These must be specified in addition to an existing memory order to | |
12816 | atomic intrinsics. | |
12817 | ||
12818 | @table @code | |
12819 | @item __ATOMIC_HLE_ACQUIRE | |
12820 | Start lock elision on a lock variable. | |
12821 | Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. | |
12822 | @item __ATOMIC_HLE_RELEASE | |
12823 | End lock elision on a lock variable. | |
12824 | Memory order must be @code{__ATOMIC_RELEASE} or stronger. | |
12825 | @end table | |
12826 | ||
12827 | When a lock acquire fails, it is required for good performance to abort | |
12828 | the transaction quickly. This can be done with a @code{_mm_pause}. | |
12829 | ||
12830 | @smallexample | |
12831 | #include <immintrin.h> // For _mm_pause | |
12832 | ||
12833 | int lockvar; | |
12834 | ||
12835 | /* Acquire lock with lock elision */ | |
12836 | while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) | |
12837 | _mm_pause(); /* Abort failed transaction */ | |
12838 | ... | |
12839 | /* Free lock with lock elision */ | |
12840 | __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); | |
12841 | @end smallexample | |
12842 | ||
12843 | @node Object Size Checking | |
b3009222 SP |
12844 | @section Object Size Checking |
12845 | ||
12846 | @subsection Object Size Checking Built-in Functions | |
d77de738 ML |
12847 | @findex __builtin___memcpy_chk |
12848 | @findex __builtin___mempcpy_chk | |
12849 | @findex __builtin___memmove_chk | |
12850 | @findex __builtin___memset_chk | |
12851 | @findex __builtin___strcpy_chk | |
12852 | @findex __builtin___stpcpy_chk | |
12853 | @findex __builtin___strncpy_chk | |
12854 | @findex __builtin___strcat_chk | |
12855 | @findex __builtin___strncat_chk | |
d77de738 ML |
12856 | |
12857 | GCC implements a limited buffer overflow protection mechanism that can | |
12858 | prevent some buffer overflow attacks by determining the sizes of objects | |
12859 | into which data is about to be written and preventing the writes when | |
12860 | the size isn't sufficient. The built-in functions described below yield | |
12861 | the best results when used together and when optimization is enabled. | |
12862 | For example, to detect object sizes across function boundaries or to | |
12863 | follow pointer assignments through non-trivial control flow they rely | |
12864 | on various optimization passes enabled with @option{-O2}. However, to | |
12865 | a limited extent, they can be used without optimization as well. | |
12866 | ||
f25efe50 | 12867 | @defbuiltin{size_t __builtin_object_size (const void * @var{ptr}, int @var{type})} |
d77de738 ML |
12868 | is a built-in construct that returns a constant number of bytes from |
12869 | @var{ptr} to the end of the object @var{ptr} pointer points to | |
12870 | (if known at compile time). To determine the sizes of dynamically allocated | |
12871 | objects the function relies on the allocation functions called to obtain | |
12872 | the storage to be declared with the @code{alloc_size} attribute (@pxref{Common | |
12873 | Function Attributes}). @code{__builtin_object_size} never evaluates | |
12874 | its arguments for side effects. If there are any side effects in them, it | |
12875 | returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} | |
12876 | for @var{type} 2 or 3. If there are multiple objects @var{ptr} can | |
12877 | point to and all of them are known at compile time, the returned number | |
12878 | is the maximum of remaining byte counts in those objects if @var{type} & 2 is | |
12879 | 0 and minimum if nonzero. If it is not possible to determine which objects | |
12880 | @var{ptr} points to at compile time, @code{__builtin_object_size} should | |
12881 | return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} | |
12882 | for @var{type} 2 or 3. | |
12883 | ||
12884 | @var{type} is an integer constant from 0 to 3. If the least significant | |
12885 | bit is clear, objects are whole variables, if it is set, a closest | |
12886 | surrounding subobject is considered the object a pointer points to. | |
12887 | The second bit determines if maximum or minimum of remaining bytes | |
12888 | is computed. | |
12889 | ||
12890 | @smallexample | |
12891 | struct V @{ char buf1[10]; int b; char buf2[10]; @} var; | |
12892 | char *p = &var.buf1[1], *q = &var.b; | |
12893 | ||
12894 | /* Here the object p points to is var. */ | |
12895 | assert (__builtin_object_size (p, 0) == sizeof (var) - 1); | |
12896 | /* The subobject p points to is var.buf1. */ | |
12897 | assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); | |
12898 | /* The object q points to is var. */ | |
12899 | assert (__builtin_object_size (q, 0) | |
12900 | == (char *) (&var + 1) - (char *) &var.b); | |
12901 | /* The subobject q points to is var.b. */ | |
12902 | assert (__builtin_object_size (q, 1) == sizeof (var.b)); | |
12903 | @end smallexample | |
f25efe50 | 12904 | @enddefbuiltin |
d77de738 | 12905 | |
f25efe50 | 12906 | @defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} |
d77de738 ML |
12907 | is similar to @code{__builtin_object_size} in that it returns a number of bytes |
12908 | from @var{ptr} to the end of the object @var{ptr} pointer points to, except | |
12909 | that the size returned may not be a constant. This results in successful | |
12910 | evaluation of object size estimates in a wider range of use cases and can be | |
12911 | more precise than @code{__builtin_object_size}, but it incurs a performance | |
12912 | penalty since it may add a runtime overhead on size computation. Semantics of | |
12913 | @var{type} as well as return values in case it is not possible to determine | |
12914 | which objects @var{ptr} points to at compile time are the same as in the case | |
12915 | of @code{__builtin_object_size}. | |
f25efe50 | 12916 | @enddefbuiltin |
d77de738 | 12917 | |
b3009222 SP |
12918 | @subsection Object Size Checking and Source Fortification |
12919 | ||
12920 | Hardening of function calls using the @code{_FORTIFY_SOURCE} macro is | |
12921 | one of the key uses of the object size checking built-in functions. To | |
12922 | make implementation of these features more convenient and improve | |
12923 | optimization and diagnostics, there are built-in functions added for | |
12924 | many common string operation functions, e.g., for @code{memcpy} | |
12925 | @code{__builtin___memcpy_chk} built-in is provided. This built-in has | |
12926 | an additional last argument, which is the number of bytes remaining in | |
12927 | the object the @var{dest} argument points to or @code{(size_t) -1} if | |
12928 | the size is not known. | |
d77de738 ML |
12929 | |
12930 | The built-in functions are optimized into the normal string functions | |
12931 | like @code{memcpy} if the last argument is @code{(size_t) -1} or if | |
12932 | it is known at compile time that the destination object will not | |
12933 | be overflowed. If the compiler can determine at compile time that the | |
12934 | object will always be overflowed, it issues a warning. | |
12935 | ||
12936 | The intended use can be e.g.@: | |
12937 | ||
12938 | @smallexample | |
12939 | #undef memcpy | |
12940 | #define bos0(dest) __builtin_object_size (dest, 0) | |
12941 | #define memcpy(dest, src, n) \ | |
12942 | __builtin___memcpy_chk (dest, src, n, bos0 (dest)) | |
12943 | ||
12944 | char *volatile p; | |
12945 | char buf[10]; | |
12946 | /* It is unknown what object p points to, so this is optimized | |
12947 | into plain memcpy - no checking is possible. */ | |
12948 | memcpy (p, "abcde", n); | |
12949 | /* Destination is known and length too. It is known at compile | |
12950 | time there will be no overflow. */ | |
12951 | memcpy (&buf[5], "abcde", 5); | |
12952 | /* Destination is known, but the length is not known at compile time. | |
12953 | This will result in __memcpy_chk call that can check for overflow | |
12954 | at run time. */ | |
12955 | memcpy (&buf[5], "abcde", n); | |
12956 | /* Destination is known and it is known at compile time there will | |
12957 | be overflow. There will be a warning and __memcpy_chk call that | |
12958 | will abort the program at run time. */ | |
12959 | memcpy (&buf[6], "abcde", 5); | |
12960 | @end smallexample | |
12961 | ||
12962 | Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, | |
12963 | @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, | |
12964 | @code{strcat} and @code{strncat}. | |
12965 | ||
e1e5ecb2 | 12966 | @subsubsection Formatted Output Function Checking |
f25efe50 AA |
12967 | @defbuiltin{int __builtin___sprintf_chk @ |
12968 | (char *@var{s}, int @var{flag}, size_t @var{os}, @ | |
12969 | const char *@var{fmt}, ...)} | |
12970 | @defbuiltinx{int __builtin___snprintf_chk @ | |
12971 | (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @ | |
12972 | size_t @var{os}, const char *@var{fmt}, ...)} | |
12973 | @defbuiltinx{int __builtin___vsprintf_chk @ | |
12974 | (char *@var{s}, int @var{flag}, size_t @var{os}, @ | |
12975 | const char *@var{fmt}, va_list @var{ap})} | |
12976 | @defbuiltinx{int __builtin___vsnprintf_chk @ | |
12977 | (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @ | |
12978 | size_t @var{os}, const char *@var{fmt}, @ | |
12979 | va_list @var{ap})} | |
d77de738 ML |
12980 | |
12981 | The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} | |
12982 | etc.@: functions and can contain implementation specific flags on what | |
12983 | additional security measures the checking function might take, such as | |
12984 | handling @code{%n} differently. | |
12985 | ||
12986 | The @var{os} argument is the object size @var{s} points to, like in the | |
12987 | other built-in functions. There is a small difference in the behavior | |
12988 | though, if @var{os} is @code{(size_t) -1}, the built-in functions are | |
12989 | optimized into the non-checking functions only if @var{flag} is 0, otherwise | |
12990 | the checking function is called with @var{os} argument set to | |
12991 | @code{(size_t) -1}. | |
12992 | ||
12993 | In addition to this, there are checking built-in functions | |
12994 | @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, | |
12995 | @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. | |
12996 | These have just one additional argument, @var{flag}, right before | |
12997 | format string @var{fmt}. If the compiler is able to optimize them to | |
12998 | @code{fputc} etc.@: functions, it does, otherwise the checking function | |
12999 | is called and the @var{flag} argument passed to it. | |
f25efe50 | 13000 | @enddefbuiltin |
d77de738 ML |
13001 | |
13002 | @node Other Builtins | |
13003 | @section Other Built-in Functions Provided by GCC | |
13004 | @cindex built-in functions | |
d77de738 ML |
13005 | @findex __builtin_isfinite |
13006 | @findex __builtin_isnormal | |
13007 | @findex __builtin_isgreater | |
13008 | @findex __builtin_isgreaterequal | |
d77de738 | 13009 | @findex __builtin_isunordered |
d77de738 ML |
13010 | @findex __builtin_speculation_safe_value |
13011 | @findex _Exit | |
13012 | @findex _exit | |
13013 | @findex abort | |
13014 | @findex abs | |
13015 | @findex acos | |
13016 | @findex acosf | |
13017 | @findex acosh | |
13018 | @findex acoshf | |
13019 | @findex acoshl | |
13020 | @findex acosl | |
13021 | @findex alloca | |
13022 | @findex asin | |
13023 | @findex asinf | |
13024 | @findex asinh | |
13025 | @findex asinhf | |
13026 | @findex asinhl | |
13027 | @findex asinl | |
13028 | @findex atan | |
13029 | @findex atan2 | |
13030 | @findex atan2f | |
13031 | @findex atan2l | |
13032 | @findex atanf | |
13033 | @findex atanh | |
13034 | @findex atanhf | |
13035 | @findex atanhl | |
13036 | @findex atanl | |
13037 | @findex bcmp | |
13038 | @findex bzero | |
13039 | @findex cabs | |
13040 | @findex cabsf | |
13041 | @findex cabsl | |
13042 | @findex cacos | |
13043 | @findex cacosf | |
13044 | @findex cacosh | |
13045 | @findex cacoshf | |
13046 | @findex cacoshl | |
13047 | @findex cacosl | |
13048 | @findex calloc | |
13049 | @findex carg | |
13050 | @findex cargf | |
13051 | @findex cargl | |
13052 | @findex casin | |
13053 | @findex casinf | |
13054 | @findex casinh | |
13055 | @findex casinhf | |
13056 | @findex casinhl | |
13057 | @findex casinl | |
13058 | @findex catan | |
13059 | @findex catanf | |
13060 | @findex catanh | |
13061 | @findex catanhf | |
13062 | @findex catanhl | |
13063 | @findex catanl | |
13064 | @findex cbrt | |
13065 | @findex cbrtf | |
13066 | @findex cbrtl | |
13067 | @findex ccos | |
13068 | @findex ccosf | |
13069 | @findex ccosh | |
13070 | @findex ccoshf | |
13071 | @findex ccoshl | |
13072 | @findex ccosl | |
13073 | @findex ceil | |
13074 | @findex ceilf | |
13075 | @findex ceill | |
13076 | @findex cexp | |
13077 | @findex cexpf | |
13078 | @findex cexpl | |
13079 | @findex cimag | |
13080 | @findex cimagf | |
13081 | @findex cimagl | |
13082 | @findex clog | |
13083 | @findex clogf | |
13084 | @findex clogl | |
13085 | @findex clog10 | |
13086 | @findex clog10f | |
13087 | @findex clog10l | |
13088 | @findex conj | |
13089 | @findex conjf | |
13090 | @findex conjl | |
13091 | @findex copysign | |
13092 | @findex copysignf | |
13093 | @findex copysignl | |
13094 | @findex cos | |
13095 | @findex cosf | |
13096 | @findex cosh | |
13097 | @findex coshf | |
13098 | @findex coshl | |
13099 | @findex cosl | |
13100 | @findex cpow | |
13101 | @findex cpowf | |
13102 | @findex cpowl | |
13103 | @findex cproj | |
13104 | @findex cprojf | |
13105 | @findex cprojl | |
13106 | @findex creal | |
13107 | @findex crealf | |
13108 | @findex creall | |
13109 | @findex csin | |
13110 | @findex csinf | |
13111 | @findex csinh | |
13112 | @findex csinhf | |
13113 | @findex csinhl | |
13114 | @findex csinl | |
13115 | @findex csqrt | |
13116 | @findex csqrtf | |
13117 | @findex csqrtl | |
13118 | @findex ctan | |
13119 | @findex ctanf | |
13120 | @findex ctanh | |
13121 | @findex ctanhf | |
13122 | @findex ctanhl | |
13123 | @findex ctanl | |
13124 | @findex dcgettext | |
13125 | @findex dgettext | |
13126 | @findex drem | |
13127 | @findex dremf | |
13128 | @findex dreml | |
13129 | @findex erf | |
13130 | @findex erfc | |
13131 | @findex erfcf | |
13132 | @findex erfcl | |
13133 | @findex erff | |
13134 | @findex erfl | |
13135 | @findex exit | |
13136 | @findex exp | |
13137 | @findex exp10 | |
13138 | @findex exp10f | |
13139 | @findex exp10l | |
13140 | @findex exp2 | |
13141 | @findex exp2f | |
13142 | @findex exp2l | |
13143 | @findex expf | |
13144 | @findex expl | |
13145 | @findex expm1 | |
13146 | @findex expm1f | |
13147 | @findex expm1l | |
13148 | @findex fabs | |
13149 | @findex fabsf | |
13150 | @findex fabsl | |
13151 | @findex fdim | |
13152 | @findex fdimf | |
13153 | @findex fdiml | |
13154 | @findex ffs | |
13155 | @findex floor | |
13156 | @findex floorf | |
13157 | @findex floorl | |
13158 | @findex fma | |
13159 | @findex fmaf | |
13160 | @findex fmal | |
13161 | @findex fmax | |
13162 | @findex fmaxf | |
13163 | @findex fmaxl | |
13164 | @findex fmin | |
13165 | @findex fminf | |
13166 | @findex fminl | |
13167 | @findex fmod | |
13168 | @findex fmodf | |
13169 | @findex fmodl | |
13170 | @findex fprintf | |
13171 | @findex fprintf_unlocked | |
13172 | @findex fputs | |
13173 | @findex fputs_unlocked | |
13174 | @findex free | |
13175 | @findex frexp | |
13176 | @findex frexpf | |
13177 | @findex frexpl | |
13178 | @findex fscanf | |
13179 | @findex gamma | |
13180 | @findex gammaf | |
13181 | @findex gammal | |
13182 | @findex gamma_r | |
13183 | @findex gammaf_r | |
13184 | @findex gammal_r | |
13185 | @findex gettext | |
13186 | @findex hypot | |
13187 | @findex hypotf | |
13188 | @findex hypotl | |
13189 | @findex ilogb | |
13190 | @findex ilogbf | |
13191 | @findex ilogbl | |
13192 | @findex imaxabs | |
13193 | @findex index | |
13194 | @findex isalnum | |
13195 | @findex isalpha | |
13196 | @findex isascii | |
13197 | @findex isblank | |
13198 | @findex iscntrl | |
13199 | @findex isdigit | |
13200 | @findex isgraph | |
13201 | @findex islower | |
13202 | @findex isprint | |
13203 | @findex ispunct | |
13204 | @findex isspace | |
13205 | @findex isupper | |
13206 | @findex iswalnum | |
13207 | @findex iswalpha | |
13208 | @findex iswblank | |
13209 | @findex iswcntrl | |
13210 | @findex iswdigit | |
13211 | @findex iswgraph | |
13212 | @findex iswlower | |
13213 | @findex iswprint | |
13214 | @findex iswpunct | |
13215 | @findex iswspace | |
13216 | @findex iswupper | |
13217 | @findex iswxdigit | |
13218 | @findex isxdigit | |
13219 | @findex j0 | |
13220 | @findex j0f | |
13221 | @findex j0l | |
13222 | @findex j1 | |
13223 | @findex j1f | |
13224 | @findex j1l | |
13225 | @findex jn | |
13226 | @findex jnf | |
13227 | @findex jnl | |
13228 | @findex labs | |
13229 | @findex ldexp | |
13230 | @findex ldexpf | |
13231 | @findex ldexpl | |
13232 | @findex lgamma | |
13233 | @findex lgammaf | |
13234 | @findex lgammal | |
13235 | @findex lgamma_r | |
13236 | @findex lgammaf_r | |
13237 | @findex lgammal_r | |
13238 | @findex llabs | |
13239 | @findex llrint | |
13240 | @findex llrintf | |
13241 | @findex llrintl | |
13242 | @findex llround | |
13243 | @findex llroundf | |
13244 | @findex llroundl | |
13245 | @findex log | |
13246 | @findex log10 | |
13247 | @findex log10f | |
13248 | @findex log10l | |
13249 | @findex log1p | |
13250 | @findex log1pf | |
13251 | @findex log1pl | |
13252 | @findex log2 | |
13253 | @findex log2f | |
13254 | @findex log2l | |
13255 | @findex logb | |
13256 | @findex logbf | |
13257 | @findex logbl | |
13258 | @findex logf | |
13259 | @findex logl | |
13260 | @findex lrint | |
13261 | @findex lrintf | |
13262 | @findex lrintl | |
13263 | @findex lround | |
13264 | @findex lroundf | |
13265 | @findex lroundl | |
13266 | @findex malloc | |
13267 | @findex memchr | |
13268 | @findex memcmp | |
13269 | @findex memcpy | |
13270 | @findex mempcpy | |
13271 | @findex memset | |
13272 | @findex modf | |
13273 | @findex modff | |
13274 | @findex modfl | |
13275 | @findex nearbyint | |
13276 | @findex nearbyintf | |
13277 | @findex nearbyintl | |
13278 | @findex nextafter | |
13279 | @findex nextafterf | |
13280 | @findex nextafterl | |
13281 | @findex nexttoward | |
13282 | @findex nexttowardf | |
13283 | @findex nexttowardl | |
13284 | @findex pow | |
13285 | @findex pow10 | |
13286 | @findex pow10f | |
13287 | @findex pow10l | |
13288 | @findex powf | |
13289 | @findex powl | |
13290 | @findex printf | |
13291 | @findex printf_unlocked | |
13292 | @findex putchar | |
13293 | @findex puts | |
13294 | @findex realloc | |
13295 | @findex remainder | |
13296 | @findex remainderf | |
13297 | @findex remainderl | |
13298 | @findex remquo | |
13299 | @findex remquof | |
13300 | @findex remquol | |
13301 | @findex rindex | |
13302 | @findex rint | |
13303 | @findex rintf | |
13304 | @findex rintl | |
13305 | @findex round | |
13306 | @findex roundf | |
13307 | @findex roundl | |
13308 | @findex scalb | |
13309 | @findex scalbf | |
13310 | @findex scalbl | |
13311 | @findex scalbln | |
13312 | @findex scalblnf | |
13313 | @findex scalblnf | |
13314 | @findex scalbn | |
13315 | @findex scalbnf | |
13316 | @findex scanfnl | |
13317 | @findex signbit | |
13318 | @findex signbitf | |
13319 | @findex signbitl | |
13320 | @findex signbitd32 | |
13321 | @findex signbitd64 | |
13322 | @findex signbitd128 | |
13323 | @findex significand | |
13324 | @findex significandf | |
13325 | @findex significandl | |
13326 | @findex sin | |
13327 | @findex sincos | |
13328 | @findex sincosf | |
13329 | @findex sincosl | |
13330 | @findex sinf | |
13331 | @findex sinh | |
13332 | @findex sinhf | |
13333 | @findex sinhl | |
13334 | @findex sinl | |
13335 | @findex snprintf | |
13336 | @findex sprintf | |
13337 | @findex sqrt | |
13338 | @findex sqrtf | |
13339 | @findex sqrtl | |
13340 | @findex sscanf | |
13341 | @findex stpcpy | |
13342 | @findex stpncpy | |
13343 | @findex strcasecmp | |
13344 | @findex strcat | |
13345 | @findex strchr | |
13346 | @findex strcmp | |
13347 | @findex strcpy | |
13348 | @findex strcspn | |
13349 | @findex strdup | |
13350 | @findex strfmon | |
13351 | @findex strftime | |
13352 | @findex strlen | |
13353 | @findex strncasecmp | |
13354 | @findex strncat | |
13355 | @findex strncmp | |
13356 | @findex strncpy | |
13357 | @findex strndup | |
13358 | @findex strnlen | |
13359 | @findex strpbrk | |
13360 | @findex strrchr | |
13361 | @findex strspn | |
13362 | @findex strstr | |
13363 | @findex tan | |
13364 | @findex tanf | |
13365 | @findex tanh | |
13366 | @findex tanhf | |
13367 | @findex tanhl | |
13368 | @findex tanl | |
13369 | @findex tgamma | |
13370 | @findex tgammaf | |
13371 | @findex tgammal | |
13372 | @findex toascii | |
13373 | @findex tolower | |
13374 | @findex toupper | |
13375 | @findex towlower | |
13376 | @findex towupper | |
13377 | @findex trunc | |
13378 | @findex truncf | |
13379 | @findex truncl | |
13380 | @findex vfprintf | |
13381 | @findex vfscanf | |
13382 | @findex vprintf | |
13383 | @findex vscanf | |
13384 | @findex vsnprintf | |
13385 | @findex vsprintf | |
13386 | @findex vsscanf | |
13387 | @findex y0 | |
13388 | @findex y0f | |
13389 | @findex y0l | |
13390 | @findex y1 | |
13391 | @findex y1f | |
13392 | @findex y1l | |
13393 | @findex yn | |
13394 | @findex ynf | |
13395 | @findex ynl | |
13396 | ||
13397 | GCC provides a large number of built-in functions other than the ones | |
13398 | mentioned above. Some of these are for internal use in the processing | |
13399 | of exceptions or variable-length argument lists and are not | |
13400 | documented here because they may change from time to time; we do not | |
13401 | recommend general use of these functions. | |
13402 | ||
13403 | The remaining functions are provided for optimization purposes. | |
13404 | ||
13405 | With the exception of built-ins that have library equivalents such as | |
13406 | the standard C library functions discussed below, or that expand to | |
13407 | library calls, GCC built-in functions are always expanded inline and | |
13408 | thus do not have corresponding entry points and their address cannot | |
13409 | be obtained. Attempting to use them in an expression other than | |
13410 | a function call results in a compile-time error. | |
13411 | ||
13412 | @opindex fno-builtin | |
13413 | GCC includes built-in versions of many of the functions in the standard | |
13414 | C library. These functions come in two forms: one whose names start with | |
13415 | the @code{__builtin_} prefix, and the other without. Both forms have the | |
13416 | same type (including prototype), the same address (when their address is | |
13417 | taken), and the same meaning as the C library functions even if you specify | |
13418 | the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these | |
13419 | functions are only optimized in certain cases; if they are not optimized in | |
13420 | a particular case, a call to the library function is emitted. | |
13421 | ||
13422 | @opindex ansi | |
13423 | @opindex std | |
13424 | Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, | |
13425 | @option{-std=c99} or @option{-std=c11}), the functions | |
13426 | @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, | |
13427 | @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, | |
13428 | @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, | |
13429 | @code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, | |
13430 | @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, | |
13431 | @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, | |
13432 | @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, | |
13433 | @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, | |
13434 | @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, | |
13435 | @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, | |
13436 | @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl}, | |
13437 | @code{scalbf}, @code{scalbl}, @code{scalb}, | |
13438 | @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, | |
13439 | @code{signbitd64}, @code{signbitd128}, @code{significandf}, | |
13440 | @code{significandl}, @code{significand}, @code{sincosf}, | |
13441 | @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, | |
13442 | @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, | |
13443 | @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, | |
13444 | @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and | |
13445 | @code{yn} | |
13446 | may be handled as built-in functions. | |
13447 | All these functions have corresponding versions | |
13448 | prefixed with @code{__builtin_}, which may be used even in strict C90 | |
13449 | mode. | |
13450 | ||
13451 | The ISO C99 functions | |
13452 | @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, | |
13453 | @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, | |
13454 | @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, | |
13455 | @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, | |
13456 | @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, | |
13457 | @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, | |
13458 | @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, | |
13459 | @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, | |
13460 | @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, | |
13461 | @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, | |
13462 | @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, | |
13463 | @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, | |
13464 | @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, | |
13465 | @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, | |
13466 | @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, | |
13467 | @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, | |
13468 | @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, | |
13469 | @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, | |
13470 | @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, | |
13471 | @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, | |
13472 | @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, | |
13473 | @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, | |
13474 | @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, | |
13475 | @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, | |
13476 | @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, | |
13477 | @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, | |
13478 | @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, | |
13479 | @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, | |
13480 | @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, | |
13481 | @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, | |
13482 | @code{nextafterf}, @code{nextafterl}, @code{nextafter}, | |
13483 | @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, | |
13484 | @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, | |
13485 | @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, | |
13486 | @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, | |
13487 | @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, | |
13488 | @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, | |
13489 | @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, | |
13490 | @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} | |
13491 | are handled as built-in functions | |
13492 | except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). | |
13493 | ||
13494 | There are also built-in versions of the ISO C99 functions | |
13495 | @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, | |
13496 | @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, | |
13497 | @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, | |
13498 | @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, | |
13499 | @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, | |
13500 | @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, | |
13501 | @code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf}, | |
13502 | @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, | |
13503 | @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} | |
13504 | that are recognized in any mode since ISO C90 reserves these names for | |
13505 | the purpose to which ISO C99 puts them. All these functions have | |
13506 | corresponding versions prefixed with @code{__builtin_}. | |
13507 | ||
13508 | There are also built-in functions @code{__builtin_fabsf@var{n}}, | |
13509 | @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and | |
13510 | @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 | |
13511 | functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, | |
13512 | @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported | |
13513 | types @code{_Float@var{n}} and @code{_Float@var{n}x}. | |
13514 | ||
13515 | There are also GNU extension functions @code{clog10}, @code{clog10f} and | |
13516 | @code{clog10l} which names are reserved by ISO C99 for future use. | |
13517 | All these functions have versions prefixed with @code{__builtin_}. | |
13518 | ||
13519 | The ISO C94 functions | |
13520 | @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, | |
13521 | @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, | |
13522 | @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and | |
13523 | @code{towupper} | |
13524 | are handled as built-in functions | |
13525 | except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). | |
13526 | ||
13527 | The ISO C90 functions | |
13528 | @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, | |
13529 | @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, | |
13530 | @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, | |
13531 | @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf}, | |
13532 | @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, | |
13533 | @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, | |
13534 | @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, | |
13535 | @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, | |
13536 | @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, | |
13537 | @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, | |
13538 | @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin}, | |
13539 | @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, | |
13540 | @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, | |
13541 | @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, | |
13542 | @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, | |
13543 | @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} | |
13544 | are all recognized as built-in functions unless | |
13545 | @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} | |
13546 | is specified for an individual function). All of these functions have | |
13547 | corresponding versions prefixed with @code{__builtin_}. | |
13548 | ||
13549 | GCC provides built-in versions of the ISO C99 floating-point comparison | |
13550 | macros that avoid raising exceptions for unordered operands. They have | |
13551 | the same names as the standard macros ( @code{isgreater}, | |
13552 | @code{isgreaterequal}, @code{isless}, @code{islessequal}, | |
13553 | @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} | |
13554 | prefixed. We intend for a library implementor to be able to simply | |
13555 | @code{#define} each standard macro to its built-in equivalent. | |
13556 | In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, | |
13557 | @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with | |
13558 | @code{__builtin_} prefixed. The @code{isinf} and @code{isnan} | |
13559 | built-in functions appear both with and without the @code{__builtin_} prefix. | |
13560 | With @code{-ffinite-math-only} option the @code{isinf} and @code{isnan} | |
13561 | built-in functions will always return 0. | |
13562 | ||
13563 | GCC provides built-in versions of the ISO C99 floating-point rounding and | |
13564 | exceptions handling functions @code{fegetround}, @code{feclearexcept} and | |
13565 | @code{feraiseexcept}. They may not be available for all targets, and because | |
13566 | they need close interaction with libc internal values, they may not be available | |
13567 | for all target libcs, but in all cases they will gracefully fallback to libc | |
13568 | calls. These built-in functions appear both with and without the | |
13569 | @code{__builtin_} prefix. | |
13570 | ||
f25efe50 | 13571 | @defbuiltin{{void *} __builtin_alloca (size_t size)} |
d77de738 ML |
13572 | The @code{__builtin_alloca} function must be called at block scope. |
13573 | The function allocates an object @var{size} bytes large on the stack | |
13574 | of the calling function. The object is aligned on the default stack | |
13575 | alignment boundary for the target determined by the | |
13576 | @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} | |
13577 | function returns a pointer to the first byte of the allocated object. | |
13578 | The lifetime of the allocated object ends just before the calling | |
13579 | function returns to its caller. This is so even when | |
13580 | @code{__builtin_alloca} is called within a nested block. | |
13581 | ||
13582 | For example, the following function allocates eight objects of @code{n} | |
13583 | bytes each on the stack, storing a pointer to each in consecutive elements | |
13584 | of the array @code{a}. It then passes the array to function @code{g} | |
13585 | which can safely use the storage pointed to by each of the array elements. | |
13586 | ||
13587 | @smallexample | |
13588 | void f (unsigned n) | |
13589 | @{ | |
13590 | void *a [8]; | |
13591 | for (int i = 0; i != 8; ++i) | |
13592 | a [i] = __builtin_alloca (n); | |
13593 | ||
13594 | g (a, n); // @r{safe} | |
13595 | @} | |
13596 | @end smallexample | |
13597 | ||
13598 | Since the @code{__builtin_alloca} function doesn't validate its argument | |
13599 | it is the responsibility of its caller to make sure the argument doesn't | |
13600 | cause it to exceed the stack size limit. | |
13601 | The @code{__builtin_alloca} function is provided to make it possible to | |
13602 | allocate on the stack arrays of bytes with an upper bound that may be | |
13603 | computed at run time. Since C99 Variable Length Arrays offer | |
13604 | similar functionality under a portable, more convenient, and safer | |
13605 | interface they are recommended instead, in both C99 and C++ programs | |
13606 | where GCC provides them as an extension. | |
13607 | @xref{Variable Length}, for details. | |
13608 | ||
f25efe50 | 13609 | @enddefbuiltin |
d77de738 | 13610 | |
f25efe50 | 13611 | @defbuiltin{{void *} __builtin_alloca_with_align (size_t size, size_t alignment)} |
d77de738 ML |
13612 | The @code{__builtin_alloca_with_align} function must be called at block |
13613 | scope. The function allocates an object @var{size} bytes large on | |
13614 | the stack of the calling function. The allocated object is aligned on | |
13615 | the boundary specified by the argument @var{alignment} whose unit is given | |
13616 | in bits (not bytes). The @var{size} argument must be positive and not | |
13617 | exceed the stack size limit. The @var{alignment} argument must be a constant | |
13618 | integer expression that evaluates to a power of 2 greater than or equal to | |
13619 | @code{CHAR_BIT} and less than some unspecified maximum. Invocations | |
13620 | with other values are rejected with an error indicating the valid bounds. | |
13621 | The function returns a pointer to the first byte of the allocated object. | |
13622 | The lifetime of the allocated object ends at the end of the block in which | |
13623 | the function was called. The allocated storage is released no later than | |
13624 | just before the calling function returns to its caller, but may be released | |
13625 | at the end of the block in which the function was called. | |
13626 | ||
13627 | For example, in the following function the call to @code{g} is unsafe | |
13628 | because when @code{overalign} is non-zero, the space allocated by | |
13629 | @code{__builtin_alloca_with_align} may have been released at the end | |
13630 | of the @code{if} statement in which it was called. | |
13631 | ||
13632 | @smallexample | |
13633 | void f (unsigned n, bool overalign) | |
13634 | @{ | |
13635 | void *p; | |
13636 | if (overalign) | |
13637 | p = __builtin_alloca_with_align (n, 64 /* bits */); | |
13638 | else | |
13639 | p = __builtin_alloc (n); | |
13640 | ||
13641 | g (p, n); // @r{unsafe} | |
13642 | @} | |
13643 | @end smallexample | |
13644 | ||
13645 | Since the @code{__builtin_alloca_with_align} function doesn't validate its | |
13646 | @var{size} argument it is the responsibility of its caller to make sure | |
13647 | the argument doesn't cause it to exceed the stack size limit. | |
13648 | The @code{__builtin_alloca_with_align} function is provided to make | |
13649 | it possible to allocate on the stack overaligned arrays of bytes with | |
13650 | an upper bound that may be computed at run time. Since C99 | |
13651 | Variable Length Arrays offer the same functionality under | |
13652 | a portable, more convenient, and safer interface they are recommended | |
13653 | instead, in both C99 and C++ programs where GCC provides them as | |
13654 | an extension. @xref{Variable Length}, for details. | |
13655 | ||
f25efe50 | 13656 | @enddefbuiltin |
d77de738 | 13657 | |
f25efe50 | 13658 | @defbuiltin{{void *}__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)} |
d77de738 ML |
13659 | Similar to @code{__builtin_alloca_with_align} but takes an extra argument |
13660 | specifying an upper bound for @var{size} in case its value cannot be computed | |
13661 | at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} | |
13662 | and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer | |
13663 | expression, it has no effect on code generation and no attempt is made to | |
13664 | check its compatibility with @var{size}. | |
13665 | ||
f25efe50 | 13666 | @enddefbuiltin |
d77de738 | 13667 | |
f25efe50 | 13668 | @defbuiltin{bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})} |
d77de738 ML |
13669 | The @code{__builtin_has_attribute} function evaluates to an integer constant |
13670 | expression equal to @code{true} if the symbol or type referenced by | |
13671 | the @var{type-or-expression} argument has been declared with | |
13672 | the @var{attribute} referenced by the second argument. For | |
13673 | an @var{type-or-expression} argument that does not reference a symbol, | |
13674 | since attributes do not apply to expressions the built-in consider | |
13675 | the type of the argument. Neither argument is evaluated. | |
13676 | The @var{type-or-expression} argument is subject to the same | |
13677 | restrictions as the argument to @code{typeof} (@pxref{Typeof}). The | |
13678 | @var{attribute} argument is an attribute name optionally followed by | |
13679 | a comma-separated list of arguments enclosed in parentheses. Both forms | |
13680 | of attribute names---with and without double leading and trailing | |
13681 | underscores---are recognized. @xref{Attribute Syntax}, for details. | |
13682 | When no attribute arguments are specified for an attribute that expects | |
13683 | one or more arguments the function returns @code{true} if | |
13684 | @var{type-or-expression} has been declared with the attribute regardless | |
13685 | of the attribute argument values. Arguments provided for an attribute | |
13686 | that expects some are validated and matched up to the provided number. | |
13687 | The function returns @code{true} if all provided arguments match. For | |
13688 | example, the first call to the function below evaluates to @code{true} | |
13689 | because @code{x} is declared with the @code{aligned} attribute but | |
13690 | the second call evaluates to @code{false} because @code{x} is declared | |
13691 | @code{aligned (8)} and not @code{aligned (4)}. | |
13692 | ||
13693 | @smallexample | |
13694 | __attribute__ ((aligned (8))) int x; | |
13695 | _Static_assert (__builtin_has_attribute (x, aligned), "aligned"); | |
13696 | _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)"); | |
13697 | @end smallexample | |
13698 | ||
13699 | Due to a limitation the @code{__builtin_has_attribute} function returns | |
13700 | @code{false} for the @code{mode} attribute even if the type or variable | |
13701 | referenced by the @var{type-or-expression} argument was declared with one. | |
13702 | The function is also not supported with labels, and in C with enumerators. | |
13703 | ||
13704 | Note that unlike the @code{__has_attribute} preprocessor operator which | |
13705 | is suitable for use in @code{#if} preprocessing directives | |
13706 | @code{__builtin_has_attribute} is an intrinsic function that is not | |
13707 | recognized in such contexts. | |
13708 | ||
f25efe50 | 13709 | @enddefbuiltin |
d77de738 | 13710 | |
f25efe50 | 13711 | @defbuiltin{@var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)} |
d77de738 ML |
13712 | |
13713 | This built-in function can be used to help mitigate against unsafe | |
13714 | speculative execution. @var{type} may be any integral type or any | |
13715 | pointer type. | |
13716 | ||
13717 | @enumerate | |
13718 | @item | |
13719 | If the CPU is not speculatively executing the code, then @var{val} | |
13720 | is returned. | |
13721 | @item | |
13722 | If the CPU is executing speculatively then either: | |
13723 | @itemize | |
13724 | @item | |
13725 | The function may cause execution to pause until it is known that the | |
13726 | code is no-longer being executed speculatively (in which case | |
13727 | @var{val} can be returned, as above); or | |
13728 | @item | |
13729 | The function may use target-dependent speculation tracking state to cause | |
13730 | @var{failval} to be returned when it is known that speculative | |
13731 | execution has incorrectly predicted a conditional branch operation. | |
13732 | @end itemize | |
13733 | @end enumerate | |
13734 | ||
13735 | The second argument, @var{failval}, is optional and defaults to zero | |
13736 | if omitted. | |
13737 | ||
13738 | GCC defines the preprocessor macro | |
13739 | @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been | |
13740 | updated to support this builtin. | |
13741 | ||
13742 | The built-in function can be used where a variable appears to be used in a | |
13743 | safe way, but the CPU, due to speculative execution may temporarily ignore | |
13744 | the bounds checks. Consider, for example, the following function: | |
13745 | ||
13746 | @smallexample | |
13747 | int array[500]; | |
13748 | int f (unsigned untrusted_index) | |
13749 | @{ | |
13750 | if (untrusted_index < 500) | |
13751 | return array[untrusted_index]; | |
13752 | return 0; | |
13753 | @} | |
13754 | @end smallexample | |
13755 | ||
13756 | If the function is called repeatedly with @code{untrusted_index} less | |
13757 | than the limit of 500, then a branch predictor will learn that the | |
13758 | block of code that returns a value stored in @code{array} will be | |
13759 | executed. If the function is subsequently called with an | |
13760 | out-of-range value it will still try to execute that block of code | |
13761 | first until the CPU determines that the prediction was incorrect | |
13762 | (the CPU will unwind any incorrect operations at that point). | |
13763 | However, depending on how the result of the function is used, it might be | |
13764 | possible to leave traces in the cache that can reveal what was stored | |
13765 | at the out-of-bounds location. The built-in function can be used to | |
13766 | provide some protection against leaking data in this way by changing | |
13767 | the code to: | |
13768 | ||
13769 | @smallexample | |
13770 | int array[500]; | |
13771 | int f (unsigned untrusted_index) | |
13772 | @{ | |
13773 | if (untrusted_index < 500) | |
13774 | return array[__builtin_speculation_safe_value (untrusted_index)]; | |
13775 | return 0; | |
13776 | @} | |
13777 | @end smallexample | |
13778 | ||
13779 | The built-in function will either cause execution to stall until the | |
13780 | conditional branch has been fully resolved, or it may permit | |
13781 | speculative execution to continue, but using 0 instead of | |
13782 | @code{untrusted_value} if that exceeds the limit. | |
13783 | ||
13784 | If accessing any memory location is potentially unsafe when speculative | |
13785 | execution is incorrect, then the code can be rewritten as | |
13786 | ||
13787 | @smallexample | |
13788 | int array[500]; | |
13789 | int f (unsigned untrusted_index) | |
13790 | @{ | |
13791 | if (untrusted_index < 500) | |
13792 | return *__builtin_speculation_safe_value (&array[untrusted_index], NULL); | |
13793 | return 0; | |
13794 | @} | |
13795 | @end smallexample | |
13796 | ||
13797 | which will cause a @code{NULL} pointer to be used for the unsafe case. | |
13798 | ||
f25efe50 | 13799 | @enddefbuiltin |
d77de738 | 13800 | |
f25efe50 | 13801 | @defbuiltin{int __builtin_types_compatible_p (@var{type1}, @var{type2})} |
d77de738 ML |
13802 | |
13803 | You can use the built-in function @code{__builtin_types_compatible_p} to | |
13804 | determine whether two types are the same. | |
13805 | ||
13806 | This built-in function returns 1 if the unqualified versions of the | |
13807 | types @var{type1} and @var{type2} (which are types, not expressions) are | |
13808 | compatible, 0 otherwise. The result of this built-in function can be | |
13809 | used in integer constant expressions. | |
13810 | ||
13811 | This built-in function ignores top level qualifiers (e.g., @code{const}, | |
13812 | @code{volatile}). For example, @code{int} is equivalent to @code{const | |
13813 | int}. | |
13814 | ||
13815 | The type @code{int[]} and @code{int[5]} are compatible. On the other | |
13816 | hand, @code{int} and @code{char *} are not compatible, even if the size | |
13817 | of their types, on the particular architecture are the same. Also, the | |
13818 | amount of pointer indirection is taken into account when determining | |
13819 | similarity. Consequently, @code{short *} is not similar to | |
13820 | @code{short **}. Furthermore, two types that are typedefed are | |
13821 | considered compatible if their underlying types are compatible. | |
13822 | ||
13823 | An @code{enum} type is not considered to be compatible with another | |
13824 | @code{enum} type even if both are compatible with the same integer | |
13825 | type; this is what the C standard specifies. | |
13826 | For example, @code{enum @{foo, bar@}} is not similar to | |
13827 | @code{enum @{hot, dog@}}. | |
13828 | ||
13829 | You typically use this function in code whose execution varies | |
13830 | depending on the arguments' types. For example: | |
13831 | ||
13832 | @smallexample | |
13833 | #define foo(x) \ | |
13834 | (@{ \ | |
13835 | typeof (x) tmp = (x); \ | |
13836 | if (__builtin_types_compatible_p (typeof (x), long double)) \ | |
13837 | tmp = foo_long_double (tmp); \ | |
13838 | else if (__builtin_types_compatible_p (typeof (x), double)) \ | |
13839 | tmp = foo_double (tmp); \ | |
13840 | else if (__builtin_types_compatible_p (typeof (x), float)) \ | |
13841 | tmp = foo_float (tmp); \ | |
13842 | else \ | |
13843 | abort (); \ | |
13844 | tmp; \ | |
13845 | @}) | |
13846 | @end smallexample | |
13847 | ||
13848 | @emph{Note:} This construct is only available for C@. | |
13849 | ||
f25efe50 | 13850 | @enddefbuiltin |
d77de738 | 13851 | |
f25efe50 | 13852 | @defbuiltin{@var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})} |
d77de738 ML |
13853 | |
13854 | The @var{call_exp} expression must be a function call, and the | |
13855 | @var{pointer_exp} expression must be a pointer. The @var{pointer_exp} | |
13856 | is passed to the function call in the target's static chain location. | |
13857 | The result of builtin is the result of the function call. | |
13858 | ||
13859 | @emph{Note:} This builtin is only available for C@. | |
13860 | This builtin can be used to call Go closures from C. | |
13861 | ||
f25efe50 | 13862 | @enddefbuiltin |
d77de738 | 13863 | |
f25efe50 | 13864 | @defbuiltin{@var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})} |
d77de738 ML |
13865 | |
13866 | You can use the built-in function @code{__builtin_choose_expr} to | |
13867 | evaluate code depending on the value of a constant expression. This | |
13868 | built-in function returns @var{exp1} if @var{const_exp}, which is an | |
13869 | integer constant expression, is nonzero. Otherwise it returns @var{exp2}. | |
13870 | ||
13871 | This built-in function is analogous to the @samp{? :} operator in C, | |
13872 | except that the expression returned has its type unaltered by promotion | |
13873 | rules. Also, the built-in function does not evaluate the expression | |
13874 | that is not chosen. For example, if @var{const_exp} evaluates to @code{true}, | |
13875 | @var{exp2} is not evaluated even if it has side effects. | |
13876 | ||
13877 | This built-in function can return an lvalue if the chosen argument is an | |
13878 | lvalue. | |
13879 | ||
13880 | If @var{exp1} is returned, the return type is the same as @var{exp1}'s | |
13881 | type. Similarly, if @var{exp2} is returned, its return type is the same | |
13882 | as @var{exp2}. | |
13883 | ||
13884 | Example: | |
13885 | ||
13886 | @smallexample | |
13887 | #define foo(x) \ | |
13888 | __builtin_choose_expr ( \ | |
13889 | __builtin_types_compatible_p (typeof (x), double), \ | |
13890 | foo_double (x), \ | |
13891 | __builtin_choose_expr ( \ | |
13892 | __builtin_types_compatible_p (typeof (x), float), \ | |
13893 | foo_float (x), \ | |
13894 | /* @r{The void expression results in a compile-time error} \ | |
13895 | @r{when assigning the result to something.} */ \ | |
13896 | (void)0)) | |
13897 | @end smallexample | |
13898 | ||
13899 | @emph{Note:} This construct is only available for C@. Furthermore, the | |
13900 | unused expression (@var{exp1} or @var{exp2} depending on the value of | |
13901 | @var{const_exp}) may still generate syntax errors. This may change in | |
13902 | future revisions. | |
13903 | ||
f25efe50 | 13904 | @enddefbuiltin |
d77de738 | 13905 | |
f25efe50 | 13906 | @defbuiltin{@var{type} __builtin_tgmath (@var{functions}, @var{arguments})} |
d77de738 ML |
13907 | |
13908 | The built-in function @code{__builtin_tgmath}, available only for C | |
13909 | and Objective-C, calls a function determined according to the rules of | |
13910 | @code{<tgmath.h>} macros. It is intended to be used in | |
13911 | implementations of that header, so that expansions of macros from that | |
13912 | header only expand each of their arguments once, to avoid problems | |
13913 | when calls to such macros are nested inside the arguments of other | |
13914 | calls to such macros; in addition, it results in better diagnostics | |
13915 | for invalid calls to @code{<tgmath.h>} macros than implementations | |
13916 | using other GNU C language features. For example, the @code{pow} | |
13917 | type-generic macro might be defined as: | |
13918 | ||
13919 | @smallexample | |
13920 | #define pow(a, b) __builtin_tgmath (powf, pow, powl, \ | |
13921 | cpowf, cpow, cpowl, a, b) | |
13922 | @end smallexample | |
13923 | ||
13924 | The arguments to @code{__builtin_tgmath} are at least two pointers to | |
13925 | functions, followed by the arguments to the type-generic macro (which | |
13926 | will be passed as arguments to the selected function). All the | |
13927 | pointers to functions must be pointers to prototyped functions, none | |
13928 | of which may have variable arguments, and all of which must have the | |
13929 | same number of parameters; the number of parameters of the first | |
13930 | function determines how many arguments to @code{__builtin_tgmath} are | |
13931 | interpreted as function pointers, and how many as the arguments to the | |
13932 | called function. | |
13933 | ||
13934 | The types of the specified functions must all be different, but | |
13935 | related to each other in the same way as a set of functions that may | |
13936 | be selected between by a macro in @code{<tgmath.h>}. This means that | |
13937 | the functions are parameterized by a floating-point type @var{t}, | |
13938 | different for each such function. The function return types may all | |
13939 | be the same type, or they may be @var{t} for each function, or they | |
13940 | may be the real type corresponding to @var{t} for each function (if | |
13941 | some of the types @var{t} are complex). Likewise, for each parameter | |
13942 | position, the type of the parameter in that position may always be the | |
13943 | same type, or may be @var{t} for each function (this case must apply | |
13944 | for at least one parameter position), or may be the real type | |
13945 | corresponding to @var{t} for each function. | |
13946 | ||
13947 | The standard rules for @code{<tgmath.h>} macros are used to find a | |
13948 | common type @var{u} from the types of the arguments for parameters | |
13949 | whose types vary between the functions; complex integer types (a GNU | |
5b68fb47 JM |
13950 | extension) are treated like the complex type corresponding to the real |
13951 | floating type that would be chosen for the corresponding real integer type. | |
d77de738 ML |
13952 | If the function return types vary, or are all the same integer type, |
13953 | the function called is the one for which @var{t} is @var{u}, and it is | |
13954 | an error if there is no such function. If the function return types | |
13955 | are all the same floating-point type, the type-generic macro is taken | |
13956 | to be one of those from TS 18661 that rounds the result to a narrower | |
13957 | type; if there is a function for which @var{t} is @var{u}, it is | |
13958 | called, and otherwise the first function, if any, for which @var{t} | |
13959 | has at least the range and precision of @var{u} is called, and it is | |
13960 | an error if there is no such function. | |
13961 | ||
f25efe50 | 13962 | @enddefbuiltin |
d77de738 | 13963 | |
f25efe50 | 13964 | @defbuiltin{int __builtin_constant_p (@var{exp})} |
d77de738 ML |
13965 | You can use the built-in function @code{__builtin_constant_p} to |
13966 | determine if a value is known to be constant at compile time and hence | |
13967 | that GCC can perform constant-folding on expressions involving that | |
13968 | value. The argument of the function is the value to test. The function | |
13969 | returns the integer 1 if the argument is known to be a compile-time | |
13970 | constant and 0 if it is not known to be a compile-time constant. A | |
13971 | return of 0 does not indicate that the value is @emph{not} a constant, | |
13972 | but merely that GCC cannot prove it is a constant with the specified | |
13973 | value of the @option{-O} option. | |
13974 | ||
13975 | You typically use this function in an embedded application where | |
13976 | memory is a critical resource. If you have some complex calculation, | |
13977 | you may want it to be folded if it involves constants, but need to call | |
13978 | a function if it does not. For example: | |
13979 | ||
13980 | @smallexample | |
13981 | #define Scale_Value(X) \ | |
13982 | (__builtin_constant_p (X) \ | |
13983 | ? ((X) * SCALE + OFFSET) : Scale (X)) | |
13984 | @end smallexample | |
13985 | ||
13986 | You may use this built-in function in either a macro or an inline | |
13987 | function. However, if you use it in an inlined function and pass an | |
13988 | argument of the function as the argument to the built-in, GCC | |
13989 | never returns 1 when you call the inline function with a string constant | |
13990 | or compound literal (@pxref{Compound Literals}) and does not return 1 | |
13991 | when you pass a constant numeric value to the inline function unless you | |
13992 | specify the @option{-O} option. | |
13993 | ||
13994 | You may also use @code{__builtin_constant_p} in initializers for static | |
13995 | data. For instance, you can write | |
13996 | ||
13997 | @smallexample | |
13998 | static const int table[] = @{ | |
13999 | __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, | |
14000 | /* @r{@dots{}} */ | |
14001 | @}; | |
14002 | @end smallexample | |
14003 | ||
14004 | @noindent | |
14005 | This is an acceptable initializer even if @var{EXPRESSION} is not a | |
14006 | constant expression, including the case where | |
14007 | @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be | |
14008 | folded to a constant but @var{EXPRESSION} contains operands that are | |
14009 | not otherwise permitted in a static initializer (for example, | |
14010 | @code{0 && foo ()}). GCC must be more conservative about evaluating the | |
14011 | built-in in this case, because it has no opportunity to perform | |
14012 | optimization. | |
f25efe50 | 14013 | @enddefbuiltin |
d77de738 | 14014 | |
f25efe50 | 14015 | @defbuiltin{bool __builtin_is_constant_evaluated (void)} |
d77de738 ML |
14016 | The @code{__builtin_is_constant_evaluated} function is available only |
14017 | in C++. The built-in is intended to be used by implementations of | |
14018 | the @code{std::is_constant_evaluated} C++ function. Programs should make | |
14019 | use of the latter function rather than invoking the built-in directly. | |
14020 | ||
14021 | The main use case of the built-in is to determine whether a @code{constexpr} | |
14022 | function is being called in a @code{constexpr} context. A call to | |
14023 | the function evaluates to a core constant expression with the value | |
14024 | @code{true} if and only if it occurs within the evaluation of an expression | |
14025 | or conversion that is manifestly constant-evaluated as defined in the C++ | |
14026 | standard. Manifestly constant-evaluated contexts include constant-expressions, | |
14027 | the conditions of @code{constexpr if} statements, constraint-expressions, and | |
14028 | initializers of variables usable in constant expressions. For more details | |
14029 | refer to the latest revision of the C++ standard. | |
f25efe50 | 14030 | @enddefbuiltin |
d77de738 | 14031 | |
f25efe50 | 14032 | @defbuiltin{void __builtin_clear_padding (@var{ptr})} |
d77de738 ML |
14033 | The built-in function @code{__builtin_clear_padding} function clears |
14034 | padding bits inside of the object representation of object pointed by | |
14035 | @var{ptr}, which has to be a pointer. The value representation of the | |
14036 | object is not affected. The type of the object is assumed to be the type | |
14037 | the pointer points to. Inside of a union, the only cleared bits are | |
14038 | bits that are padding bits for all the union members. | |
14039 | ||
14040 | This built-in-function is useful if the padding bits of an object might | |
14041 | have intederminate values and the object representation needs to be | |
14042 | bitwise compared to some other object, for example for atomic operations. | |
14043 | ||
14044 | For C++, @var{ptr} argument type should be pointer to trivially-copyable | |
14045 | type, unless the argument is address of a variable or parameter, because | |
14046 | otherwise it isn't known if the type isn't just a base class whose padding | |
14047 | bits are reused or laid out differently in a derived class. | |
f25efe50 | 14048 | @enddefbuiltin |
d77de738 | 14049 | |
f25efe50 | 14050 | @defbuiltin{@var{type} __builtin_bit_cast (@var{type}, @var{arg})} |
d77de738 ML |
14051 | The @code{__builtin_bit_cast} function is available only |
14052 | in C++. The built-in is intended to be used by implementations of | |
14053 | the @code{std::bit_cast} C++ template function. Programs should make | |
14054 | use of the latter function rather than invoking the built-in directly. | |
14055 | ||
14056 | This built-in function allows reinterpreting the bits of the @var{arg} | |
14057 | argument as if it had type @var{type}. @var{type} and the type of the | |
14058 | @var{arg} argument need to be trivially copyable types with the same size. | |
14059 | When manifestly constant-evaluated, it performs extra diagnostics required | |
14060 | for @code{std::bit_cast} and returns a constant expression if @var{arg} | |
14061 | is a constant expression. For more details | |
14062 | refer to the latest revision of the C++ standard. | |
f25efe50 | 14063 | @enddefbuiltin |
d77de738 | 14064 | |
f25efe50 | 14065 | @defbuiltin{long __builtin_expect (long @var{exp}, long @var{c})} |
d77de738 ML |
14066 | @opindex fprofile-arcs |
14067 | You may use @code{__builtin_expect} to provide the compiler with | |
14068 | branch prediction information. In general, you should prefer to | |
14069 | use actual profile feedback for this (@option{-fprofile-arcs}), as | |
14070 | programmers are notoriously bad at predicting how their programs | |
14071 | actually perform. However, there are applications in which this | |
14072 | data is hard to collect. | |
14073 | ||
14074 | The return value is the value of @var{exp}, which should be an integral | |
14075 | expression. The semantics of the built-in are that it is expected that | |
14076 | @var{exp} == @var{c}. For example: | |
14077 | ||
14078 | @smallexample | |
14079 | if (__builtin_expect (x, 0)) | |
14080 | foo (); | |
14081 | @end smallexample | |
14082 | ||
14083 | @noindent | |
14084 | indicates that we do not expect to call @code{foo}, since | |
14085 | we expect @code{x} to be zero. Since you are limited to integral | |
14086 | expressions for @var{exp}, you should use constructions such as | |
14087 | ||
14088 | @smallexample | |
14089 | if (__builtin_expect (ptr != NULL, 1)) | |
14090 | foo (*ptr); | |
14091 | @end smallexample | |
14092 | ||
14093 | @noindent | |
14094 | when testing pointer or floating-point values. | |
14095 | ||
14096 | For the purposes of branch prediction optimizations, the probability that | |
14097 | a @code{__builtin_expect} expression is @code{true} is controlled by GCC's | |
14098 | @code{builtin-expect-probability} parameter, which defaults to 90%. | |
14099 | ||
14100 | You can also use @code{__builtin_expect_with_probability} to explicitly | |
14101 | assign a probability value to individual expressions. If the built-in | |
14102 | is used in a loop construct, the provided probability will influence | |
14103 | the expected number of iterations made by loop optimizations. | |
f25efe50 | 14104 | @enddefbuiltin |
d77de738 | 14105 | |
f25efe50 | 14106 | @defbuiltin{long __builtin_expect_with_probability} |
d77de738 ML |
14107 | (long @var{exp}, long @var{c}, double @var{probability}) |
14108 | ||
14109 | This function has the same semantics as @code{__builtin_expect}, | |
14110 | but the caller provides the expected probability that @var{exp} == @var{c}. | |
14111 | The last argument, @var{probability}, is a floating-point value in the | |
14112 | range 0.0 to 1.0, inclusive. The @var{probability} argument must be | |
14113 | constant floating-point expression. | |
f25efe50 | 14114 | @enddefbuiltin |
d77de738 | 14115 | |
f25efe50 | 14116 | @defbuiltin{void __builtin_trap (void)} |
d77de738 ML |
14117 | This function causes the program to exit abnormally. GCC implements |
14118 | this function by using a target-dependent mechanism (such as | |
14119 | intentionally executing an illegal instruction) or by calling | |
14120 | @code{abort}. The mechanism used may vary from release to release so | |
14121 | you should not rely on any particular implementation. | |
f25efe50 | 14122 | @enddefbuiltin |
d77de738 | 14123 | |
f25efe50 | 14124 | @defbuiltin{void __builtin_unreachable (void)} |
d77de738 ML |
14125 | If control flow reaches the point of the @code{__builtin_unreachable}, |
14126 | the program is undefined. It is useful in situations where the | |
14127 | compiler cannot deduce the unreachability of the code. | |
14128 | ||
14129 | One such case is immediately following an @code{asm} statement that | |
14130 | either never terminates, or one that transfers control elsewhere | |
14131 | and never returns. In this example, without the | |
14132 | @code{__builtin_unreachable}, GCC issues a warning that control | |
14133 | reaches the end of a non-void function. It also generates code | |
14134 | to return after the @code{asm}. | |
14135 | ||
14136 | @smallexample | |
14137 | int f (int c, int v) | |
14138 | @{ | |
14139 | if (c) | |
14140 | @{ | |
14141 | return v; | |
14142 | @} | |
14143 | else | |
14144 | @{ | |
14145 | asm("jmp error_handler"); | |
14146 | __builtin_unreachable (); | |
14147 | @} | |
14148 | @} | |
14149 | @end smallexample | |
14150 | ||
14151 | @noindent | |
14152 | Because the @code{asm} statement unconditionally transfers control out | |
14153 | of the function, control never reaches the end of the function | |
14154 | body. The @code{__builtin_unreachable} is in fact unreachable and | |
14155 | communicates this fact to the compiler. | |
14156 | ||
14157 | Another use for @code{__builtin_unreachable} is following a call a | |
14158 | function that never returns but that is not declared | |
14159 | @code{__attribute__((noreturn))}, as in this example: | |
14160 | ||
14161 | @smallexample | |
14162 | void function_that_never_returns (void); | |
14163 | ||
14164 | int g (int c) | |
14165 | @{ | |
14166 | if (c) | |
14167 | @{ | |
14168 | return 1; | |
14169 | @} | |
14170 | else | |
14171 | @{ | |
14172 | function_that_never_returns (); | |
14173 | __builtin_unreachable (); | |
14174 | @} | |
14175 | @} | |
14176 | @end smallexample | |
14177 | ||
f25efe50 | 14178 | @enddefbuiltin |
d77de738 | 14179 | |
f25efe50 | 14180 | @defbuiltin{@var{type} __builtin_assoc_barrier (@var{type} @var{expr})} |
d77de738 ML |
14181 | This built-in inhibits re-association of the floating-point expression |
14182 | @var{expr} with expressions consuming the return value of the built-in. The | |
14183 | expression @var{expr} itself can be reordered, and the whole expression | |
14184 | @var{expr} can be reordered with operands after the barrier. The barrier is | |
14185 | only relevant when @code{-fassociative-math} is active, since otherwise | |
14186 | floating-point is not treated as associative. | |
14187 | ||
14188 | @smallexample | |
14189 | float x0 = a + b - b; | |
14190 | float x1 = __builtin_assoc_barrier(a + b) - b; | |
14191 | @end smallexample | |
14192 | ||
14193 | @noindent | |
14194 | means that, with @code{-fassociative-math}, @code{x0} can be optimized to | |
14195 | @code{x0 = a} but @code{x1} cannot. | |
f25efe50 | 14196 | @enddefbuiltin |
d77de738 | 14197 | |
f25efe50 | 14198 | @defbuiltin{{void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)} |
d77de738 ML |
14199 | This function returns its first argument, and allows the compiler |
14200 | to assume that the returned pointer is at least @var{align} bytes | |
14201 | aligned. This built-in can have either two or three arguments, | |
14202 | if it has three, the third argument should have integer type, and | |
14203 | if it is nonzero means misalignment offset. For example: | |
14204 | ||
14205 | @smallexample | |
14206 | void *x = __builtin_assume_aligned (arg, 16); | |
14207 | @end smallexample | |
14208 | ||
14209 | @noindent | |
14210 | means that the compiler can assume @code{x}, set to @code{arg}, is at least | |
14211 | 16-byte aligned, while: | |
14212 | ||
14213 | @smallexample | |
14214 | void *x = __builtin_assume_aligned (arg, 32, 8); | |
14215 | @end smallexample | |
14216 | ||
14217 | @noindent | |
14218 | means that the compiler can assume for @code{x}, set to @code{arg}, that | |
14219 | @code{(char *) x - 8} is 32-byte aligned. | |
f25efe50 | 14220 | @enddefbuiltin |
d77de738 | 14221 | |
f25efe50 | 14222 | @defbuiltin{int __builtin_LINE ()} |
d77de738 ML |
14223 | This function is the equivalent of the preprocessor @code{__LINE__} |
14224 | macro and returns a constant integer expression that evaluates to | |
14225 | the line number of the invocation of the built-in. When used as a C++ | |
14226 | default argument for a function @var{F}, it returns the line number | |
14227 | of the call to @var{F}. | |
f25efe50 | 14228 | @enddefbuiltin |
d77de738 | 14229 | |
f25efe50 | 14230 | @defbuiltin{{const char *} __builtin_FUNCTION ()} |
d77de738 ML |
14231 | This function is the equivalent of the @code{__FUNCTION__} symbol |
14232 | and returns an address constant pointing to the name of the function | |
14233 | from which the built-in was invoked, or the empty string if | |
14234 | the invocation is not at function scope. When used as a C++ default | |
14235 | argument for a function @var{F}, it returns the name of @var{F}'s | |
14236 | caller or the empty string if the call was not made at function | |
14237 | scope. | |
f25efe50 | 14238 | @enddefbuiltin |
d77de738 | 14239 | |
f25efe50 | 14240 | @defbuiltin{{const char *} __builtin_FILE ()} |
d77de738 ML |
14241 | This function is the equivalent of the preprocessor @code{__FILE__} |
14242 | macro and returns an address constant pointing to the file name | |
14243 | containing the invocation of the built-in, or the empty string if | |
14244 | the invocation is not at function scope. When used as a C++ default | |
14245 | argument for a function @var{F}, it returns the file name of the call | |
14246 | to @var{F} or the empty string if the call was not made at function | |
14247 | scope. | |
14248 | ||
14249 | For example, in the following, each call to function @code{foo} will | |
14250 | print a line similar to @code{"file.c:123: foo: message"} with the name | |
14251 | of the file and the line number of the @code{printf} call, the name of | |
14252 | the function @code{foo}, followed by the word @code{message}. | |
14253 | ||
14254 | @smallexample | |
14255 | const char* | |
14256 | function (const char *func = __builtin_FUNCTION ()) | |
14257 | @{ | |
14258 | return func; | |
14259 | @} | |
14260 | ||
14261 | void foo (void) | |
14262 | @{ | |
14263 | printf ("%s:%i: %s: message\n", file (), line (), function ()); | |
14264 | @} | |
14265 | @end smallexample | |
14266 | ||
f25efe50 | 14267 | @enddefbuiltin |
d77de738 | 14268 | |
f25efe50 | 14269 | @defbuiltin{void __builtin___clear_cache (void *@var{begin}, void *@var{end})} |
d77de738 ML |
14270 | This function is used to flush the processor's instruction cache for |
14271 | the region of memory between @var{begin} inclusive and @var{end} | |
14272 | exclusive. Some targets require that the instruction cache be | |
14273 | flushed, after modifying memory containing code, in order to obtain | |
14274 | deterministic behavior. | |
14275 | ||
14276 | If the target does not require instruction cache flushes, | |
14277 | @code{__builtin___clear_cache} has no effect. Otherwise either | |
14278 | instructions are emitted in-line to clear the instruction cache or a | |
14279 | call to the @code{__clear_cache} function in libgcc is made. | |
f25efe50 | 14280 | @enddefbuiltin |
d77de738 | 14281 | |
f25efe50 | 14282 | @defbuiltin{void __builtin_prefetch (const void *@var{addr}, ...)} |
d77de738 ML |
14283 | This function is used to minimize cache-miss latency by moving data into |
14284 | a cache before it is accessed. | |
14285 | You can insert calls to @code{__builtin_prefetch} into code for which | |
14286 | you know addresses of data in memory that is likely to be accessed soon. | |
14287 | If the target supports them, data prefetch instructions are generated. | |
14288 | If the prefetch is done early enough before the access then the data will | |
14289 | be in the cache by the time it is accessed. | |
14290 | ||
14291 | The value of @var{addr} is the address of the memory to prefetch. | |
14292 | There are two optional arguments, @var{rw} and @var{locality}. | |
14293 | The value of @var{rw} is a compile-time constant one or zero; one | |
14294 | means that the prefetch is preparing for a write to the memory address | |
14295 | and zero, the default, means that the prefetch is preparing for a read. | |
14296 | The value @var{locality} must be a compile-time constant integer between | |
14297 | zero and three. A value of zero means that the data has no temporal | |
14298 | locality, so it need not be left in the cache after the access. A value | |
14299 | of three means that the data has a high degree of temporal locality and | |
14300 | should be left in all levels of cache possible. Values of one and two | |
14301 | mean, respectively, a low or moderate degree of temporal locality. The | |
14302 | default is three. | |
14303 | ||
14304 | @smallexample | |
14305 | for (i = 0; i < n; i++) | |
14306 | @{ | |
14307 | a[i] = a[i] + b[i]; | |
14308 | __builtin_prefetch (&a[i+j], 1, 1); | |
14309 | __builtin_prefetch (&b[i+j], 0, 1); | |
14310 | /* @r{@dots{}} */ | |
14311 | @} | |
14312 | @end smallexample | |
14313 | ||
14314 | Data prefetch does not generate faults if @var{addr} is invalid, but | |
14315 | the address expression itself must be valid. For example, a prefetch | |
14316 | of @code{p->next} does not fault if @code{p->next} is not a valid | |
14317 | address, but evaluation faults if @code{p} is not a valid address. | |
14318 | ||
14319 | If the target does not support data prefetch, the address expression | |
14320 | is evaluated if it includes side effects but no other code is generated | |
14321 | and GCC does not issue a warning. | |
f25efe50 | 14322 | @enddefbuiltin |
d77de738 | 14323 | |
f25efe50 | 14324 | @defbuiltin{{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})} |
f5300d28 SP |
14325 | Returns a constant size estimate of an object pointed to by @var{ptr}. |
14326 | @xref{Object Size Checking}, for a detailed description of the function. | |
f25efe50 | 14327 | @enddefbuiltin |
f5300d28 | 14328 | |
f25efe50 | 14329 | @defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} |
f5300d28 SP |
14330 | Similar to @code{__builtin_object_size} except that the return value |
14331 | need not be a constant. @xref{Object Size Checking}, for a detailed | |
14332 | description of the function. | |
f25efe50 | 14333 | @enddefbuiltin |
d77de738 | 14334 | |
f25efe50 | 14335 | @defbuiltin{double __builtin_huge_val (void)} |
d77de738 ML |
14336 | Returns a positive infinity, if supported by the floating-point format, |
14337 | else @code{DBL_MAX}. This function is suitable for implementing the | |
14338 | ISO C macro @code{HUGE_VAL}. | |
f25efe50 | 14339 | @enddefbuiltin |
d77de738 | 14340 | |
f25efe50 | 14341 | @defbuiltin{float __builtin_huge_valf (void)} |
d77de738 | 14342 | Similar to @code{__builtin_huge_val}, except the return type is @code{float}. |
f25efe50 | 14343 | @enddefbuiltin |
d77de738 | 14344 | |
f25efe50 | 14345 | @defbuiltin{{long double} __builtin_huge_vall (void)} |
d77de738 ML |
14346 | Similar to @code{__builtin_huge_val}, except the return |
14347 | type is @code{long double}. | |
f25efe50 | 14348 | @enddefbuiltin |
d77de738 | 14349 | |
f25efe50 | 14350 | @defbuiltin{_Float@var{n} __builtin_huge_valf@var{n} (void)} |
d77de738 ML |
14351 | Similar to @code{__builtin_huge_val}, except the return type is |
14352 | @code{_Float@var{n}}. | |
f25efe50 | 14353 | @enddefbuiltin |
d77de738 | 14354 | |
f25efe50 | 14355 | @defbuiltin{_Float@var{n}x __builtin_huge_valf@var{n}x (void)} |
d77de738 ML |
14356 | Similar to @code{__builtin_huge_val}, except the return type is |
14357 | @code{_Float@var{n}x}. | |
f25efe50 | 14358 | @enddefbuiltin |
d77de738 | 14359 | |
f25efe50 | 14360 | @defbuiltin{int __builtin_fpclassify (int, int, int, int, int, ...)} |
d77de738 ML |
14361 | This built-in implements the C99 fpclassify functionality. The first |
14362 | five int arguments should be the target library's notion of the | |
14363 | possible FP classes and are used for return values. They must be | |
14364 | constant values and they must appear in this order: @code{FP_NAN}, | |
14365 | @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and | |
14366 | @code{FP_ZERO}. The ellipsis is for exactly one floating-point value | |
14367 | to classify. GCC treats the last argument as type-generic, which | |
14368 | means it does not do default promotion from float to double. | |
f25efe50 | 14369 | @enddefbuiltin |
d77de738 | 14370 | |
f25efe50 | 14371 | @defbuiltin{double __builtin_inf (void)} |
d77de738 ML |
14372 | Similar to @code{__builtin_huge_val}, except a warning is generated |
14373 | if the target floating-point format does not support infinities. | |
f25efe50 | 14374 | @enddefbuiltin |
d77de738 | 14375 | |
f25efe50 | 14376 | @defbuiltin{_Decimal32 __builtin_infd32 (void)} |
d77de738 | 14377 | Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. |
f25efe50 | 14378 | @enddefbuiltin |
d77de738 | 14379 | |
f25efe50 | 14380 | @defbuiltin{_Decimal64 __builtin_infd64 (void)} |
d77de738 | 14381 | Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. |
f25efe50 | 14382 | @enddefbuiltin |
d77de738 | 14383 | |
f25efe50 | 14384 | @defbuiltin{_Decimal128 __builtin_infd128 (void)} |
d77de738 | 14385 | Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. |
f25efe50 | 14386 | @enddefbuiltin |
d77de738 | 14387 | |
f25efe50 | 14388 | @defbuiltin{float __builtin_inff (void)} |
d77de738 ML |
14389 | Similar to @code{__builtin_inf}, except the return type is @code{float}. |
14390 | This function is suitable for implementing the ISO C99 macro @code{INFINITY}. | |
f25efe50 | 14391 | @enddefbuiltin |
d77de738 | 14392 | |
f25efe50 | 14393 | @defbuiltin{{long double} __builtin_infl (void)} |
d77de738 ML |
14394 | Similar to @code{__builtin_inf}, except the return |
14395 | type is @code{long double}. | |
f25efe50 | 14396 | @enddefbuiltin |
d77de738 | 14397 | |
f25efe50 | 14398 | @defbuiltin{_Float@var{n} __builtin_inff@var{n} (void)} |
d77de738 ML |
14399 | Similar to @code{__builtin_inf}, except the return |
14400 | type is @code{_Float@var{n}}. | |
f25efe50 | 14401 | @enddefbuiltin |
d77de738 | 14402 | |
f25efe50 | 14403 | @defbuiltin{_Float@var{n} __builtin_inff@var{n}x (void)} |
d77de738 ML |
14404 | Similar to @code{__builtin_inf}, except the return |
14405 | type is @code{_Float@var{n}x}. | |
f25efe50 | 14406 | @enddefbuiltin |
d77de738 | 14407 | |
f25efe50 | 14408 | @defbuiltin{int __builtin_isinf_sign (...)} |
d77de738 ML |
14409 | Similar to @code{isinf}, except the return value is -1 for |
14410 | an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. | |
14411 | Note while the parameter list is an | |
14412 | ellipsis, this function only accepts exactly one floating-point | |
14413 | argument. GCC treats this parameter as type-generic, which means it | |
14414 | does not do default promotion from float to double. | |
f25efe50 | 14415 | @enddefbuiltin |
d77de738 | 14416 | |
f25efe50 | 14417 | @defbuiltin{double __builtin_nan (const char *str)} |
d77de738 ML |
14418 | This is an implementation of the ISO C99 function @code{nan}. |
14419 | ||
14420 | Since ISO C99 defines this function in terms of @code{strtod}, which we | |
14421 | do not implement, a description of the parsing is in order. The string | |
14422 | is parsed as by @code{strtol}; that is, the base is recognized by | |
14423 | leading @samp{0} or @samp{0x} prefixes. The number parsed is placed | |
14424 | in the significand such that the least significant bit of the number | |
14425 | is at the least significant bit of the significand. The number is | |
14426 | truncated to fit the significand field provided. The significand is | |
14427 | forced to be a quiet NaN@. | |
14428 | ||
14429 | This function, if given a string literal all of which would have been | |
14430 | consumed by @code{strtol}, is evaluated early enough that it is considered a | |
14431 | compile-time constant. | |
f25efe50 | 14432 | @enddefbuiltin |
d77de738 | 14433 | |
f25efe50 | 14434 | @defbuiltin{_Decimal32 __builtin_nand32 (const char *str)} |
d77de738 | 14435 | Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. |
f25efe50 | 14436 | @enddefbuiltin |
d77de738 | 14437 | |
f25efe50 | 14438 | @defbuiltin{_Decimal64 __builtin_nand64 (const char *str)} |
d77de738 | 14439 | Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. |
f25efe50 | 14440 | @enddefbuiltin |
d77de738 | 14441 | |
f25efe50 | 14442 | @defbuiltin{_Decimal128 __builtin_nand128 (const char *str)} |
d77de738 | 14443 | Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. |
f25efe50 | 14444 | @enddefbuiltin |
d77de738 | 14445 | |
f25efe50 | 14446 | @defbuiltin{float __builtin_nanf (const char *str)} |
d77de738 | 14447 | Similar to @code{__builtin_nan}, except the return type is @code{float}. |
f25efe50 | 14448 | @enddefbuiltin |
d77de738 | 14449 | |
f25efe50 | 14450 | @defbuiltin{{long double} __builtin_nanl (const char *str)} |
d77de738 | 14451 | Similar to @code{__builtin_nan}, except the return type is @code{long double}. |
f25efe50 | 14452 | @enddefbuiltin |
d77de738 | 14453 | |
f25efe50 | 14454 | @defbuiltin{_Float@var{n} __builtin_nanf@var{n} (const char *str)} |
d77de738 ML |
14455 | Similar to @code{__builtin_nan}, except the return type is |
14456 | @code{_Float@var{n}}. | |
f25efe50 | 14457 | @enddefbuiltin |
d77de738 | 14458 | |
f25efe50 | 14459 | @defbuiltin{_Float@var{n}x __builtin_nanf@var{n}x (const char *str)} |
d77de738 ML |
14460 | Similar to @code{__builtin_nan}, except the return type is |
14461 | @code{_Float@var{n}x}. | |
f25efe50 | 14462 | @enddefbuiltin |
d77de738 | 14463 | |
f25efe50 | 14464 | @defbuiltin{double __builtin_nans (const char *str)} |
d77de738 ML |
14465 | Similar to @code{__builtin_nan}, except the significand is forced |
14466 | to be a signaling NaN@. The @code{nans} function is proposed by | |
d1bf1c97 | 14467 | @uref{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. |
f25efe50 | 14468 | @enddefbuiltin |
d77de738 | 14469 | |
f25efe50 | 14470 | @defbuiltin{_Decimal32 __builtin_nansd32 (const char *str)} |
d77de738 | 14471 | Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}. |
f25efe50 | 14472 | @enddefbuiltin |
d77de738 | 14473 | |
f25efe50 | 14474 | @defbuiltin{_Decimal64 __builtin_nansd64 (const char *str)} |
d77de738 | 14475 | Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}. |
f25efe50 | 14476 | @enddefbuiltin |
d77de738 | 14477 | |
f25efe50 | 14478 | @defbuiltin{_Decimal128 __builtin_nansd128 (const char *str)} |
d77de738 | 14479 | Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}. |
f25efe50 | 14480 | @enddefbuiltin |
d77de738 | 14481 | |
f25efe50 | 14482 | @defbuiltin{float __builtin_nansf (const char *str)} |
d77de738 | 14483 | Similar to @code{__builtin_nans}, except the return type is @code{float}. |
f25efe50 | 14484 | @enddefbuiltin |
d77de738 | 14485 | |
f25efe50 | 14486 | @defbuiltin{{long double} __builtin_nansl (const char *str)} |
d77de738 | 14487 | Similar to @code{__builtin_nans}, except the return type is @code{long double}. |
f25efe50 | 14488 | @enddefbuiltin |
d77de738 | 14489 | |
f25efe50 | 14490 | @defbuiltin{_Float@var{n} __builtin_nansf@var{n} (const char *str)} |
d77de738 ML |
14491 | Similar to @code{__builtin_nans}, except the return type is |
14492 | @code{_Float@var{n}}. | |
f25efe50 | 14493 | @enddefbuiltin |
d77de738 | 14494 | |
f25efe50 | 14495 | @defbuiltin{_Float@var{n}x __builtin_nansf@var{n}x (const char *str)} |
d77de738 ML |
14496 | Similar to @code{__builtin_nans}, except the return type is |
14497 | @code{_Float@var{n}x}. | |
f25efe50 | 14498 | @enddefbuiltin |
d77de738 | 14499 | |
f25efe50 | 14500 | @defbuiltin{int __builtin_issignaling (...)} |
d77de738 ML |
14501 | Return non-zero if the argument is a signaling NaN and zero otherwise. |
14502 | Note while the parameter list is an | |
14503 | ellipsis, this function only accepts exactly one floating-point | |
14504 | argument. GCC treats this parameter as type-generic, which means it | |
14505 | does not do default promotion from float to double. | |
14506 | This built-in function can work even without the non-default | |
14507 | @code{-fsignaling-nans} option, although if a signaling NaN is computed, | |
14508 | stored or passed as argument to some function other than this built-in | |
14509 | in the current translation unit, it is safer to use @code{-fsignaling-nans}. | |
14510 | With @code{-ffinite-math-only} option this built-in function will always | |
14511 | return 0. | |
f25efe50 | 14512 | @enddefbuiltin |
d77de738 | 14513 | |
f25efe50 | 14514 | @defbuiltin{int __builtin_ffs (int x)} |
d77de738 ML |
14515 | Returns one plus the index of the least significant 1-bit of @var{x}, or |
14516 | if @var{x} is zero, returns zero. | |
f25efe50 | 14517 | @enddefbuiltin |
d77de738 | 14518 | |
f25efe50 | 14519 | @defbuiltin{int __builtin_clz (unsigned int x)} |
d77de738 ML |
14520 | Returns the number of leading 0-bits in @var{x}, starting at the most |
14521 | significant bit position. If @var{x} is 0, the result is undefined. | |
f25efe50 | 14522 | @enddefbuiltin |
d77de738 | 14523 | |
f25efe50 | 14524 | @defbuiltin{int __builtin_ctz (unsigned int x)} |
d77de738 ML |
14525 | Returns the number of trailing 0-bits in @var{x}, starting at the least |
14526 | significant bit position. If @var{x} is 0, the result is undefined. | |
f25efe50 | 14527 | @enddefbuiltin |
d77de738 | 14528 | |
f25efe50 | 14529 | @defbuiltin{int __builtin_clrsb (int x)} |
d77de738 ML |
14530 | Returns the number of leading redundant sign bits in @var{x}, i.e.@: the |
14531 | number of bits following the most significant bit that are identical | |
14532 | to it. There are no special cases for 0 or other values. | |
f25efe50 | 14533 | @enddefbuiltin |
d77de738 | 14534 | |
f25efe50 | 14535 | @defbuiltin{int __builtin_popcount (unsigned int x)} |
d77de738 | 14536 | Returns the number of 1-bits in @var{x}. |
f25efe50 | 14537 | @enddefbuiltin |
d77de738 | 14538 | |
f25efe50 | 14539 | @defbuiltin{int __builtin_parity (unsigned int x)} |
d77de738 ML |
14540 | Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} |
14541 | modulo 2. | |
f25efe50 | 14542 | @enddefbuiltin |
d77de738 | 14543 | |
f25efe50 | 14544 | @defbuiltin{int __builtin_ffsl (long)} |
d77de738 ML |
14545 | Similar to @code{__builtin_ffs}, except the argument type is |
14546 | @code{long}. | |
f25efe50 | 14547 | @enddefbuiltin |
d77de738 | 14548 | |
f25efe50 | 14549 | @defbuiltin{int __builtin_clzl (unsigned long)} |
d77de738 ML |
14550 | Similar to @code{__builtin_clz}, except the argument type is |
14551 | @code{unsigned long}. | |
f25efe50 | 14552 | @enddefbuiltin |
d77de738 | 14553 | |
f25efe50 | 14554 | @defbuiltin{int __builtin_ctzl (unsigned long)} |
d77de738 ML |
14555 | Similar to @code{__builtin_ctz}, except the argument type is |
14556 | @code{unsigned long}. | |
f25efe50 | 14557 | @enddefbuiltin |
d77de738 | 14558 | |
f25efe50 | 14559 | @defbuiltin{int __builtin_clrsbl (long)} |
d77de738 ML |
14560 | Similar to @code{__builtin_clrsb}, except the argument type is |
14561 | @code{long}. | |
f25efe50 | 14562 | @enddefbuiltin |
d77de738 | 14563 | |
f25efe50 | 14564 | @defbuiltin{int __builtin_popcountl (unsigned long)} |
d77de738 ML |
14565 | Similar to @code{__builtin_popcount}, except the argument type is |
14566 | @code{unsigned long}. | |
f25efe50 | 14567 | @enddefbuiltin |
d77de738 | 14568 | |
f25efe50 | 14569 | @defbuiltin{int __builtin_parityl (unsigned long)} |
d77de738 ML |
14570 | Similar to @code{__builtin_parity}, except the argument type is |
14571 | @code{unsigned long}. | |
f25efe50 | 14572 | @enddefbuiltin |
d77de738 | 14573 | |
f25efe50 | 14574 | @defbuiltin{int __builtin_ffsll (long long)} |
d77de738 ML |
14575 | Similar to @code{__builtin_ffs}, except the argument type is |
14576 | @code{long long}. | |
f25efe50 | 14577 | @enddefbuiltin |
d77de738 | 14578 | |
f25efe50 | 14579 | @defbuiltin{int __builtin_clzll (unsigned long long)} |
d77de738 ML |
14580 | Similar to @code{__builtin_clz}, except the argument type is |
14581 | @code{unsigned long long}. | |
f25efe50 | 14582 | @enddefbuiltin |
d77de738 | 14583 | |
f25efe50 | 14584 | @defbuiltin{int __builtin_ctzll (unsigned long long)} |
d77de738 ML |
14585 | Similar to @code{__builtin_ctz}, except the argument type is |
14586 | @code{unsigned long long}. | |
f25efe50 | 14587 | @enddefbuiltin |
d77de738 | 14588 | |
f25efe50 | 14589 | @defbuiltin{int __builtin_clrsbll (long long)} |
d77de738 ML |
14590 | Similar to @code{__builtin_clrsb}, except the argument type is |
14591 | @code{long long}. | |
f25efe50 | 14592 | @enddefbuiltin |
d77de738 | 14593 | |
f25efe50 | 14594 | @defbuiltin{int __builtin_popcountll (unsigned long long)} |
d77de738 ML |
14595 | Similar to @code{__builtin_popcount}, except the argument type is |
14596 | @code{unsigned long long}. | |
f25efe50 | 14597 | @enddefbuiltin |
d77de738 | 14598 | |
f25efe50 | 14599 | @defbuiltin{int __builtin_parityll (unsigned long long)} |
d77de738 ML |
14600 | Similar to @code{__builtin_parity}, except the argument type is |
14601 | @code{unsigned long long}. | |
f25efe50 | 14602 | @enddefbuiltin |
d77de738 | 14603 | |
f25efe50 AA |
14604 | @defbuiltin{double __builtin_powi (double, int)} |
14605 | @defbuiltinx{float __builtin_powif (float, int)} | |
14606 | @defbuiltinx{{long double} __builtin_powil (long double, int)} | |
d77de738 ML |
14607 | Returns the first argument raised to the power of the second. Unlike the |
14608 | @code{pow} function no guarantees about precision and rounding are made. | |
f25efe50 | 14609 | @enddefbuiltin |
d77de738 | 14610 | |
f25efe50 | 14611 | @defbuiltin{uint16_t __builtin_bswap16 (uint16_t x)} |
d77de738 ML |
14612 | Returns @var{x} with the order of the bytes reversed; for example, |
14613 | @code{0xaabb} becomes @code{0xbbaa}. Byte here always means | |
14614 | exactly 8 bits. | |
f25efe50 | 14615 | @enddefbuiltin |
d77de738 | 14616 | |
f25efe50 | 14617 | @defbuiltin{uint32_t __builtin_bswap32 (uint32_t x)} |
d77de738 ML |
14618 | Similar to @code{__builtin_bswap16}, except the argument and return types |
14619 | are 32-bit. | |
f25efe50 | 14620 | @enddefbuiltin |
d77de738 | 14621 | |
f25efe50 | 14622 | @defbuiltin{uint64_t __builtin_bswap64 (uint64_t x)} |
d77de738 ML |
14623 | Similar to @code{__builtin_bswap32}, except the argument and return types |
14624 | are 64-bit. | |
f25efe50 | 14625 | @enddefbuiltin |
d77de738 | 14626 | |
f25efe50 | 14627 | @defbuiltin{uint128_t __builtin_bswap128 (uint128_t x)} |
d77de738 ML |
14628 | Similar to @code{__builtin_bswap64}, except the argument and return types |
14629 | are 128-bit. Only supported on targets when 128-bit types are supported. | |
f25efe50 | 14630 | @enddefbuiltin |
d77de738 ML |
14631 | |
14632 | ||
f25efe50 | 14633 | @defbuiltin{Pmode __builtin_extend_pointer (void * x)} |
d77de738 ML |
14634 | On targets where the user visible pointer size is smaller than the size |
14635 | of an actual hardware address this function returns the extended user | |
14636 | pointer. Targets where this is true included ILP32 mode on x86_64 or | |
14637 | Aarch64. This function is mainly useful when writing inline assembly | |
14638 | code. | |
f25efe50 | 14639 | @enddefbuiltin |
d77de738 | 14640 | |
f25efe50 | 14641 | @defbuiltin{int __builtin_goacc_parlevel_id (int x)} |
d77de738 ML |
14642 | Returns the openacc gang, worker or vector id depending on whether @var{x} is |
14643 | 0, 1 or 2. | |
f25efe50 | 14644 | @enddefbuiltin |
d77de738 | 14645 | |
f25efe50 | 14646 | @defbuiltin{int __builtin_goacc_parlevel_size (int x)} |
d77de738 ML |
14647 | Returns the openacc gang, worker or vector size depending on whether @var{x} is |
14648 | 0, 1 or 2. | |
f25efe50 | 14649 | @enddefbuiltin |
d77de738 ML |
14650 | |
14651 | @node Target Builtins | |
14652 | @section Built-in Functions Specific to Particular Target Machines | |
14653 | ||
14654 | On some target machines, GCC supports many built-in functions specific | |
14655 | to those machines. Generally these generate calls to specific machine | |
14656 | instructions, but allow the compiler to schedule those calls. | |
14657 | ||
14658 | @menu | |
14659 | * AArch64 Built-in Functions:: | |
14660 | * Alpha Built-in Functions:: | |
14661 | * Altera Nios II Built-in Functions:: | |
14662 | * ARC Built-in Functions:: | |
14663 | * ARC SIMD Built-in Functions:: | |
14664 | * ARM iWMMXt Built-in Functions:: | |
14665 | * ARM C Language Extensions (ACLE):: | |
14666 | * ARM Floating Point Status and Control Intrinsics:: | |
14667 | * ARM ARMv8-M Security Extensions:: | |
14668 | * AVR Built-in Functions:: | |
14669 | * Blackfin Built-in Functions:: | |
14670 | * BPF Built-in Functions:: | |
14671 | * FR-V Built-in Functions:: | |
14672 | * MIPS DSP Built-in Functions:: | |
14673 | * MIPS Paired-Single Support:: | |
14674 | * MIPS Loongson Built-in Functions:: | |
14675 | * MIPS SIMD Architecture (MSA) Support:: | |
14676 | * Other MIPS Built-in Functions:: | |
14677 | * MSP430 Built-in Functions:: | |
14678 | * NDS32 Built-in Functions:: | |
d77de738 ML |
14679 | * Basic PowerPC Built-in Functions:: |
14680 | * PowerPC AltiVec/VSX Built-in Functions:: | |
14681 | * PowerPC Hardware Transactional Memory Built-in Functions:: | |
14682 | * PowerPC Atomic Memory Operation Functions:: | |
14683 | * PowerPC Matrix-Multiply Assist Built-in Functions:: | |
14684 | * PRU Built-in Functions:: | |
14685 | * RISC-V Built-in Functions:: | |
14686 | * RX Built-in Functions:: | |
14687 | * S/390 System z Built-in Functions:: | |
14688 | * SH Built-in Functions:: | |
14689 | * SPARC VIS Built-in Functions:: | |
14690 | * TI C6X Built-in Functions:: | |
14691 | * x86 Built-in Functions:: | |
14692 | * x86 transactional memory intrinsics:: | |
14693 | * x86 control-flow protection intrinsics:: | |
14694 | @end menu | |
14695 | ||
14696 | @node AArch64 Built-in Functions | |
14697 | @subsection AArch64 Built-in Functions | |
14698 | ||
14699 | These built-in functions are available for the AArch64 family of | |
14700 | processors. | |
14701 | @smallexample | |
14702 | unsigned int __builtin_aarch64_get_fpcr (); | |
14703 | void __builtin_aarch64_set_fpcr (unsigned int); | |
14704 | unsigned int __builtin_aarch64_get_fpsr (); | |
14705 | void __builtin_aarch64_set_fpsr (unsigned int); | |
14706 | ||
14707 | unsigned long long __builtin_aarch64_get_fpcr64 (); | |
14708 | void __builtin_aarch64_set_fpcr64 (unsigned long long); | |
14709 | unsigned long long __builtin_aarch64_get_fpsr64 (); | |
14710 | void __builtin_aarch64_set_fpsr64 (unsigned long long); | |
14711 | @end smallexample | |
14712 | ||
14713 | @node Alpha Built-in Functions | |
14714 | @subsection Alpha Built-in Functions | |
14715 | ||
14716 | These built-in functions are available for the Alpha family of | |
14717 | processors, depending on the command-line switches used. | |
14718 | ||
14719 | The following built-in functions are always available. They | |
14720 | all generate the machine instruction that is part of the name. | |
14721 | ||
14722 | @smallexample | |
14723 | long __builtin_alpha_implver (void); | |
14724 | long __builtin_alpha_rpcc (void); | |
14725 | long __builtin_alpha_amask (long); | |
14726 | long __builtin_alpha_cmpbge (long, long); | |
14727 | long __builtin_alpha_extbl (long, long); | |
14728 | long __builtin_alpha_extwl (long, long); | |
14729 | long __builtin_alpha_extll (long, long); | |
14730 | long __builtin_alpha_extql (long, long); | |
14731 | long __builtin_alpha_extwh (long, long); | |
14732 | long __builtin_alpha_extlh (long, long); | |
14733 | long __builtin_alpha_extqh (long, long); | |
14734 | long __builtin_alpha_insbl (long, long); | |
14735 | long __builtin_alpha_inswl (long, long); | |
14736 | long __builtin_alpha_insll (long, long); | |
14737 | long __builtin_alpha_insql (long, long); | |
14738 | long __builtin_alpha_inswh (long, long); | |
14739 | long __builtin_alpha_inslh (long, long); | |
14740 | long __builtin_alpha_insqh (long, long); | |
14741 | long __builtin_alpha_mskbl (long, long); | |
14742 | long __builtin_alpha_mskwl (long, long); | |
14743 | long __builtin_alpha_mskll (long, long); | |
14744 | long __builtin_alpha_mskql (long, long); | |
14745 | long __builtin_alpha_mskwh (long, long); | |
14746 | long __builtin_alpha_msklh (long, long); | |
14747 | long __builtin_alpha_mskqh (long, long); | |
14748 | long __builtin_alpha_umulh (long, long); | |
14749 | long __builtin_alpha_zap (long, long); | |
14750 | long __builtin_alpha_zapnot (long, long); | |
14751 | @end smallexample | |
14752 | ||
14753 | The following built-in functions are always with @option{-mmax} | |
14754 | or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or | |
14755 | later. They all generate the machine instruction that is part | |
14756 | of the name. | |
14757 | ||
14758 | @smallexample | |
14759 | long __builtin_alpha_pklb (long); | |
14760 | long __builtin_alpha_pkwb (long); | |
14761 | long __builtin_alpha_unpkbl (long); | |
14762 | long __builtin_alpha_unpkbw (long); | |
14763 | long __builtin_alpha_minub8 (long, long); | |
14764 | long __builtin_alpha_minsb8 (long, long); | |
14765 | long __builtin_alpha_minuw4 (long, long); | |
14766 | long __builtin_alpha_minsw4 (long, long); | |
14767 | long __builtin_alpha_maxub8 (long, long); | |
14768 | long __builtin_alpha_maxsb8 (long, long); | |
14769 | long __builtin_alpha_maxuw4 (long, long); | |
14770 | long __builtin_alpha_maxsw4 (long, long); | |
14771 | long __builtin_alpha_perr (long, long); | |
14772 | @end smallexample | |
14773 | ||
14774 | The following built-in functions are always with @option{-mcix} | |
14775 | or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or | |
14776 | later. They all generate the machine instruction that is part | |
14777 | of the name. | |
14778 | ||
14779 | @smallexample | |
14780 | long __builtin_alpha_cttz (long); | |
14781 | long __builtin_alpha_ctlz (long); | |
14782 | long __builtin_alpha_ctpop (long); | |
14783 | @end smallexample | |
14784 | ||
14785 | The following built-in functions are available on systems that use the OSF/1 | |
14786 | PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} | |
14787 | PAL calls, but when invoked with @option{-mtls-kernel}, they invoke | |
14788 | @code{rdval} and @code{wrval}. | |
14789 | ||
14790 | @smallexample | |
14791 | void *__builtin_thread_pointer (void); | |
14792 | void __builtin_set_thread_pointer (void *); | |
14793 | @end smallexample | |
14794 | ||
14795 | @node Altera Nios II Built-in Functions | |
14796 | @subsection Altera Nios II Built-in Functions | |
14797 | ||
14798 | These built-in functions are available for the Altera Nios II | |
14799 | family of processors. | |
14800 | ||
14801 | The following built-in functions are always available. They | |
14802 | all generate the machine instruction that is part of the name. | |
14803 | ||
14804 | @example | |
14805 | int __builtin_ldbio (volatile const void *); | |
14806 | int __builtin_ldbuio (volatile const void *); | |
14807 | int __builtin_ldhio (volatile const void *); | |
14808 | int __builtin_ldhuio (volatile const void *); | |
14809 | int __builtin_ldwio (volatile const void *); | |
14810 | void __builtin_stbio (volatile void *, int); | |
14811 | void __builtin_sthio (volatile void *, int); | |
14812 | void __builtin_stwio (volatile void *, int); | |
14813 | void __builtin_sync (void); | |
14814 | int __builtin_rdctl (int); | |
14815 | int __builtin_rdprs (int, int); | |
14816 | void __builtin_wrctl (int, int); | |
14817 | void __builtin_flushd (volatile void *); | |
14818 | void __builtin_flushda (volatile void *); | |
14819 | int __builtin_wrpie (int); | |
14820 | void __builtin_eni (int); | |
14821 | int __builtin_ldex (volatile const void *); | |
14822 | int __builtin_stex (volatile void *, int); | |
14823 | int __builtin_ldsex (volatile const void *); | |
14824 | int __builtin_stsex (volatile void *, int); | |
14825 | @end example | |
14826 | ||
14827 | The following built-in functions are always available. They | |
14828 | all generate a Nios II Custom Instruction. The name of the | |
14829 | function represents the types that the function takes and | |
14830 | returns. The letter before the @code{n} is the return type | |
14831 | or void if absent. The @code{n} represents the first parameter | |
14832 | to all the custom instructions, the custom instruction number. | |
14833 | The two letters after the @code{n} represent the up to two | |
14834 | parameters to the function. | |
14835 | ||
14836 | The letters represent the following data types: | |
14837 | @table @code | |
14838 | @item <no letter> | |
14839 | @code{void} for return type and no parameter for parameter types. | |
14840 | ||
14841 | @item i | |
14842 | @code{int} for return type and parameter type | |
14843 | ||
14844 | @item f | |
14845 | @code{float} for return type and parameter type | |
14846 | ||
14847 | @item p | |
14848 | @code{void *} for return type and parameter type | |
14849 | ||
14850 | @end table | |
14851 | ||
14852 | And the function names are: | |
14853 | @example | |
14854 | void __builtin_custom_n (void); | |
14855 | void __builtin_custom_ni (int); | |
14856 | void __builtin_custom_nf (float); | |
14857 | void __builtin_custom_np (void *); | |
14858 | void __builtin_custom_nii (int, int); | |
14859 | void __builtin_custom_nif (int, float); | |
14860 | void __builtin_custom_nip (int, void *); | |
14861 | void __builtin_custom_nfi (float, int); | |
14862 | void __builtin_custom_nff (float, float); | |
14863 | void __builtin_custom_nfp (float, void *); | |
14864 | void __builtin_custom_npi (void *, int); | |
14865 | void __builtin_custom_npf (void *, float); | |
14866 | void __builtin_custom_npp (void *, void *); | |
14867 | int __builtin_custom_in (void); | |
14868 | int __builtin_custom_ini (int); | |
14869 | int __builtin_custom_inf (float); | |
14870 | int __builtin_custom_inp (void *); | |
14871 | int __builtin_custom_inii (int, int); | |
14872 | int __builtin_custom_inif (int, float); | |
14873 | int __builtin_custom_inip (int, void *); | |
14874 | int __builtin_custom_infi (float, int); | |
14875 | int __builtin_custom_inff (float, float); | |
14876 | int __builtin_custom_infp (float, void *); | |
14877 | int __builtin_custom_inpi (void *, int); | |
14878 | int __builtin_custom_inpf (void *, float); | |
14879 | int __builtin_custom_inpp (void *, void *); | |
14880 | float __builtin_custom_fn (void); | |
14881 | float __builtin_custom_fni (int); | |
14882 | float __builtin_custom_fnf (float); | |
14883 | float __builtin_custom_fnp (void *); | |
14884 | float __builtin_custom_fnii (int, int); | |
14885 | float __builtin_custom_fnif (int, float); | |
14886 | float __builtin_custom_fnip (int, void *); | |
14887 | float __builtin_custom_fnfi (float, int); | |
14888 | float __builtin_custom_fnff (float, float); | |
14889 | float __builtin_custom_fnfp (float, void *); | |
14890 | float __builtin_custom_fnpi (void *, int); | |
14891 | float __builtin_custom_fnpf (void *, float); | |
14892 | float __builtin_custom_fnpp (void *, void *); | |
14893 | void * __builtin_custom_pn (void); | |
14894 | void * __builtin_custom_pni (int); | |
14895 | void * __builtin_custom_pnf (float); | |
14896 | void * __builtin_custom_pnp (void *); | |
14897 | void * __builtin_custom_pnii (int, int); | |
14898 | void * __builtin_custom_pnif (int, float); | |
14899 | void * __builtin_custom_pnip (int, void *); | |
14900 | void * __builtin_custom_pnfi (float, int); | |
14901 | void * __builtin_custom_pnff (float, float); | |
14902 | void * __builtin_custom_pnfp (float, void *); | |
14903 | void * __builtin_custom_pnpi (void *, int); | |
14904 | void * __builtin_custom_pnpf (void *, float); | |
14905 | void * __builtin_custom_pnpp (void *, void *); | |
14906 | @end example | |
14907 | ||
14908 | @node ARC Built-in Functions | |
14909 | @subsection ARC Built-in Functions | |
14910 | ||
14911 | The following built-in functions are provided for ARC targets. The | |
14912 | built-ins generate the corresponding assembly instructions. In the | |
14913 | examples given below, the generated code often requires an operand or | |
14914 | result to be in a register. Where necessary further code will be | |
14915 | generated to ensure this is true, but for brevity this is not | |
14916 | described in each case. | |
14917 | ||
14918 | @emph{Note:} Using a built-in to generate an instruction not supported | |
14919 | by a target may cause problems. At present the compiler is not | |
14920 | guaranteed to detect such misuse, and as a result an internal compiler | |
14921 | error may be generated. | |
14922 | ||
f25efe50 | 14923 | @defbuiltin{int __builtin_arc_aligned (void *@var{val}, int @var{alignval})} |
d77de738 ML |
14924 | Return 1 if @var{val} is known to have the byte alignment given |
14925 | by @var{alignval}, otherwise return 0. | |
14926 | Note that this is different from | |
14927 | @smallexample | |
14928 | __alignof__(*(char *)@var{val}) >= alignval | |
14929 | @end smallexample | |
14930 | because __alignof__ sees only the type of the dereference, whereas | |
14931 | __builtin_arc_align uses alignment information from the pointer | |
14932 | as well as from the pointed-to type. | |
14933 | The information available will depend on optimization level. | |
f25efe50 | 14934 | @enddefbuiltin |
d77de738 | 14935 | |
f25efe50 | 14936 | @defbuiltin{void __builtin_arc_brk (void)} |
d77de738 ML |
14937 | Generates |
14938 | @example | |
14939 | brk | |
14940 | @end example | |
f25efe50 | 14941 | @enddefbuiltin |
d77de738 | 14942 | |
f25efe50 | 14943 | @defbuiltin{{unsigned int} __builtin_arc_core_read (unsigned int @var{regno})} |
d77de738 ML |
14944 | The operand is the number of a register to be read. Generates: |
14945 | @example | |
14946 | mov @var{dest}, r@var{regno} | |
14947 | @end example | |
14948 | where the value in @var{dest} will be the result returned from the | |
14949 | built-in. | |
f25efe50 | 14950 | @enddefbuiltin |
d77de738 | 14951 | |
f25efe50 | 14952 | @defbuiltin{void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})} |
d77de738 ML |
14953 | The first operand is the number of a register to be written, the |
14954 | second operand is a compile time constant to write into that | |
14955 | register. Generates: | |
14956 | @example | |
14957 | mov r@var{regno}, @var{val} | |
14958 | @end example | |
f25efe50 | 14959 | @enddefbuiltin |
d77de738 | 14960 | |
f25efe50 | 14961 | @defbuiltin{int __builtin_arc_divaw (int @var{a}, int @var{b})} |
d77de738 ML |
14962 | Only available if either @option{-mcpu=ARC700} or @option{-meA} is set. |
14963 | Generates: | |
14964 | @example | |
14965 | divaw @var{dest}, @var{a}, @var{b} | |
14966 | @end example | |
14967 | where the value in @var{dest} will be the result returned from the | |
14968 | built-in. | |
f25efe50 | 14969 | @enddefbuiltin |
d77de738 | 14970 | |
f25efe50 | 14971 | @defbuiltin{void __builtin_arc_flag (unsigned int @var{a})} |
d77de738 ML |
14972 | Generates |
14973 | @example | |
14974 | flag @var{a} | |
14975 | @end example | |
f25efe50 | 14976 | @enddefbuiltin |
d77de738 | 14977 | |
f25efe50 | 14978 | @defbuiltin{{unsigned int} __builtin_arc_lr (unsigned int @var{auxr})} |
d77de738 ML |
14979 | The operand, @var{auxv}, is the address of an auxiliary register and |
14980 | must be a compile time constant. Generates: | |
14981 | @example | |
14982 | lr @var{dest}, [@var{auxr}] | |
14983 | @end example | |
14984 | Where the value in @var{dest} will be the result returned from the | |
14985 | built-in. | |
f25efe50 | 14986 | @enddefbuiltin |
d77de738 | 14987 | |
f25efe50 | 14988 | @defbuiltin{void __builtin_arc_mul64 (int @var{a}, int @var{b})} |
d77de738 ML |
14989 | Only available with @option{-mmul64}. Generates: |
14990 | @example | |
14991 | mul64 @var{a}, @var{b} | |
14992 | @end example | |
f25efe50 | 14993 | @enddefbuiltin |
d77de738 | 14994 | |
f25efe50 | 14995 | @defbuiltin{void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})} |
d77de738 ML |
14996 | Only available with @option{-mmul64}. Generates: |
14997 | @example | |
14998 | mulu64 @var{a}, @var{b} | |
14999 | @end example | |
f25efe50 | 15000 | @enddefbuiltin |
d77de738 | 15001 | |
f25efe50 | 15002 | @defbuiltin{void __builtin_arc_nop (void)} |
d77de738 ML |
15003 | Generates: |
15004 | @example | |
15005 | nop | |
15006 | @end example | |
f25efe50 | 15007 | @enddefbuiltin |
d77de738 | 15008 | |
f25efe50 | 15009 | @defbuiltin{int __builtin_arc_norm (int @var{src})} |
d77de738 ML |
15010 | Only valid if the @samp{norm} instruction is available through the |
15011 | @option{-mnorm} option or by default with @option{-mcpu=ARC700}. | |
15012 | Generates: | |
15013 | @example | |
15014 | norm @var{dest}, @var{src} | |
15015 | @end example | |
15016 | Where the value in @var{dest} will be the result returned from the | |
15017 | built-in. | |
f25efe50 | 15018 | @enddefbuiltin |
d77de738 | 15019 | |
f25efe50 | 15020 | @defbuiltin{{short int} __builtin_arc_normw (short int @var{src})} |
d77de738 ML |
15021 | Only valid if the @samp{normw} instruction is available through the |
15022 | @option{-mnorm} option or by default with @option{-mcpu=ARC700}. | |
15023 | Generates: | |
15024 | @example | |
15025 | normw @var{dest}, @var{src} | |
15026 | @end example | |
15027 | Where the value in @var{dest} will be the result returned from the | |
15028 | built-in. | |
f25efe50 | 15029 | @enddefbuiltin |
d77de738 | 15030 | |
f25efe50 | 15031 | @defbuiltin{void __builtin_arc_rtie (void)} |
d77de738 ML |
15032 | Generates: |
15033 | @example | |
15034 | rtie | |
15035 | @end example | |
f25efe50 | 15036 | @enddefbuiltin |
d77de738 | 15037 | |
f25efe50 | 15038 | @defbuiltin{void __builtin_arc_sleep (int @var{a}} |
d77de738 ML |
15039 | Generates: |
15040 | @example | |
15041 | sleep @var{a} | |
15042 | @end example | |
f25efe50 | 15043 | @enddefbuiltin |
d77de738 | 15044 | |
f25efe50 | 15045 | @defbuiltin{void __builtin_arc_sr (unsigned int @var{val}, unsigned int @var{auxr})} |
d77de738 ML |
15046 | The first argument, @var{val}, is a compile time constant to be |
15047 | written to the register, the second argument, @var{auxr}, is the | |
15048 | address of an auxiliary register. Generates: | |
15049 | @example | |
15050 | sr @var{val}, [@var{auxr}] | |
15051 | @end example | |
f25efe50 | 15052 | @enddefbuiltin |
d77de738 | 15053 | |
f25efe50 | 15054 | @defbuiltin{int __builtin_arc_swap (int @var{src})} |
d77de738 ML |
15055 | Only valid with @option{-mswap}. Generates: |
15056 | @example | |
15057 | swap @var{dest}, @var{src} | |
15058 | @end example | |
15059 | Where the value in @var{dest} will be the result returned from the | |
15060 | built-in. | |
f25efe50 | 15061 | @enddefbuiltin |
d77de738 | 15062 | |
f25efe50 | 15063 | @defbuiltin{void __builtin_arc_swi (void)} |
d77de738 ML |
15064 | Generates: |
15065 | @example | |
15066 | swi | |
15067 | @end example | |
f25efe50 | 15068 | @enddefbuiltin |
d77de738 | 15069 | |
f25efe50 | 15070 | @defbuiltin{void __builtin_arc_sync (void)} |
d77de738 ML |
15071 | Only available with @option{-mcpu=ARC700}. Generates: |
15072 | @example | |
15073 | sync | |
15074 | @end example | |
f25efe50 | 15075 | @enddefbuiltin |
d77de738 | 15076 | |
f25efe50 | 15077 | @defbuiltin{void __builtin_arc_trap_s (unsigned int @var{c})} |
d77de738 ML |
15078 | Only available with @option{-mcpu=ARC700}. Generates: |
15079 | @example | |
15080 | trap_s @var{c} | |
15081 | @end example | |
f25efe50 | 15082 | @enddefbuiltin |
d77de738 | 15083 | |
f25efe50 | 15084 | @defbuiltin{void __builtin_arc_unimp_s (void)} |
d77de738 ML |
15085 | Only available with @option{-mcpu=ARC700}. Generates: |
15086 | @example | |
15087 | unimp_s | |
15088 | @end example | |
f25efe50 | 15089 | @enddefbuiltin |
d77de738 ML |
15090 | |
15091 | The instructions generated by the following builtins are not | |
15092 | considered as candidates for scheduling. They are not moved around by | |
15093 | the compiler during scheduling, and thus can be expected to appear | |
15094 | where they are put in the C code: | |
15095 | @example | |
15096 | __builtin_arc_brk() | |
15097 | __builtin_arc_core_read() | |
15098 | __builtin_arc_core_write() | |
15099 | __builtin_arc_flag() | |
15100 | __builtin_arc_lr() | |
15101 | __builtin_arc_sleep() | |
15102 | __builtin_arc_sr() | |
15103 | __builtin_arc_swi() | |
15104 | @end example | |
15105 | ||
15106 | @node ARC SIMD Built-in Functions | |
15107 | @subsection ARC SIMD Built-in Functions | |
15108 | ||
15109 | SIMD builtins provided by the compiler can be used to generate the | |
15110 | vector instructions. This section describes the available builtins | |
15111 | and their usage in programs. With the @option{-msimd} option, the | |
15112 | compiler provides 128-bit vector types, which can be specified using | |
15113 | the @code{vector_size} attribute. The header file @file{arc-simd.h} | |
15114 | can be included to use the following predefined types: | |
15115 | @example | |
15116 | typedef int __v4si __attribute__((vector_size(16))); | |
15117 | typedef short __v8hi __attribute__((vector_size(16))); | |
15118 | @end example | |
15119 | ||
15120 | These types can be used to define 128-bit variables. The built-in | |
15121 | functions listed in the following section can be used on these | |
15122 | variables to generate the vector operations. | |
15123 | ||
15124 | For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file | |
15125 | @file{arc-simd.h} also provides equivalent macros called | |
15126 | @code{_@var{someinsn}} that can be used for programming ease and | |
15127 | improved readability. The following macros for DMA control are also | |
15128 | provided: | |
15129 | @example | |
15130 | #define _setup_dma_in_channel_reg _vdiwr | |
15131 | #define _setup_dma_out_channel_reg _vdowr | |
15132 | @end example | |
15133 | ||
15134 | The following is a complete list of all the SIMD built-ins provided | |
15135 | for ARC, grouped by calling signature. | |
15136 | ||
15137 | The following take two @code{__v8hi} arguments and return a | |
15138 | @code{__v8hi} result: | |
15139 | @example | |
15140 | __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi); | |
15141 | __v8hi __builtin_arc_vaddw (__v8hi, __v8hi); | |
15142 | __v8hi __builtin_arc_vand (__v8hi, __v8hi); | |
15143 | __v8hi __builtin_arc_vandaw (__v8hi, __v8hi); | |
15144 | __v8hi __builtin_arc_vavb (__v8hi, __v8hi); | |
15145 | __v8hi __builtin_arc_vavrb (__v8hi, __v8hi); | |
15146 | __v8hi __builtin_arc_vbic (__v8hi, __v8hi); | |
15147 | __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi); | |
15148 | __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi); | |
15149 | __v8hi __builtin_arc_vdifw (__v8hi, __v8hi); | |
15150 | __v8hi __builtin_arc_veqw (__v8hi, __v8hi); | |
15151 | __v8hi __builtin_arc_vh264f (__v8hi, __v8hi); | |
15152 | __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi); | |
15153 | __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi); | |
15154 | __v8hi __builtin_arc_vlew (__v8hi, __v8hi); | |
15155 | __v8hi __builtin_arc_vltw (__v8hi, __v8hi); | |
15156 | __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi); | |
15157 | __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi); | |
15158 | __v8hi __builtin_arc_vminaw (__v8hi, __v8hi); | |
15159 | __v8hi __builtin_arc_vminw (__v8hi, __v8hi); | |
15160 | __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi); | |
15161 | __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi); | |
15162 | __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi); | |
15163 | __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi); | |
15164 | __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi); | |
15165 | __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi); | |
15166 | __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi); | |
15167 | __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi); | |
15168 | __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi); | |
15169 | __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi); | |
15170 | __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi); | |
15171 | __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi); | |
15172 | __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi); | |
15173 | __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi); | |
15174 | __v8hi __builtin_arc_vmrb (__v8hi, __v8hi); | |
15175 | __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi); | |
15176 | __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi); | |
15177 | __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi); | |
15178 | __v8hi __builtin_arc_vmulw (__v8hi, __v8hi); | |
15179 | __v8hi __builtin_arc_vnew (__v8hi, __v8hi); | |
15180 | __v8hi __builtin_arc_vor (__v8hi, __v8hi); | |
15181 | __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi); | |
15182 | __v8hi __builtin_arc_vsubw (__v8hi, __v8hi); | |
15183 | __v8hi __builtin_arc_vsummw (__v8hi, __v8hi); | |
15184 | __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi); | |
15185 | __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi); | |
15186 | __v8hi __builtin_arc_vxor (__v8hi, __v8hi); | |
15187 | __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi); | |
15188 | @end example | |
15189 | ||
15190 | The following take one @code{__v8hi} and one @code{int} argument and return a | |
15191 | @code{__v8hi} result: | |
15192 | ||
15193 | @example | |
15194 | __v8hi __builtin_arc_vbaddw (__v8hi, int); | |
15195 | __v8hi __builtin_arc_vbmaxw (__v8hi, int); | |
15196 | __v8hi __builtin_arc_vbminw (__v8hi, int); | |
15197 | __v8hi __builtin_arc_vbmulaw (__v8hi, int); | |
15198 | __v8hi __builtin_arc_vbmulfw (__v8hi, int); | |
15199 | __v8hi __builtin_arc_vbmulw (__v8hi, int); | |
15200 | __v8hi __builtin_arc_vbrsubw (__v8hi, int); | |
15201 | __v8hi __builtin_arc_vbsubw (__v8hi, int); | |
15202 | @end example | |
15203 | ||
15204 | The following take one @code{__v8hi} argument and one @code{int} argument which | |
15205 | must be a 3-bit compile time constant indicating a register number | |
15206 | I0-I7. They return a @code{__v8hi} result. | |
15207 | @example | |
15208 | __v8hi __builtin_arc_vasrw (__v8hi, const int); | |
15209 | __v8hi __builtin_arc_vsr8 (__v8hi, const int); | |
15210 | __v8hi __builtin_arc_vsr8aw (__v8hi, const int); | |
15211 | @end example | |
15212 | ||
15213 | The following take one @code{__v8hi} argument and one @code{int} | |
15214 | argument which must be a 6-bit compile time constant. They return a | |
15215 | @code{__v8hi} result. | |
15216 | @example | |
15217 | __v8hi __builtin_arc_vasrpwbi (__v8hi, const int); | |
15218 | __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int); | |
15219 | __v8hi __builtin_arc_vasrrwi (__v8hi, const int); | |
15220 | __v8hi __builtin_arc_vasrsrwi (__v8hi, const int); | |
15221 | __v8hi __builtin_arc_vasrwi (__v8hi, const int); | |
15222 | __v8hi __builtin_arc_vsr8awi (__v8hi, const int); | |
15223 | __v8hi __builtin_arc_vsr8i (__v8hi, const int); | |
15224 | @end example | |
15225 | ||
15226 | The following take one @code{__v8hi} argument and one @code{int} argument which | |
15227 | must be a 8-bit compile time constant. They return a @code{__v8hi} | |
15228 | result. | |
15229 | @example | |
15230 | __v8hi __builtin_arc_vd6tapf (__v8hi, const int); | |
15231 | __v8hi __builtin_arc_vmvaw (__v8hi, const int); | |
15232 | __v8hi __builtin_arc_vmvw (__v8hi, const int); | |
15233 | __v8hi __builtin_arc_vmvzw (__v8hi, const int); | |
15234 | @end example | |
15235 | ||
15236 | The following take two @code{int} arguments, the second of which which | |
15237 | must be a 8-bit compile time constant. They return a @code{__v8hi} | |
15238 | result: | |
15239 | @example | |
15240 | __v8hi __builtin_arc_vmovaw (int, const int); | |
15241 | __v8hi __builtin_arc_vmovw (int, const int); | |
15242 | __v8hi __builtin_arc_vmovzw (int, const int); | |
15243 | @end example | |
15244 | ||
15245 | The following take a single @code{__v8hi} argument and return a | |
15246 | @code{__v8hi} result: | |
15247 | @example | |
15248 | __v8hi __builtin_arc_vabsaw (__v8hi); | |
15249 | __v8hi __builtin_arc_vabsw (__v8hi); | |
15250 | __v8hi __builtin_arc_vaddsuw (__v8hi); | |
15251 | __v8hi __builtin_arc_vexch1 (__v8hi); | |
15252 | __v8hi __builtin_arc_vexch2 (__v8hi); | |
15253 | __v8hi __builtin_arc_vexch4 (__v8hi); | |
15254 | __v8hi __builtin_arc_vsignw (__v8hi); | |
15255 | __v8hi __builtin_arc_vupbaw (__v8hi); | |
15256 | __v8hi __builtin_arc_vupbw (__v8hi); | |
15257 | __v8hi __builtin_arc_vupsbaw (__v8hi); | |
15258 | __v8hi __builtin_arc_vupsbw (__v8hi); | |
15259 | @end example | |
15260 | ||
15261 | The following take two @code{int} arguments and return no result: | |
15262 | @example | |
15263 | void __builtin_arc_vdirun (int, int); | |
15264 | void __builtin_arc_vdorun (int, int); | |
15265 | @end example | |
15266 | ||
15267 | The following take two @code{int} arguments and return no result. The | |
15268 | first argument must a 3-bit compile time constant indicating one of | |
15269 | the DR0-DR7 DMA setup channels: | |
15270 | @example | |
15271 | void __builtin_arc_vdiwr (const int, int); | |
15272 | void __builtin_arc_vdowr (const int, int); | |
15273 | @end example | |
15274 | ||
15275 | The following take an @code{int} argument and return no result: | |
15276 | @example | |
15277 | void __builtin_arc_vendrec (int); | |
15278 | void __builtin_arc_vrec (int); | |
15279 | void __builtin_arc_vrecrun (int); | |
15280 | void __builtin_arc_vrun (int); | |
15281 | @end example | |
15282 | ||
15283 | The following take a @code{__v8hi} argument and two @code{int} | |
15284 | arguments and return a @code{__v8hi} result. The second argument must | |
15285 | be a 3-bit compile time constants, indicating one the registers I0-I7, | |
15286 | and the third argument must be an 8-bit compile time constant. | |
15287 | ||
15288 | @emph{Note:} Although the equivalent hardware instructions do not take | |
15289 | an SIMD register as an operand, these builtins overwrite the relevant | |
15290 | bits of the @code{__v8hi} register provided as the first argument with | |
15291 | the value loaded from the @code{[Ib, u8]} location in the SDM. | |
15292 | ||
15293 | @example | |
15294 | __v8hi __builtin_arc_vld32 (__v8hi, const int, const int); | |
15295 | __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int); | |
15296 | __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int); | |
15297 | __v8hi __builtin_arc_vld64 (__v8hi, const int, const int); | |
15298 | @end example | |
15299 | ||
15300 | The following take two @code{int} arguments and return a @code{__v8hi} | |
15301 | result. The first argument must be a 3-bit compile time constants, | |
15302 | indicating one the registers I0-I7, and the second argument must be an | |
15303 | 8-bit compile time constant. | |
15304 | ||
15305 | @example | |
15306 | __v8hi __builtin_arc_vld128 (const int, const int); | |
15307 | __v8hi __builtin_arc_vld64w (const int, const int); | |
15308 | @end example | |
15309 | ||
15310 | The following take a @code{__v8hi} argument and two @code{int} | |
15311 | arguments and return no result. The second argument must be a 3-bit | |
15312 | compile time constants, indicating one the registers I0-I7, and the | |
15313 | third argument must be an 8-bit compile time constant. | |
15314 | ||
15315 | @example | |
15316 | void __builtin_arc_vst128 (__v8hi, const int, const int); | |
15317 | void __builtin_arc_vst64 (__v8hi, const int, const int); | |
15318 | @end example | |
15319 | ||
15320 | The following take a @code{__v8hi} argument and three @code{int} | |
15321 | arguments and return no result. The second argument must be a 3-bit | |
15322 | compile-time constant, identifying the 16-bit sub-register to be | |
15323 | stored, the third argument must be a 3-bit compile time constants, | |
15324 | indicating one the registers I0-I7, and the fourth argument must be an | |
15325 | 8-bit compile time constant. | |
15326 | ||
15327 | @example | |
15328 | void __builtin_arc_vst16_n (__v8hi, const int, const int, const int); | |
15329 | void __builtin_arc_vst32_n (__v8hi, const int, const int, const int); | |
15330 | @end example | |
15331 | ||
15332 | @node ARM iWMMXt Built-in Functions | |
15333 | @subsection ARM iWMMXt Built-in Functions | |
15334 | ||
15335 | These built-in functions are available for the ARM family of | |
15336 | processors when the @option{-mcpu=iwmmxt} switch is used: | |
15337 | ||
15338 | @smallexample | |
15339 | typedef int v2si __attribute__ ((vector_size (8))); | |
15340 | typedef short v4hi __attribute__ ((vector_size (8))); | |
15341 | typedef char v8qi __attribute__ ((vector_size (8))); | |
15342 | ||
15343 | int __builtin_arm_getwcgr0 (void); | |
15344 | void __builtin_arm_setwcgr0 (int); | |
15345 | int __builtin_arm_getwcgr1 (void); | |
15346 | void __builtin_arm_setwcgr1 (int); | |
15347 | int __builtin_arm_getwcgr2 (void); | |
15348 | void __builtin_arm_setwcgr2 (int); | |
15349 | int __builtin_arm_getwcgr3 (void); | |
15350 | void __builtin_arm_setwcgr3 (int); | |
15351 | int __builtin_arm_textrmsb (v8qi, int); | |
15352 | int __builtin_arm_textrmsh (v4hi, int); | |
15353 | int __builtin_arm_textrmsw (v2si, int); | |
15354 | int __builtin_arm_textrmub (v8qi, int); | |
15355 | int __builtin_arm_textrmuh (v4hi, int); | |
15356 | int __builtin_arm_textrmuw (v2si, int); | |
15357 | v8qi __builtin_arm_tinsrb (v8qi, int, int); | |
15358 | v4hi __builtin_arm_tinsrh (v4hi, int, int); | |
15359 | v2si __builtin_arm_tinsrw (v2si, int, int); | |
15360 | long long __builtin_arm_tmia (long long, int, int); | |
15361 | long long __builtin_arm_tmiabb (long long, int, int); | |
15362 | long long __builtin_arm_tmiabt (long long, int, int); | |
15363 | long long __builtin_arm_tmiaph (long long, int, int); | |
15364 | long long __builtin_arm_tmiatb (long long, int, int); | |
15365 | long long __builtin_arm_tmiatt (long long, int, int); | |
15366 | int __builtin_arm_tmovmskb (v8qi); | |
15367 | int __builtin_arm_tmovmskh (v4hi); | |
15368 | int __builtin_arm_tmovmskw (v2si); | |
15369 | long long __builtin_arm_waccb (v8qi); | |
15370 | long long __builtin_arm_wacch (v4hi); | |
15371 | long long __builtin_arm_waccw (v2si); | |
15372 | v8qi __builtin_arm_waddb (v8qi, v8qi); | |
15373 | v8qi __builtin_arm_waddbss (v8qi, v8qi); | |
15374 | v8qi __builtin_arm_waddbus (v8qi, v8qi); | |
15375 | v4hi __builtin_arm_waddh (v4hi, v4hi); | |
15376 | v4hi __builtin_arm_waddhss (v4hi, v4hi); | |
15377 | v4hi __builtin_arm_waddhus (v4hi, v4hi); | |
15378 | v2si __builtin_arm_waddw (v2si, v2si); | |
15379 | v2si __builtin_arm_waddwss (v2si, v2si); | |
15380 | v2si __builtin_arm_waddwus (v2si, v2si); | |
15381 | v8qi __builtin_arm_walign (v8qi, v8qi, int); | |
15382 | long long __builtin_arm_wand(long long, long long); | |
15383 | long long __builtin_arm_wandn (long long, long long); | |
15384 | v8qi __builtin_arm_wavg2b (v8qi, v8qi); | |
15385 | v8qi __builtin_arm_wavg2br (v8qi, v8qi); | |
15386 | v4hi __builtin_arm_wavg2h (v4hi, v4hi); | |
15387 | v4hi __builtin_arm_wavg2hr (v4hi, v4hi); | |
15388 | v8qi __builtin_arm_wcmpeqb (v8qi, v8qi); | |
15389 | v4hi __builtin_arm_wcmpeqh (v4hi, v4hi); | |
15390 | v2si __builtin_arm_wcmpeqw (v2si, v2si); | |
15391 | v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi); | |
15392 | v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi); | |
15393 | v2si __builtin_arm_wcmpgtsw (v2si, v2si); | |
15394 | v8qi __builtin_arm_wcmpgtub (v8qi, v8qi); | |
15395 | v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi); | |
15396 | v2si __builtin_arm_wcmpgtuw (v2si, v2si); | |
15397 | long long __builtin_arm_wmacs (long long, v4hi, v4hi); | |
15398 | long long __builtin_arm_wmacsz (v4hi, v4hi); | |
15399 | long long __builtin_arm_wmacu (long long, v4hi, v4hi); | |
15400 | long long __builtin_arm_wmacuz (v4hi, v4hi); | |
15401 | v4hi __builtin_arm_wmadds (v4hi, v4hi); | |
15402 | v4hi __builtin_arm_wmaddu (v4hi, v4hi); | |
15403 | v8qi __builtin_arm_wmaxsb (v8qi, v8qi); | |
15404 | v4hi __builtin_arm_wmaxsh (v4hi, v4hi); | |
15405 | v2si __builtin_arm_wmaxsw (v2si, v2si); | |
15406 | v8qi __builtin_arm_wmaxub (v8qi, v8qi); | |
15407 | v4hi __builtin_arm_wmaxuh (v4hi, v4hi); | |
15408 | v2si __builtin_arm_wmaxuw (v2si, v2si); | |
15409 | v8qi __builtin_arm_wminsb (v8qi, v8qi); | |
15410 | v4hi __builtin_arm_wminsh (v4hi, v4hi); | |
15411 | v2si __builtin_arm_wminsw (v2si, v2si); | |
15412 | v8qi __builtin_arm_wminub (v8qi, v8qi); | |
15413 | v4hi __builtin_arm_wminuh (v4hi, v4hi); | |
15414 | v2si __builtin_arm_wminuw (v2si, v2si); | |
15415 | v4hi __builtin_arm_wmulsm (v4hi, v4hi); | |
15416 | v4hi __builtin_arm_wmulul (v4hi, v4hi); | |
15417 | v4hi __builtin_arm_wmulum (v4hi, v4hi); | |
15418 | long long __builtin_arm_wor (long long, long long); | |
15419 | v2si __builtin_arm_wpackdss (long long, long long); | |
15420 | v2si __builtin_arm_wpackdus (long long, long long); | |
15421 | v8qi __builtin_arm_wpackhss (v4hi, v4hi); | |
15422 | v8qi __builtin_arm_wpackhus (v4hi, v4hi); | |
15423 | v4hi __builtin_arm_wpackwss (v2si, v2si); | |
15424 | v4hi __builtin_arm_wpackwus (v2si, v2si); | |
15425 | long long __builtin_arm_wrord (long long, long long); | |
15426 | long long __builtin_arm_wrordi (long long, int); | |
15427 | v4hi __builtin_arm_wrorh (v4hi, long long); | |
15428 | v4hi __builtin_arm_wrorhi (v4hi, int); | |
15429 | v2si __builtin_arm_wrorw (v2si, long long); | |
15430 | v2si __builtin_arm_wrorwi (v2si, int); | |
15431 | v2si __builtin_arm_wsadb (v2si, v8qi, v8qi); | |
15432 | v2si __builtin_arm_wsadbz (v8qi, v8qi); | |
15433 | v2si __builtin_arm_wsadh (v2si, v4hi, v4hi); | |
15434 | v2si __builtin_arm_wsadhz (v4hi, v4hi); | |
15435 | v4hi __builtin_arm_wshufh (v4hi, int); | |
15436 | long long __builtin_arm_wslld (long long, long long); | |
15437 | long long __builtin_arm_wslldi (long long, int); | |
15438 | v4hi __builtin_arm_wsllh (v4hi, long long); | |
15439 | v4hi __builtin_arm_wsllhi (v4hi, int); | |
15440 | v2si __builtin_arm_wsllw (v2si, long long); | |
15441 | v2si __builtin_arm_wsllwi (v2si, int); | |
15442 | long long __builtin_arm_wsrad (long long, long long); | |
15443 | long long __builtin_arm_wsradi (long long, int); | |
15444 | v4hi __builtin_arm_wsrah (v4hi, long long); | |
15445 | v4hi __builtin_arm_wsrahi (v4hi, int); | |
15446 | v2si __builtin_arm_wsraw (v2si, long long); | |
15447 | v2si __builtin_arm_wsrawi (v2si, int); | |
15448 | long long __builtin_arm_wsrld (long long, long long); | |
15449 | long long __builtin_arm_wsrldi (long long, int); | |
15450 | v4hi __builtin_arm_wsrlh (v4hi, long long); | |
15451 | v4hi __builtin_arm_wsrlhi (v4hi, int); | |
15452 | v2si __builtin_arm_wsrlw (v2si, long long); | |
15453 | v2si __builtin_arm_wsrlwi (v2si, int); | |
15454 | v8qi __builtin_arm_wsubb (v8qi, v8qi); | |
15455 | v8qi __builtin_arm_wsubbss (v8qi, v8qi); | |
15456 | v8qi __builtin_arm_wsubbus (v8qi, v8qi); | |
15457 | v4hi __builtin_arm_wsubh (v4hi, v4hi); | |
15458 | v4hi __builtin_arm_wsubhss (v4hi, v4hi); | |
15459 | v4hi __builtin_arm_wsubhus (v4hi, v4hi); | |
15460 | v2si __builtin_arm_wsubw (v2si, v2si); | |
15461 | v2si __builtin_arm_wsubwss (v2si, v2si); | |
15462 | v2si __builtin_arm_wsubwus (v2si, v2si); | |
15463 | v4hi __builtin_arm_wunpckehsb (v8qi); | |
15464 | v2si __builtin_arm_wunpckehsh (v4hi); | |
15465 | long long __builtin_arm_wunpckehsw (v2si); | |
15466 | v4hi __builtin_arm_wunpckehub (v8qi); | |
15467 | v2si __builtin_arm_wunpckehuh (v4hi); | |
15468 | long long __builtin_arm_wunpckehuw (v2si); | |
15469 | v4hi __builtin_arm_wunpckelsb (v8qi); | |
15470 | v2si __builtin_arm_wunpckelsh (v4hi); | |
15471 | long long __builtin_arm_wunpckelsw (v2si); | |
15472 | v4hi __builtin_arm_wunpckelub (v8qi); | |
15473 | v2si __builtin_arm_wunpckeluh (v4hi); | |
15474 | long long __builtin_arm_wunpckeluw (v2si); | |
15475 | v8qi __builtin_arm_wunpckihb (v8qi, v8qi); | |
15476 | v4hi __builtin_arm_wunpckihh (v4hi, v4hi); | |
15477 | v2si __builtin_arm_wunpckihw (v2si, v2si); | |
15478 | v8qi __builtin_arm_wunpckilb (v8qi, v8qi); | |
15479 | v4hi __builtin_arm_wunpckilh (v4hi, v4hi); | |
15480 | v2si __builtin_arm_wunpckilw (v2si, v2si); | |
15481 | long long __builtin_arm_wxor (long long, long long); | |
15482 | long long __builtin_arm_wzero (); | |
15483 | @end smallexample | |
15484 | ||
15485 | ||
15486 | @node ARM C Language Extensions (ACLE) | |
15487 | @subsection ARM C Language Extensions (ACLE) | |
15488 | ||
15489 | GCC implements extensions for C as described in the ARM C Language | |
15490 | Extensions (ACLE) specification, which can be found at | |
15491 | @uref{https://developer.arm.com/documentation/ihi0053/latest/}. | |
15492 | ||
15493 | As a part of ACLE, GCC implements extensions for Advanced SIMD as described in | |
15494 | the ARM C Language Extensions Specification. The complete list of Advanced SIMD | |
15495 | intrinsics can be found at | |
15496 | @uref{https://developer.arm.com/documentation/ihi0073/latest/}. | |
15497 | The built-in intrinsics for the Advanced SIMD extension are available when | |
15498 | NEON is enabled. | |
15499 | ||
15500 | Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both | |
15501 | back ends support CRC32 intrinsics and the ARM back end supports the | |
15502 | Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit | |
15503 | floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1. | |
15504 | AArch64's back end does not have support for 16-bit floating point Advanced SIMD | |
15505 | intrinsics yet. | |
15506 | ||
15507 | See @ref{ARM Options} and @ref{AArch64 Options} for more information on the | |
15508 | availability of extensions. | |
15509 | ||
15510 | @node ARM Floating Point Status and Control Intrinsics | |
15511 | @subsection ARM Floating Point Status and Control Intrinsics | |
15512 | ||
15513 | These built-in functions are available for the ARM family of | |
15514 | processors with floating-point unit. | |
15515 | ||
15516 | @smallexample | |
15517 | unsigned int __builtin_arm_get_fpscr (); | |
15518 | void __builtin_arm_set_fpscr (unsigned int); | |
15519 | @end smallexample | |
15520 | ||
15521 | @node ARM ARMv8-M Security Extensions | |
15522 | @subsection ARM ARMv8-M Security Extensions | |
15523 | ||
15524 | GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M | |
15525 | Security Extensions: Requirements on Development Tools Engineering | |
15526 | Specification, which can be found at | |
15527 | @uref{https://developer.arm.com/documentation/ecm0359818/latest/}. | |
15528 | ||
15529 | As part of the Security Extensions GCC implements two new function attributes: | |
15530 | @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}. | |
15531 | ||
15532 | As part of the Security Extensions GCC implements the intrinsics below. FPTR | |
15533 | is used here to mean any function pointer type. | |
15534 | ||
15535 | @smallexample | |
15536 | cmse_address_info_t cmse_TT (void *); | |
15537 | cmse_address_info_t cmse_TT_fptr (FPTR); | |
15538 | cmse_address_info_t cmse_TTT (void *); | |
15539 | cmse_address_info_t cmse_TTT_fptr (FPTR); | |
15540 | cmse_address_info_t cmse_TTA (void *); | |
15541 | cmse_address_info_t cmse_TTA_fptr (FPTR); | |
15542 | cmse_address_info_t cmse_TTAT (void *); | |
15543 | cmse_address_info_t cmse_TTAT_fptr (FPTR); | |
15544 | void * cmse_check_address_range (void *, size_t, int); | |
15545 | typeof(p) cmse_nsfptr_create (FPTR p); | |
15546 | intptr_t cmse_is_nsfptr (FPTR); | |
15547 | int cmse_nonsecure_caller (void); | |
15548 | @end smallexample | |
15549 | ||
15550 | @node AVR Built-in Functions | |
15551 | @subsection AVR Built-in Functions | |
15552 | ||
15553 | For each built-in function for AVR, there is an equally named, | |
15554 | uppercase built-in macro defined. That way users can easily query if | |
15555 | or if not a specific built-in is implemented or not. For example, if | |
15556 | @code{__builtin_avr_nop} is available the macro | |
15557 | @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. | |
15558 | ||
15559 | @table @code | |
15560 | ||
15561 | @item void __builtin_avr_nop (void) | |
15562 | @itemx void __builtin_avr_sei (void) | |
15563 | @itemx void __builtin_avr_cli (void) | |
15564 | @itemx void __builtin_avr_sleep (void) | |
15565 | @itemx void __builtin_avr_wdr (void) | |
15566 | @itemx unsigned char __builtin_avr_swap (unsigned char) | |
15567 | @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char) | |
15568 | @itemx int __builtin_avr_fmuls (char, char) | |
15569 | @itemx int __builtin_avr_fmulsu (char, unsigned char) | |
15570 | These built-in functions map to the respective machine | |
15571 | instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, | |
15572 | @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} | |
15573 | resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented | |
15574 | as library call if no hardware multiplier is available. | |
15575 | ||
15576 | @item void __builtin_avr_delay_cycles (unsigned long ticks) | |
15577 | Delay execution for @var{ticks} cycles. Note that this | |
15578 | built-in does not take into account the effect of interrupts that | |
15579 | might increase delay time. @var{ticks} must be a compile-time | |
15580 | integer constant; delays with a variable number of cycles are not supported. | |
15581 | ||
15582 | @item char __builtin_avr_flash_segment (const __memx void*) | |
15583 | This built-in takes a byte address to the 24-bit | |
15584 | @ref{AVR Named Address Spaces,address space} @code{__memx} and returns | |
15585 | the number of the flash segment (the 64 KiB chunk) where the address | |
15586 | points to. Counting starts at @code{0}. | |
15587 | If the address does not point to flash memory, return @code{-1}. | |
15588 | ||
15589 | @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val) | |
15590 | Insert bits from @var{bits} into @var{val} and return the resulting | |
15591 | value. The nibbles of @var{map} determine how the insertion is | |
15592 | performed: Let @var{X} be the @var{n}-th nibble of @var{map} | |
15593 | @enumerate | |
15594 | @item If @var{X} is @code{0xf}, | |
15595 | then the @var{n}-th bit of @var{val} is returned unaltered. | |
15596 | ||
15597 | @item If X is in the range 0@dots{}7, | |
15598 | then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} | |
15599 | ||
15600 | @item If X is in the range 8@dots{}@code{0xe}, | |
15601 | then the @var{n}-th result bit is undefined. | |
15602 | @end enumerate | |
15603 | ||
15604 | @noindent | |
15605 | One typical use case for this built-in is adjusting input and | |
15606 | output values to non-contiguous port layouts. Some examples: | |
15607 | ||
15608 | @smallexample | |
15609 | // same as val, bits is unused | |
15610 | __builtin_avr_insert_bits (0xffffffff, bits, val); | |
15611 | @end smallexample | |
15612 | ||
15613 | @smallexample | |
15614 | // same as bits, val is unused | |
15615 | __builtin_avr_insert_bits (0x76543210, bits, val); | |
15616 | @end smallexample | |
15617 | ||
15618 | @smallexample | |
15619 | // same as rotating bits by 4 | |
15620 | __builtin_avr_insert_bits (0x32107654, bits, 0); | |
15621 | @end smallexample | |
15622 | ||
15623 | @smallexample | |
15624 | // high nibble of result is the high nibble of val | |
15625 | // low nibble of result is the low nibble of bits | |
15626 | __builtin_avr_insert_bits (0xffff3210, bits, val); | |
15627 | @end smallexample | |
15628 | ||
15629 | @smallexample | |
15630 | // reverse the bit order of bits | |
15631 | __builtin_avr_insert_bits (0x01234567, bits, 0); | |
15632 | @end smallexample | |
15633 | ||
15634 | @item void __builtin_avr_nops (unsigned count) | |
15635 | Insert @var{count} @code{NOP} instructions. | |
15636 | The number of instructions must be a compile-time integer constant. | |
15637 | ||
15638 | @end table | |
15639 | ||
15640 | @noindent | |
15641 | There are many more AVR-specific built-in functions that are used to | |
15642 | implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of | |
15643 | section 7.18a.6. You don't need to use these built-ins directly. | |
15644 | Instead, use the declarations as supplied by the @code{stdfix.h} header | |
15645 | with GNU-C99: | |
15646 | ||
15647 | @smallexample | |
15648 | #include <stdfix.h> | |
15649 | ||
15650 | // Re-interpret the bit representation of unsigned 16-bit | |
15651 | // integer @var{uval} as Q-format 0.16 value. | |
15652 | unsigned fract get_bits (uint_ur_t uval) | |
15653 | @{ | |
15654 | return urbits (uval); | |
15655 | @} | |
15656 | @end smallexample | |
15657 | ||
15658 | @node Blackfin Built-in Functions | |
15659 | @subsection Blackfin Built-in Functions | |
15660 | ||
15661 | Currently, there are two Blackfin-specific built-in functions. These are | |
15662 | used for generating @code{CSYNC} and @code{SSYNC} machine insns without | |
15663 | using inline assembly; by using these built-in functions the compiler can | |
15664 | automatically add workarounds for hardware errata involving these | |
15665 | instructions. These functions are named as follows: | |
15666 | ||
15667 | @smallexample | |
15668 | void __builtin_bfin_csync (void); | |
15669 | void __builtin_bfin_ssync (void); | |
15670 | @end smallexample | |
15671 | ||
15672 | @node BPF Built-in Functions | |
15673 | @subsection BPF Built-in Functions | |
15674 | ||
15675 | The following built-in functions are available for eBPF targets. | |
15676 | ||
f25efe50 | 15677 | @defbuiltin{{unsigned long long} __builtin_bpf_load_byte (unsigned long long @var{offset})} |
d77de738 | 15678 | Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. |
f25efe50 | 15679 | @enddefbuiltin |
d77de738 | 15680 | |
f25efe50 | 15681 | @defbuiltin{{unsigned long long} __builtin_bpf_load_half (unsigned long long @var{offset})} |
7ffbc74c | 15682 | Load 16 bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. |
f25efe50 | 15683 | @enddefbuiltin |
d77de738 | 15684 | |
f25efe50 | 15685 | @defbuiltin{{unsigned long long} __builtin_bpf_load_word (unsigned long long @var{offset})} |
7ffbc74c | 15686 | Load 32 bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. |
f25efe50 | 15687 | @enddefbuiltin |
d77de738 | 15688 | |
f25efe50 | 15689 | @defbuiltin{{void *} __builtin_preserve_access_index (@var{expr})} |
d77de738 | 15690 | BPF Compile Once-Run Everywhere (CO-RE) support. Instruct GCC to generate CO-RE relocation records for any accesses to aggregate data structures (struct, union, array types) in @var{expr}. This builtin is otherwise transparent, the return value is whatever @var{expr} evaluates to. It is also overloaded: @var{expr} may be of any type (not necessarily a pointer), the return type is the same. Has no effect if @code{-mco-re} is not in effect (either specified or implied). |
f25efe50 | 15691 | @enddefbuiltin |
d77de738 | 15692 | |
f25efe50 | 15693 | @defbuiltin{{unsigned int} __builtin_preserve_field_info (@var{expr}, unsigned int @var{kind})} |
d77de738 ML |
15694 | BPF Compile Once-Run Everywhere (CO-RE) support. This builtin is used to |
15695 | extract information to aid in struct/union relocations. @var{expr} is | |
15696 | an access to a field of a struct or union. Depending on @var{kind}, different | |
15697 | information is returned to the program. A CO-RE relocation for the access in | |
15698 | @var{expr} with kind @var{kind} is recorded if @code{-mco-re} is in effect. | |
15699 | ||
15700 | The following values are supported for @var{kind}: | |
7ffbc74c | 15701 | @table @code |
d77de738 ML |
15702 | @item FIELD_BYTE_OFFSET = 0 |
15703 | The returned value is the offset, in bytes, of the field from the | |
7ffbc74c | 15704 | beginning of the containing structure. For bit-fields, this is the byte offset |
d77de738 ML |
15705 | of the containing word. |
15706 | ||
15707 | @item FIELD_BYTE_SIZE = 1 | |
7ffbc74c SL |
15708 | The returned value is the size, in bytes, of the field. For bit-fields, |
15709 | this is the size in bytes of the containing word. | |
d77de738 ML |
15710 | |
15711 | @item FIELD_EXISTENCE = 2 | |
15712 | The returned value is 1 if the field exists, 0 otherwise. Always 1 at | |
15713 | compile time. | |
15714 | ||
15715 | @item FIELD_SIGNEDNESS = 3 | |
15716 | The returned value is 1 if the field is signed, 0 otherwise. | |
15717 | ||
15718 | @item FIELD_LSHIFT_U64 = 4 | |
15719 | @itemx FIELD_RSHIFT_U64 = 5 | |
15720 | The returned value is the number of bits of left- or right-shifting | |
7ffbc74c SL |
15721 | (respectively) needed in order to recover the original value of the field, |
15722 | after it has been loaded by a read of @code{FIELD_BYTE_SIZE} bytes into an | |
15723 | unsigned 64-bit value. Primarily useful for reading bit-field values | |
15724 | from structures that may change between kernel versions. | |
d77de738 ML |
15725 | |
15726 | @end table | |
15727 | ||
15728 | Note that the return value is a constant which is known at | |
7ffbc74c SL |
15729 | compile time. If the field has a variable offset then |
15730 | @code{FIELD_BYTE_OFFSET}, @code{FIELD_LSHIFT_U64}, | |
15731 | and @code{FIELD_RSHIFT_U64} are not supported. | |
15732 | Similarly, if the field has a variable size then | |
15733 | @code{FIELD_BYTE_SIZE}, @code{FIELD_LSHIFT_U64}, | |
15734 | and @code{FIELD_RSHIFT_U64} are not supported. | |
15735 | ||
15736 | For example, @code{__builtin_preserve_field_info} can be used to reliably | |
15737 | extract bit-field values from a structure that may change between | |
d77de738 ML |
15738 | kernel versions: |
15739 | ||
7ffbc74c | 15740 | @smallexample |
d77de738 ML |
15741 | struct S |
15742 | @{ | |
15743 | short a; | |
15744 | int x:7; | |
15745 | int y:5; | |
15746 | @}; | |
15747 | ||
15748 | int | |
15749 | read_y (struct S *arg) | |
15750 | @{ | |
15751 | unsigned long long val; | |
7ffbc74c SL |
15752 | unsigned int offset |
15753 | = __builtin_preserve_field_info (arg->y, FIELD_BYTE_OFFSET); | |
15754 | unsigned int size | |
15755 | = __builtin_preserve_field_info (arg->y, FIELD_BYTE_SIZE); | |
d77de738 ML |
15756 | |
15757 | /* Read size bytes from arg + offset into val. */ | |
15758 | bpf_probe_read (&val, size, arg + offset); | |
15759 | ||
15760 | val <<= __builtin_preserve_field_info (arg->y, FIELD_LSHIFT_U64); | |
15761 | ||
15762 | if (__builtin_preserve_field_info (arg->y, FIELD_SIGNEDNESS)) | |
7ffbc74c SL |
15763 | val = ((long long) val |
15764 | >> __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64)); | |
d77de738 ML |
15765 | else |
15766 | val >>= __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64); | |
15767 | ||
15768 | return val; | |
15769 | @} | |
15770 | ||
7ffbc74c | 15771 | @end smallexample |
f25efe50 | 15772 | @enddefbuiltin |
d77de738 ML |
15773 | |
15774 | @node FR-V Built-in Functions | |
15775 | @subsection FR-V Built-in Functions | |
15776 | ||
15777 | GCC provides many FR-V-specific built-in functions. In general, | |
15778 | these functions are intended to be compatible with those described | |
15779 | by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu | |
15780 | Semiconductor}. The two exceptions are @code{__MDUNPACKH} and | |
15781 | @code{__MBTOHE}, the GCC forms of which pass 128-bit values by | |
15782 | pointer rather than by value. | |
15783 | ||
15784 | Most of the functions are named after specific FR-V instructions. | |
15785 | Such functions are said to be ``directly mapped'' and are summarized | |
15786 | here in tabular form. | |
15787 | ||
15788 | @menu | |
15789 | * Argument Types:: | |
15790 | * Directly-mapped Integer Functions:: | |
15791 | * Directly-mapped Media Functions:: | |
15792 | * Raw read/write Functions:: | |
15793 | * Other Built-in Functions:: | |
15794 | @end menu | |
15795 | ||
15796 | @node Argument Types | |
15797 | @subsubsection Argument Types | |
15798 | ||
15799 | The arguments to the built-in functions can be divided into three groups: | |
15800 | register numbers, compile-time constants and run-time values. In order | |
15801 | to make this classification clear at a glance, the arguments and return | |
15802 | values are given the following pseudo types: | |
15803 | ||
15804 | @multitable @columnfractions .20 .30 .15 .35 | |
15805 | @headitem Pseudo type @tab Real C type @tab Constant? @tab Description | |
15806 | @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword | |
15807 | @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word | |
15808 | @item @code{sw1} @tab @code{int} @tab No @tab a signed word | |
15809 | @item @code{uw2} @tab @code{unsigned long long} @tab No | |
15810 | @tab an unsigned doubleword | |
15811 | @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword | |
15812 | @item @code{const} @tab @code{int} @tab Yes @tab an integer constant | |
15813 | @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number | |
15814 | @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number | |
15815 | @end multitable | |
15816 | ||
15817 | These pseudo types are not defined by GCC, they are simply a notational | |
15818 | convenience used in this manual. | |
15819 | ||
15820 | Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} | |
15821 | and @code{sw2} are evaluated at run time. They correspond to | |
15822 | register operands in the underlying FR-V instructions. | |
15823 | ||
15824 | @code{const} arguments represent immediate operands in the underlying | |
15825 | FR-V instructions. They must be compile-time constants. | |
15826 | ||
15827 | @code{acc} arguments are evaluated at compile time and specify the number | |
15828 | of an accumulator register. For example, an @code{acc} argument of 2 | |
15829 | selects the ACC2 register. | |
15830 | ||
15831 | @code{iacc} arguments are similar to @code{acc} arguments but specify the | |
15832 | number of an IACC register. See @pxref{Other Built-in Functions} | |
15833 | for more details. | |
15834 | ||
15835 | @node Directly-mapped Integer Functions | |
15836 | @subsubsection Directly-Mapped Integer Functions | |
15837 | ||
15838 | The functions listed below map directly to FR-V I-type instructions. | |
15839 | ||
15840 | @multitable @columnfractions .45 .32 .23 | |
15841 | @headitem Function prototype @tab Example usage @tab Assembly output | |
15842 | @item @code{sw1 __ADDSS (sw1, sw1)} | |
15843 | @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} | |
15844 | @tab @code{ADDSS @var{a},@var{b},@var{c}} | |
15845 | @item @code{sw1 __SCAN (sw1, sw1)} | |
15846 | @tab @code{@var{c} = __SCAN (@var{a}, @var{b})} | |
15847 | @tab @code{SCAN @var{a},@var{b},@var{c}} | |
15848 | @item @code{sw1 __SCUTSS (sw1)} | |
15849 | @tab @code{@var{b} = __SCUTSS (@var{a})} | |
15850 | @tab @code{SCUTSS @var{a},@var{b}} | |
15851 | @item @code{sw1 __SLASS (sw1, sw1)} | |
15852 | @tab @code{@var{c} = __SLASS (@var{a}, @var{b})} | |
15853 | @tab @code{SLASS @var{a},@var{b},@var{c}} | |
15854 | @item @code{void __SMASS (sw1, sw1)} | |
15855 | @tab @code{__SMASS (@var{a}, @var{b})} | |
15856 | @tab @code{SMASS @var{a},@var{b}} | |
15857 | @item @code{void __SMSSS (sw1, sw1)} | |
15858 | @tab @code{__SMSSS (@var{a}, @var{b})} | |
15859 | @tab @code{SMSSS @var{a},@var{b}} | |
15860 | @item @code{void __SMU (sw1, sw1)} | |
15861 | @tab @code{__SMU (@var{a}, @var{b})} | |
15862 | @tab @code{SMU @var{a},@var{b}} | |
15863 | @item @code{sw2 __SMUL (sw1, sw1)} | |
15864 | @tab @code{@var{c} = __SMUL (@var{a}, @var{b})} | |
15865 | @tab @code{SMUL @var{a},@var{b},@var{c}} | |
15866 | @item @code{sw1 __SUBSS (sw1, sw1)} | |
15867 | @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} | |
15868 | @tab @code{SUBSS @var{a},@var{b},@var{c}} | |
15869 | @item @code{uw2 __UMUL (uw1, uw1)} | |
15870 | @tab @code{@var{c} = __UMUL (@var{a}, @var{b})} | |
15871 | @tab @code{UMUL @var{a},@var{b},@var{c}} | |
15872 | @end multitable | |
15873 | ||
15874 | @node Directly-mapped Media Functions | |
15875 | @subsubsection Directly-Mapped Media Functions | |
15876 | ||
15877 | The functions listed below map directly to FR-V M-type instructions. | |
15878 | ||
15879 | @multitable @columnfractions .45 .32 .23 | |
15880 | @headitem Function prototype @tab Example usage @tab Assembly output | |
15881 | @item @code{uw1 __MABSHS (sw1)} | |
15882 | @tab @code{@var{b} = __MABSHS (@var{a})} | |
15883 | @tab @code{MABSHS @var{a},@var{b}} | |
15884 | @item @code{void __MADDACCS (acc, acc)} | |
15885 | @tab @code{__MADDACCS (@var{b}, @var{a})} | |
15886 | @tab @code{MADDACCS @var{a},@var{b}} | |
15887 | @item @code{sw1 __MADDHSS (sw1, sw1)} | |
15888 | @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} | |
15889 | @tab @code{MADDHSS @var{a},@var{b},@var{c}} | |
15890 | @item @code{uw1 __MADDHUS (uw1, uw1)} | |
15891 | @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} | |
15892 | @tab @code{MADDHUS @var{a},@var{b},@var{c}} | |
15893 | @item @code{uw1 __MAND (uw1, uw1)} | |
15894 | @tab @code{@var{c} = __MAND (@var{a}, @var{b})} | |
15895 | @tab @code{MAND @var{a},@var{b},@var{c}} | |
15896 | @item @code{void __MASACCS (acc, acc)} | |
15897 | @tab @code{__MASACCS (@var{b}, @var{a})} | |
15898 | @tab @code{MASACCS @var{a},@var{b}} | |
15899 | @item @code{uw1 __MAVEH (uw1, uw1)} | |
15900 | @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} | |
15901 | @tab @code{MAVEH @var{a},@var{b},@var{c}} | |
15902 | @item @code{uw2 __MBTOH (uw1)} | |
15903 | @tab @code{@var{b} = __MBTOH (@var{a})} | |
15904 | @tab @code{MBTOH @var{a},@var{b}} | |
15905 | @item @code{void __MBTOHE (uw1 *, uw1)} | |
15906 | @tab @code{__MBTOHE (&@var{b}, @var{a})} | |
15907 | @tab @code{MBTOHE @var{a},@var{b}} | |
15908 | @item @code{void __MCLRACC (acc)} | |
15909 | @tab @code{__MCLRACC (@var{a})} | |
15910 | @tab @code{MCLRACC @var{a}} | |
15911 | @item @code{void __MCLRACCA (void)} | |
15912 | @tab @code{__MCLRACCA ()} | |
15913 | @tab @code{MCLRACCA} | |
15914 | @item @code{uw1 __Mcop1 (uw1, uw1)} | |
15915 | @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} | |
15916 | @tab @code{Mcop1 @var{a},@var{b},@var{c}} | |
15917 | @item @code{uw1 __Mcop2 (uw1, uw1)} | |
15918 | @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} | |
15919 | @tab @code{Mcop2 @var{a},@var{b},@var{c}} | |
15920 | @item @code{uw1 __MCPLHI (uw2, const)} | |
15921 | @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} | |
15922 | @tab @code{MCPLHI @var{a},#@var{b},@var{c}} | |
15923 | @item @code{uw1 __MCPLI (uw2, const)} | |
15924 | @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} | |
15925 | @tab @code{MCPLI @var{a},#@var{b},@var{c}} | |
15926 | @item @code{void __MCPXIS (acc, sw1, sw1)} | |
15927 | @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} | |
15928 | @tab @code{MCPXIS @var{a},@var{b},@var{c}} | |
15929 | @item @code{void __MCPXIU (acc, uw1, uw1)} | |
15930 | @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} | |
15931 | @tab @code{MCPXIU @var{a},@var{b},@var{c}} | |
15932 | @item @code{void __MCPXRS (acc, sw1, sw1)} | |
15933 | @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} | |
15934 | @tab @code{MCPXRS @var{a},@var{b},@var{c}} | |
15935 | @item @code{void __MCPXRU (acc, uw1, uw1)} | |
15936 | @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} | |
15937 | @tab @code{MCPXRU @var{a},@var{b},@var{c}} | |
15938 | @item @code{uw1 __MCUT (acc, uw1)} | |
15939 | @tab @code{@var{c} = __MCUT (@var{a}, @var{b})} | |
15940 | @tab @code{MCUT @var{a},@var{b},@var{c}} | |
15941 | @item @code{uw1 __MCUTSS (acc, sw1)} | |
15942 | @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} | |
15943 | @tab @code{MCUTSS @var{a},@var{b},@var{c}} | |
15944 | @item @code{void __MDADDACCS (acc, acc)} | |
15945 | @tab @code{__MDADDACCS (@var{b}, @var{a})} | |
15946 | @tab @code{MDADDACCS @var{a},@var{b}} | |
15947 | @item @code{void __MDASACCS (acc, acc)} | |
15948 | @tab @code{__MDASACCS (@var{b}, @var{a})} | |
15949 | @tab @code{MDASACCS @var{a},@var{b}} | |
15950 | @item @code{uw2 __MDCUTSSI (acc, const)} | |
15951 | @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} | |
15952 | @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} | |
15953 | @item @code{uw2 __MDPACKH (uw2, uw2)} | |
15954 | @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} | |
15955 | @tab @code{MDPACKH @var{a},@var{b},@var{c}} | |
15956 | @item @code{uw2 __MDROTLI (uw2, const)} | |
15957 | @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} | |
15958 | @tab @code{MDROTLI @var{a},#@var{b},@var{c}} | |
15959 | @item @code{void __MDSUBACCS (acc, acc)} | |
15960 | @tab @code{__MDSUBACCS (@var{b}, @var{a})} | |
15961 | @tab @code{MDSUBACCS @var{a},@var{b}} | |
15962 | @item @code{void __MDUNPACKH (uw1 *, uw2)} | |
15963 | @tab @code{__MDUNPACKH (&@var{b}, @var{a})} | |
15964 | @tab @code{MDUNPACKH @var{a},@var{b}} | |
15965 | @item @code{uw2 __MEXPDHD (uw1, const)} | |
15966 | @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} | |
15967 | @tab @code{MEXPDHD @var{a},#@var{b},@var{c}} | |
15968 | @item @code{uw1 __MEXPDHW (uw1, const)} | |
15969 | @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} | |
15970 | @tab @code{MEXPDHW @var{a},#@var{b},@var{c}} | |
15971 | @item @code{uw1 __MHDSETH (uw1, const)} | |
15972 | @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} | |
15973 | @tab @code{MHDSETH @var{a},#@var{b},@var{c}} | |
15974 | @item @code{sw1 __MHDSETS (const)} | |
15975 | @tab @code{@var{b} = __MHDSETS (@var{a})} | |
15976 | @tab @code{MHDSETS #@var{a},@var{b}} | |
15977 | @item @code{uw1 __MHSETHIH (uw1, const)} | |
15978 | @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} | |
15979 | @tab @code{MHSETHIH #@var{a},@var{b}} | |
15980 | @item @code{sw1 __MHSETHIS (sw1, const)} | |
15981 | @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} | |
15982 | @tab @code{MHSETHIS #@var{a},@var{b}} | |
15983 | @item @code{uw1 __MHSETLOH (uw1, const)} | |
15984 | @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} | |
15985 | @tab @code{MHSETLOH #@var{a},@var{b}} | |
15986 | @item @code{sw1 __MHSETLOS (sw1, const)} | |
15987 | @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} | |
15988 | @tab @code{MHSETLOS #@var{a},@var{b}} | |
15989 | @item @code{uw1 __MHTOB (uw2)} | |
15990 | @tab @code{@var{b} = __MHTOB (@var{a})} | |
15991 | @tab @code{MHTOB @var{a},@var{b}} | |
15992 | @item @code{void __MMACHS (acc, sw1, sw1)} | |
15993 | @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} | |
15994 | @tab @code{MMACHS @var{a},@var{b},@var{c}} | |
15995 | @item @code{void __MMACHU (acc, uw1, uw1)} | |
15996 | @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} | |
15997 | @tab @code{MMACHU @var{a},@var{b},@var{c}} | |
15998 | @item @code{void __MMRDHS (acc, sw1, sw1)} | |
15999 | @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} | |
16000 | @tab @code{MMRDHS @var{a},@var{b},@var{c}} | |
16001 | @item @code{void __MMRDHU (acc, uw1, uw1)} | |
16002 | @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} | |
16003 | @tab @code{MMRDHU @var{a},@var{b},@var{c}} | |
16004 | @item @code{void __MMULHS (acc, sw1, sw1)} | |
16005 | @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} | |
16006 | @tab @code{MMULHS @var{a},@var{b},@var{c}} | |
16007 | @item @code{void __MMULHU (acc, uw1, uw1)} | |
16008 | @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} | |
16009 | @tab @code{MMULHU @var{a},@var{b},@var{c}} | |
16010 | @item @code{void __MMULXHS (acc, sw1, sw1)} | |
16011 | @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} | |
16012 | @tab @code{MMULXHS @var{a},@var{b},@var{c}} | |
16013 | @item @code{void __MMULXHU (acc, uw1, uw1)} | |
16014 | @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} | |
16015 | @tab @code{MMULXHU @var{a},@var{b},@var{c}} | |
16016 | @item @code{uw1 __MNOT (uw1)} | |
16017 | @tab @code{@var{b} = __MNOT (@var{a})} | |
16018 | @tab @code{MNOT @var{a},@var{b}} | |
16019 | @item @code{uw1 __MOR (uw1, uw1)} | |
16020 | @tab @code{@var{c} = __MOR (@var{a}, @var{b})} | |
16021 | @tab @code{MOR @var{a},@var{b},@var{c}} | |
16022 | @item @code{uw1 __MPACKH (uh, uh)} | |
16023 | @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} | |
16024 | @tab @code{MPACKH @var{a},@var{b},@var{c}} | |
16025 | @item @code{sw2 __MQADDHSS (sw2, sw2)} | |
16026 | @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} | |
16027 | @tab @code{MQADDHSS @var{a},@var{b},@var{c}} | |
16028 | @item @code{uw2 __MQADDHUS (uw2, uw2)} | |
16029 | @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} | |
16030 | @tab @code{MQADDHUS @var{a},@var{b},@var{c}} | |
16031 | @item @code{void __MQCPXIS (acc, sw2, sw2)} | |
16032 | @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} | |
16033 | @tab @code{MQCPXIS @var{a},@var{b},@var{c}} | |
16034 | @item @code{void __MQCPXIU (acc, uw2, uw2)} | |
16035 | @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} | |
16036 | @tab @code{MQCPXIU @var{a},@var{b},@var{c}} | |
16037 | @item @code{void __MQCPXRS (acc, sw2, sw2)} | |
16038 | @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} | |
16039 | @tab @code{MQCPXRS @var{a},@var{b},@var{c}} | |
16040 | @item @code{void __MQCPXRU (acc, uw2, uw2)} | |
16041 | @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} | |
16042 | @tab @code{MQCPXRU @var{a},@var{b},@var{c}} | |
16043 | @item @code{sw2 __MQLCLRHS (sw2, sw2)} | |
16044 | @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} | |
16045 | @tab @code{MQLCLRHS @var{a},@var{b},@var{c}} | |
16046 | @item @code{sw2 __MQLMTHS (sw2, sw2)} | |
16047 | @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} | |
16048 | @tab @code{MQLMTHS @var{a},@var{b},@var{c}} | |
16049 | @item @code{void __MQMACHS (acc, sw2, sw2)} | |
16050 | @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} | |
16051 | @tab @code{MQMACHS @var{a},@var{b},@var{c}} | |
16052 | @item @code{void __MQMACHU (acc, uw2, uw2)} | |
16053 | @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} | |
16054 | @tab @code{MQMACHU @var{a},@var{b},@var{c}} | |
16055 | @item @code{void __MQMACXHS (acc, sw2, sw2)} | |
16056 | @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} | |
16057 | @tab @code{MQMACXHS @var{a},@var{b},@var{c}} | |
16058 | @item @code{void __MQMULHS (acc, sw2, sw2)} | |
16059 | @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} | |
16060 | @tab @code{MQMULHS @var{a},@var{b},@var{c}} | |
16061 | @item @code{void __MQMULHU (acc, uw2, uw2)} | |
16062 | @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} | |
16063 | @tab @code{MQMULHU @var{a},@var{b},@var{c}} | |
16064 | @item @code{void __MQMULXHS (acc, sw2, sw2)} | |
16065 | @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} | |
16066 | @tab @code{MQMULXHS @var{a},@var{b},@var{c}} | |
16067 | @item @code{void __MQMULXHU (acc, uw2, uw2)} | |
16068 | @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} | |
16069 | @tab @code{MQMULXHU @var{a},@var{b},@var{c}} | |
16070 | @item @code{sw2 __MQSATHS (sw2, sw2)} | |
16071 | @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} | |
16072 | @tab @code{MQSATHS @var{a},@var{b},@var{c}} | |
16073 | @item @code{uw2 __MQSLLHI (uw2, int)} | |
16074 | @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} | |
16075 | @tab @code{MQSLLHI @var{a},@var{b},@var{c}} | |
16076 | @item @code{sw2 __MQSRAHI (sw2, int)} | |
16077 | @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} | |
16078 | @tab @code{MQSRAHI @var{a},@var{b},@var{c}} | |
16079 | @item @code{sw2 __MQSUBHSS (sw2, sw2)} | |
16080 | @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} | |
16081 | @tab @code{MQSUBHSS @var{a},@var{b},@var{c}} | |
16082 | @item @code{uw2 __MQSUBHUS (uw2, uw2)} | |
16083 | @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} | |
16084 | @tab @code{MQSUBHUS @var{a},@var{b},@var{c}} | |
16085 | @item @code{void __MQXMACHS (acc, sw2, sw2)} | |
16086 | @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} | |
16087 | @tab @code{MQXMACHS @var{a},@var{b},@var{c}} | |
16088 | @item @code{void __MQXMACXHS (acc, sw2, sw2)} | |
16089 | @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} | |
16090 | @tab @code{MQXMACXHS @var{a},@var{b},@var{c}} | |
16091 | @item @code{uw1 __MRDACC (acc)} | |
16092 | @tab @code{@var{b} = __MRDACC (@var{a})} | |
16093 | @tab @code{MRDACC @var{a},@var{b}} | |
16094 | @item @code{uw1 __MRDACCG (acc)} | |
16095 | @tab @code{@var{b} = __MRDACCG (@var{a})} | |
16096 | @tab @code{MRDACCG @var{a},@var{b}} | |
16097 | @item @code{uw1 __MROTLI (uw1, const)} | |
16098 | @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} | |
16099 | @tab @code{MROTLI @var{a},#@var{b},@var{c}} | |
16100 | @item @code{uw1 __MROTRI (uw1, const)} | |
16101 | @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} | |
16102 | @tab @code{MROTRI @var{a},#@var{b},@var{c}} | |
16103 | @item @code{sw1 __MSATHS (sw1, sw1)} | |
16104 | @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} | |
16105 | @tab @code{MSATHS @var{a},@var{b},@var{c}} | |
16106 | @item @code{uw1 __MSATHU (uw1, uw1)} | |
16107 | @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} | |
16108 | @tab @code{MSATHU @var{a},@var{b},@var{c}} | |
16109 | @item @code{uw1 __MSLLHI (uw1, const)} | |
16110 | @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} | |
16111 | @tab @code{MSLLHI @var{a},#@var{b},@var{c}} | |
16112 | @item @code{sw1 __MSRAHI (sw1, const)} | |
16113 | @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} | |
16114 | @tab @code{MSRAHI @var{a},#@var{b},@var{c}} | |
16115 | @item @code{uw1 __MSRLHI (uw1, const)} | |
16116 | @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} | |
16117 | @tab @code{MSRLHI @var{a},#@var{b},@var{c}} | |
16118 | @item @code{void __MSUBACCS (acc, acc)} | |
16119 | @tab @code{__MSUBACCS (@var{b}, @var{a})} | |
16120 | @tab @code{MSUBACCS @var{a},@var{b}} | |
16121 | @item @code{sw1 __MSUBHSS (sw1, sw1)} | |
16122 | @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} | |
16123 | @tab @code{MSUBHSS @var{a},@var{b},@var{c}} | |
16124 | @item @code{uw1 __MSUBHUS (uw1, uw1)} | |
16125 | @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} | |
16126 | @tab @code{MSUBHUS @var{a},@var{b},@var{c}} | |
16127 | @item @code{void __MTRAP (void)} | |
16128 | @tab @code{__MTRAP ()} | |
16129 | @tab @code{MTRAP} | |
16130 | @item @code{uw2 __MUNPACKH (uw1)} | |
16131 | @tab @code{@var{b} = __MUNPACKH (@var{a})} | |
16132 | @tab @code{MUNPACKH @var{a},@var{b}} | |
16133 | @item @code{uw1 __MWCUT (uw2, uw1)} | |
16134 | @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} | |
16135 | @tab @code{MWCUT @var{a},@var{b},@var{c}} | |
16136 | @item @code{void __MWTACC (acc, uw1)} | |
16137 | @tab @code{__MWTACC (@var{b}, @var{a})} | |
16138 | @tab @code{MWTACC @var{a},@var{b}} | |
16139 | @item @code{void __MWTACCG (acc, uw1)} | |
16140 | @tab @code{__MWTACCG (@var{b}, @var{a})} | |
16141 | @tab @code{MWTACCG @var{a},@var{b}} | |
16142 | @item @code{uw1 __MXOR (uw1, uw1)} | |
16143 | @tab @code{@var{c} = __MXOR (@var{a}, @var{b})} | |
16144 | @tab @code{MXOR @var{a},@var{b},@var{c}} | |
16145 | @end multitable | |
16146 | ||
16147 | @node Raw read/write Functions | |
16148 | @subsubsection Raw Read/Write Functions | |
16149 | ||
16150 | This sections describes built-in functions related to read and write | |
16151 | instructions to access memory. These functions generate | |
16152 | @code{membar} instructions to flush the I/O load and stores where | |
16153 | appropriate, as described in Fujitsu's manual described above. | |
16154 | ||
16155 | @table @code | |
16156 | ||
16157 | @item unsigned char __builtin_read8 (void *@var{data}) | |
16158 | @item unsigned short __builtin_read16 (void *@var{data}) | |
16159 | @item unsigned long __builtin_read32 (void *@var{data}) | |
16160 | @item unsigned long long __builtin_read64 (void *@var{data}) | |
16161 | ||
16162 | @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) | |
16163 | @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) | |
16164 | @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) | |
16165 | @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) | |
16166 | @end table | |
16167 | ||
16168 | @node Other Built-in Functions | |
16169 | @subsubsection Other Built-in Functions | |
16170 | ||
16171 | This section describes built-in functions that are not named after | |
16172 | a specific FR-V instruction. | |
16173 | ||
16174 | @table @code | |
16175 | @item sw2 __IACCreadll (iacc @var{reg}) | |
16176 | Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved | |
16177 | for future expansion and must be 0. | |
16178 | ||
16179 | @item sw1 __IACCreadl (iacc @var{reg}) | |
16180 | Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. | |
16181 | Other values of @var{reg} are rejected as invalid. | |
16182 | ||
16183 | @item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) | |
16184 | Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument | |
16185 | is reserved for future expansion and must be 0. | |
16186 | ||
16187 | @item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) | |
16188 | Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} | |
16189 | is 1. Other values of @var{reg} are rejected as invalid. | |
16190 | ||
16191 | @item void __data_prefetch0 (const void *@var{x}) | |
16192 | Use the @code{dcpl} instruction to load the contents of address @var{x} | |
16193 | into the data cache. | |
16194 | ||
16195 | @item void __data_prefetch (const void *@var{x}) | |
16196 | Use the @code{nldub} instruction to load the contents of address @var{x} | |
16197 | into the data cache. The instruction is issued in slot I1@. | |
16198 | @end table | |
16199 | ||
16200 | @node MIPS DSP Built-in Functions | |
16201 | @subsection MIPS DSP Built-in Functions | |
16202 | ||
16203 | The MIPS DSP Application-Specific Extension (ASE) includes new | |
16204 | instructions that are designed to improve the performance of DSP and | |
16205 | media applications. It provides instructions that operate on packed | |
16206 | 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. | |
16207 | ||
16208 | GCC supports MIPS DSP operations using both the generic | |
16209 | vector extensions (@pxref{Vector Extensions}) and a collection of | |
16210 | MIPS-specific built-in functions. Both kinds of support are | |
16211 | enabled by the @option{-mdsp} command-line option. | |
16212 | ||
16213 | Revision 2 of the ASE was introduced in the second half of 2006. | |
16214 | This revision adds extra instructions to the original ASE, but is | |
16215 | otherwise backwards-compatible with it. You can select revision 2 | |
16216 | using the command-line option @option{-mdspr2}; this option implies | |
16217 | @option{-mdsp}. | |
16218 | ||
16219 | The SCOUNT and POS bits of the DSP control register are global. The | |
16220 | WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and | |
16221 | POS bits. During optimization, the compiler does not delete these | |
16222 | instructions and it does not delete calls to functions containing | |
16223 | these instructions. | |
16224 | ||
16225 | At present, GCC only provides support for operations on 32-bit | |
16226 | vectors. The vector type associated with 8-bit integer data is | |
16227 | usually called @code{v4i8}, the vector type associated with Q7 | |
16228 | is usually called @code{v4q7}, the vector type associated with 16-bit | |
16229 | integer data is usually called @code{v2i16}, and the vector type | |
16230 | associated with Q15 is usually called @code{v2q15}. They can be | |
16231 | defined in C as follows: | |
16232 | ||
16233 | @smallexample | |
16234 | typedef signed char v4i8 __attribute__ ((vector_size(4))); | |
16235 | typedef signed char v4q7 __attribute__ ((vector_size(4))); | |
16236 | typedef short v2i16 __attribute__ ((vector_size(4))); | |
16237 | typedef short v2q15 __attribute__ ((vector_size(4))); | |
16238 | @end smallexample | |
16239 | ||
16240 | @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are | |
16241 | initialized in the same way as aggregates. For example: | |
16242 | ||
16243 | @smallexample | |
16244 | v4i8 a = @{1, 2, 3, 4@}; | |
16245 | v4i8 b; | |
16246 | b = (v4i8) @{5, 6, 7, 8@}; | |
16247 | ||
16248 | v2q15 c = @{0x0fcb, 0x3a75@}; | |
16249 | v2q15 d; | |
16250 | d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; | |
16251 | @end smallexample | |
16252 | ||
16253 | @emph{Note:} The CPU's endianness determines the order in which values | |
16254 | are packed. On little-endian targets, the first value is the least | |
16255 | significant and the last value is the most significant. The opposite | |
16256 | order applies to big-endian targets. For example, the code above | |
16257 | sets the lowest byte of @code{a} to @code{1} on little-endian targets | |
16258 | and @code{4} on big-endian targets. | |
16259 | ||
16260 | @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer | |
16261 | representation. As shown in this example, the integer representation | |
16262 | of a Q7 value can be obtained by multiplying the fractional value by | |
16263 | @code{0x1.0p7}. The equivalent for Q15 values is to multiply by | |
16264 | @code{0x1.0p15}. The equivalent for Q31 values is to multiply by | |
16265 | @code{0x1.0p31}. | |
16266 | ||
16267 | The table below lists the @code{v4i8} and @code{v2q15} operations for which | |
16268 | hardware support exists. @code{a} and @code{b} are @code{v4i8} values, | |
16269 | and @code{c} and @code{d} are @code{v2q15} values. | |
16270 | ||
16271 | @multitable @columnfractions .50 .50 | |
16272 | @headitem C code @tab MIPS instruction | |
16273 | @item @code{a + b} @tab @code{addu.qb} | |
16274 | @item @code{c + d} @tab @code{addq.ph} | |
16275 | @item @code{a - b} @tab @code{subu.qb} | |
16276 | @item @code{c - d} @tab @code{subq.ph} | |
16277 | @end multitable | |
16278 | ||
16279 | The table below lists the @code{v2i16} operation for which | |
16280 | hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are | |
16281 | @code{v2i16} values. | |
16282 | ||
16283 | @multitable @columnfractions .50 .50 | |
16284 | @headitem C code @tab MIPS instruction | |
16285 | @item @code{e * f} @tab @code{mul.ph} | |
16286 | @end multitable | |
16287 | ||
16288 | It is easier to describe the DSP built-in functions if we first define | |
16289 | the following types: | |
16290 | ||
16291 | @smallexample | |
16292 | typedef int q31; | |
16293 | typedef int i32; | |
16294 | typedef unsigned int ui32; | |
16295 | typedef long long a64; | |
16296 | @end smallexample | |
16297 | ||
16298 | @code{q31} and @code{i32} are actually the same as @code{int}, but we | |
16299 | use @code{q31} to indicate a Q31 fractional value and @code{i32} to | |
16300 | indicate a 32-bit integer value. Similarly, @code{a64} is the same as | |
16301 | @code{long long}, but we use @code{a64} to indicate values that are | |
16302 | placed in one of the four DSP accumulators (@code{$ac0}, | |
16303 | @code{$ac1}, @code{$ac2} or @code{$ac3}). | |
16304 | ||
16305 | Also, some built-in functions prefer or require immediate numbers as | |
16306 | parameters, because the corresponding DSP instructions accept both immediate | |
16307 | numbers and register operands, or accept immediate numbers only. The | |
16308 | immediate parameters are listed as follows. | |
16309 | ||
16310 | @smallexample | |
16311 | imm0_3: 0 to 3. | |
16312 | imm0_7: 0 to 7. | |
16313 | imm0_15: 0 to 15. | |
16314 | imm0_31: 0 to 31. | |
16315 | imm0_63: 0 to 63. | |
16316 | imm0_255: 0 to 255. | |
16317 | imm_n32_31: -32 to 31. | |
16318 | imm_n512_511: -512 to 511. | |
16319 | @end smallexample | |
16320 | ||
16321 | The following built-in functions map directly to a particular MIPS DSP | |
16322 | instruction. Please refer to the architecture specification | |
16323 | for details on what each instruction does. | |
16324 | ||
16325 | @smallexample | |
16326 | v2q15 __builtin_mips_addq_ph (v2q15, v2q15); | |
16327 | v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15); | |
16328 | q31 __builtin_mips_addq_s_w (q31, q31); | |
16329 | v4i8 __builtin_mips_addu_qb (v4i8, v4i8); | |
16330 | v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8); | |
16331 | v2q15 __builtin_mips_subq_ph (v2q15, v2q15); | |
16332 | v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15); | |
16333 | q31 __builtin_mips_subq_s_w (q31, q31); | |
16334 | v4i8 __builtin_mips_subu_qb (v4i8, v4i8); | |
16335 | v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8); | |
16336 | i32 __builtin_mips_addsc (i32, i32); | |
16337 | i32 __builtin_mips_addwc (i32, i32); | |
16338 | i32 __builtin_mips_modsub (i32, i32); | |
16339 | i32 __builtin_mips_raddu_w_qb (v4i8); | |
16340 | v2q15 __builtin_mips_absq_s_ph (v2q15); | |
16341 | q31 __builtin_mips_absq_s_w (q31); | |
16342 | v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15); | |
16343 | v2q15 __builtin_mips_precrq_ph_w (q31, q31); | |
16344 | v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31); | |
16345 | v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15); | |
16346 | q31 __builtin_mips_preceq_w_phl (v2q15); | |
16347 | q31 __builtin_mips_preceq_w_phr (v2q15); | |
16348 | v2q15 __builtin_mips_precequ_ph_qbl (v4i8); | |
16349 | v2q15 __builtin_mips_precequ_ph_qbr (v4i8); | |
16350 | v2q15 __builtin_mips_precequ_ph_qbla (v4i8); | |
16351 | v2q15 __builtin_mips_precequ_ph_qbra (v4i8); | |
16352 | v2q15 __builtin_mips_preceu_ph_qbl (v4i8); | |
16353 | v2q15 __builtin_mips_preceu_ph_qbr (v4i8); | |
16354 | v2q15 __builtin_mips_preceu_ph_qbla (v4i8); | |
16355 | v2q15 __builtin_mips_preceu_ph_qbra (v4i8); | |
16356 | v4i8 __builtin_mips_shll_qb (v4i8, imm0_7); | |
16357 | v4i8 __builtin_mips_shll_qb (v4i8, i32); | |
16358 | v2q15 __builtin_mips_shll_ph (v2q15, imm0_15); | |
16359 | v2q15 __builtin_mips_shll_ph (v2q15, i32); | |
16360 | v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15); | |
16361 | v2q15 __builtin_mips_shll_s_ph (v2q15, i32); | |
16362 | q31 __builtin_mips_shll_s_w (q31, imm0_31); | |
16363 | q31 __builtin_mips_shll_s_w (q31, i32); | |
16364 | v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7); | |
16365 | v4i8 __builtin_mips_shrl_qb (v4i8, i32); | |
16366 | v2q15 __builtin_mips_shra_ph (v2q15, imm0_15); | |
16367 | v2q15 __builtin_mips_shra_ph (v2q15, i32); | |
16368 | v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15); | |
16369 | v2q15 __builtin_mips_shra_r_ph (v2q15, i32); | |
16370 | q31 __builtin_mips_shra_r_w (q31, imm0_31); | |
16371 | q31 __builtin_mips_shra_r_w (q31, i32); | |
16372 | v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15); | |
16373 | v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15); | |
16374 | v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15); | |
16375 | q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15); | |
16376 | q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15); | |
16377 | a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8); | |
16378 | a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8); | |
16379 | a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8); | |
16380 | a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8); | |
16381 | a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15); | |
16382 | a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31); | |
16383 | a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15); | |
16384 | a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31); | |
16385 | a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15); | |
16386 | a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15); | |
16387 | a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15); | |
16388 | a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15); | |
16389 | a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15); | |
16390 | i32 __builtin_mips_bitrev (i32); | |
16391 | i32 __builtin_mips_insv (i32, i32); | |
16392 | v4i8 __builtin_mips_repl_qb (imm0_255); | |
16393 | v4i8 __builtin_mips_repl_qb (i32); | |
16394 | v2q15 __builtin_mips_repl_ph (imm_n512_511); | |
16395 | v2q15 __builtin_mips_repl_ph (i32); | |
16396 | void __builtin_mips_cmpu_eq_qb (v4i8, v4i8); | |
16397 | void __builtin_mips_cmpu_lt_qb (v4i8, v4i8); | |
16398 | void __builtin_mips_cmpu_le_qb (v4i8, v4i8); | |
16399 | i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8); | |
16400 | i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8); | |
16401 | i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8); | |
16402 | void __builtin_mips_cmp_eq_ph (v2q15, v2q15); | |
16403 | void __builtin_mips_cmp_lt_ph (v2q15, v2q15); | |
16404 | void __builtin_mips_cmp_le_ph (v2q15, v2q15); | |
16405 | v4i8 __builtin_mips_pick_qb (v4i8, v4i8); | |
16406 | v2q15 __builtin_mips_pick_ph (v2q15, v2q15); | |
16407 | v2q15 __builtin_mips_packrl_ph (v2q15, v2q15); | |
16408 | i32 __builtin_mips_extr_w (a64, imm0_31); | |
16409 | i32 __builtin_mips_extr_w (a64, i32); | |
16410 | i32 __builtin_mips_extr_r_w (a64, imm0_31); | |
16411 | i32 __builtin_mips_extr_s_h (a64, i32); | |
16412 | i32 __builtin_mips_extr_rs_w (a64, imm0_31); | |
16413 | i32 __builtin_mips_extr_rs_w (a64, i32); | |
16414 | i32 __builtin_mips_extr_s_h (a64, imm0_31); | |
16415 | i32 __builtin_mips_extr_r_w (a64, i32); | |
16416 | i32 __builtin_mips_extp (a64, imm0_31); | |
16417 | i32 __builtin_mips_extp (a64, i32); | |
16418 | i32 __builtin_mips_extpdp (a64, imm0_31); | |
16419 | i32 __builtin_mips_extpdp (a64, i32); | |
16420 | a64 __builtin_mips_shilo (a64, imm_n32_31); | |
16421 | a64 __builtin_mips_shilo (a64, i32); | |
16422 | a64 __builtin_mips_mthlip (a64, i32); | |
16423 | void __builtin_mips_wrdsp (i32, imm0_63); | |
16424 | i32 __builtin_mips_rddsp (imm0_63); | |
16425 | i32 __builtin_mips_lbux (void *, i32); | |
16426 | i32 __builtin_mips_lhx (void *, i32); | |
16427 | i32 __builtin_mips_lwx (void *, i32); | |
16428 | a64 __builtin_mips_ldx (void *, i32); /* MIPS64 only */ | |
16429 | i32 __builtin_mips_bposge32 (void); | |
16430 | a64 __builtin_mips_madd (a64, i32, i32); | |
16431 | a64 __builtin_mips_maddu (a64, ui32, ui32); | |
16432 | a64 __builtin_mips_msub (a64, i32, i32); | |
16433 | a64 __builtin_mips_msubu (a64, ui32, ui32); | |
16434 | a64 __builtin_mips_mult (i32, i32); | |
16435 | a64 __builtin_mips_multu (ui32, ui32); | |
16436 | @end smallexample | |
16437 | ||
16438 | The following built-in functions map directly to a particular MIPS DSP REV 2 | |
16439 | instruction. Please refer to the architecture specification | |
16440 | for details on what each instruction does. | |
16441 | ||
16442 | @smallexample | |
16443 | v4q7 __builtin_mips_absq_s_qb (v4q7); | |
16444 | v2i16 __builtin_mips_addu_ph (v2i16, v2i16); | |
16445 | v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); | |
16446 | v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); | |
16447 | v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); | |
16448 | i32 __builtin_mips_append (i32, i32, imm0_31); | |
16449 | i32 __builtin_mips_balign (i32, i32, imm0_3); | |
16450 | i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); | |
16451 | i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); | |
16452 | i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); | |
16453 | a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); | |
16454 | a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); | |
16455 | v2i16 __builtin_mips_mul_ph (v2i16, v2i16); | |
16456 | v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); | |
16457 | q31 __builtin_mips_mulq_rs_w (q31, q31); | |
16458 | v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); | |
16459 | q31 __builtin_mips_mulq_s_w (q31, q31); | |
16460 | a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); | |
16461 | v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); | |
16462 | v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); | |
16463 | v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); | |
16464 | i32 __builtin_mips_prepend (i32, i32, imm0_31); | |
16465 | v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); | |
16466 | v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); | |
16467 | v4i8 __builtin_mips_shra_qb (v4i8, i32); | |
16468 | v4i8 __builtin_mips_shra_r_qb (v4i8, i32); | |
16469 | v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); | |
16470 | v2i16 __builtin_mips_shrl_ph (v2i16, i32); | |
16471 | v2i16 __builtin_mips_subu_ph (v2i16, v2i16); | |
16472 | v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); | |
16473 | v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); | |
16474 | v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); | |
16475 | v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); | |
16476 | v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); | |
16477 | q31 __builtin_mips_addqh_w (q31, q31); | |
16478 | q31 __builtin_mips_addqh_r_w (q31, q31); | |
16479 | v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); | |
16480 | v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); | |
16481 | q31 __builtin_mips_subqh_w (q31, q31); | |
16482 | q31 __builtin_mips_subqh_r_w (q31, q31); | |
16483 | a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); | |
16484 | a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); | |
16485 | a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); | |
16486 | a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); | |
16487 | a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); | |
16488 | a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); | |
16489 | @end smallexample | |
16490 | ||
16491 | ||
16492 | @node MIPS Paired-Single Support | |
16493 | @subsection MIPS Paired-Single Support | |
16494 | ||
16495 | The MIPS64 architecture includes a number of instructions that | |
16496 | operate on pairs of single-precision floating-point values. | |
16497 | Each pair is packed into a 64-bit floating-point register, | |
16498 | with one element being designated the ``upper half'' and | |
16499 | the other being designated the ``lower half''. | |
16500 | ||
16501 | GCC supports paired-single operations using both the generic | |
16502 | vector extensions (@pxref{Vector Extensions}) and a collection of | |
16503 | MIPS-specific built-in functions. Both kinds of support are | |
16504 | enabled by the @option{-mpaired-single} command-line option. | |
16505 | ||
16506 | The vector type associated with paired-single values is usually | |
16507 | called @code{v2sf}. It can be defined in C as follows: | |
16508 | ||
16509 | @smallexample | |
16510 | typedef float v2sf __attribute__ ((vector_size (8))); | |
16511 | @end smallexample | |
16512 | ||
16513 | @code{v2sf} values are initialized in the same way as aggregates. | |
16514 | For example: | |
16515 | ||
16516 | @smallexample | |
16517 | v2sf a = @{1.5, 9.1@}; | |
16518 | v2sf b; | |
16519 | float e, f; | |
16520 | b = (v2sf) @{e, f@}; | |
16521 | @end smallexample | |
16522 | ||
16523 | @emph{Note:} The CPU's endianness determines which value is stored in | |
16524 | the upper half of a register and which value is stored in the lower half. | |
16525 | On little-endian targets, the first value is the lower one and the second | |
16526 | value is the upper one. The opposite order applies to big-endian targets. | |
16527 | For example, the code above sets the lower half of @code{a} to | |
16528 | @code{1.5} on little-endian targets and @code{9.1} on big-endian targets. | |
16529 | ||
16530 | @node MIPS Loongson Built-in Functions | |
16531 | @subsection MIPS Loongson Built-in Functions | |
16532 | ||
16533 | GCC provides intrinsics to access the SIMD instructions provided by the | |
16534 | ST Microelectronics Loongson-2E and -2F processors. These intrinsics, | |
16535 | available after inclusion of the @code{loongson.h} header file, | |
16536 | operate on the following 64-bit vector types: | |
16537 | ||
16538 | @itemize | |
16539 | @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; | |
16540 | @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; | |
16541 | @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; | |
16542 | @item @code{int8x8_t}, a vector of eight signed 8-bit integers; | |
16543 | @item @code{int16x4_t}, a vector of four signed 16-bit integers; | |
16544 | @item @code{int32x2_t}, a vector of two signed 32-bit integers. | |
16545 | @end itemize | |
16546 | ||
16547 | The intrinsics provided are listed below; each is named after the | |
16548 | machine instruction to which it corresponds, with suffixes added as | |
16549 | appropriate to distinguish intrinsics that expand to the same machine | |
16550 | instruction yet have different argument types. Refer to the architecture | |
16551 | documentation for a description of the functionality of each | |
16552 | instruction. | |
16553 | ||
16554 | @smallexample | |
16555 | int16x4_t packsswh (int32x2_t s, int32x2_t t); | |
16556 | int8x8_t packsshb (int16x4_t s, int16x4_t t); | |
16557 | uint8x8_t packushb (uint16x4_t s, uint16x4_t t); | |
16558 | uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); | |
16559 | uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); | |
16560 | uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); | |
16561 | int32x2_t paddw_s (int32x2_t s, int32x2_t t); | |
16562 | int16x4_t paddh_s (int16x4_t s, int16x4_t t); | |
16563 | int8x8_t paddb_s (int8x8_t s, int8x8_t t); | |
16564 | uint64_t paddd_u (uint64_t s, uint64_t t); | |
16565 | int64_t paddd_s (int64_t s, int64_t t); | |
16566 | int16x4_t paddsh (int16x4_t s, int16x4_t t); | |
16567 | int8x8_t paddsb (int8x8_t s, int8x8_t t); | |
16568 | uint16x4_t paddush (uint16x4_t s, uint16x4_t t); | |
16569 | uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); | |
16570 | uint64_t pandn_ud (uint64_t s, uint64_t t); | |
16571 | uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); | |
16572 | uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); | |
16573 | uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); | |
16574 | int64_t pandn_sd (int64_t s, int64_t t); | |
16575 | int32x2_t pandn_sw (int32x2_t s, int32x2_t t); | |
16576 | int16x4_t pandn_sh (int16x4_t s, int16x4_t t); | |
16577 | int8x8_t pandn_sb (int8x8_t s, int8x8_t t); | |
16578 | uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); | |
16579 | uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); | |
16580 | uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); | |
16581 | uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); | |
16582 | uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); | |
16583 | int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); | |
16584 | int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); | |
16585 | int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); | |
16586 | uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); | |
16587 | uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); | |
16588 | uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); | |
16589 | int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); | |
16590 | int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); | |
16591 | int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); | |
16592 | uint16x4_t pextrh_u (uint16x4_t s, int field); | |
16593 | int16x4_t pextrh_s (int16x4_t s, int field); | |
16594 | uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); | |
16595 | uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); | |
16596 | uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); | |
16597 | uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); | |
16598 | int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); | |
16599 | int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); | |
16600 | int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); | |
16601 | int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); | |
16602 | int32x2_t pmaddhw (int16x4_t s, int16x4_t t); | |
16603 | int16x4_t pmaxsh (int16x4_t s, int16x4_t t); | |
16604 | uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); | |
16605 | int16x4_t pminsh (int16x4_t s, int16x4_t t); | |
16606 | uint8x8_t pminub (uint8x8_t s, uint8x8_t t); | |
16607 | uint8x8_t pmovmskb_u (uint8x8_t s); | |
16608 | int8x8_t pmovmskb_s (int8x8_t s); | |
16609 | uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); | |
16610 | int16x4_t pmulhh (int16x4_t s, int16x4_t t); | |
16611 | int16x4_t pmullh (int16x4_t s, int16x4_t t); | |
16612 | int64_t pmuluw (uint32x2_t s, uint32x2_t t); | |
16613 | uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); | |
16614 | uint16x4_t biadd (uint8x8_t s); | |
16615 | uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); | |
16616 | uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); | |
16617 | int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); | |
16618 | uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); | |
16619 | int16x4_t psllh_s (int16x4_t s, uint8_t amount); | |
16620 | uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); | |
16621 | int32x2_t psllw_s (int32x2_t s, uint8_t amount); | |
16622 | uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); | |
16623 | int16x4_t psrlh_s (int16x4_t s, uint8_t amount); | |
16624 | uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); | |
16625 | int32x2_t psrlw_s (int32x2_t s, uint8_t amount); | |
16626 | uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); | |
16627 | int16x4_t psrah_s (int16x4_t s, uint8_t amount); | |
16628 | uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); | |
16629 | int32x2_t psraw_s (int32x2_t s, uint8_t amount); | |
16630 | uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); | |
16631 | uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); | |
16632 | uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); | |
16633 | int32x2_t psubw_s (int32x2_t s, int32x2_t t); | |
16634 | int16x4_t psubh_s (int16x4_t s, int16x4_t t); | |
16635 | int8x8_t psubb_s (int8x8_t s, int8x8_t t); | |
16636 | uint64_t psubd_u (uint64_t s, uint64_t t); | |
16637 | int64_t psubd_s (int64_t s, int64_t t); | |
16638 | int16x4_t psubsh (int16x4_t s, int16x4_t t); | |
16639 | int8x8_t psubsb (int8x8_t s, int8x8_t t); | |
16640 | uint16x4_t psubush (uint16x4_t s, uint16x4_t t); | |
16641 | uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); | |
16642 | uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); | |
16643 | uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); | |
16644 | uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); | |
16645 | int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); | |
16646 | int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); | |
16647 | int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); | |
16648 | uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); | |
16649 | uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); | |
16650 | uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); | |
16651 | int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); | |
16652 | int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); | |
16653 | int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); | |
16654 | @end smallexample | |
16655 | ||
16656 | @menu | |
16657 | * Paired-Single Arithmetic:: | |
16658 | * Paired-Single Built-in Functions:: | |
16659 | * MIPS-3D Built-in Functions:: | |
16660 | @end menu | |
16661 | ||
16662 | @node Paired-Single Arithmetic | |
16663 | @subsubsection Paired-Single Arithmetic | |
16664 | ||
16665 | The table below lists the @code{v2sf} operations for which hardware | |
16666 | support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} | |
16667 | values and @code{x} is an integral value. | |
16668 | ||
16669 | @multitable @columnfractions .50 .50 | |
16670 | @headitem C code @tab MIPS instruction | |
16671 | @item @code{a + b} @tab @code{add.ps} | |
16672 | @item @code{a - b} @tab @code{sub.ps} | |
16673 | @item @code{-a} @tab @code{neg.ps} | |
16674 | @item @code{a * b} @tab @code{mul.ps} | |
16675 | @item @code{a * b + c} @tab @code{madd.ps} | |
16676 | @item @code{a * b - c} @tab @code{msub.ps} | |
16677 | @item @code{-(a * b + c)} @tab @code{nmadd.ps} | |
16678 | @item @code{-(a * b - c)} @tab @code{nmsub.ps} | |
16679 | @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} | |
16680 | @end multitable | |
16681 | ||
16682 | Note that the multiply-accumulate instructions can be disabled | |
16683 | using the command-line option @code{-mno-fused-madd}. | |
16684 | ||
16685 | @node Paired-Single Built-in Functions | |
16686 | @subsubsection Paired-Single Built-in Functions | |
16687 | ||
16688 | The following paired-single functions map directly to a particular | |
16689 | MIPS instruction. Please refer to the architecture specification | |
16690 | for details on what each instruction does. | |
16691 | ||
16692 | @table @code | |
16693 | @item v2sf __builtin_mips_pll_ps (v2sf, v2sf) | |
16694 | Pair lower lower (@code{pll.ps}). | |
16695 | ||
16696 | @item v2sf __builtin_mips_pul_ps (v2sf, v2sf) | |
16697 | Pair upper lower (@code{pul.ps}). | |
16698 | ||
16699 | @item v2sf __builtin_mips_plu_ps (v2sf, v2sf) | |
16700 | Pair lower upper (@code{plu.ps}). | |
16701 | ||
16702 | @item v2sf __builtin_mips_puu_ps (v2sf, v2sf) | |
16703 | Pair upper upper (@code{puu.ps}). | |
16704 | ||
16705 | @item v2sf __builtin_mips_cvt_ps_s (float, float) | |
16706 | Convert pair to paired single (@code{cvt.ps.s}). | |
16707 | ||
16708 | @item float __builtin_mips_cvt_s_pl (v2sf) | |
16709 | Convert pair lower to single (@code{cvt.s.pl}). | |
16710 | ||
16711 | @item float __builtin_mips_cvt_s_pu (v2sf) | |
16712 | Convert pair upper to single (@code{cvt.s.pu}). | |
16713 | ||
16714 | @item v2sf __builtin_mips_abs_ps (v2sf) | |
16715 | Absolute value (@code{abs.ps}). | |
16716 | ||
16717 | @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) | |
16718 | Align variable (@code{alnv.ps}). | |
16719 | ||
16720 | @emph{Note:} The value of the third parameter must be 0 or 4 | |
16721 | modulo 8, otherwise the result is unpredictable. Please read the | |
16722 | instruction description for details. | |
16723 | @end table | |
16724 | ||
16725 | The following multi-instruction functions are also available. | |
16726 | In each case, @var{cond} can be any of the 16 floating-point conditions: | |
16727 | @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, | |
16728 | @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, | |
16729 | @code{lt}, @code{nge}, @code{le} or @code{ngt}. | |
16730 | ||
16731 | @table @code | |
16732 | @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
16733 | @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
16734 | Conditional move based on floating-point comparison (@code{c.@var{cond}.ps}, | |
16735 | @code{movt.ps}/@code{movf.ps}). | |
16736 | ||
16737 | The @code{movt} functions return the value @var{x} computed by: | |
16738 | ||
16739 | @smallexample | |
16740 | c.@var{cond}.ps @var{cc},@var{a},@var{b} | |
16741 | mov.ps @var{x},@var{c} | |
16742 | movt.ps @var{x},@var{d},@var{cc} | |
16743 | @end smallexample | |
16744 | ||
16745 | The @code{movf} functions are similar but use @code{movf.ps} instead | |
16746 | of @code{movt.ps}. | |
16747 | ||
16748 | @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
16749 | @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
16750 | Comparison of two paired-single values (@code{c.@var{cond}.ps}, | |
16751 | @code{bc1t}/@code{bc1f}). | |
16752 | ||
16753 | These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} | |
16754 | and return either the upper or lower half of the result. For example: | |
16755 | ||
16756 | @smallexample | |
16757 | v2sf a, b; | |
16758 | if (__builtin_mips_upper_c_eq_ps (a, b)) | |
16759 | upper_halves_are_equal (); | |
16760 | else | |
16761 | upper_halves_are_unequal (); | |
16762 | ||
16763 | if (__builtin_mips_lower_c_eq_ps (a, b)) | |
16764 | lower_halves_are_equal (); | |
16765 | else | |
16766 | lower_halves_are_unequal (); | |
16767 | @end smallexample | |
16768 | @end table | |
16769 | ||
16770 | @node MIPS-3D Built-in Functions | |
16771 | @subsubsection MIPS-3D Built-in Functions | |
16772 | ||
16773 | The MIPS-3D Application-Specific Extension (ASE) includes additional | |
16774 | paired-single instructions that are designed to improve the performance | |
16775 | of 3D graphics operations. Support for these instructions is controlled | |
16776 | by the @option{-mips3d} command-line option. | |
16777 | ||
16778 | The functions listed below map directly to a particular MIPS-3D | |
16779 | instruction. Please refer to the architecture specification for | |
16780 | more details on what each instruction does. | |
16781 | ||
16782 | @table @code | |
16783 | @item v2sf __builtin_mips_addr_ps (v2sf, v2sf) | |
16784 | Reduction add (@code{addr.ps}). | |
16785 | ||
16786 | @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) | |
16787 | Reduction multiply (@code{mulr.ps}). | |
16788 | ||
16789 | @item v2sf __builtin_mips_cvt_pw_ps (v2sf) | |
16790 | Convert paired single to paired word (@code{cvt.pw.ps}). | |
16791 | ||
16792 | @item v2sf __builtin_mips_cvt_ps_pw (v2sf) | |
16793 | Convert paired word to paired single (@code{cvt.ps.pw}). | |
16794 | ||
16795 | @item float __builtin_mips_recip1_s (float) | |
16796 | @itemx double __builtin_mips_recip1_d (double) | |
16797 | @itemx v2sf __builtin_mips_recip1_ps (v2sf) | |
16798 | Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). | |
16799 | ||
16800 | @item float __builtin_mips_recip2_s (float, float) | |
16801 | @itemx double __builtin_mips_recip2_d (double, double) | |
16802 | @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) | |
16803 | Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). | |
16804 | ||
16805 | @item float __builtin_mips_rsqrt1_s (float) | |
16806 | @itemx double __builtin_mips_rsqrt1_d (double) | |
16807 | @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) | |
16808 | Reduced-precision reciprocal square root (sequence step 1) | |
16809 | (@code{rsqrt1.@var{fmt}}). | |
16810 | ||
16811 | @item float __builtin_mips_rsqrt2_s (float, float) | |
16812 | @itemx double __builtin_mips_rsqrt2_d (double, double) | |
16813 | @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) | |
16814 | Reduced-precision reciprocal square root (sequence step 2) | |
16815 | (@code{rsqrt2.@var{fmt}}). | |
16816 | @end table | |
16817 | ||
16818 | The following multi-instruction functions are also available. | |
16819 | In each case, @var{cond} can be any of the 16 floating-point conditions: | |
16820 | @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, | |
16821 | @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, | |
16822 | @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. | |
16823 | ||
16824 | @table @code | |
16825 | @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) | |
16826 | @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) | |
16827 | Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, | |
16828 | @code{bc1t}/@code{bc1f}). | |
16829 | ||
16830 | These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} | |
16831 | or @code{cabs.@var{cond}.d} and return the result as a boolean value. | |
16832 | For example: | |
16833 | ||
16834 | @smallexample | |
16835 | float a, b; | |
16836 | if (__builtin_mips_cabs_eq_s (a, b)) | |
16837 | true (); | |
16838 | else | |
16839 | false (); | |
16840 | @end smallexample | |
16841 | ||
16842 | @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
16843 | @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
16844 | Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, | |
16845 | @code{bc1t}/@code{bc1f}). | |
16846 | ||
16847 | These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} | |
16848 | and return either the upper or lower half of the result. For example: | |
16849 | ||
16850 | @smallexample | |
16851 | v2sf a, b; | |
16852 | if (__builtin_mips_upper_cabs_eq_ps (a, b)) | |
16853 | upper_halves_are_equal (); | |
16854 | else | |
16855 | upper_halves_are_unequal (); | |
16856 | ||
16857 | if (__builtin_mips_lower_cabs_eq_ps (a, b)) | |
16858 | lower_halves_are_equal (); | |
16859 | else | |
16860 | lower_halves_are_unequal (); | |
16861 | @end smallexample | |
16862 | ||
16863 | @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
16864 | @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
16865 | Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, | |
16866 | @code{movt.ps}/@code{movf.ps}). | |
16867 | ||
16868 | The @code{movt} functions return the value @var{x} computed by: | |
16869 | ||
16870 | @smallexample | |
16871 | cabs.@var{cond}.ps @var{cc},@var{a},@var{b} | |
16872 | mov.ps @var{x},@var{c} | |
16873 | movt.ps @var{x},@var{d},@var{cc} | |
16874 | @end smallexample | |
16875 | ||
16876 | The @code{movf} functions are similar but use @code{movf.ps} instead | |
16877 | of @code{movt.ps}. | |
16878 | ||
16879 | @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
16880 | @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
16881 | @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
16882 | @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
16883 | Comparison of two paired-single values | |
16884 | (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, | |
16885 | @code{bc1any2t}/@code{bc1any2f}). | |
16886 | ||
16887 | These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} | |
16888 | or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either | |
16889 | result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}. | |
16890 | For example: | |
16891 | ||
16892 | @smallexample | |
16893 | v2sf a, b; | |
16894 | if (__builtin_mips_any_c_eq_ps (a, b)) | |
16895 | one_is_true (); | |
16896 | else | |
16897 | both_are_false (); | |
16898 | ||
16899 | if (__builtin_mips_all_c_eq_ps (a, b)) | |
16900 | both_are_true (); | |
16901 | else | |
16902 | one_is_false (); | |
16903 | @end smallexample | |
16904 | ||
16905 | @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
16906 | @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
16907 | @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
16908 | @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
16909 | Comparison of four paired-single values | |
16910 | (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, | |
16911 | @code{bc1any4t}/@code{bc1any4f}). | |
16912 | ||
16913 | These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} | |
16914 | to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. | |
16915 | The @code{any} forms return @code{true} if any of the four results are @code{true} | |
16916 | and the @code{all} forms return @code{true} if all four results are @code{true}. | |
16917 | For example: | |
16918 | ||
16919 | @smallexample | |
16920 | v2sf a, b, c, d; | |
16921 | if (__builtin_mips_any_c_eq_4s (a, b, c, d)) | |
16922 | some_are_true (); | |
16923 | else | |
16924 | all_are_false (); | |
16925 | ||
16926 | if (__builtin_mips_all_c_eq_4s (a, b, c, d)) | |
16927 | all_are_true (); | |
16928 | else | |
16929 | some_are_false (); | |
16930 | @end smallexample | |
16931 | @end table | |
16932 | ||
16933 | @node MIPS SIMD Architecture (MSA) Support | |
16934 | @subsection MIPS SIMD Architecture (MSA) Support | |
16935 | ||
16936 | @menu | |
16937 | * MIPS SIMD Architecture Built-in Functions:: | |
16938 | @end menu | |
16939 | ||
16940 | GCC provides intrinsics to access the SIMD instructions provided by the | |
16941 | MSA MIPS SIMD Architecture. The interface is made available by including | |
16942 | @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}. | |
16943 | For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic, | |
16944 | @code{__msa_*}. | |
16945 | ||
16946 | MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and | |
16947 | 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point | |
16948 | data elements. The following vectors typedefs are included in @code{msa.h}: | |
16949 | @itemize | |
16950 | @item @code{v16i8}, a vector of sixteen signed 8-bit integers; | |
16951 | @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers; | |
16952 | @item @code{v8i16}, a vector of eight signed 16-bit integers; | |
16953 | @item @code{v8u16}, a vector of eight unsigned 16-bit integers; | |
16954 | @item @code{v4i32}, a vector of four signed 32-bit integers; | |
16955 | @item @code{v4u32}, a vector of four unsigned 32-bit integers; | |
16956 | @item @code{v2i64}, a vector of two signed 64-bit integers; | |
16957 | @item @code{v2u64}, a vector of two unsigned 64-bit integers; | |
16958 | @item @code{v4f32}, a vector of four 32-bit floats; | |
16959 | @item @code{v2f64}, a vector of two 64-bit doubles. | |
16960 | @end itemize | |
16961 | ||
16962 | Instructions and corresponding built-ins may have additional restrictions and/or | |
16963 | input/output values manipulated: | |
16964 | @itemize | |
16965 | @item @code{imm0_1}, an integer literal in range 0 to 1; | |
16966 | @item @code{imm0_3}, an integer literal in range 0 to 3; | |
16967 | @item @code{imm0_7}, an integer literal in range 0 to 7; | |
16968 | @item @code{imm0_15}, an integer literal in range 0 to 15; | |
16969 | @item @code{imm0_31}, an integer literal in range 0 to 31; | |
16970 | @item @code{imm0_63}, an integer literal in range 0 to 63; | |
16971 | @item @code{imm0_255}, an integer literal in range 0 to 255; | |
16972 | @item @code{imm_n16_15}, an integer literal in range -16 to 15; | |
16973 | @item @code{imm_n512_511}, an integer literal in range -512 to 511; | |
16974 | @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left | |
16975 | shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022; | |
16976 | @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left | |
16977 | shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044; | |
16978 | @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left | |
16979 | shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088; | |
16980 | @item @code{imm1_4}, an integer literal in range 1 to 4; | |
16981 | @item @code{i32, i64, u32, u64, f32, f64}, defined as follows: | |
16982 | @end itemize | |
16983 | ||
16984 | @smallexample | |
16985 | @{ | |
16986 | typedef int i32; | |
16987 | #if __LONG_MAX__ == __LONG_LONG_MAX__ | |
16988 | typedef long i64; | |
16989 | #else | |
16990 | typedef long long i64; | |
16991 | #endif | |
16992 | ||
16993 | typedef unsigned int u32; | |
16994 | #if __LONG_MAX__ == __LONG_LONG_MAX__ | |
16995 | typedef unsigned long u64; | |
16996 | #else | |
16997 | typedef unsigned long long u64; | |
16998 | #endif | |
16999 | ||
17000 | typedef double f64; | |
17001 | typedef float f32; | |
17002 | @} | |
17003 | @end smallexample | |
17004 | ||
17005 | @node MIPS SIMD Architecture Built-in Functions | |
17006 | @subsubsection MIPS SIMD Architecture Built-in Functions | |
17007 | ||
17008 | The intrinsics provided are listed below; each is named after the | |
17009 | machine instruction. | |
17010 | ||
17011 | @smallexample | |
17012 | v16i8 __builtin_msa_add_a_b (v16i8, v16i8); | |
17013 | v8i16 __builtin_msa_add_a_h (v8i16, v8i16); | |
17014 | v4i32 __builtin_msa_add_a_w (v4i32, v4i32); | |
17015 | v2i64 __builtin_msa_add_a_d (v2i64, v2i64); | |
17016 | ||
17017 | v16i8 __builtin_msa_adds_a_b (v16i8, v16i8); | |
17018 | v8i16 __builtin_msa_adds_a_h (v8i16, v8i16); | |
17019 | v4i32 __builtin_msa_adds_a_w (v4i32, v4i32); | |
17020 | v2i64 __builtin_msa_adds_a_d (v2i64, v2i64); | |
17021 | ||
17022 | v16i8 __builtin_msa_adds_s_b (v16i8, v16i8); | |
17023 | v8i16 __builtin_msa_adds_s_h (v8i16, v8i16); | |
17024 | v4i32 __builtin_msa_adds_s_w (v4i32, v4i32); | |
17025 | v2i64 __builtin_msa_adds_s_d (v2i64, v2i64); | |
17026 | ||
17027 | v16u8 __builtin_msa_adds_u_b (v16u8, v16u8); | |
17028 | v8u16 __builtin_msa_adds_u_h (v8u16, v8u16); | |
17029 | v4u32 __builtin_msa_adds_u_w (v4u32, v4u32); | |
17030 | v2u64 __builtin_msa_adds_u_d (v2u64, v2u64); | |
17031 | ||
17032 | v16i8 __builtin_msa_addv_b (v16i8, v16i8); | |
17033 | v8i16 __builtin_msa_addv_h (v8i16, v8i16); | |
17034 | v4i32 __builtin_msa_addv_w (v4i32, v4i32); | |
17035 | v2i64 __builtin_msa_addv_d (v2i64, v2i64); | |
17036 | ||
17037 | v16i8 __builtin_msa_addvi_b (v16i8, imm0_31); | |
17038 | v8i16 __builtin_msa_addvi_h (v8i16, imm0_31); | |
17039 | v4i32 __builtin_msa_addvi_w (v4i32, imm0_31); | |
17040 | v2i64 __builtin_msa_addvi_d (v2i64, imm0_31); | |
17041 | ||
17042 | v16u8 __builtin_msa_and_v (v16u8, v16u8); | |
17043 | ||
17044 | v16u8 __builtin_msa_andi_b (v16u8, imm0_255); | |
17045 | ||
17046 | v16i8 __builtin_msa_asub_s_b (v16i8, v16i8); | |
17047 | v8i16 __builtin_msa_asub_s_h (v8i16, v8i16); | |
17048 | v4i32 __builtin_msa_asub_s_w (v4i32, v4i32); | |
17049 | v2i64 __builtin_msa_asub_s_d (v2i64, v2i64); | |
17050 | ||
17051 | v16u8 __builtin_msa_asub_u_b (v16u8, v16u8); | |
17052 | v8u16 __builtin_msa_asub_u_h (v8u16, v8u16); | |
17053 | v4u32 __builtin_msa_asub_u_w (v4u32, v4u32); | |
17054 | v2u64 __builtin_msa_asub_u_d (v2u64, v2u64); | |
17055 | ||
17056 | v16i8 __builtin_msa_ave_s_b (v16i8, v16i8); | |
17057 | v8i16 __builtin_msa_ave_s_h (v8i16, v8i16); | |
17058 | v4i32 __builtin_msa_ave_s_w (v4i32, v4i32); | |
17059 | v2i64 __builtin_msa_ave_s_d (v2i64, v2i64); | |
17060 | ||
17061 | v16u8 __builtin_msa_ave_u_b (v16u8, v16u8); | |
17062 | v8u16 __builtin_msa_ave_u_h (v8u16, v8u16); | |
17063 | v4u32 __builtin_msa_ave_u_w (v4u32, v4u32); | |
17064 | v2u64 __builtin_msa_ave_u_d (v2u64, v2u64); | |
17065 | ||
17066 | v16i8 __builtin_msa_aver_s_b (v16i8, v16i8); | |
17067 | v8i16 __builtin_msa_aver_s_h (v8i16, v8i16); | |
17068 | v4i32 __builtin_msa_aver_s_w (v4i32, v4i32); | |
17069 | v2i64 __builtin_msa_aver_s_d (v2i64, v2i64); | |
17070 | ||
17071 | v16u8 __builtin_msa_aver_u_b (v16u8, v16u8); | |
17072 | v8u16 __builtin_msa_aver_u_h (v8u16, v8u16); | |
17073 | v4u32 __builtin_msa_aver_u_w (v4u32, v4u32); | |
17074 | v2u64 __builtin_msa_aver_u_d (v2u64, v2u64); | |
17075 | ||
17076 | v16u8 __builtin_msa_bclr_b (v16u8, v16u8); | |
17077 | v8u16 __builtin_msa_bclr_h (v8u16, v8u16); | |
17078 | v4u32 __builtin_msa_bclr_w (v4u32, v4u32); | |
17079 | v2u64 __builtin_msa_bclr_d (v2u64, v2u64); | |
17080 | ||
17081 | v16u8 __builtin_msa_bclri_b (v16u8, imm0_7); | |
17082 | v8u16 __builtin_msa_bclri_h (v8u16, imm0_15); | |
17083 | v4u32 __builtin_msa_bclri_w (v4u32, imm0_31); | |
17084 | v2u64 __builtin_msa_bclri_d (v2u64, imm0_63); | |
17085 | ||
17086 | v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8); | |
17087 | v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16); | |
17088 | v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32); | |
17089 | v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64); | |
17090 | ||
17091 | v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7); | |
17092 | v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15); | |
17093 | v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31); | |
17094 | v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63); | |
17095 | ||
17096 | v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8); | |
17097 | v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16); | |
17098 | v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32); | |
17099 | v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64); | |
17100 | ||
17101 | v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7); | |
17102 | v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15); | |
17103 | v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31); | |
17104 | v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63); | |
17105 | ||
17106 | v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8); | |
17107 | ||
17108 | v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255); | |
17109 | ||
17110 | v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8); | |
17111 | ||
17112 | v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255); | |
17113 | ||
17114 | v16u8 __builtin_msa_bneg_b (v16u8, v16u8); | |
17115 | v8u16 __builtin_msa_bneg_h (v8u16, v8u16); | |
17116 | v4u32 __builtin_msa_bneg_w (v4u32, v4u32); | |
17117 | v2u64 __builtin_msa_bneg_d (v2u64, v2u64); | |
17118 | ||
17119 | v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7); | |
17120 | v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15); | |
17121 | v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31); | |
17122 | v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63); | |
17123 | ||
17124 | i32 __builtin_msa_bnz_b (v16u8); | |
17125 | i32 __builtin_msa_bnz_h (v8u16); | |
17126 | i32 __builtin_msa_bnz_w (v4u32); | |
17127 | i32 __builtin_msa_bnz_d (v2u64); | |
17128 | ||
17129 | i32 __builtin_msa_bnz_v (v16u8); | |
17130 | ||
17131 | v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8); | |
17132 | ||
17133 | v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255); | |
17134 | ||
17135 | v16u8 __builtin_msa_bset_b (v16u8, v16u8); | |
17136 | v8u16 __builtin_msa_bset_h (v8u16, v8u16); | |
17137 | v4u32 __builtin_msa_bset_w (v4u32, v4u32); | |
17138 | v2u64 __builtin_msa_bset_d (v2u64, v2u64); | |
17139 | ||
17140 | v16u8 __builtin_msa_bseti_b (v16u8, imm0_7); | |
17141 | v8u16 __builtin_msa_bseti_h (v8u16, imm0_15); | |
17142 | v4u32 __builtin_msa_bseti_w (v4u32, imm0_31); | |
17143 | v2u64 __builtin_msa_bseti_d (v2u64, imm0_63); | |
17144 | ||
17145 | i32 __builtin_msa_bz_b (v16u8); | |
17146 | i32 __builtin_msa_bz_h (v8u16); | |
17147 | i32 __builtin_msa_bz_w (v4u32); | |
17148 | i32 __builtin_msa_bz_d (v2u64); | |
17149 | ||
17150 | i32 __builtin_msa_bz_v (v16u8); | |
17151 | ||
17152 | v16i8 __builtin_msa_ceq_b (v16i8, v16i8); | |
17153 | v8i16 __builtin_msa_ceq_h (v8i16, v8i16); | |
17154 | v4i32 __builtin_msa_ceq_w (v4i32, v4i32); | |
17155 | v2i64 __builtin_msa_ceq_d (v2i64, v2i64); | |
17156 | ||
17157 | v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15); | |
17158 | v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15); | |
17159 | v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15); | |
17160 | v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15); | |
17161 | ||
17162 | i32 __builtin_msa_cfcmsa (imm0_31); | |
17163 | ||
17164 | v16i8 __builtin_msa_cle_s_b (v16i8, v16i8); | |
17165 | v8i16 __builtin_msa_cle_s_h (v8i16, v8i16); | |
17166 | v4i32 __builtin_msa_cle_s_w (v4i32, v4i32); | |
17167 | v2i64 __builtin_msa_cle_s_d (v2i64, v2i64); | |
17168 | ||
17169 | v16i8 __builtin_msa_cle_u_b (v16u8, v16u8); | |
17170 | v8i16 __builtin_msa_cle_u_h (v8u16, v8u16); | |
17171 | v4i32 __builtin_msa_cle_u_w (v4u32, v4u32); | |
17172 | v2i64 __builtin_msa_cle_u_d (v2u64, v2u64); | |
17173 | ||
17174 | v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15); | |
17175 | v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15); | |
17176 | v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15); | |
17177 | v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15); | |
17178 | ||
17179 | v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31); | |
17180 | v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31); | |
17181 | v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31); | |
17182 | v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31); | |
17183 | ||
17184 | v16i8 __builtin_msa_clt_s_b (v16i8, v16i8); | |
17185 | v8i16 __builtin_msa_clt_s_h (v8i16, v8i16); | |
17186 | v4i32 __builtin_msa_clt_s_w (v4i32, v4i32); | |
17187 | v2i64 __builtin_msa_clt_s_d (v2i64, v2i64); | |
17188 | ||
17189 | v16i8 __builtin_msa_clt_u_b (v16u8, v16u8); | |
17190 | v8i16 __builtin_msa_clt_u_h (v8u16, v8u16); | |
17191 | v4i32 __builtin_msa_clt_u_w (v4u32, v4u32); | |
17192 | v2i64 __builtin_msa_clt_u_d (v2u64, v2u64); | |
17193 | ||
17194 | v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15); | |
17195 | v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15); | |
17196 | v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15); | |
17197 | v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15); | |
17198 | ||
17199 | v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31); | |
17200 | v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31); | |
17201 | v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31); | |
17202 | v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31); | |
17203 | ||
17204 | i32 __builtin_msa_copy_s_b (v16i8, imm0_15); | |
17205 | i32 __builtin_msa_copy_s_h (v8i16, imm0_7); | |
17206 | i32 __builtin_msa_copy_s_w (v4i32, imm0_3); | |
17207 | i64 __builtin_msa_copy_s_d (v2i64, imm0_1); | |
17208 | ||
17209 | u32 __builtin_msa_copy_u_b (v16i8, imm0_15); | |
17210 | u32 __builtin_msa_copy_u_h (v8i16, imm0_7); | |
17211 | u32 __builtin_msa_copy_u_w (v4i32, imm0_3); | |
17212 | u64 __builtin_msa_copy_u_d (v2i64, imm0_1); | |
17213 | ||
17214 | void __builtin_msa_ctcmsa (imm0_31, i32); | |
17215 | ||
17216 | v16i8 __builtin_msa_div_s_b (v16i8, v16i8); | |
17217 | v8i16 __builtin_msa_div_s_h (v8i16, v8i16); | |
17218 | v4i32 __builtin_msa_div_s_w (v4i32, v4i32); | |
17219 | v2i64 __builtin_msa_div_s_d (v2i64, v2i64); | |
17220 | ||
17221 | v16u8 __builtin_msa_div_u_b (v16u8, v16u8); | |
17222 | v8u16 __builtin_msa_div_u_h (v8u16, v8u16); | |
17223 | v4u32 __builtin_msa_div_u_w (v4u32, v4u32); | |
17224 | v2u64 __builtin_msa_div_u_d (v2u64, v2u64); | |
17225 | ||
17226 | v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8); | |
17227 | v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16); | |
17228 | v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32); | |
17229 | ||
17230 | v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8); | |
17231 | v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16); | |
17232 | v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32); | |
17233 | ||
17234 | v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8); | |
17235 | v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16); | |
17236 | v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32); | |
17237 | ||
17238 | v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8); | |
17239 | v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16); | |
17240 | v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32); | |
17241 | ||
17242 | v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8); | |
17243 | v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16); | |
17244 | v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32); | |
17245 | ||
17246 | v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8); | |
17247 | v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16); | |
17248 | v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32); | |
17249 | ||
17250 | v4f32 __builtin_msa_fadd_w (v4f32, v4f32); | |
17251 | v2f64 __builtin_msa_fadd_d (v2f64, v2f64); | |
17252 | ||
17253 | v4i32 __builtin_msa_fcaf_w (v4f32, v4f32); | |
17254 | v2i64 __builtin_msa_fcaf_d (v2f64, v2f64); | |
17255 | ||
17256 | v4i32 __builtin_msa_fceq_w (v4f32, v4f32); | |
17257 | v2i64 __builtin_msa_fceq_d (v2f64, v2f64); | |
17258 | ||
17259 | v4i32 __builtin_msa_fclass_w (v4f32); | |
17260 | v2i64 __builtin_msa_fclass_d (v2f64); | |
17261 | ||
17262 | v4i32 __builtin_msa_fcle_w (v4f32, v4f32); | |
17263 | v2i64 __builtin_msa_fcle_d (v2f64, v2f64); | |
17264 | ||
17265 | v4i32 __builtin_msa_fclt_w (v4f32, v4f32); | |
17266 | v2i64 __builtin_msa_fclt_d (v2f64, v2f64); | |
17267 | ||
17268 | v4i32 __builtin_msa_fcne_w (v4f32, v4f32); | |
17269 | v2i64 __builtin_msa_fcne_d (v2f64, v2f64); | |
17270 | ||
17271 | v4i32 __builtin_msa_fcor_w (v4f32, v4f32); | |
17272 | v2i64 __builtin_msa_fcor_d (v2f64, v2f64); | |
17273 | ||
17274 | v4i32 __builtin_msa_fcueq_w (v4f32, v4f32); | |
17275 | v2i64 __builtin_msa_fcueq_d (v2f64, v2f64); | |
17276 | ||
17277 | v4i32 __builtin_msa_fcule_w (v4f32, v4f32); | |
17278 | v2i64 __builtin_msa_fcule_d (v2f64, v2f64); | |
17279 | ||
17280 | v4i32 __builtin_msa_fcult_w (v4f32, v4f32); | |
17281 | v2i64 __builtin_msa_fcult_d (v2f64, v2f64); | |
17282 | ||
17283 | v4i32 __builtin_msa_fcun_w (v4f32, v4f32); | |
17284 | v2i64 __builtin_msa_fcun_d (v2f64, v2f64); | |
17285 | ||
17286 | v4i32 __builtin_msa_fcune_w (v4f32, v4f32); | |
17287 | v2i64 __builtin_msa_fcune_d (v2f64, v2f64); | |
17288 | ||
17289 | v4f32 __builtin_msa_fdiv_w (v4f32, v4f32); | |
17290 | v2f64 __builtin_msa_fdiv_d (v2f64, v2f64); | |
17291 | ||
17292 | v8i16 __builtin_msa_fexdo_h (v4f32, v4f32); | |
17293 | v4f32 __builtin_msa_fexdo_w (v2f64, v2f64); | |
17294 | ||
17295 | v4f32 __builtin_msa_fexp2_w (v4f32, v4i32); | |
17296 | v2f64 __builtin_msa_fexp2_d (v2f64, v2i64); | |
17297 | ||
17298 | v4f32 __builtin_msa_fexupl_w (v8i16); | |
17299 | v2f64 __builtin_msa_fexupl_d (v4f32); | |
17300 | ||
17301 | v4f32 __builtin_msa_fexupr_w (v8i16); | |
17302 | v2f64 __builtin_msa_fexupr_d (v4f32); | |
17303 | ||
17304 | v4f32 __builtin_msa_ffint_s_w (v4i32); | |
17305 | v2f64 __builtin_msa_ffint_s_d (v2i64); | |
17306 | ||
17307 | v4f32 __builtin_msa_ffint_u_w (v4u32); | |
17308 | v2f64 __builtin_msa_ffint_u_d (v2u64); | |
17309 | ||
17310 | v4f32 __builtin_msa_ffql_w (v8i16); | |
17311 | v2f64 __builtin_msa_ffql_d (v4i32); | |
17312 | ||
17313 | v4f32 __builtin_msa_ffqr_w (v8i16); | |
17314 | v2f64 __builtin_msa_ffqr_d (v4i32); | |
17315 | ||
17316 | v16i8 __builtin_msa_fill_b (i32); | |
17317 | v8i16 __builtin_msa_fill_h (i32); | |
17318 | v4i32 __builtin_msa_fill_w (i32); | |
17319 | v2i64 __builtin_msa_fill_d (i64); | |
17320 | ||
17321 | v4f32 __builtin_msa_flog2_w (v4f32); | |
17322 | v2f64 __builtin_msa_flog2_d (v2f64); | |
17323 | ||
17324 | v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32); | |
17325 | v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64); | |
17326 | ||
17327 | v4f32 __builtin_msa_fmax_w (v4f32, v4f32); | |
17328 | v2f64 __builtin_msa_fmax_d (v2f64, v2f64); | |
17329 | ||
17330 | v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32); | |
17331 | v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64); | |
17332 | ||
17333 | v4f32 __builtin_msa_fmin_w (v4f32, v4f32); | |
17334 | v2f64 __builtin_msa_fmin_d (v2f64, v2f64); | |
17335 | ||
17336 | v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32); | |
17337 | v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64); | |
17338 | ||
17339 | v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32); | |
17340 | v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64); | |
17341 | ||
17342 | v4f32 __builtin_msa_fmul_w (v4f32, v4f32); | |
17343 | v2f64 __builtin_msa_fmul_d (v2f64, v2f64); | |
17344 | ||
17345 | v4f32 __builtin_msa_frint_w (v4f32); | |
17346 | v2f64 __builtin_msa_frint_d (v2f64); | |
17347 | ||
17348 | v4f32 __builtin_msa_frcp_w (v4f32); | |
17349 | v2f64 __builtin_msa_frcp_d (v2f64); | |
17350 | ||
17351 | v4f32 __builtin_msa_frsqrt_w (v4f32); | |
17352 | v2f64 __builtin_msa_frsqrt_d (v2f64); | |
17353 | ||
17354 | v4i32 __builtin_msa_fsaf_w (v4f32, v4f32); | |
17355 | v2i64 __builtin_msa_fsaf_d (v2f64, v2f64); | |
17356 | ||
17357 | v4i32 __builtin_msa_fseq_w (v4f32, v4f32); | |
17358 | v2i64 __builtin_msa_fseq_d (v2f64, v2f64); | |
17359 | ||
17360 | v4i32 __builtin_msa_fsle_w (v4f32, v4f32); | |
17361 | v2i64 __builtin_msa_fsle_d (v2f64, v2f64); | |
17362 | ||
17363 | v4i32 __builtin_msa_fslt_w (v4f32, v4f32); | |
17364 | v2i64 __builtin_msa_fslt_d (v2f64, v2f64); | |
17365 | ||
17366 | v4i32 __builtin_msa_fsne_w (v4f32, v4f32); | |
17367 | v2i64 __builtin_msa_fsne_d (v2f64, v2f64); | |
17368 | ||
17369 | v4i32 __builtin_msa_fsor_w (v4f32, v4f32); | |
17370 | v2i64 __builtin_msa_fsor_d (v2f64, v2f64); | |
17371 | ||
17372 | v4f32 __builtin_msa_fsqrt_w (v4f32); | |
17373 | v2f64 __builtin_msa_fsqrt_d (v2f64); | |
17374 | ||
17375 | v4f32 __builtin_msa_fsub_w (v4f32, v4f32); | |
17376 | v2f64 __builtin_msa_fsub_d (v2f64, v2f64); | |
17377 | ||
17378 | v4i32 __builtin_msa_fsueq_w (v4f32, v4f32); | |
17379 | v2i64 __builtin_msa_fsueq_d (v2f64, v2f64); | |
17380 | ||
17381 | v4i32 __builtin_msa_fsule_w (v4f32, v4f32); | |
17382 | v2i64 __builtin_msa_fsule_d (v2f64, v2f64); | |
17383 | ||
17384 | v4i32 __builtin_msa_fsult_w (v4f32, v4f32); | |
17385 | v2i64 __builtin_msa_fsult_d (v2f64, v2f64); | |
17386 | ||
17387 | v4i32 __builtin_msa_fsun_w (v4f32, v4f32); | |
17388 | v2i64 __builtin_msa_fsun_d (v2f64, v2f64); | |
17389 | ||
17390 | v4i32 __builtin_msa_fsune_w (v4f32, v4f32); | |
17391 | v2i64 __builtin_msa_fsune_d (v2f64, v2f64); | |
17392 | ||
17393 | v4i32 __builtin_msa_ftint_s_w (v4f32); | |
17394 | v2i64 __builtin_msa_ftint_s_d (v2f64); | |
17395 | ||
17396 | v4u32 __builtin_msa_ftint_u_w (v4f32); | |
17397 | v2u64 __builtin_msa_ftint_u_d (v2f64); | |
17398 | ||
17399 | v8i16 __builtin_msa_ftq_h (v4f32, v4f32); | |
17400 | v4i32 __builtin_msa_ftq_w (v2f64, v2f64); | |
17401 | ||
17402 | v4i32 __builtin_msa_ftrunc_s_w (v4f32); | |
17403 | v2i64 __builtin_msa_ftrunc_s_d (v2f64); | |
17404 | ||
17405 | v4u32 __builtin_msa_ftrunc_u_w (v4f32); | |
17406 | v2u64 __builtin_msa_ftrunc_u_d (v2f64); | |
17407 | ||
17408 | v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8); | |
17409 | v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16); | |
17410 | v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32); | |
17411 | ||
17412 | v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8); | |
17413 | v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16); | |
17414 | v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32); | |
17415 | ||
17416 | v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8); | |
17417 | v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16); | |
17418 | v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32); | |
17419 | ||
17420 | v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8); | |
17421 | v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16); | |
17422 | v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32); | |
17423 | ||
17424 | v16i8 __builtin_msa_ilvev_b (v16i8, v16i8); | |
17425 | v8i16 __builtin_msa_ilvev_h (v8i16, v8i16); | |
17426 | v4i32 __builtin_msa_ilvev_w (v4i32, v4i32); | |
17427 | v2i64 __builtin_msa_ilvev_d (v2i64, v2i64); | |
17428 | ||
17429 | v16i8 __builtin_msa_ilvl_b (v16i8, v16i8); | |
17430 | v8i16 __builtin_msa_ilvl_h (v8i16, v8i16); | |
17431 | v4i32 __builtin_msa_ilvl_w (v4i32, v4i32); | |
17432 | v2i64 __builtin_msa_ilvl_d (v2i64, v2i64); | |
17433 | ||
17434 | v16i8 __builtin_msa_ilvod_b (v16i8, v16i8); | |
17435 | v8i16 __builtin_msa_ilvod_h (v8i16, v8i16); | |
17436 | v4i32 __builtin_msa_ilvod_w (v4i32, v4i32); | |
17437 | v2i64 __builtin_msa_ilvod_d (v2i64, v2i64); | |
17438 | ||
17439 | v16i8 __builtin_msa_ilvr_b (v16i8, v16i8); | |
17440 | v8i16 __builtin_msa_ilvr_h (v8i16, v8i16); | |
17441 | v4i32 __builtin_msa_ilvr_w (v4i32, v4i32); | |
17442 | v2i64 __builtin_msa_ilvr_d (v2i64, v2i64); | |
17443 | ||
17444 | v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32); | |
17445 | v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32); | |
17446 | v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32); | |
17447 | v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64); | |
17448 | ||
17449 | v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8); | |
17450 | v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16); | |
17451 | v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32); | |
17452 | v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64); | |
17453 | ||
17454 | v16i8 __builtin_msa_ld_b (const void *, imm_n512_511); | |
17455 | v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022); | |
17456 | v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044); | |
17457 | v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088); | |
17458 | ||
17459 | v16i8 __builtin_msa_ldi_b (imm_n512_511); | |
17460 | v8i16 __builtin_msa_ldi_h (imm_n512_511); | |
17461 | v4i32 __builtin_msa_ldi_w (imm_n512_511); | |
17462 | v2i64 __builtin_msa_ldi_d (imm_n512_511); | |
17463 | ||
17464 | v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16); | |
17465 | v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32); | |
17466 | ||
17467 | v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16); | |
17468 | v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32); | |
17469 | ||
17470 | v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8); | |
17471 | v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16); | |
17472 | v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32); | |
17473 | v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64); | |
17474 | ||
17475 | v16i8 __builtin_msa_max_a_b (v16i8, v16i8); | |
17476 | v8i16 __builtin_msa_max_a_h (v8i16, v8i16); | |
17477 | v4i32 __builtin_msa_max_a_w (v4i32, v4i32); | |
17478 | v2i64 __builtin_msa_max_a_d (v2i64, v2i64); | |
17479 | ||
17480 | v16i8 __builtin_msa_max_s_b (v16i8, v16i8); | |
17481 | v8i16 __builtin_msa_max_s_h (v8i16, v8i16); | |
17482 | v4i32 __builtin_msa_max_s_w (v4i32, v4i32); | |
17483 | v2i64 __builtin_msa_max_s_d (v2i64, v2i64); | |
17484 | ||
17485 | v16u8 __builtin_msa_max_u_b (v16u8, v16u8); | |
17486 | v8u16 __builtin_msa_max_u_h (v8u16, v8u16); | |
17487 | v4u32 __builtin_msa_max_u_w (v4u32, v4u32); | |
17488 | v2u64 __builtin_msa_max_u_d (v2u64, v2u64); | |
17489 | ||
17490 | v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15); | |
17491 | v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15); | |
17492 | v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15); | |
17493 | v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15); | |
17494 | ||
17495 | v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31); | |
17496 | v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31); | |
17497 | v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31); | |
17498 | v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31); | |
17499 | ||
17500 | v16i8 __builtin_msa_min_a_b (v16i8, v16i8); | |
17501 | v8i16 __builtin_msa_min_a_h (v8i16, v8i16); | |
17502 | v4i32 __builtin_msa_min_a_w (v4i32, v4i32); | |
17503 | v2i64 __builtin_msa_min_a_d (v2i64, v2i64); | |
17504 | ||
17505 | v16i8 __builtin_msa_min_s_b (v16i8, v16i8); | |
17506 | v8i16 __builtin_msa_min_s_h (v8i16, v8i16); | |
17507 | v4i32 __builtin_msa_min_s_w (v4i32, v4i32); | |
17508 | v2i64 __builtin_msa_min_s_d (v2i64, v2i64); | |
17509 | ||
17510 | v16u8 __builtin_msa_min_u_b (v16u8, v16u8); | |
17511 | v8u16 __builtin_msa_min_u_h (v8u16, v8u16); | |
17512 | v4u32 __builtin_msa_min_u_w (v4u32, v4u32); | |
17513 | v2u64 __builtin_msa_min_u_d (v2u64, v2u64); | |
17514 | ||
17515 | v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15); | |
17516 | v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15); | |
17517 | v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15); | |
17518 | v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15); | |
17519 | ||
17520 | v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31); | |
17521 | v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31); | |
17522 | v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31); | |
17523 | v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31); | |
17524 | ||
17525 | v16i8 __builtin_msa_mod_s_b (v16i8, v16i8); | |
17526 | v8i16 __builtin_msa_mod_s_h (v8i16, v8i16); | |
17527 | v4i32 __builtin_msa_mod_s_w (v4i32, v4i32); | |
17528 | v2i64 __builtin_msa_mod_s_d (v2i64, v2i64); | |
17529 | ||
17530 | v16u8 __builtin_msa_mod_u_b (v16u8, v16u8); | |
17531 | v8u16 __builtin_msa_mod_u_h (v8u16, v8u16); | |
17532 | v4u32 __builtin_msa_mod_u_w (v4u32, v4u32); | |
17533 | v2u64 __builtin_msa_mod_u_d (v2u64, v2u64); | |
17534 | ||
17535 | v16i8 __builtin_msa_move_v (v16i8); | |
17536 | ||
17537 | v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16); | |
17538 | v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32); | |
17539 | ||
17540 | v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16); | |
17541 | v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32); | |
17542 | ||
17543 | v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8); | |
17544 | v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16); | |
17545 | v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32); | |
17546 | v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64); | |
17547 | ||
17548 | v8i16 __builtin_msa_mul_q_h (v8i16, v8i16); | |
17549 | v4i32 __builtin_msa_mul_q_w (v4i32, v4i32); | |
17550 | ||
17551 | v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16); | |
17552 | v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32); | |
17553 | ||
17554 | v16i8 __builtin_msa_mulv_b (v16i8, v16i8); | |
17555 | v8i16 __builtin_msa_mulv_h (v8i16, v8i16); | |
17556 | v4i32 __builtin_msa_mulv_w (v4i32, v4i32); | |
17557 | v2i64 __builtin_msa_mulv_d (v2i64, v2i64); | |
17558 | ||
17559 | v16i8 __builtin_msa_nloc_b (v16i8); | |
17560 | v8i16 __builtin_msa_nloc_h (v8i16); | |
17561 | v4i32 __builtin_msa_nloc_w (v4i32); | |
17562 | v2i64 __builtin_msa_nloc_d (v2i64); | |
17563 | ||
17564 | v16i8 __builtin_msa_nlzc_b (v16i8); | |
17565 | v8i16 __builtin_msa_nlzc_h (v8i16); | |
17566 | v4i32 __builtin_msa_nlzc_w (v4i32); | |
17567 | v2i64 __builtin_msa_nlzc_d (v2i64); | |
17568 | ||
17569 | v16u8 __builtin_msa_nor_v (v16u8, v16u8); | |
17570 | ||
17571 | v16u8 __builtin_msa_nori_b (v16u8, imm0_255); | |
17572 | ||
17573 | v16u8 __builtin_msa_or_v (v16u8, v16u8); | |
17574 | ||
17575 | v16u8 __builtin_msa_ori_b (v16u8, imm0_255); | |
17576 | ||
17577 | v16i8 __builtin_msa_pckev_b (v16i8, v16i8); | |
17578 | v8i16 __builtin_msa_pckev_h (v8i16, v8i16); | |
17579 | v4i32 __builtin_msa_pckev_w (v4i32, v4i32); | |
17580 | v2i64 __builtin_msa_pckev_d (v2i64, v2i64); | |
17581 | ||
17582 | v16i8 __builtin_msa_pckod_b (v16i8, v16i8); | |
17583 | v8i16 __builtin_msa_pckod_h (v8i16, v8i16); | |
17584 | v4i32 __builtin_msa_pckod_w (v4i32, v4i32); | |
17585 | v2i64 __builtin_msa_pckod_d (v2i64, v2i64); | |
17586 | ||
17587 | v16i8 __builtin_msa_pcnt_b (v16i8); | |
17588 | v8i16 __builtin_msa_pcnt_h (v8i16); | |
17589 | v4i32 __builtin_msa_pcnt_w (v4i32); | |
17590 | v2i64 __builtin_msa_pcnt_d (v2i64); | |
17591 | ||
17592 | v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7); | |
17593 | v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15); | |
17594 | v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31); | |
17595 | v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63); | |
17596 | ||
17597 | v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7); | |
17598 | v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15); | |
17599 | v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31); | |
17600 | v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63); | |
17601 | ||
17602 | v16i8 __builtin_msa_shf_b (v16i8, imm0_255); | |
17603 | v8i16 __builtin_msa_shf_h (v8i16, imm0_255); | |
17604 | v4i32 __builtin_msa_shf_w (v4i32, imm0_255); | |
17605 | ||
17606 | v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32); | |
17607 | v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32); | |
17608 | v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32); | |
17609 | v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32); | |
17610 | ||
17611 | v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15); | |
17612 | v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7); | |
17613 | v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3); | |
17614 | v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1); | |
17615 | ||
17616 | v16i8 __builtin_msa_sll_b (v16i8, v16i8); | |
17617 | v8i16 __builtin_msa_sll_h (v8i16, v8i16); | |
17618 | v4i32 __builtin_msa_sll_w (v4i32, v4i32); | |
17619 | v2i64 __builtin_msa_sll_d (v2i64, v2i64); | |
17620 | ||
17621 | v16i8 __builtin_msa_slli_b (v16i8, imm0_7); | |
17622 | v8i16 __builtin_msa_slli_h (v8i16, imm0_15); | |
17623 | v4i32 __builtin_msa_slli_w (v4i32, imm0_31); | |
17624 | v2i64 __builtin_msa_slli_d (v2i64, imm0_63); | |
17625 | ||
17626 | v16i8 __builtin_msa_splat_b (v16i8, i32); | |
17627 | v8i16 __builtin_msa_splat_h (v8i16, i32); | |
17628 | v4i32 __builtin_msa_splat_w (v4i32, i32); | |
17629 | v2i64 __builtin_msa_splat_d (v2i64, i32); | |
17630 | ||
17631 | v16i8 __builtin_msa_splati_b (v16i8, imm0_15); | |
17632 | v8i16 __builtin_msa_splati_h (v8i16, imm0_7); | |
17633 | v4i32 __builtin_msa_splati_w (v4i32, imm0_3); | |
17634 | v2i64 __builtin_msa_splati_d (v2i64, imm0_1); | |
17635 | ||
17636 | v16i8 __builtin_msa_sra_b (v16i8, v16i8); | |
17637 | v8i16 __builtin_msa_sra_h (v8i16, v8i16); | |
17638 | v4i32 __builtin_msa_sra_w (v4i32, v4i32); | |
17639 | v2i64 __builtin_msa_sra_d (v2i64, v2i64); | |
17640 | ||
17641 | v16i8 __builtin_msa_srai_b (v16i8, imm0_7); | |
17642 | v8i16 __builtin_msa_srai_h (v8i16, imm0_15); | |
17643 | v4i32 __builtin_msa_srai_w (v4i32, imm0_31); | |
17644 | v2i64 __builtin_msa_srai_d (v2i64, imm0_63); | |
17645 | ||
17646 | v16i8 __builtin_msa_srar_b (v16i8, v16i8); | |
17647 | v8i16 __builtin_msa_srar_h (v8i16, v8i16); | |
17648 | v4i32 __builtin_msa_srar_w (v4i32, v4i32); | |
17649 | v2i64 __builtin_msa_srar_d (v2i64, v2i64); | |
17650 | ||
17651 | v16i8 __builtin_msa_srari_b (v16i8, imm0_7); | |
17652 | v8i16 __builtin_msa_srari_h (v8i16, imm0_15); | |
17653 | v4i32 __builtin_msa_srari_w (v4i32, imm0_31); | |
17654 | v2i64 __builtin_msa_srari_d (v2i64, imm0_63); | |
17655 | ||
17656 | v16i8 __builtin_msa_srl_b (v16i8, v16i8); | |
17657 | v8i16 __builtin_msa_srl_h (v8i16, v8i16); | |
17658 | v4i32 __builtin_msa_srl_w (v4i32, v4i32); | |
17659 | v2i64 __builtin_msa_srl_d (v2i64, v2i64); | |
17660 | ||
17661 | v16i8 __builtin_msa_srli_b (v16i8, imm0_7); | |
17662 | v8i16 __builtin_msa_srli_h (v8i16, imm0_15); | |
17663 | v4i32 __builtin_msa_srli_w (v4i32, imm0_31); | |
17664 | v2i64 __builtin_msa_srli_d (v2i64, imm0_63); | |
17665 | ||
17666 | v16i8 __builtin_msa_srlr_b (v16i8, v16i8); | |
17667 | v8i16 __builtin_msa_srlr_h (v8i16, v8i16); | |
17668 | v4i32 __builtin_msa_srlr_w (v4i32, v4i32); | |
17669 | v2i64 __builtin_msa_srlr_d (v2i64, v2i64); | |
17670 | ||
17671 | v16i8 __builtin_msa_srlri_b (v16i8, imm0_7); | |
17672 | v8i16 __builtin_msa_srlri_h (v8i16, imm0_15); | |
17673 | v4i32 __builtin_msa_srlri_w (v4i32, imm0_31); | |
17674 | v2i64 __builtin_msa_srlri_d (v2i64, imm0_63); | |
17675 | ||
17676 | void __builtin_msa_st_b (v16i8, void *, imm_n512_511); | |
17677 | void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022); | |
17678 | void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044); | |
17679 | void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088); | |
17680 | ||
17681 | v16i8 __builtin_msa_subs_s_b (v16i8, v16i8); | |
17682 | v8i16 __builtin_msa_subs_s_h (v8i16, v8i16); | |
17683 | v4i32 __builtin_msa_subs_s_w (v4i32, v4i32); | |
17684 | v2i64 __builtin_msa_subs_s_d (v2i64, v2i64); | |
17685 | ||
17686 | v16u8 __builtin_msa_subs_u_b (v16u8, v16u8); | |
17687 | v8u16 __builtin_msa_subs_u_h (v8u16, v8u16); | |
17688 | v4u32 __builtin_msa_subs_u_w (v4u32, v4u32); | |
17689 | v2u64 __builtin_msa_subs_u_d (v2u64, v2u64); | |
17690 | ||
17691 | v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8); | |
17692 | v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16); | |
17693 | v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32); | |
17694 | v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64); | |
17695 | ||
17696 | v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8); | |
17697 | v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16); | |
17698 | v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32); | |
17699 | v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64); | |
17700 | ||
17701 | v16i8 __builtin_msa_subv_b (v16i8, v16i8); | |
17702 | v8i16 __builtin_msa_subv_h (v8i16, v8i16); | |
17703 | v4i32 __builtin_msa_subv_w (v4i32, v4i32); | |
17704 | v2i64 __builtin_msa_subv_d (v2i64, v2i64); | |
17705 | ||
17706 | v16i8 __builtin_msa_subvi_b (v16i8, imm0_31); | |
17707 | v8i16 __builtin_msa_subvi_h (v8i16, imm0_31); | |
17708 | v4i32 __builtin_msa_subvi_w (v4i32, imm0_31); | |
17709 | v2i64 __builtin_msa_subvi_d (v2i64, imm0_31); | |
17710 | ||
17711 | v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8); | |
17712 | v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16); | |
17713 | v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32); | |
17714 | v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64); | |
17715 | ||
17716 | v16u8 __builtin_msa_xor_v (v16u8, v16u8); | |
17717 | ||
17718 | v16u8 __builtin_msa_xori_b (v16u8, imm0_255); | |
17719 | @end smallexample | |
17720 | ||
17721 | @node Other MIPS Built-in Functions | |
17722 | @subsection Other MIPS Built-in Functions | |
17723 | ||
17724 | GCC provides other MIPS-specific built-in functions: | |
17725 | ||
17726 | @table @code | |
17727 | @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) | |
17728 | Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. | |
17729 | GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} | |
17730 | when this function is available. | |
17731 | ||
17732 | @item unsigned int __builtin_mips_get_fcsr (void) | |
17733 | @itemx void __builtin_mips_set_fcsr (unsigned int @var{value}) | |
17734 | Get and set the contents of the floating-point control and status register | |
17735 | (FPU control register 31). These functions are only available in hard-float | |
17736 | code but can be called in both MIPS16 and non-MIPS16 contexts. | |
17737 | ||
17738 | @code{__builtin_mips_set_fcsr} can be used to change any bit of the | |
17739 | register except the condition codes, which GCC assumes are preserved. | |
17740 | @end table | |
17741 | ||
17742 | @node MSP430 Built-in Functions | |
17743 | @subsection MSP430 Built-in Functions | |
17744 | ||
17745 | GCC provides a couple of special builtin functions to aid in the | |
17746 | writing of interrupt handlers in C. | |
17747 | ||
17748 | @table @code | |
17749 | @item __bic_SR_register_on_exit (int @var{mask}) | |
17750 | This clears the indicated bits in the saved copy of the status register | |
17751 | currently residing on the stack. This only works inside interrupt | |
17752 | handlers and the changes to the status register will only take affect | |
17753 | once the handler returns. | |
17754 | ||
17755 | @item __bis_SR_register_on_exit (int @var{mask}) | |
17756 | This sets the indicated bits in the saved copy of the status register | |
17757 | currently residing on the stack. This only works inside interrupt | |
17758 | handlers and the changes to the status register will only take affect | |
17759 | once the handler returns. | |
17760 | ||
17761 | @item __delay_cycles (long long @var{cycles}) | |
17762 | This inserts an instruction sequence that takes exactly @var{cycles} | |
17763 | cycles (between 0 and about 17E9) to complete. The inserted sequence | |
17764 | may use jumps, loops, or no-ops, and does not interfere with any other | |
17765 | instructions. Note that @var{cycles} must be a compile-time constant | |
17766 | integer - that is, you must pass a number, not a variable that may be | |
17767 | optimized to a constant later. The number of cycles delayed by this | |
17768 | builtin is exact. | |
17769 | @end table | |
17770 | ||
17771 | @node NDS32 Built-in Functions | |
17772 | @subsection NDS32 Built-in Functions | |
17773 | ||
17774 | These built-in functions are available for the NDS32 target: | |
17775 | ||
f25efe50 | 17776 | @defbuiltin{void __builtin_nds32_isync (int *@var{addr})} |
d77de738 ML |
17777 | Insert an ISYNC instruction into the instruction stream where |
17778 | @var{addr} is an instruction address for serialization. | |
f25efe50 | 17779 | @enddefbuiltin |
d77de738 | 17780 | |
f25efe50 | 17781 | @defbuiltin{void __builtin_nds32_isb (void)} |
d77de738 | 17782 | Insert an ISB instruction into the instruction stream. |
f25efe50 | 17783 | @enddefbuiltin |
d77de738 | 17784 | |
f25efe50 | 17785 | @defbuiltin{int __builtin_nds32_mfsr (int @var{sr})} |
d77de738 | 17786 | Return the content of a system register which is mapped by @var{sr}. |
f25efe50 | 17787 | @enddefbuiltin |
d77de738 | 17788 | |
f25efe50 | 17789 | @defbuiltin{int __builtin_nds32_mfusr (int @var{usr})} |
d77de738 | 17790 | Return the content of a user space register which is mapped by @var{usr}. |
f25efe50 | 17791 | @enddefbuiltin |
d77de738 | 17792 | |
f25efe50 | 17793 | @defbuiltin{void __builtin_nds32_mtsr (int @var{value}, int @var{sr})} |
d77de738 | 17794 | Move the @var{value} to a system register which is mapped by @var{sr}. |
f25efe50 | 17795 | @enddefbuiltin |
d77de738 | 17796 | |
f25efe50 | 17797 | @defbuiltin{void __builtin_nds32_mtusr (int @var{value}, int @var{usr})} |
d77de738 | 17798 | Move the @var{value} to a user space register which is mapped by @var{usr}. |
f25efe50 | 17799 | @enddefbuiltin |
d77de738 | 17800 | |
f25efe50 | 17801 | @defbuiltin{void __builtin_nds32_setgie_en (void)} |
d77de738 | 17802 | Enable global interrupt. |
f25efe50 | 17803 | @enddefbuiltin |
d77de738 | 17804 | |
f25efe50 | 17805 | @defbuiltin{void __builtin_nds32_setgie_dis (void)} |
d77de738 | 17806 | Disable global interrupt. |
f25efe50 | 17807 | @enddefbuiltin |
d77de738 | 17808 | |
d77de738 ML |
17809 | @node Basic PowerPC Built-in Functions |
17810 | @subsection Basic PowerPC Built-in Functions | |
17811 | ||
17812 | @menu | |
17813 | * Basic PowerPC Built-in Functions Available on all Configurations:: | |
17814 | * Basic PowerPC Built-in Functions Available on ISA 2.05:: | |
17815 | * Basic PowerPC Built-in Functions Available on ISA 2.06:: | |
17816 | * Basic PowerPC Built-in Functions Available on ISA 2.07:: | |
17817 | * Basic PowerPC Built-in Functions Available on ISA 3.0:: | |
17818 | * Basic PowerPC Built-in Functions Available on ISA 3.1:: | |
17819 | @end menu | |
17820 | ||
17821 | This section describes PowerPC built-in functions that do not require | |
17822 | the inclusion of any special header files to declare prototypes or | |
17823 | provide macro definitions. The sections that follow describe | |
17824 | additional PowerPC built-in functions. | |
17825 | ||
17826 | @node Basic PowerPC Built-in Functions Available on all Configurations | |
17827 | @subsubsection Basic PowerPC Built-in Functions Available on all Configurations | |
17828 | ||
f25efe50 | 17829 | @defbuiltin{void __builtin_cpu_init (void)} |
d77de738 ML |
17830 | This function is a @code{nop} on the PowerPC platform and is included solely |
17831 | to maintain API compatibility with the x86 builtins. | |
f25efe50 | 17832 | @enddefbuiltin |
d77de738 | 17833 | |
f25efe50 | 17834 | @defbuiltin{int __builtin_cpu_is (const char *@var{cpuname})} |
d77de738 ML |
17835 | This function returns a value of @code{1} if the run-time CPU is of type |
17836 | @var{cpuname} and returns @code{0} otherwise | |
17837 | ||
17838 | The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer | |
17839 | which exports the hardware capability bits. GCC defines the macro | |
17840 | @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports} | |
17841 | built-in function is fully supported. | |
17842 | ||
17843 | If GCC was configured to use a GLIBC before 2.23, the built-in | |
17844 | function @code{__builtin_cpu_is} always returns a 0 and the compiler | |
17845 | issues a warning. | |
17846 | ||
17847 | The following CPU names can be detected: | |
17848 | ||
17849 | @table @samp | |
17850 | @item power10 | |
17851 | IBM POWER10 Server CPU. | |
17852 | @item power9 | |
17853 | IBM POWER9 Server CPU. | |
17854 | @item power8 | |
17855 | IBM POWER8 Server CPU. | |
17856 | @item power7 | |
17857 | IBM POWER7 Server CPU. | |
17858 | @item power6x | |
17859 | IBM POWER6 Server CPU (RAW mode). | |
17860 | @item power6 | |
17861 | IBM POWER6 Server CPU (Architected mode). | |
17862 | @item power5+ | |
17863 | IBM POWER5+ Server CPU. | |
17864 | @item power5 | |
17865 | IBM POWER5 Server CPU. | |
17866 | @item ppc970 | |
17867 | IBM 970 Server CPU (ie, Apple G5). | |
17868 | @item power4 | |
17869 | IBM POWER4 Server CPU. | |
17870 | @item ppca2 | |
17871 | IBM A2 64-bit Embedded CPU | |
17872 | @item ppc476 | |
17873 | IBM PowerPC 476FP 32-bit Embedded CPU. | |
17874 | @item ppc464 | |
17875 | IBM PowerPC 464 32-bit Embedded CPU. | |
17876 | @item ppc440 | |
17877 | PowerPC 440 32-bit Embedded CPU. | |
17878 | @item ppc405 | |
17879 | PowerPC 405 32-bit Embedded CPU. | |
17880 | @item ppc-cell-be | |
17881 | IBM PowerPC Cell Broadband Engine Architecture CPU. | |
17882 | @end table | |
17883 | ||
17884 | Here is an example: | |
17885 | @smallexample | |
17886 | #ifdef __BUILTIN_CPU_SUPPORTS__ | |
17887 | if (__builtin_cpu_is ("power8")) | |
17888 | @{ | |
17889 | do_power8 (); // POWER8 specific implementation. | |
17890 | @} | |
17891 | else | |
17892 | #endif | |
17893 | @{ | |
17894 | do_generic (); // Generic implementation. | |
17895 | @} | |
17896 | @end smallexample | |
f25efe50 | 17897 | @enddefbuiltin |
d77de738 | 17898 | |
f25efe50 | 17899 | @defbuiltin{int __builtin_cpu_supports (const char *@var{feature})} |
d77de738 ML |
17900 | This function returns a value of @code{1} if the run-time CPU supports the HWCAP |
17901 | feature @var{feature} and returns @code{0} otherwise. | |
17902 | ||
17903 | The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or | |
17904 | newer which exports the hardware capability bits. GCC defines the | |
17905 | macro @code{__BUILTIN_CPU_SUPPORTS__} if the | |
17906 | @code{__builtin_cpu_supports} built-in function is fully supported. | |
17907 | ||
17908 | If GCC was configured to use a GLIBC before 2.23, the built-in | |
17909 | function @code{__builtin_cpu_supports} always returns a 0 and the | |
17910 | compiler issues a warning. | |
17911 | ||
17912 | The following features can be | |
17913 | detected: | |
17914 | ||
17915 | @table @samp | |
17916 | @item 4xxmac | |
17917 | 4xx CPU has a Multiply Accumulator. | |
17918 | @item altivec | |
17919 | CPU has a SIMD/Vector Unit. | |
17920 | @item arch_2_05 | |
17921 | CPU supports ISA 2.05 (eg, POWER6) | |
17922 | @item arch_2_06 | |
17923 | CPU supports ISA 2.06 (eg, POWER7) | |
17924 | @item arch_2_07 | |
17925 | CPU supports ISA 2.07 (eg, POWER8) | |
17926 | @item arch_3_00 | |
17927 | CPU supports ISA 3.0 (eg, POWER9) | |
17928 | @item arch_3_1 | |
17929 | CPU supports ISA 3.1 (eg, POWER10) | |
17930 | @item archpmu | |
17931 | CPU supports the set of compatible performance monitoring events. | |
17932 | @item booke | |
17933 | CPU supports the Embedded ISA category. | |
17934 | @item cellbe | |
17935 | CPU has a CELL broadband engine. | |
17936 | @item darn | |
17937 | CPU supports the @code{darn} (deliver a random number) instruction. | |
17938 | @item dfp | |
17939 | CPU has a decimal floating point unit. | |
17940 | @item dscr | |
17941 | CPU supports the data stream control register. | |
17942 | @item ebb | |
17943 | CPU supports event base branching. | |
17944 | @item efpdouble | |
17945 | CPU has a SPE double precision floating point unit. | |
17946 | @item efpsingle | |
17947 | CPU has a SPE single precision floating point unit. | |
17948 | @item fpu | |
17949 | CPU has a floating point unit. | |
17950 | @item htm | |
17951 | CPU has hardware transaction memory instructions. | |
17952 | @item htm-nosc | |
17953 | Kernel aborts hardware transactions when a syscall is made. | |
17954 | @item htm-no-suspend | |
17955 | CPU supports hardware transaction memory but does not support the | |
17956 | @code{tsuspend.} instruction. | |
17957 | @item ic_snoop | |
17958 | CPU supports icache snooping capabilities. | |
17959 | @item ieee128 | |
17960 | CPU supports 128-bit IEEE binary floating point instructions. | |
17961 | @item isel | |
17962 | CPU supports the integer select instruction. | |
17963 | @item mma | |
17964 | CPU supports the matrix-multiply assist instructions. | |
17965 | @item mmu | |
17966 | CPU has a memory management unit. | |
17967 | @item notb | |
17968 | CPU does not have a timebase (eg, 601 and 403gx). | |
17969 | @item pa6t | |
17970 | CPU supports the PA Semi 6T CORE ISA. | |
17971 | @item power4 | |
17972 | CPU supports ISA 2.00 (eg, POWER4) | |
17973 | @item power5 | |
17974 | CPU supports ISA 2.02 (eg, POWER5) | |
17975 | @item power5+ | |
17976 | CPU supports ISA 2.03 (eg, POWER5+) | |
17977 | @item power6x | |
17978 | CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr. | |
17979 | @item ppc32 | |
17980 | CPU supports 32-bit mode execution. | |
17981 | @item ppc601 | |
17982 | CPU supports the old POWER ISA (eg, 601) | |
17983 | @item ppc64 | |
17984 | CPU supports 64-bit mode execution. | |
17985 | @item ppcle | |
17986 | CPU supports a little-endian mode that uses address swizzling. | |
17987 | @item scv | |
17988 | Kernel supports system call vectored. | |
17989 | @item smt | |
17990 | CPU support simultaneous multi-threading. | |
17991 | @item spe | |
17992 | CPU has a signal processing extension unit. | |
17993 | @item tar | |
17994 | CPU supports the target address register. | |
17995 | @item true_le | |
17996 | CPU supports true little-endian mode. | |
17997 | @item ucache | |
17998 | CPU has unified I/D cache. | |
17999 | @item vcrypto | |
18000 | CPU supports the vector cryptography instructions. | |
18001 | @item vsx | |
18002 | CPU supports the vector-scalar extension. | |
18003 | @end table | |
18004 | ||
18005 | Here is an example: | |
18006 | @smallexample | |
18007 | #ifdef __BUILTIN_CPU_SUPPORTS__ | |
18008 | if (__builtin_cpu_supports ("fpu")) | |
18009 | @{ | |
18010 | asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2)); | |
18011 | @} | |
18012 | else | |
18013 | #endif | |
18014 | @{ | |
18015 | dst = __fadd (src1, src2); // Software FP addition function. | |
18016 | @} | |
18017 | @end smallexample | |
f25efe50 | 18018 | @enddefbuiltin |
d77de738 ML |
18019 | |
18020 | The following built-in functions are also available on all PowerPC | |
18021 | processors: | |
18022 | @smallexample | |
18023 | uint64_t __builtin_ppc_get_timebase (); | |
18024 | unsigned long __builtin_ppc_mftb (); | |
18025 | double __builtin_unpack_ibm128 (__ibm128, int); | |
18026 | __ibm128 __builtin_pack_ibm128 (double, double); | |
18027 | double __builtin_mffs (void); | |
18028 | void __builtin_mtfsf (const int, double); | |
18029 | void __builtin_mtfsb0 (const int); | |
18030 | void __builtin_mtfsb1 (const int); | |
18031 | void __builtin_set_fpscr_rn (int); | |
18032 | @end smallexample | |
18033 | ||
18034 | The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb} | |
18035 | functions generate instructions to read the Time Base Register. The | |
18036 | @code{__builtin_ppc_get_timebase} function may generate multiple | |
18037 | instructions and always returns the 64 bits of the Time Base Register. | |
18038 | The @code{__builtin_ppc_mftb} function always generates one instruction and | |
18039 | returns the Time Base Register value as an unsigned long, throwing away | |
18040 | the most significant word on 32-bit environments. The @code{__builtin_mffs} | |
18041 | return the value of the FPSCR register. Note, ISA 3.0 supports the | |
18042 | @code{__builtin_mffsl()} which permits software to read the control and | |
18043 | non-sticky status bits in the FSPCR without the higher latency associated with | |
18044 | accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant | |
18045 | 8-bit integer field mask and a double precision floating point argument | |
18046 | and generates the @code{mtfsf} (extended mnemonic) instruction to write new | |
18047 | values to selected fields of the FPSCR. The | |
18048 | @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change | |
18049 | as an argument. The valid bit range is between 0 and 31. The builtins map to | |
18050 | the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and | |
18051 | add 32. Hence these instructions only modify the FPSCR[32:63] bits by | |
18052 | changing the specified bit to a zero or one respectively. The | |
18053 | @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating | |
18054 | point rounding mode bits. The argument is a 2-bit value. The argument can | |
18055 | either be a @code{const int} or stored in a variable. The builtin uses | |
18056 | the ISA 3.0 | |
18057 | instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks | |
18058 | the current rounding mode bits out and OR's in the new value. | |
18059 | ||
18060 | @node Basic PowerPC Built-in Functions Available on ISA 2.05 | |
18061 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05 | |
18062 | ||
18063 | The basic built-in functions described in this section are | |
18064 | available on the PowerPC family of processors starting with ISA 2.05 | |
18065 | or later. Unless specific options are explicitly disabled on the | |
18066 | command line, specifying option @option{-mcpu=power6} has the effect of | |
18067 | enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt}, | |
18068 | @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb}, | |
18069 | @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and | |
18070 | @option{-mrecip-precision} options. Specify the | |
18071 | @option{-maltivec} option explicitly in | |
18072 | combination with the above options if desired. | |
18073 | ||
18074 | The following functions require option @option{-mcmpb}. | |
18075 | @smallexample | |
18076 | unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int); | |
18077 | unsigned int __builtin_cmpb (unsigned int, unsigned int); | |
18078 | @end smallexample | |
18079 | ||
18080 | The @code{__builtin_cmpb} function | |
18081 | performs a byte-wise compare on the contents of its two arguments, | |
18082 | returning the result of the byte-wise comparison as the returned | |
18083 | value. For each byte comparison, the corresponding byte of the return | |
18084 | value holds 0xff if the input bytes are equal and 0 if the input bytes | |
18085 | are not equal. If either of the arguments to this built-in function | |
18086 | is wider than 32 bits, the function call expands into the form that | |
18087 | expects @code{unsigned long long int} arguments | |
18088 | which is only available on 64-bit targets. | |
18089 | ||
18090 | The following built-in functions are available | |
18091 | when hardware decimal floating point | |
18092 | (@option{-mhard-dfp}) is available: | |
18093 | @smallexample | |
18094 | void __builtin_set_fpscr_drn(int); | |
18095 | _Decimal64 __builtin_ddedpd (int, _Decimal64); | |
18096 | _Decimal128 __builtin_ddedpdq (int, _Decimal128); | |
18097 | _Decimal64 __builtin_denbcd (int, _Decimal64); | |
18098 | _Decimal128 __builtin_denbcdq (int, _Decimal128); | |
18099 | _Decimal64 __builtin_diex (long long, _Decimal64); | |
18100 | _Decimal128 _builtin_diexq (long long, _Decimal128); | |
18101 | _Decimal64 __builtin_dscli (_Decimal64, int); | |
18102 | _Decimal128 __builtin_dscliq (_Decimal128, int); | |
18103 | _Decimal64 __builtin_dscri (_Decimal64, int); | |
18104 | _Decimal128 __builtin_dscriq (_Decimal128, int); | |
18105 | long long __builtin_dxex (_Decimal64); | |
18106 | long long __builtin_dxexq (_Decimal128); | |
18107 | _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long); | |
18108 | unsigned long long __builtin_unpack_dec128 (_Decimal128, int); | |
18109 | ||
18110 | The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal | |
18111 | floating point rounding mode bits. The argument is a 3-bit value. The | |
18112 | argument can either be a @code{const int} or the value can be stored in | |
18113 | a variable. | |
18114 | The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available. | |
18115 | Otherwise the builtin reads the FPSCR, masks the current decimal rounding | |
18116 | mode bits out and OR's in the new value. | |
18117 | ||
18118 | @end smallexample | |
18119 | ||
18120 | The following functions require @option{-mhard-float}, | |
18121 | @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options. | |
18122 | ||
18123 | @smallexample | |
18124 | double __builtin_recipdiv (double, double); | |
18125 | float __builtin_recipdivf (float, float); | |
18126 | double __builtin_rsqrt (double); | |
18127 | float __builtin_rsqrtf (float); | |
18128 | @end smallexample | |
18129 | ||
18130 | The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and | |
18131 | @code{__builtin_rsqrtf} functions generate multiple instructions to | |
18132 | implement the reciprocal sqrt functionality using reciprocal sqrt | |
18133 | estimate instructions. | |
18134 | ||
18135 | The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} | |
18136 | functions generate multiple instructions to implement division using | |
18137 | the reciprocal estimate instructions. | |
18138 | ||
18139 | The following functions require @option{-mhard-float} and | |
18140 | @option{-mmultiple} options. | |
18141 | ||
18142 | The @code{__builtin_unpack_longdouble} function takes a | |
18143 | @code{long double} argument and a compile time constant of 0 or 1. If | |
18144 | the constant is 0, the first @code{double} within the | |
18145 | @code{long double} is returned, otherwise the second @code{double} | |
18146 | is returned. The @code{__builtin_unpack_longdouble} function is only | |
18147 | available if @code{long double} uses the IBM extended double | |
18148 | representation. | |
18149 | ||
18150 | The @code{__builtin_pack_longdouble} function takes two @code{double} | |
18151 | arguments and returns a @code{long double} value that combines the two | |
18152 | arguments. The @code{__builtin_pack_longdouble} function is only | |
18153 | available if @code{long double} uses the IBM extended double | |
18154 | representation. | |
18155 | ||
18156 | The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128} | |
18157 | argument and a compile time constant of 0 or 1. If the constant is 0, | |
18158 | the first @code{double} within the @code{__ibm128} is returned, | |
18159 | otherwise the second @code{double} is returned. | |
18160 | ||
18161 | The @code{__builtin_pack_ibm128} function takes two @code{double} | |
18162 | arguments and returns a @code{__ibm128} value that combines the two | |
18163 | arguments. | |
18164 | ||
18165 | Additional built-in functions are available for the 64-bit PowerPC | |
18166 | family of processors, for efficient use of 128-bit floating point | |
18167 | (@code{__float128}) values. | |
18168 | ||
18169 | @node Basic PowerPC Built-in Functions Available on ISA 2.06 | |
18170 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06 | |
18171 | ||
18172 | The basic built-in functions described in this section are | |
18173 | available on the PowerPC family of processors starting with ISA 2.05 | |
18174 | or later. Unless specific options are explicitly disabled on the | |
18175 | command line, specifying option @option{-mcpu=power7} has the effect of | |
18176 | enabling all the same options as for @option{-mcpu=power6} in | |
18177 | addition to the @option{-maltivec}, @option{-mpopcntd}, and | |
18178 | @option{-mvsx} options. | |
18179 | ||
18180 | The following basic built-in functions require @option{-mpopcntd}: | |
18181 | @smallexample | |
18182 | unsigned int __builtin_addg6s (unsigned int, unsigned int); | |
18183 | long long __builtin_bpermd (long long, long long); | |
18184 | unsigned int __builtin_cbcdtd (unsigned int); | |
18185 | unsigned int __builtin_cdtbcd (unsigned int); | |
18186 | long long __builtin_divde (long long, long long); | |
18187 | unsigned long long __builtin_divdeu (unsigned long long, unsigned long long); | |
18188 | int __builtin_divwe (int, int); | |
18189 | unsigned int __builtin_divweu (unsigned int, unsigned int); | |
18190 | vector __int128 __builtin_pack_vector_int128 (long long, long long); | |
18191 | void __builtin_rs6000_speculation_barrier (void); | |
18192 | long long __builtin_unpack_vector_int128 (vector __int128, signed char); | |
18193 | @end smallexample | |
18194 | ||
18195 | Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions | |
18196 | require a 64-bit environment. | |
18197 | ||
18198 | The following basic built-in functions, which are also supported on | |
18199 | x86 targets, require @option{-mfloat128}. | |
18200 | @smallexample | |
18201 | __float128 __builtin_fabsq (__float128); | |
18202 | __float128 __builtin_copysignq (__float128, __float128); | |
18203 | __float128 __builtin_infq (void); | |
18204 | __float128 __builtin_huge_valq (void); | |
18205 | __float128 __builtin_nanq (void); | |
18206 | __float128 __builtin_nansq (void); | |
18207 | ||
18208 | __float128 __builtin_sqrtf128 (__float128); | |
18209 | __float128 __builtin_fmaf128 (__float128, __float128, __float128); | |
18210 | @end smallexample | |
18211 | ||
18212 | @node Basic PowerPC Built-in Functions Available on ISA 2.07 | |
18213 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07 | |
18214 | ||
18215 | The basic built-in functions described in this section are | |
18216 | available on the PowerPC family of processors starting with ISA 2.07 | |
18217 | or later. Unless specific options are explicitly disabled on the | |
18218 | command line, specifying option @option{-mcpu=power8} has the effect of | |
18219 | enabling all the same options as for @option{-mcpu=power7} in | |
18220 | addition to the @option{-mpower8-fusion}, @option{-mpower8-vector}, | |
18221 | @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and | |
18222 | @option{-mquad-memory-atomic} options. | |
18223 | ||
18224 | This section intentionally empty. | |
18225 | ||
18226 | @node Basic PowerPC Built-in Functions Available on ISA 3.0 | |
18227 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0 | |
18228 | ||
18229 | The basic built-in functions described in this section are | |
18230 | available on the PowerPC family of processors starting with ISA 3.0 | |
18231 | or later. Unless specific options are explicitly disabled on the | |
18232 | command line, specifying option @option{-mcpu=power9} has the effect of | |
18233 | enabling all the same options as for @option{-mcpu=power8} in | |
18234 | addition to the @option{-misel} option. | |
18235 | ||
18236 | The following built-in functions are available on Linux 64-bit systems | |
18237 | that use the ISA 3.0 instruction set (@option{-mcpu=power9}): | |
18238 | ||
f25efe50 | 18239 | @defbuiltin{__float128 __builtin_addf128_round_to_odd (__float128, __float128)} |
d77de738 ML |
18240 | Perform a 128-bit IEEE floating point add using round to odd as the |
18241 | rounding mode. | |
f25efe50 | 18242 | @enddefbuiltin |
d77de738 | 18243 | |
f25efe50 | 18244 | @defbuiltin{__float128 __builtin_subf128_round_to_odd (__float128, __float128)} |
d77de738 ML |
18245 | Perform a 128-bit IEEE floating point subtract using round to odd as |
18246 | the rounding mode. | |
f25efe50 | 18247 | @enddefbuiltin |
d77de738 | 18248 | |
f25efe50 | 18249 | @defbuiltin{__float128 __builtin_mulf128_round_to_odd (__float128, __float128)} |
d77de738 ML |
18250 | Perform a 128-bit IEEE floating point multiply using round to odd as |
18251 | the rounding mode. | |
f25efe50 | 18252 | @enddefbuiltin |
d77de738 | 18253 | |
f25efe50 | 18254 | @defbuiltin{__float128 __builtin_divf128_round_to_odd (__float128, __float128)} |
d77de738 ML |
18255 | Perform a 128-bit IEEE floating point divide using round to odd as |
18256 | the rounding mode. | |
f25efe50 | 18257 | @enddefbuiltin |
d77de738 | 18258 | |
f25efe50 | 18259 | @defbuiltin{__float128 __builtin_sqrtf128_round_to_odd (__float128)} |
d77de738 ML |
18260 | Perform a 128-bit IEEE floating point square root using round to odd |
18261 | as the rounding mode. | |
f25efe50 | 18262 | @enddefbuiltin |
d77de738 | 18263 | |
f25efe50 | 18264 | @defbuiltin{__float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)} |
d77de738 ML |
18265 | Perform a 128-bit IEEE floating point fused multiply and add operation |
18266 | using round to odd as the rounding mode. | |
f25efe50 | 18267 | @enddefbuiltin |
d77de738 | 18268 | |
f25efe50 | 18269 | @defbuiltin{double __builtin_truncf128_round_to_odd (__float128)} |
d77de738 ML |
18270 | Convert a 128-bit IEEE floating point value to @code{double} using |
18271 | round to odd as the rounding mode. | |
f25efe50 AA |
18272 | @enddefbuiltin |
18273 | ||
d77de738 ML |
18274 | |
18275 | The following additional built-in functions are also available for the | |
18276 | PowerPC family of processors, starting with ISA 3.0 or later: | |
d77de738 | 18277 | |
f25efe50 AA |
18278 | @defbuiltin{long long __builtin_darn (void)} |
18279 | @defbuiltinx{long long __builtin_darn_raw (void)} | |
18280 | @defbuiltinx{int __builtin_darn_32 (void)} | |
d77de738 ML |
18281 | The @code{__builtin_darn} and @code{__builtin_darn_raw} |
18282 | functions require a | |
18283 | 64-bit environment supporting ISA 3.0 or later. | |
18284 | The @code{__builtin_darn} function provides a 64-bit conditioned | |
18285 | random number. The @code{__builtin_darn_raw} function provides a | |
18286 | 64-bit raw random number. The @code{__builtin_darn_32} function | |
18287 | provides a 32-bit conditioned random number. | |
f25efe50 | 18288 | @enddefbuiltin |
d77de738 ML |
18289 | |
18290 | The following additional built-in functions are also available for the | |
18291 | PowerPC family of processors, starting with ISA 3.0 or later: | |
18292 | ||
18293 | @smallexample | |
18294 | int __builtin_byte_in_set (unsigned char u, unsigned long long set); | |
18295 | int __builtin_byte_in_range (unsigned char u, unsigned int range); | |
18296 | int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges); | |
18297 | ||
18298 | int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value); | |
18299 | int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value); | |
18300 | int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value); | |
18301 | int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value); | |
18302 | ||
18303 | int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value); | |
18304 | int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value); | |
18305 | int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value); | |
18306 | int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value); | |
18307 | ||
18308 | int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value); | |
18309 | int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value); | |
18310 | int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value); | |
18311 | int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value); | |
18312 | ||
18313 | int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value); | |
18314 | int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value); | |
18315 | int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value); | |
18316 | int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value); | |
18317 | ||
18318 | double __builtin_mffsl(void); | |
18319 | ||
18320 | @end smallexample | |
18321 | The @code{__builtin_byte_in_set} function requires a | |
18322 | 64-bit environment supporting ISA 3.0 or later. This function returns | |
18323 | a non-zero value if and only if its @code{u} argument exactly equals one of | |
18324 | the eight bytes contained within its 64-bit @code{set} argument. | |
18325 | ||
18326 | The @code{__builtin_byte_in_range} and | |
18327 | @code{__builtin_byte_in_either_range} require an environment | |
18328 | supporting ISA 3.0 or later. For these two functions, the | |
18329 | @code{range} argument is encoded as 4 bytes, organized as | |
18330 | @code{hi_1:lo_1:hi_2:lo_2}. | |
18331 | The @code{__builtin_byte_in_range} function returns a | |
18332 | non-zero value if and only if its @code{u} argument is within the | |
18333 | range bounded between @code{lo_2} and @code{hi_2} inclusive. | |
18334 | The @code{__builtin_byte_in_either_range} function returns non-zero if | |
18335 | and only if its @code{u} argument is within either the range bounded | |
18336 | between @code{lo_1} and @code{hi_1} inclusive or the range bounded | |
18337 | between @code{lo_2} and @code{hi_2} inclusive. | |
18338 | ||
18339 | The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value | |
18340 | if and only if the number of signficant digits of its @code{value} argument | |
18341 | is less than its @code{comparison} argument. The | |
18342 | @code{__builtin_dfp_dtstsfi_lt_dd} and | |
18343 | @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but | |
18344 | require that the type of the @code{value} argument be | |
18345 | @code{__Decimal64} and @code{__Decimal128} respectively. | |
18346 | ||
18347 | The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value | |
18348 | if and only if the number of signficant digits of its @code{value} argument | |
18349 | is greater than its @code{comparison} argument. The | |
18350 | @code{__builtin_dfp_dtstsfi_gt_dd} and | |
18351 | @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but | |
18352 | require that the type of the @code{value} argument be | |
18353 | @code{__Decimal64} and @code{__Decimal128} respectively. | |
18354 | ||
18355 | The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value | |
18356 | if and only if the number of signficant digits of its @code{value} argument | |
18357 | equals its @code{comparison} argument. The | |
18358 | @code{__builtin_dfp_dtstsfi_eq_dd} and | |
18359 | @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but | |
18360 | require that the type of the @code{value} argument be | |
18361 | @code{__Decimal64} and @code{__Decimal128} respectively. | |
18362 | ||
18363 | The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value | |
18364 | if and only if its @code{value} argument has an undefined number of | |
18365 | significant digits, such as when @code{value} is an encoding of @code{NaN}. | |
18366 | The @code{__builtin_dfp_dtstsfi_ov_dd} and | |
18367 | @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but | |
18368 | require that the type of the @code{value} argument be | |
18369 | @code{__Decimal64} and @code{__Decimal128} respectively. | |
18370 | ||
18371 | The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read | |
18372 | the FPSCR. The instruction is a lower latency version of the @code{mffs} | |
18373 | instruction. If the @code{mffsl} instruction is not available, then the | |
18374 | builtin uses the older @code{mffs} instruction to read the FPSCR. | |
18375 | ||
18376 | @node Basic PowerPC Built-in Functions Available on ISA 3.1 | |
18377 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1 | |
18378 | ||
18379 | The basic built-in functions described in this section are | |
18380 | available on the PowerPC family of processors starting with ISA 3.1. | |
18381 | Unless specific options are explicitly disabled on the | |
18382 | command line, specifying option @option{-mcpu=power10} has the effect of | |
18383 | enabling all the same options as for @option{-mcpu=power9}. | |
18384 | ||
18385 | The following built-in functions are available on Linux 64-bit systems | |
18386 | that use a future architecture instruction set (@option{-mcpu=power10}): | |
18387 | ||
f25efe50 AA |
18388 | @defbuiltin{{unsigned long long} @ |
18389 | __builtin_cfuged (unsigned long long, unsigned long long)} | |
d77de738 ML |
18390 | Perform a 64-bit centrifuge operation, as if implemented by the |
18391 | @code{cfuged} instruction. | |
f25efe50 | 18392 | @enddefbuiltin |
d77de738 | 18393 | |
f25efe50 AA |
18394 | @defbuiltin{{unsigned long long} @ |
18395 | __builtin_cntlzdm (unsigned long long, unsigned long long)} | |
d77de738 ML |
18396 | Perform a 64-bit count leading zeros operation under mask, as if |
18397 | implemented by the @code{cntlzdm} instruction. | |
f25efe50 | 18398 | @enddefbuiltin |
d77de738 | 18399 | |
f25efe50 AA |
18400 | @defbuiltin{{unsigned long long} @ |
18401 | __builtin_cnttzdm (unsigned long long, unsigned long long)} | |
d77de738 ML |
18402 | Perform a 64-bit count trailing zeros operation under mask, as if |
18403 | implemented by the @code{cnttzdm} instruction. | |
f25efe50 | 18404 | @enddefbuiltin |
d77de738 | 18405 | |
f25efe50 AA |
18406 | @defbuiltin{{unsigned long long} @ |
18407 | __builtin_pdepd (unsigned long long, unsigned long long)} | |
d77de738 ML |
18408 | Perform a 64-bit parallel bits deposit operation, as if implemented by the |
18409 | @code{pdepd} instruction. | |
f25efe50 | 18410 | @enddefbuiltin |
d77de738 | 18411 | |
f25efe50 AA |
18412 | @defbuiltin{{unsigned long long} @ |
18413 | __builtin_pextd (unsigned long long, unsigned long long)} | |
d77de738 ML |
18414 | Perform a 64-bit parallel bits extract operation, as if implemented by the |
18415 | @code{pextd} instruction. | |
f25efe50 | 18416 | @enddefbuiltin |
d77de738 | 18417 | |
f25efe50 AA |
18418 | @defbuiltin{{vector signed __int128} vsx_xl_sext (signed long long, signed char *)} |
18419 | @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed short *)} | |
18420 | @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed int *)} | |
18421 | @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed long long *)} | |
18422 | @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned char *)} | |
18423 | @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned short *)} | |
18424 | @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned int *)} | |
18425 | @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned long long *)} | |
d77de738 ML |
18426 | |
18427 | Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1 | |
f25efe50 AA |
18428 | @code{lxvrbx}, @code{lxvrhx}, @code{lxvrwx}, and @code{lxvrdx} |
18429 | instructions. | |
18430 | @enddefbuiltin | |
d77de738 | 18431 | |
f25efe50 AA |
18432 | @defbuiltin{{void} vec_xst_trunc (vector signed __int128, signed long long, signed char *)} |
18433 | @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed short *)} | |
18434 | @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed int *)} | |
18435 | @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed long long *)} | |
18436 | @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *)} | |
18437 | @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *)} | |
18438 | @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *)} | |
18439 | @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *)} | |
d77de738 ML |
18440 | |
18441 | Truncate and store the rightmost element of a vector, as if implemented by the | |
18442 | ISA 3.1 @code{stxvrbx}, @code{stxvrhx}, @code{stxvrwx}, and @code{stxvrdx} | |
18443 | instructions. | |
f25efe50 | 18444 | @enddefbuiltin |
d77de738 ML |
18445 | |
18446 | @node PowerPC AltiVec/VSX Built-in Functions | |
18447 | @subsection PowerPC AltiVec/VSX Built-in Functions | |
18448 | ||
18449 | GCC provides an interface for the PowerPC family of processors to access | |
18450 | the AltiVec operations described in Motorola's AltiVec Programming | |
18451 | Interface Manual. The interface is made available by including | |
18452 | @code{<altivec.h>} and using @option{-maltivec} and | |
18453 | @option{-mabi=altivec}. The interface supports the following vector | |
18454 | types. | |
18455 | ||
18456 | @smallexample | |
18457 | vector unsigned char | |
18458 | vector signed char | |
18459 | vector bool char | |
18460 | ||
18461 | vector unsigned short | |
18462 | vector signed short | |
18463 | vector bool short | |
18464 | vector pixel | |
18465 | ||
18466 | vector unsigned int | |
18467 | vector signed int | |
18468 | vector bool int | |
18469 | vector float | |
18470 | @end smallexample | |
18471 | ||
18472 | GCC's implementation of the high-level language interface available from | |
18473 | C and C++ code differs from Motorola's documentation in several ways. | |
18474 | ||
18475 | @itemize @bullet | |
18476 | ||
18477 | @item | |
18478 | A vector constant is a list of constant expressions within curly braces. | |
18479 | ||
18480 | @item | |
18481 | A vector initializer requires no cast if the vector constant is of the | |
18482 | same type as the variable it is initializing. | |
18483 | ||
18484 | @item | |
18485 | If @code{signed} or @code{unsigned} is omitted, the signedness of the | |
18486 | vector type is the default signedness of the base type. The default | |
18487 | varies depending on the operating system, so a portable program should | |
18488 | always specify the signedness. | |
18489 | ||
18490 | @item | |
18491 | Compiling with @option{-maltivec} adds keywords @code{__vector}, | |
18492 | @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and | |
18493 | @code{bool}. When compiling ISO C, the context-sensitive substitution | |
18494 | of the keywords @code{vector}, @code{pixel} and @code{bool} is | |
18495 | disabled. To use them, you must include @code{<altivec.h>} instead. | |
18496 | ||
18497 | @item | |
18498 | GCC allows using a @code{typedef} name as the type specifier for a | |
18499 | vector type, but only under the following circumstances: | |
18500 | ||
18501 | @itemize @bullet | |
18502 | ||
18503 | @item | |
18504 | When using @code{__vector} instead of @code{vector}; for example, | |
18505 | ||
18506 | @smallexample | |
18507 | typedef signed short int16; | |
18508 | __vector int16 data; | |
18509 | @end smallexample | |
18510 | ||
18511 | @item | |
18512 | When using @code{vector} in keyword-and-predefine mode; for example, | |
18513 | ||
18514 | @smallexample | |
18515 | typedef signed short int16; | |
18516 | vector int16 data; | |
18517 | @end smallexample | |
18518 | ||
18519 | Note that keyword-and-predefine mode is enabled by disabling GNU | |
18520 | extensions (e.g., by using @code{-std=c11}) and including | |
18521 | @code{<altivec.h>}. | |
18522 | @end itemize | |
18523 | ||
18524 | @item | |
18525 | For C, overloaded functions are implemented with macros so the following | |
18526 | does not work: | |
18527 | ||
18528 | @smallexample | |
18529 | vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); | |
18530 | @end smallexample | |
18531 | ||
18532 | @noindent | |
18533 | Since @code{vec_add} is a macro, the vector constant in the example | |
18534 | is treated as four separate arguments. Wrap the entire argument in | |
18535 | parentheses for this to work. | |
18536 | @end itemize | |
18537 | ||
18538 | @emph{Note:} Only the @code{<altivec.h>} interface is supported. | |
18539 | Internally, GCC uses built-in functions to achieve the functionality in | |
18540 | the aforementioned header file, but they are not supported and are | |
18541 | subject to change without notice. | |
18542 | ||
18543 | GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR), | |
18544 | which may be found at | |
18545 | @uref{https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference}. | |
18546 | Chapter 4 of this document fully documents the vector API interfaces | |
18547 | that must be | |
18548 | provided by compliant compilers. Programmers should preferentially use | |
18549 | the interfaces described therein. However, historically GCC has provided | |
18550 | additional interfaces for access to vector instructions. These are | |
18551 | briefly described below. Where the PVIPR provides a portable interface, | |
18552 | other functions in GCC that provide the same capabilities should be | |
18553 | considered deprecated. | |
18554 | ||
18555 | The PVIPR documents the following overloaded functions: | |
18556 | ||
18557 | @multitable @columnfractions 0.33 0.33 0.33 | |
18558 | ||
18559 | @item @code{vec_abs} | |
18560 | @tab @code{vec_absd} | |
18561 | @tab @code{vec_abss} | |
18562 | @item @code{vec_add} | |
18563 | @tab @code{vec_addc} | |
18564 | @tab @code{vec_adde} | |
18565 | @item @code{vec_addec} | |
18566 | @tab @code{vec_adds} | |
18567 | @tab @code{vec_all_eq} | |
18568 | @item @code{vec_all_ge} | |
18569 | @tab @code{vec_all_gt} | |
18570 | @tab @code{vec_all_in} | |
18571 | @item @code{vec_all_le} | |
18572 | @tab @code{vec_all_lt} | |
18573 | @tab @code{vec_all_nan} | |
18574 | @item @code{vec_all_ne} | |
18575 | @tab @code{vec_all_nge} | |
18576 | @tab @code{vec_all_ngt} | |
18577 | @item @code{vec_all_nle} | |
18578 | @tab @code{vec_all_nlt} | |
18579 | @tab @code{vec_all_numeric} | |
18580 | @item @code{vec_and} | |
18581 | @tab @code{vec_andc} | |
18582 | @tab @code{vec_any_eq} | |
18583 | @item @code{vec_any_ge} | |
18584 | @tab @code{vec_any_gt} | |
18585 | @tab @code{vec_any_le} | |
18586 | @item @code{vec_any_lt} | |
18587 | @tab @code{vec_any_nan} | |
18588 | @tab @code{vec_any_ne} | |
18589 | @item @code{vec_any_nge} | |
18590 | @tab @code{vec_any_ngt} | |
18591 | @tab @code{vec_any_nle} | |
18592 | @item @code{vec_any_nlt} | |
18593 | @tab @code{vec_any_numeric} | |
18594 | @tab @code{vec_any_out} | |
18595 | @item @code{vec_avg} | |
18596 | @tab @code{vec_bperm} | |
18597 | @tab @code{vec_ceil} | |
18598 | @item @code{vec_cipher_be} | |
18599 | @tab @code{vec_cipherlast_be} | |
18600 | @tab @code{vec_cmpb} | |
18601 | @item @code{vec_cmpeq} | |
18602 | @tab @code{vec_cmpge} | |
18603 | @tab @code{vec_cmpgt} | |
18604 | @item @code{vec_cmple} | |
18605 | @tab @code{vec_cmplt} | |
18606 | @tab @code{vec_cmpne} | |
18607 | @item @code{vec_cmpnez} | |
18608 | @tab @code{vec_cntlz} | |
18609 | @tab @code{vec_cntlz_lsbb} | |
18610 | @item @code{vec_cnttz} | |
18611 | @tab @code{vec_cnttz_lsbb} | |
18612 | @tab @code{vec_cpsgn} | |
18613 | @item @code{vec_ctf} | |
18614 | @tab @code{vec_cts} | |
18615 | @tab @code{vec_ctu} | |
18616 | @item @code{vec_div} | |
18617 | @tab @code{vec_double} | |
18618 | @tab @code{vec_doublee} | |
18619 | @item @code{vec_doubleh} | |
18620 | @tab @code{vec_doublel} | |
18621 | @tab @code{vec_doubleo} | |
18622 | @item @code{vec_eqv} | |
18623 | @tab @code{vec_expte} | |
18624 | @tab @code{vec_extract} | |
18625 | @item @code{vec_extract_exp} | |
18626 | @tab @code{vec_extract_fp32_from_shorth} | |
18627 | @tab @code{vec_extract_fp32_from_shortl} | |
18628 | @item @code{vec_extract_sig} | |
18629 | @tab @code{vec_extract_4b} | |
18630 | @tab @code{vec_first_match_index} | |
18631 | @item @code{vec_first_match_or_eos_index} | |
18632 | @tab @code{vec_first_mismatch_index} | |
18633 | @tab @code{vec_first_mismatch_or_eos_index} | |
18634 | @item @code{vec_float} | |
18635 | @tab @code{vec_float2} | |
18636 | @tab @code{vec_floate} | |
18637 | @item @code{vec_floato} | |
18638 | @tab @code{vec_floor} | |
18639 | @tab @code{vec_gb} | |
18640 | @item @code{vec_insert} | |
18641 | @tab @code{vec_insert_exp} | |
18642 | @tab @code{vec_insert4b} | |
18643 | @item @code{vec_ld} | |
18644 | @tab @code{vec_lde} | |
18645 | @tab @code{vec_ldl} | |
18646 | @item @code{vec_loge} | |
18647 | @tab @code{vec_madd} | |
18648 | @tab @code{vec_madds} | |
18649 | @item @code{vec_max} | |
18650 | @tab @code{vec_mergee} | |
18651 | @tab @code{vec_mergeh} | |
18652 | @item @code{vec_mergel} | |
18653 | @tab @code{vec_mergeo} | |
18654 | @tab @code{vec_mfvscr} | |
18655 | @item @code{vec_min} | |
18656 | @tab @code{vec_mradds} | |
18657 | @tab @code{vec_msub} | |
18658 | @item @code{vec_msum} | |
18659 | @tab @code{vec_msums} | |
18660 | @tab @code{vec_mtvscr} | |
18661 | @item @code{vec_mul} | |
18662 | @tab @code{vec_mule} | |
18663 | @tab @code{vec_mulo} | |
18664 | @item @code{vec_nabs} | |
18665 | @tab @code{vec_nand} | |
18666 | @tab @code{vec_ncipher_be} | |
18667 | @item @code{vec_ncipherlast_be} | |
18668 | @tab @code{vec_nearbyint} | |
18669 | @tab @code{vec_neg} | |
18670 | @item @code{vec_nmadd} | |
18671 | @tab @code{vec_nmsub} | |
18672 | @tab @code{vec_nor} | |
18673 | @item @code{vec_or} | |
18674 | @tab @code{vec_orc} | |
18675 | @tab @code{vec_pack} | |
18676 | @item @code{vec_pack_to_short_fp32} | |
18677 | @tab @code{vec_packpx} | |
18678 | @tab @code{vec_packs} | |
18679 | @item @code{vec_packsu} | |
18680 | @tab @code{vec_parity_lsbb} | |
18681 | @tab @code{vec_perm} | |
18682 | @item @code{vec_permxor} | |
18683 | @tab @code{vec_pmsum_be} | |
18684 | @tab @code{vec_popcnt} | |
18685 | @item @code{vec_re} | |
18686 | @tab @code{vec_recipdiv} | |
18687 | @tab @code{vec_revb} | |
18688 | @item @code{vec_reve} | |
18689 | @tab @code{vec_rint} | |
18690 | @tab @code{vec_rl} | |
18691 | @item @code{vec_rlmi} | |
18692 | @tab @code{vec_rlnm} | |
18693 | @tab @code{vec_round} | |
18694 | @item @code{vec_rsqrt} | |
18695 | @tab @code{vec_rsqrte} | |
18696 | @tab @code{vec_sbox_be} | |
18697 | @item @code{vec_sel} | |
18698 | @tab @code{vec_shasigma_be} | |
18699 | @tab @code{vec_signed} | |
18700 | @item @code{vec_signed2} | |
18701 | @tab @code{vec_signede} | |
18702 | @tab @code{vec_signedo} | |
18703 | @item @code{vec_sl} | |
18704 | @tab @code{vec_sld} | |
18705 | @tab @code{vec_sldw} | |
18706 | @item @code{vec_sll} | |
18707 | @tab @code{vec_slo} | |
18708 | @tab @code{vec_slv} | |
18709 | @item @code{vec_splat} | |
18710 | @tab @code{vec_splat_s8} | |
18711 | @tab @code{vec_splat_s16} | |
18712 | @item @code{vec_splat_s32} | |
18713 | @tab @code{vec_splat_u8} | |
18714 | @tab @code{vec_splat_u16} | |
18715 | @item @code{vec_splat_u32} | |
18716 | @tab @code{vec_splats} | |
18717 | @tab @code{vec_sqrt} | |
18718 | @item @code{vec_sr} | |
18719 | @tab @code{vec_sra} | |
18720 | @tab @code{vec_srl} | |
18721 | @item @code{vec_sro} | |
18722 | @tab @code{vec_srv} | |
18723 | @tab @code{vec_st} | |
18724 | @item @code{vec_ste} | |
18725 | @tab @code{vec_stl} | |
18726 | @tab @code{vec_sub} | |
18727 | @item @code{vec_subc} | |
18728 | @tab @code{vec_sube} | |
18729 | @tab @code{vec_subec} | |
18730 | @item @code{vec_subs} | |
18731 | @tab @code{vec_sum2s} | |
18732 | @tab @code{vec_sum4s} | |
18733 | @item @code{vec_sums} | |
18734 | @tab @code{vec_test_data_class} | |
18735 | @tab @code{vec_trunc} | |
18736 | @item @code{vec_unpackh} | |
18737 | @tab @code{vec_unpackl} | |
18738 | @tab @code{vec_unsigned} | |
18739 | @item @code{vec_unsigned2} | |
18740 | @tab @code{vec_unsignede} | |
18741 | @tab @code{vec_unsignedo} | |
18742 | @item @code{vec_xl} | |
18743 | @tab @code{vec_xl_be} | |
18744 | @tab @code{vec_xl_len} | |
18745 | @item @code{vec_xl_len_r} | |
18746 | @tab @code{vec_xor} | |
18747 | @tab @code{vec_xst} | |
18748 | @item @code{vec_xst_be} | |
18749 | @tab @code{vec_xst_len} | |
18750 | @tab @code{vec_xst_len_r} | |
18751 | ||
18752 | @end multitable | |
18753 | ||
18754 | @menu | |
18755 | * PowerPC AltiVec Built-in Functions on ISA 2.05:: | |
18756 | * PowerPC AltiVec Built-in Functions Available on ISA 2.06:: | |
18757 | * PowerPC AltiVec Built-in Functions Available on ISA 2.07:: | |
18758 | * PowerPC AltiVec Built-in Functions Available on ISA 3.0:: | |
18759 | * PowerPC AltiVec Built-in Functions Available on ISA 3.1:: | |
18760 | @end menu | |
18761 | ||
18762 | @node PowerPC AltiVec Built-in Functions on ISA 2.05 | |
18763 | @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05 | |
18764 | ||
18765 | The following interfaces are supported for the generic and specific | |
18766 | AltiVec operations and the AltiVec predicates. In cases where there | |
18767 | is a direct mapping between generic and specific operations, only the | |
18768 | generic names are shown here, although the specific operations can also | |
18769 | be used. | |
18770 | ||
18771 | Arguments that are documented as @code{const int} require literal | |
18772 | integral values within the range required for that operation. | |
18773 | ||
18774 | Only functions excluded from the PVIPR are listed here. | |
18775 | ||
18776 | @smallexample | |
18777 | void vec_dss (const int); | |
18778 | ||
18779 | void vec_dssall (void); | |
18780 | ||
18781 | void vec_dst (const vector unsigned char *, int, const int); | |
18782 | void vec_dst (const vector signed char *, int, const int); | |
18783 | void vec_dst (const vector bool char *, int, const int); | |
18784 | void vec_dst (const vector unsigned short *, int, const int); | |
18785 | void vec_dst (const vector signed short *, int, const int); | |
18786 | void vec_dst (const vector bool short *, int, const int); | |
18787 | void vec_dst (const vector pixel *, int, const int); | |
18788 | void vec_dst (const vector unsigned int *, int, const int); | |
18789 | void vec_dst (const vector signed int *, int, const int); | |
18790 | void vec_dst (const vector bool int *, int, const int); | |
18791 | void vec_dst (const vector float *, int, const int); | |
18792 | void vec_dst (const unsigned char *, int, const int); | |
18793 | void vec_dst (const signed char *, int, const int); | |
18794 | void vec_dst (const unsigned short *, int, const int); | |
18795 | void vec_dst (const short *, int, const int); | |
18796 | void vec_dst (const unsigned int *, int, const int); | |
18797 | void vec_dst (const int *, int, const int); | |
18798 | void vec_dst (const float *, int, const int); | |
18799 | ||
18800 | void vec_dstst (const vector unsigned char *, int, const int); | |
18801 | void vec_dstst (const vector signed char *, int, const int); | |
18802 | void vec_dstst (const vector bool char *, int, const int); | |
18803 | void vec_dstst (const vector unsigned short *, int, const int); | |
18804 | void vec_dstst (const vector signed short *, int, const int); | |
18805 | void vec_dstst (const vector bool short *, int, const int); | |
18806 | void vec_dstst (const vector pixel *, int, const int); | |
18807 | void vec_dstst (const vector unsigned int *, int, const int); | |
18808 | void vec_dstst (const vector signed int *, int, const int); | |
18809 | void vec_dstst (const vector bool int *, int, const int); | |
18810 | void vec_dstst (const vector float *, int, const int); | |
18811 | void vec_dstst (const unsigned char *, int, const int); | |
18812 | void vec_dstst (const signed char *, int, const int); | |
18813 | void vec_dstst (const unsigned short *, int, const int); | |
18814 | void vec_dstst (const short *, int, const int); | |
18815 | void vec_dstst (const unsigned int *, int, const int); | |
18816 | void vec_dstst (const int *, int, const int); | |
18817 | void vec_dstst (const unsigned long *, int, const int); | |
18818 | void vec_dstst (const long *, int, const int); | |
18819 | void vec_dstst (const float *, int, const int); | |
18820 | ||
18821 | void vec_dststt (const vector unsigned char *, int, const int); | |
18822 | void vec_dststt (const vector signed char *, int, const int); | |
18823 | void vec_dststt (const vector bool char *, int, const int); | |
18824 | void vec_dststt (const vector unsigned short *, int, const int); | |
18825 | void vec_dststt (const vector signed short *, int, const int); | |
18826 | void vec_dststt (const vector bool short *, int, const int); | |
18827 | void vec_dststt (const vector pixel *, int, const int); | |
18828 | void vec_dststt (const vector unsigned int *, int, const int); | |
18829 | void vec_dststt (const vector signed int *, int, const int); | |
18830 | void vec_dststt (const vector bool int *, int, const int); | |
18831 | void vec_dststt (const vector float *, int, const int); | |
18832 | void vec_dststt (const unsigned char *, int, const int); | |
18833 | void vec_dststt (const signed char *, int, const int); | |
18834 | void vec_dststt (const unsigned short *, int, const int); | |
18835 | void vec_dststt (const short *, int, const int); | |
18836 | void vec_dststt (const unsigned int *, int, const int); | |
18837 | void vec_dststt (const int *, int, const int); | |
18838 | void vec_dststt (const float *, int, const int); | |
18839 | ||
18840 | void vec_dstt (const vector unsigned char *, int, const int); | |
18841 | void vec_dstt (const vector signed char *, int, const int); | |
18842 | void vec_dstt (const vector bool char *, int, const int); | |
18843 | void vec_dstt (const vector unsigned short *, int, const int); | |
18844 | void vec_dstt (const vector signed short *, int, const int); | |
18845 | void vec_dstt (const vector bool short *, int, const int); | |
18846 | void vec_dstt (const vector pixel *, int, const int); | |
18847 | void vec_dstt (const vector unsigned int *, int, const int); | |
18848 | void vec_dstt (const vector signed int *, int, const int); | |
18849 | void vec_dstt (const vector bool int *, int, const int); | |
18850 | void vec_dstt (const vector float *, int, const int); | |
18851 | void vec_dstt (const unsigned char *, int, const int); | |
18852 | void vec_dstt (const signed char *, int, const int); | |
18853 | void vec_dstt (const unsigned short *, int, const int); | |
18854 | void vec_dstt (const short *, int, const int); | |
18855 | void vec_dstt (const unsigned int *, int, const int); | |
18856 | void vec_dstt (const int *, int, const int); | |
18857 | void vec_dstt (const float *, int, const int); | |
18858 | ||
18859 | vector signed char vec_lvebx (int, char *); | |
18860 | vector unsigned char vec_lvebx (int, unsigned char *); | |
18861 | ||
18862 | vector signed short vec_lvehx (int, short *); | |
18863 | vector unsigned short vec_lvehx (int, unsigned short *); | |
18864 | ||
18865 | vector float vec_lvewx (int, float *); | |
18866 | vector signed int vec_lvewx (int, int *); | |
18867 | vector unsigned int vec_lvewx (int, unsigned int *); | |
18868 | ||
18869 | vector unsigned char vec_lvsl (int, const unsigned char *); | |
18870 | vector unsigned char vec_lvsl (int, const signed char *); | |
18871 | vector unsigned char vec_lvsl (int, const unsigned short *); | |
18872 | vector unsigned char vec_lvsl (int, const short *); | |
18873 | vector unsigned char vec_lvsl (int, const unsigned int *); | |
18874 | vector unsigned char vec_lvsl (int, const int *); | |
18875 | vector unsigned char vec_lvsl (int, const float *); | |
18876 | ||
18877 | vector unsigned char vec_lvsr (int, const unsigned char *); | |
18878 | vector unsigned char vec_lvsr (int, const signed char *); | |
18879 | vector unsigned char vec_lvsr (int, const unsigned short *); | |
18880 | vector unsigned char vec_lvsr (int, const short *); | |
18881 | vector unsigned char vec_lvsr (int, const unsigned int *); | |
18882 | vector unsigned char vec_lvsr (int, const int *); | |
18883 | vector unsigned char vec_lvsr (int, const float *); | |
18884 | ||
18885 | void vec_stvebx (vector signed char, int, signed char *); | |
18886 | void vec_stvebx (vector unsigned char, int, unsigned char *); | |
18887 | void vec_stvebx (vector bool char, int, signed char *); | |
18888 | void vec_stvebx (vector bool char, int, unsigned char *); | |
18889 | ||
18890 | void vec_stvehx (vector signed short, int, short *); | |
18891 | void vec_stvehx (vector unsigned short, int, unsigned short *); | |
18892 | void vec_stvehx (vector bool short, int, short *); | |
18893 | void vec_stvehx (vector bool short, int, unsigned short *); | |
18894 | ||
18895 | void vec_stvewx (vector float, int, float *); | |
18896 | void vec_stvewx (vector signed int, int, int *); | |
18897 | void vec_stvewx (vector unsigned int, int, unsigned int *); | |
18898 | void vec_stvewx (vector bool int, int, int *); | |
18899 | void vec_stvewx (vector bool int, int, unsigned int *); | |
18900 | ||
18901 | vector float vec_vaddfp (vector float, vector float); | |
18902 | ||
18903 | vector signed char vec_vaddsbs (vector bool char, vector signed char); | |
18904 | vector signed char vec_vaddsbs (vector signed char, vector bool char); | |
18905 | vector signed char vec_vaddsbs (vector signed char, vector signed char); | |
18906 | ||
18907 | vector signed short vec_vaddshs (vector bool short, vector signed short); | |
18908 | vector signed short vec_vaddshs (vector signed short, vector bool short); | |
18909 | vector signed short vec_vaddshs (vector signed short, vector signed short); | |
18910 | ||
18911 | vector signed int vec_vaddsws (vector bool int, vector signed int); | |
18912 | vector signed int vec_vaddsws (vector signed int, vector bool int); | |
18913 | vector signed int vec_vaddsws (vector signed int, vector signed int); | |
18914 | ||
18915 | vector signed char vec_vaddubm (vector bool char, vector signed char); | |
18916 | vector signed char vec_vaddubm (vector signed char, vector bool char); | |
18917 | vector signed char vec_vaddubm (vector signed char, vector signed char); | |
18918 | vector unsigned char vec_vaddubm (vector bool char, vector unsigned char); | |
18919 | vector unsigned char vec_vaddubm (vector unsigned char, vector bool char); | |
18920 | vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char); | |
18921 | ||
18922 | vector unsigned char vec_vaddubs (vector bool char, vector unsigned char); | |
18923 | vector unsigned char vec_vaddubs (vector unsigned char, vector bool char); | |
18924 | vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char); | |
18925 | ||
18926 | vector signed short vec_vadduhm (vector bool short, vector signed short); | |
18927 | vector signed short vec_vadduhm (vector signed short, vector bool short); | |
18928 | vector signed short vec_vadduhm (vector signed short, vector signed short); | |
18929 | vector unsigned short vec_vadduhm (vector bool short, vector unsigned short); | |
18930 | vector unsigned short vec_vadduhm (vector unsigned short, vector bool short); | |
18931 | vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short); | |
18932 | ||
18933 | vector unsigned short vec_vadduhs (vector bool short, vector unsigned short); | |
18934 | vector unsigned short vec_vadduhs (vector unsigned short, vector bool short); | |
18935 | vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short); | |
18936 | ||
18937 | vector signed int vec_vadduwm (vector bool int, vector signed int); | |
18938 | vector signed int vec_vadduwm (vector signed int, vector bool int); | |
18939 | vector signed int vec_vadduwm (vector signed int, vector signed int); | |
18940 | vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); | |
18941 | vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); | |
18942 | vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int); | |
18943 | ||
18944 | vector unsigned int vec_vadduws (vector bool int, vector unsigned int); | |
18945 | vector unsigned int vec_vadduws (vector unsigned int, vector bool int); | |
18946 | vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int); | |
18947 | ||
18948 | vector signed char vec_vavgsb (vector signed char, vector signed char); | |
18949 | ||
18950 | vector signed short vec_vavgsh (vector signed short, vector signed short); | |
18951 | ||
18952 | vector signed int vec_vavgsw (vector signed int, vector signed int); | |
18953 | ||
18954 | vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char); | |
18955 | ||
18956 | vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short); | |
18957 | ||
18958 | vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int); | |
18959 | ||
18960 | vector float vec_vcfsx (vector signed int, const int); | |
18961 | ||
18962 | vector float vec_vcfux (vector unsigned int, const int); | |
18963 | ||
18964 | vector bool int vec_vcmpeqfp (vector float, vector float); | |
18965 | ||
18966 | vector bool char vec_vcmpequb (vector signed char, vector signed char); | |
18967 | vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char); | |
18968 | ||
18969 | vector bool short vec_vcmpequh (vector signed short, vector signed short); | |
18970 | vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short); | |
18971 | ||
18972 | vector bool int vec_vcmpequw (vector signed int, vector signed int); | |
18973 | vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); | |
18974 | ||
18975 | vector bool int vec_vcmpgtfp (vector float, vector float); | |
18976 | ||
18977 | vector bool char vec_vcmpgtsb (vector signed char, vector signed char); | |
18978 | ||
18979 | vector bool short vec_vcmpgtsh (vector signed short, vector signed short); | |
18980 | ||
18981 | vector bool int vec_vcmpgtsw (vector signed int, vector signed int); | |
18982 | ||
18983 | vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char); | |
18984 | ||
18985 | vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short); | |
18986 | ||
18987 | vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); | |
18988 | ||
18989 | vector float vec_vmaxfp (vector float, vector float); | |
18990 | ||
18991 | vector signed char vec_vmaxsb (vector bool char, vector signed char); | |
18992 | vector signed char vec_vmaxsb (vector signed char, vector bool char); | |
18993 | vector signed char vec_vmaxsb (vector signed char, vector signed char); | |
18994 | ||
18995 | vector signed short vec_vmaxsh (vector bool short, vector signed short); | |
18996 | vector signed short vec_vmaxsh (vector signed short, vector bool short); | |
18997 | vector signed short vec_vmaxsh (vector signed short, vector signed short); | |
18998 | ||
18999 | vector signed int vec_vmaxsw (vector bool int, vector signed int); | |
19000 | vector signed int vec_vmaxsw (vector signed int, vector bool int); | |
19001 | vector signed int vec_vmaxsw (vector signed int, vector signed int); | |
19002 | ||
19003 | vector unsigned char vec_vmaxub (vector bool char, vector unsigned char); | |
19004 | vector unsigned char vec_vmaxub (vector unsigned char, vector bool char); | |
19005 | vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char); | |
19006 | ||
19007 | vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short); | |
19008 | vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short); | |
19009 | vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short); | |
19010 | ||
19011 | vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); | |
19012 | vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); | |
19013 | vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int); | |
19014 | ||
19015 | vector float vec_vminfp (vector float, vector float); | |
19016 | ||
19017 | vector signed char vec_vminsb (vector bool char, vector signed char); | |
19018 | vector signed char vec_vminsb (vector signed char, vector bool char); | |
19019 | vector signed char vec_vminsb (vector signed char, vector signed char); | |
19020 | ||
19021 | vector signed short vec_vminsh (vector bool short, vector signed short); | |
19022 | vector signed short vec_vminsh (vector signed short, vector bool short); | |
19023 | vector signed short vec_vminsh (vector signed short, vector signed short); | |
19024 | ||
19025 | vector signed int vec_vminsw (vector bool int, vector signed int); | |
19026 | vector signed int vec_vminsw (vector signed int, vector bool int); | |
19027 | vector signed int vec_vminsw (vector signed int, vector signed int); | |
19028 | ||
19029 | vector unsigned char vec_vminub (vector bool char, vector unsigned char); | |
19030 | vector unsigned char vec_vminub (vector unsigned char, vector bool char); | |
19031 | vector unsigned char vec_vminub (vector unsigned char, vector unsigned char); | |
19032 | ||
19033 | vector unsigned short vec_vminuh (vector bool short, vector unsigned short); | |
19034 | vector unsigned short vec_vminuh (vector unsigned short, vector bool short); | |
19035 | vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short); | |
19036 | ||
19037 | vector unsigned int vec_vminuw (vector bool int, vector unsigned int); | |
19038 | vector unsigned int vec_vminuw (vector unsigned int, vector bool int); | |
19039 | vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int); | |
19040 | ||
19041 | vector bool char vec_vmrghb (vector bool char, vector bool char); | |
19042 | vector signed char vec_vmrghb (vector signed char, vector signed char); | |
19043 | vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char); | |
19044 | ||
19045 | vector bool short vec_vmrghh (vector bool short, vector bool short); | |
19046 | vector signed short vec_vmrghh (vector signed short, vector signed short); | |
19047 | vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short); | |
19048 | vector pixel vec_vmrghh (vector pixel, vector pixel); | |
19049 | ||
19050 | vector float vec_vmrghw (vector float, vector float); | |
19051 | vector bool int vec_vmrghw (vector bool int, vector bool int); | |
19052 | vector signed int vec_vmrghw (vector signed int, vector signed int); | |
19053 | vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int); | |
19054 | ||
19055 | vector bool char vec_vmrglb (vector bool char, vector bool char); | |
19056 | vector signed char vec_vmrglb (vector signed char, vector signed char); | |
19057 | vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char); | |
19058 | ||
19059 | vector bool short vec_vmrglh (vector bool short, vector bool short); | |
19060 | vector signed short vec_vmrglh (vector signed short, vector signed short); | |
19061 | vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short); | |
19062 | vector pixel vec_vmrglh (vector pixel, vector pixel); | |
19063 | ||
19064 | vector float vec_vmrglw (vector float, vector float); | |
19065 | vector signed int vec_vmrglw (vector signed int, vector signed int); | |
19066 | vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int); | |
19067 | vector bool int vec_vmrglw (vector bool int, vector bool int); | |
19068 | ||
19069 | vector signed int vec_vmsummbm (vector signed char, vector unsigned char, | |
19070 | vector signed int); | |
19071 | ||
19072 | vector signed int vec_vmsumshm (vector signed short, vector signed short, | |
19073 | vector signed int); | |
19074 | ||
19075 | vector signed int vec_vmsumshs (vector signed short, vector signed short, | |
19076 | vector signed int); | |
19077 | ||
19078 | vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char, | |
19079 | vector unsigned int); | |
19080 | ||
19081 | vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short, | |
19082 | vector unsigned int); | |
19083 | ||
19084 | vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short, | |
19085 | vector unsigned int); | |
19086 | ||
19087 | vector signed short vec_vmulesb (vector signed char, vector signed char); | |
19088 | ||
19089 | vector signed int vec_vmulesh (vector signed short, vector signed short); | |
19090 | ||
19091 | vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char); | |
19092 | ||
19093 | vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short); | |
19094 | ||
19095 | vector signed short vec_vmulosb (vector signed char, vector signed char); | |
19096 | ||
19097 | vector signed int vec_vmulosh (vector signed short, vector signed short); | |
19098 | ||
19099 | vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char); | |
19100 | ||
19101 | vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short); | |
19102 | ||
19103 | vector signed char vec_vpkshss (vector signed short, vector signed short); | |
19104 | ||
19105 | vector unsigned char vec_vpkshus (vector signed short, vector signed short); | |
19106 | ||
19107 | vector signed short vec_vpkswss (vector signed int, vector signed int); | |
19108 | ||
19109 | vector unsigned short vec_vpkswus (vector signed int, vector signed int); | |
19110 | ||
19111 | vector bool char vec_vpkuhum (vector bool short, vector bool short); | |
19112 | vector signed char vec_vpkuhum (vector signed short, vector signed short); | |
19113 | vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short); | |
19114 | ||
19115 | vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short); | |
19116 | ||
19117 | vector bool short vec_vpkuwum (vector bool int, vector bool int); | |
19118 | vector signed short vec_vpkuwum (vector signed int, vector signed int); | |
19119 | vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int); | |
19120 | ||
19121 | vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int); | |
19122 | ||
19123 | vector signed char vec_vrlb (vector signed char, vector unsigned char); | |
19124 | vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char); | |
19125 | ||
19126 | vector signed short vec_vrlh (vector signed short, vector unsigned short); | |
19127 | vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short); | |
19128 | ||
19129 | vector signed int vec_vrlw (vector signed int, vector unsigned int); | |
19130 | vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); | |
19131 | ||
19132 | vector signed char vec_vslb (vector signed char, vector unsigned char); | |
19133 | vector unsigned char vec_vslb (vector unsigned char, vector unsigned char); | |
19134 | ||
19135 | vector signed short vec_vslh (vector signed short, vector unsigned short); | |
19136 | vector unsigned short vec_vslh (vector unsigned short, vector unsigned short); | |
19137 | ||
19138 | vector signed int vec_vslw (vector signed int, vector unsigned int); | |
19139 | vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); | |
19140 | ||
19141 | vector signed char vec_vspltb (vector signed char, const int); | |
19142 | vector unsigned char vec_vspltb (vector unsigned char, const int); | |
19143 | vector bool char vec_vspltb (vector bool char, const int); | |
19144 | ||
19145 | vector bool short vec_vsplth (vector bool short, const int); | |
19146 | vector signed short vec_vsplth (vector signed short, const int); | |
19147 | vector unsigned short vec_vsplth (vector unsigned short, const int); | |
19148 | vector pixel vec_vsplth (vector pixel, const int); | |
19149 | ||
19150 | vector float vec_vspltw (vector float, const int); | |
19151 | vector signed int vec_vspltw (vector signed int, const int); | |
19152 | vector unsigned int vec_vspltw (vector unsigned int, const int); | |
19153 | vector bool int vec_vspltw (vector bool int, const int); | |
19154 | ||
19155 | vector signed char vec_vsrab (vector signed char, vector unsigned char); | |
19156 | vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char); | |
19157 | ||
19158 | vector signed short vec_vsrah (vector signed short, vector unsigned short); | |
19159 | vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short); | |
19160 | ||
19161 | vector signed int vec_vsraw (vector signed int, vector unsigned int); | |
19162 | vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int); | |
19163 | ||
19164 | vector signed char vec_vsrb (vector signed char, vector unsigned char); | |
19165 | vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char); | |
19166 | ||
19167 | vector signed short vec_vsrh (vector signed short, vector unsigned short); | |
19168 | vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short); | |
19169 | ||
19170 | vector signed int vec_vsrw (vector signed int, vector unsigned int); | |
19171 | vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); | |
19172 | ||
19173 | vector float vec_vsubfp (vector float, vector float); | |
19174 | ||
19175 | vector signed char vec_vsubsbs (vector bool char, vector signed char); | |
19176 | vector signed char vec_vsubsbs (vector signed char, vector bool char); | |
19177 | vector signed char vec_vsubsbs (vector signed char, vector signed char); | |
19178 | ||
19179 | vector signed short vec_vsubshs (vector bool short, vector signed short); | |
19180 | vector signed short vec_vsubshs (vector signed short, vector bool short); | |
19181 | vector signed short vec_vsubshs (vector signed short, vector signed short); | |
19182 | ||
19183 | vector signed int vec_vsubsws (vector bool int, vector signed int); | |
19184 | vector signed int vec_vsubsws (vector signed int, vector bool int); | |
19185 | vector signed int vec_vsubsws (vector signed int, vector signed int); | |
19186 | ||
19187 | vector signed char vec_vsububm (vector bool char, vector signed char); | |
19188 | vector signed char vec_vsububm (vector signed char, vector bool char); | |
19189 | vector signed char vec_vsububm (vector signed char, vector signed char); | |
19190 | vector unsigned char vec_vsububm (vector bool char, vector unsigned char); | |
19191 | vector unsigned char vec_vsububm (vector unsigned char, vector bool char); | |
19192 | vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char); | |
19193 | ||
19194 | vector unsigned char vec_vsububs (vector bool char, vector unsigned char); | |
19195 | vector unsigned char vec_vsububs (vector unsigned char, vector bool char); | |
19196 | vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char); | |
19197 | ||
19198 | vector signed short vec_vsubuhm (vector bool short, vector signed short); | |
19199 | vector signed short vec_vsubuhm (vector signed short, vector bool short); | |
19200 | vector signed short vec_vsubuhm (vector signed short, vector signed short); | |
19201 | vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short); | |
19202 | vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short); | |
19203 | vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short); | |
19204 | ||
19205 | vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short); | |
19206 | vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short); | |
19207 | vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short); | |
19208 | ||
19209 | vector signed int vec_vsubuwm (vector bool int, vector signed int); | |
19210 | vector signed int vec_vsubuwm (vector signed int, vector bool int); | |
19211 | vector signed int vec_vsubuwm (vector signed int, vector signed int); | |
19212 | vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); | |
19213 | vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); | |
19214 | vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int); | |
19215 | ||
19216 | vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); | |
19217 | vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); | |
19218 | vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int); | |
19219 | ||
19220 | vector signed int vec_vsum4sbs (vector signed char, vector signed int); | |
19221 | ||
19222 | vector signed int vec_vsum4shs (vector signed short, vector signed int); | |
19223 | ||
19224 | vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int); | |
19225 | ||
19226 | vector unsigned int vec_vupkhpx (vector pixel); | |
19227 | ||
19228 | vector bool short vec_vupkhsb (vector bool char); | |
19229 | vector signed short vec_vupkhsb (vector signed char); | |
19230 | ||
19231 | vector bool int vec_vupkhsh (vector bool short); | |
19232 | vector signed int vec_vupkhsh (vector signed short); | |
19233 | ||
19234 | vector unsigned int vec_vupklpx (vector pixel); | |
19235 | ||
19236 | vector bool short vec_vupklsb (vector bool char); | |
19237 | vector signed short vec_vupklsb (vector signed char); | |
19238 | ||
19239 | vector bool int vec_vupklsh (vector bool short); | |
19240 | vector signed int vec_vupklsh (vector signed short); | |
19241 | @end smallexample | |
19242 | ||
19243 | @node PowerPC AltiVec Built-in Functions Available on ISA 2.06 | |
19244 | @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06 | |
19245 | ||
19246 | The AltiVec built-in functions described in this section are | |
19247 | available on the PowerPC family of processors starting with ISA 2.06 | |
19248 | or later. These are normally enabled by adding @option{-mvsx} to the | |
19249 | command line. | |
19250 | ||
19251 | When @option{-mvsx} is used, the following additional vector types are | |
19252 | implemented. | |
19253 | ||
19254 | @smallexample | |
19255 | vector unsigned __int128 | |
19256 | vector signed __int128 | |
19257 | vector unsigned long long int | |
19258 | vector signed long long int | |
19259 | vector double | |
19260 | @end smallexample | |
19261 | ||
19262 | The long long types are only implemented for 64-bit code generation. | |
19263 | ||
19264 | Only functions excluded from the PVIPR are listed here. | |
19265 | ||
19266 | @smallexample | |
19267 | void vec_dst (const unsigned long *, int, const int); | |
19268 | void vec_dst (const long *, int, const int); | |
19269 | ||
19270 | void vec_dststt (const unsigned long *, int, const int); | |
19271 | void vec_dststt (const long *, int, const int); | |
19272 | ||
19273 | void vec_dstt (const unsigned long *, int, const int); | |
19274 | void vec_dstt (const long *, int, const int); | |
19275 | ||
19276 | vector unsigned char vec_lvsl (int, const unsigned long *); | |
19277 | vector unsigned char vec_lvsl (int, const long *); | |
19278 | ||
19279 | vector unsigned char vec_lvsr (int, const unsigned long *); | |
19280 | vector unsigned char vec_lvsr (int, const long *); | |
19281 | ||
19282 | vector unsigned char vec_lvsl (int, const double *); | |
19283 | vector unsigned char vec_lvsr (int, const double *); | |
19284 | ||
19285 | vector double vec_vsx_ld (int, const vector double *); | |
19286 | vector double vec_vsx_ld (int, const double *); | |
19287 | vector float vec_vsx_ld (int, const vector float *); | |
19288 | vector float vec_vsx_ld (int, const float *); | |
19289 | vector bool int vec_vsx_ld (int, const vector bool int *); | |
19290 | vector signed int vec_vsx_ld (int, const vector signed int *); | |
19291 | vector signed int vec_vsx_ld (int, const int *); | |
19292 | vector signed int vec_vsx_ld (int, const long *); | |
19293 | vector unsigned int vec_vsx_ld (int, const vector unsigned int *); | |
19294 | vector unsigned int vec_vsx_ld (int, const unsigned int *); | |
19295 | vector unsigned int vec_vsx_ld (int, const unsigned long *); | |
19296 | vector bool short vec_vsx_ld (int, const vector bool short *); | |
19297 | vector pixel vec_vsx_ld (int, const vector pixel *); | |
19298 | vector signed short vec_vsx_ld (int, const vector signed short *); | |
19299 | vector signed short vec_vsx_ld (int, const short *); | |
19300 | vector unsigned short vec_vsx_ld (int, const vector unsigned short *); | |
19301 | vector unsigned short vec_vsx_ld (int, const unsigned short *); | |
19302 | vector bool char vec_vsx_ld (int, const vector bool char *); | |
19303 | vector signed char vec_vsx_ld (int, const vector signed char *); | |
19304 | vector signed char vec_vsx_ld (int, const signed char *); | |
19305 | vector unsigned char vec_vsx_ld (int, const vector unsigned char *); | |
19306 | vector unsigned char vec_vsx_ld (int, const unsigned char *); | |
19307 | ||
19308 | void vec_vsx_st (vector double, int, vector double *); | |
19309 | void vec_vsx_st (vector double, int, double *); | |
19310 | void vec_vsx_st (vector float, int, vector float *); | |
19311 | void vec_vsx_st (vector float, int, float *); | |
19312 | void vec_vsx_st (vector signed int, int, vector signed int *); | |
19313 | void vec_vsx_st (vector signed int, int, int *); | |
19314 | void vec_vsx_st (vector unsigned int, int, vector unsigned int *); | |
19315 | void vec_vsx_st (vector unsigned int, int, unsigned int *); | |
19316 | void vec_vsx_st (vector bool int, int, vector bool int *); | |
19317 | void vec_vsx_st (vector bool int, int, unsigned int *); | |
19318 | void vec_vsx_st (vector bool int, int, int *); | |
19319 | void vec_vsx_st (vector signed short, int, vector signed short *); | |
19320 | void vec_vsx_st (vector signed short, int, short *); | |
19321 | void vec_vsx_st (vector unsigned short, int, vector unsigned short *); | |
19322 | void vec_vsx_st (vector unsigned short, int, unsigned short *); | |
19323 | void vec_vsx_st (vector bool short, int, vector bool short *); | |
19324 | void vec_vsx_st (vector bool short, int, unsigned short *); | |
19325 | void vec_vsx_st (vector pixel, int, vector pixel *); | |
19326 | void vec_vsx_st (vector pixel, int, unsigned short *); | |
19327 | void vec_vsx_st (vector pixel, int, short *); | |
19328 | void vec_vsx_st (vector bool short, int, short *); | |
19329 | void vec_vsx_st (vector signed char, int, vector signed char *); | |
19330 | void vec_vsx_st (vector signed char, int, signed char *); | |
19331 | void vec_vsx_st (vector unsigned char, int, vector unsigned char *); | |
19332 | void vec_vsx_st (vector unsigned char, int, unsigned char *); | |
19333 | void vec_vsx_st (vector bool char, int, vector bool char *); | |
19334 | void vec_vsx_st (vector bool char, int, unsigned char *); | |
19335 | void vec_vsx_st (vector bool char, int, signed char *); | |
19336 | ||
19337 | vector double vec_xxpermdi (vector double, vector double, const int); | |
19338 | vector float vec_xxpermdi (vector float, vector float, const int); | |
19339 | vector long long vec_xxpermdi (vector long long, vector long long, const int); | |
19340 | vector unsigned long long vec_xxpermdi (vector unsigned long long, | |
19341 | vector unsigned long long, const int); | |
19342 | vector int vec_xxpermdi (vector int, vector int, const int); | |
19343 | vector unsigned int vec_xxpermdi (vector unsigned int, | |
19344 | vector unsigned int, const int); | |
19345 | vector short vec_xxpermdi (vector short, vector short, const int); | |
19346 | vector unsigned short vec_xxpermdi (vector unsigned short, | |
19347 | vector unsigned short, const int); | |
19348 | vector signed char vec_xxpermdi (vector signed char, vector signed char, | |
19349 | const int); | |
19350 | vector unsigned char vec_xxpermdi (vector unsigned char, | |
19351 | vector unsigned char, const int); | |
19352 | ||
19353 | vector double vec_xxsldi (vector double, vector double, int); | |
19354 | vector float vec_xxsldi (vector float, vector float, int); | |
19355 | vector long long vec_xxsldi (vector long long, vector long long, int); | |
19356 | vector unsigned long long vec_xxsldi (vector unsigned long long, | |
19357 | vector unsigned long long, int); | |
19358 | vector int vec_xxsldi (vector int, vector int, int); | |
19359 | vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int); | |
19360 | vector short vec_xxsldi (vector short, vector short, int); | |
19361 | vector unsigned short vec_xxsldi (vector unsigned short, | |
19362 | vector unsigned short, int); | |
19363 | vector signed char vec_xxsldi (vector signed char, vector signed char, int); | |
19364 | vector unsigned char vec_xxsldi (vector unsigned char, | |
19365 | vector unsigned char, int); | |
19366 | @end smallexample | |
19367 | ||
19368 | Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always | |
19369 | generate the AltiVec @samp{LVX} and @samp{STVX} instructions even | |
19370 | if the VSX instruction set is available. The @samp{vec_vsx_ld} and | |
19371 | @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X}, | |
19372 | @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. | |
19373 | ||
19374 | @node PowerPC AltiVec Built-in Functions Available on ISA 2.07 | |
19375 | @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07 | |
19376 | ||
19377 | If the ISA 2.07 additions to the vector/scalar (power8-vector) | |
19378 | instruction set are available, the following additional functions are | |
19379 | available for both 32-bit and 64-bit targets. For 64-bit targets, you | |
19380 | can use @var{vector long} instead of @var{vector long long}, | |
19381 | @var{vector bool long} instead of @var{vector bool long long}, and | |
19382 | @var{vector unsigned long} instead of @var{vector unsigned long long}. | |
19383 | ||
19384 | Only functions excluded from the PVIPR are listed here. | |
19385 | ||
19386 | @smallexample | |
19387 | vector long long vec_vaddudm (vector long long, vector long long); | |
19388 | vector long long vec_vaddudm (vector bool long long, vector long long); | |
19389 | vector long long vec_vaddudm (vector long long, vector bool long long); | |
19390 | vector unsigned long long vec_vaddudm (vector unsigned long long, | |
19391 | vector unsigned long long); | |
19392 | vector unsigned long long vec_vaddudm (vector bool unsigned long long, | |
19393 | vector unsigned long long); | |
19394 | vector unsigned long long vec_vaddudm (vector unsigned long long, | |
19395 | vector bool unsigned long long); | |
19396 | ||
19397 | vector long long vec_vclz (vector long long); | |
19398 | vector unsigned long long vec_vclz (vector unsigned long long); | |
19399 | vector int vec_vclz (vector int); | |
19400 | vector unsigned int vec_vclz (vector int); | |
19401 | vector short vec_vclz (vector short); | |
19402 | vector unsigned short vec_vclz (vector unsigned short); | |
19403 | vector signed char vec_vclz (vector signed char); | |
19404 | vector unsigned char vec_vclz (vector unsigned char); | |
19405 | ||
19406 | vector signed char vec_vclzb (vector signed char); | |
19407 | vector unsigned char vec_vclzb (vector unsigned char); | |
19408 | ||
19409 | vector long long vec_vclzd (vector long long); | |
19410 | vector unsigned long long vec_vclzd (vector unsigned long long); | |
19411 | ||
19412 | vector short vec_vclzh (vector short); | |
19413 | vector unsigned short vec_vclzh (vector unsigned short); | |
19414 | ||
19415 | vector int vec_vclzw (vector int); | |
19416 | vector unsigned int vec_vclzw (vector int); | |
19417 | ||
19418 | vector signed char vec_vgbbd (vector signed char); | |
19419 | vector unsigned char vec_vgbbd (vector unsigned char); | |
19420 | ||
19421 | vector long long vec_vmaxsd (vector long long, vector long long); | |
19422 | ||
19423 | vector unsigned long long vec_vmaxud (vector unsigned long long, | |
19424 | unsigned vector long long); | |
19425 | ||
19426 | vector long long vec_vminsd (vector long long, vector long long); | |
19427 | ||
19428 | vector unsigned long long vec_vminud (vector long long, vector long long); | |
19429 | ||
19430 | vector int vec_vpksdss (vector long long, vector long long); | |
19431 | vector unsigned int vec_vpksdss (vector long long, vector long long); | |
19432 | ||
19433 | vector unsigned int vec_vpkudus (vector unsigned long long, | |
19434 | vector unsigned long long); | |
19435 | ||
19436 | vector int vec_vpkudum (vector long long, vector long long); | |
19437 | vector unsigned int vec_vpkudum (vector unsigned long long, | |
19438 | vector unsigned long long); | |
19439 | vector bool int vec_vpkudum (vector bool long long, vector bool long long); | |
19440 | ||
19441 | vector long long vec_vpopcnt (vector long long); | |
19442 | vector unsigned long long vec_vpopcnt (vector unsigned long long); | |
19443 | vector int vec_vpopcnt (vector int); | |
19444 | vector unsigned int vec_vpopcnt (vector int); | |
19445 | vector short vec_vpopcnt (vector short); | |
19446 | vector unsigned short vec_vpopcnt (vector unsigned short); | |
19447 | vector signed char vec_vpopcnt (vector signed char); | |
19448 | vector unsigned char vec_vpopcnt (vector unsigned char); | |
19449 | ||
19450 | vector signed char vec_vpopcntb (vector signed char); | |
19451 | vector unsigned char vec_vpopcntb (vector unsigned char); | |
19452 | ||
19453 | vector long long vec_vpopcntd (vector long long); | |
19454 | vector unsigned long long vec_vpopcntd (vector unsigned long long); | |
19455 | ||
19456 | vector short vec_vpopcnth (vector short); | |
19457 | vector unsigned short vec_vpopcnth (vector unsigned short); | |
19458 | ||
19459 | vector int vec_vpopcntw (vector int); | |
19460 | vector unsigned int vec_vpopcntw (vector int); | |
19461 | ||
19462 | vector long long vec_vrld (vector long long, vector unsigned long long); | |
19463 | vector unsigned long long vec_vrld (vector unsigned long long, | |
19464 | vector unsigned long long); | |
19465 | ||
19466 | vector long long vec_vsld (vector long long, vector unsigned long long); | |
19467 | vector long long vec_vsld (vector unsigned long long, | |
19468 | vector unsigned long long); | |
19469 | ||
19470 | vector long long vec_vsrad (vector long long, vector unsigned long long); | |
19471 | vector unsigned long long vec_vsrad (vector unsigned long long, | |
19472 | vector unsigned long long); | |
19473 | ||
19474 | vector long long vec_vsrd (vector long long, vector unsigned long long); | |
19475 | vector unsigned long long char vec_vsrd (vector unsigned long long, | |
19476 | vector unsigned long long); | |
19477 | ||
19478 | vector long long vec_vsubudm (vector long long, vector long long); | |
19479 | vector long long vec_vsubudm (vector bool long long, vector long long); | |
19480 | vector long long vec_vsubudm (vector long long, vector bool long long); | |
19481 | vector unsigned long long vec_vsubudm (vector unsigned long long, | |
19482 | vector unsigned long long); | |
19483 | vector unsigned long long vec_vsubudm (vector bool long long, | |
19484 | vector unsigned long long); | |
19485 | vector unsigned long long vec_vsubudm (vector unsigned long long, | |
19486 | vector bool long long); | |
19487 | ||
19488 | vector long long vec_vupkhsw (vector int); | |
19489 | vector unsigned long long vec_vupkhsw (vector unsigned int); | |
19490 | ||
19491 | vector long long vec_vupklsw (vector int); | |
19492 | vector unsigned long long vec_vupklsw (vector int); | |
19493 | @end smallexample | |
19494 | ||
19495 | If the ISA 2.07 additions to the vector/scalar (power8-vector) | |
19496 | instruction set are available, the following additional functions are | |
19497 | available for 64-bit targets. New vector types | |
19498 | (@var{vector __int128} and @var{vector __uint128}) are available | |
19499 | to hold the @var{__int128} and @var{__uint128} types to use these | |
19500 | builtins. | |
19501 | ||
19502 | The normal vector extract, and set operations work on | |
19503 | @var{vector __int128} and @var{vector __uint128} types, | |
19504 | but the index value must be 0. | |
19505 | ||
19506 | Only functions excluded from the PVIPR are listed here. | |
19507 | ||
19508 | @smallexample | |
19509 | vector __int128 vec_vaddcuq (vector __int128, vector __int128); | |
19510 | vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128); | |
19511 | ||
19512 | vector __int128 vec_vadduqm (vector __int128, vector __int128); | |
19513 | vector __uint128 vec_vadduqm (vector __uint128, vector __uint128); | |
19514 | ||
19515 | vector __int128 vec_vaddecuq (vector __int128, vector __int128, | |
19516 | vector __int128); | |
19517 | vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128, | |
19518 | vector __uint128); | |
19519 | ||
19520 | vector __int128 vec_vaddeuqm (vector __int128, vector __int128, | |
19521 | vector __int128); | |
19522 | vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128, | |
19523 | vector __uint128); | |
19524 | ||
19525 | vector __int128 vec_vsubecuq (vector __int128, vector __int128, | |
19526 | vector __int128); | |
19527 | vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128, | |
19528 | vector __uint128); | |
19529 | ||
19530 | vector __int128 vec_vsubeuqm (vector __int128, vector __int128, | |
19531 | vector __int128); | |
19532 | vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128, | |
19533 | vector __uint128); | |
19534 | ||
19535 | vector __int128 vec_vsubcuq (vector __int128, vector __int128); | |
19536 | vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128); | |
19537 | ||
19538 | __int128 vec_vsubuqm (__int128, __int128); | |
19539 | __uint128 vec_vsubuqm (__uint128, __uint128); | |
19540 | ||
19541 | vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int); | |
19542 | vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char, | |
19543 | const int); | |
19544 | int __builtin_bcdadd_lt (vector __int128, vector __int128, const int); | |
19545 | int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int); | |
19546 | int __builtin_bcdadd_eq (vector __int128, vector __int128, const int); | |
19547 | int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int); | |
19548 | int __builtin_bcdadd_gt (vector __int128, vector __int128, const int); | |
19549 | int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int); | |
19550 | int __builtin_bcdadd_ov (vector __int128, vector __int128, const int); | |
19551 | int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int); | |
19552 | ||
19553 | vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int); | |
19554 | vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char, | |
19555 | const int); | |
19556 | int __builtin_bcdsub_lt (vector __int128, vector __int128, const int); | |
19557 | int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int); | |
19558 | int __builtin_bcdsub_eq (vector __int128, vector __int128, const int); | |
19559 | int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int); | |
19560 | int __builtin_bcdsub_gt (vector __int128, vector __int128, const int); | |
19561 | int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int); | |
19562 | int __builtin_bcdsub_ov (vector __int128, vector __int128, const int); | |
19563 | int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int); | |
19564 | @end smallexample | |
19565 | ||
19566 | @node PowerPC AltiVec Built-in Functions Available on ISA 3.0 | |
19567 | @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0 | |
19568 | ||
19569 | The following additional built-in functions are also available for the | |
19570 | PowerPC family of processors, starting with ISA 3.0 | |
19571 | (@option{-mcpu=power9}) or later. | |
19572 | ||
19573 | Only instructions excluded from the PVIPR are listed here. | |
19574 | ||
19575 | @smallexample | |
19576 | unsigned int scalar_extract_exp (double source); | |
19577 | unsigned long long int scalar_extract_exp (__ieee128 source); | |
19578 | ||
19579 | unsigned long long int scalar_extract_sig (double source); | |
19580 | unsigned __int128 scalar_extract_sig (__ieee128 source); | |
19581 | ||
19582 | double scalar_insert_exp (unsigned long long int significand, | |
19583 | unsigned long long int exponent); | |
19584 | double scalar_insert_exp (double significand, unsigned long long int exponent); | |
19585 | ||
19586 | ieee_128 scalar_insert_exp (unsigned __int128 significand, | |
19587 | unsigned long long int exponent); | |
19588 | ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent); | |
19589 | ||
19590 | int scalar_cmp_exp_gt (double arg1, double arg2); | |
19591 | int scalar_cmp_exp_lt (double arg1, double arg2); | |
19592 | int scalar_cmp_exp_eq (double arg1, double arg2); | |
19593 | int scalar_cmp_exp_unordered (double arg1, double arg2); | |
19594 | ||
19595 | bool scalar_test_data_class (float source, const int condition); | |
19596 | bool scalar_test_data_class (double source, const int condition); | |
19597 | bool scalar_test_data_class (__ieee128 source, const int condition); | |
19598 | ||
19599 | bool scalar_test_neg (float source); | |
19600 | bool scalar_test_neg (double source); | |
19601 | bool scalar_test_neg (__ieee128 source); | |
19602 | @end smallexample | |
19603 | ||
19604 | The @code{scalar_extract_exp} and @code{scalar_extract_sig} | |
19605 | functions require a 64-bit environment supporting ISA 3.0 or later. | |
19606 | The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in | |
19607 | functions return the significand and the biased exponent value | |
19608 | respectively of their @code{source} arguments. | |
19609 | When supplied with a 64-bit @code{source} argument, the | |
19610 | result returned by @code{scalar_extract_sig} has | |
19611 | the @code{0x0010000000000000} bit set if the | |
19612 | function's @code{source} argument is in normalized form. | |
19613 | Otherwise, this bit is set to 0. | |
19614 | When supplied with a 128-bit @code{source} argument, the | |
19615 | @code{0x00010000000000000000000000000000} bit of the result is | |
19616 | treated similarly. | |
19617 | Note that the sign of the significand is not represented in the result | |
19618 | returned from the @code{scalar_extract_sig} function. Use the | |
19619 | @code{scalar_test_neg} function to test the sign of its @code{double} | |
19620 | argument. | |
19621 | ||
19622 | The @code{scalar_insert_exp} | |
19623 | functions require a 64-bit environment supporting ISA 3.0 or later. | |
19624 | When supplied with a 64-bit first argument, the | |
19625 | @code{scalar_insert_exp} built-in function returns a double-precision | |
19626 | floating point value that is constructed by assembling the values of its | |
19627 | @code{significand} and @code{exponent} arguments. The sign of the | |
19628 | result is copied from the most significant bit of the | |
19629 | @code{significand} argument. The significand and exponent components | |
19630 | of the result are composed of the least significant 11 bits of the | |
19631 | @code{exponent} argument and the least significant 52 bits of the | |
19632 | @code{significand} argument respectively. | |
19633 | ||
19634 | When supplied with a 128-bit first argument, the | |
19635 | @code{scalar_insert_exp} built-in function returns a quad-precision | |
19636 | ieee floating point value. The sign bit of the result is copied from | |
19637 | the most significant bit of the @code{significand} argument. | |
19638 | The significand and exponent components of the result are composed of | |
19639 | the least significant 15 bits of the @code{exponent} argument and the | |
19640 | least significant 112 bits of the @code{significand} argument respectively. | |
19641 | ||
19642 | The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt}, | |
19643 | @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in | |
19644 | functions return a non-zero value if @code{arg1} is greater than, less | |
19645 | than, equal to, or not comparable to @code{arg2} respectively. The | |
19646 | arguments are not comparable if one or the other equals NaN (not a | |
19647 | number). | |
19648 | ||
19649 | The @code{scalar_test_data_class} built-in function returns 1 | |
19650 | if any of the condition tests enabled by the value of the | |
19651 | @code{condition} variable are true, and 0 otherwise. The | |
19652 | @code{condition} argument must be a compile-time constant integer with | |
19653 | value not exceeding 127. The | |
19654 | @code{condition} argument is encoded as a bitmask with each bit | |
19655 | enabling the testing of a different condition, as characterized by the | |
19656 | following: | |
19657 | @smallexample | |
19658 | 0x40 Test for NaN | |
19659 | 0x20 Test for +Infinity | |
19660 | 0x10 Test for -Infinity | |
19661 | 0x08 Test for +Zero | |
19662 | 0x04 Test for -Zero | |
19663 | 0x02 Test for +Denormal | |
19664 | 0x01 Test for -Denormal | |
19665 | @end smallexample | |
19666 | ||
19667 | The @code{scalar_test_neg} built-in function returns 1 if its | |
19668 | @code{source} argument holds a negative value, 0 otherwise. | |
19669 | ||
19670 | The following built-in functions are also available for the PowerPC family | |
19671 | of processors, starting with ISA 3.0 or later | |
19672 | (@option{-mcpu=power9}). These string functions are described | |
19673 | separately in order to group the descriptions closer to the function | |
19674 | prototypes. | |
19675 | ||
19676 | Only functions excluded from the PVIPR are listed here. | |
19677 | ||
19678 | @smallexample | |
19679 | int vec_all_nez (vector signed char, vector signed char); | |
19680 | int vec_all_nez (vector unsigned char, vector unsigned char); | |
19681 | int vec_all_nez (vector signed short, vector signed short); | |
19682 | int vec_all_nez (vector unsigned short, vector unsigned short); | |
19683 | int vec_all_nez (vector signed int, vector signed int); | |
19684 | int vec_all_nez (vector unsigned int, vector unsigned int); | |
19685 | ||
19686 | int vec_any_eqz (vector signed char, vector signed char); | |
19687 | int vec_any_eqz (vector unsigned char, vector unsigned char); | |
19688 | int vec_any_eqz (vector signed short, vector signed short); | |
19689 | int vec_any_eqz (vector unsigned short, vector unsigned short); | |
19690 | int vec_any_eqz (vector signed int, vector signed int); | |
19691 | int vec_any_eqz (vector unsigned int, vector unsigned int); | |
19692 | ||
19693 | signed char vec_xlx (unsigned int index, vector signed char data); | |
19694 | unsigned char vec_xlx (unsigned int index, vector unsigned char data); | |
19695 | signed short vec_xlx (unsigned int index, vector signed short data); | |
19696 | unsigned short vec_xlx (unsigned int index, vector unsigned short data); | |
19697 | signed int vec_xlx (unsigned int index, vector signed int data); | |
19698 | unsigned int vec_xlx (unsigned int index, vector unsigned int data); | |
19699 | float vec_xlx (unsigned int index, vector float data); | |
19700 | ||
19701 | signed char vec_xrx (unsigned int index, vector signed char data); | |
19702 | unsigned char vec_xrx (unsigned int index, vector unsigned char data); | |
19703 | signed short vec_xrx (unsigned int index, vector signed short data); | |
19704 | unsigned short vec_xrx (unsigned int index, vector unsigned short data); | |
19705 | signed int vec_xrx (unsigned int index, vector signed int data); | |
19706 | unsigned int vec_xrx (unsigned int index, vector unsigned int data); | |
19707 | float vec_xrx (unsigned int index, vector float data); | |
19708 | @end smallexample | |
19709 | ||
19710 | The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez} | |
19711 | perform pairwise comparisons between the elements at the same | |
19712 | positions within their two vector arguments. | |
19713 | The @code{vec_all_nez} function returns a | |
19714 | non-zero value if and only if all pairwise comparisons are not | |
19715 | equal and no element of either vector argument contains a zero. | |
19716 | The @code{vec_any_eqz} function returns a | |
19717 | non-zero value if and only if at least one pairwise comparison is equal | |
19718 | or if at least one element of either vector argument contains a zero. | |
19719 | The @code{vec_cmpnez} function returns a vector of the same type as | |
19720 | its two arguments, within which each element consists of all ones to | |
19721 | denote that either the corresponding elements of the incoming arguments are | |
19722 | not equal or that at least one of the corresponding elements contains | |
19723 | zero. Otherwise, the element of the returned vector contains all zeros. | |
19724 | ||
19725 | The @code{vec_xlx} and @code{vec_xrx} functions extract the single | |
19726 | element selected by the @code{index} argument from the vector | |
19727 | represented by the @code{data} argument. The @code{index} argument | |
19728 | always specifies a byte offset, regardless of the size of the vector | |
19729 | element. With @code{vec_xlx}, @code{index} is the offset of the first | |
19730 | byte of the element to be extracted. With @code{vec_xrx}, @code{index} | |
19731 | represents the last byte of the element to be extracted, measured | |
19732 | from the right end of the vector. In other words, the last byte of | |
19733 | the element to be extracted is found at position @code{(15 - index)}. | |
19734 | There is no requirement that @code{index} be a multiple of the vector | |
19735 | element size. However, if the size of the vector element added to | |
19736 | @code{index} is greater than 15, the content of the returned value is | |
19737 | undefined. | |
19738 | ||
19739 | The following functions are also available if the ISA 3.0 instruction | |
19740 | set additions (@option{-mcpu=power9}) are available. | |
19741 | ||
19742 | Only functions excluded from the PVIPR are listed here. | |
19743 | ||
19744 | @smallexample | |
19745 | vector long long vec_vctz (vector long long); | |
19746 | vector unsigned long long vec_vctz (vector unsigned long long); | |
19747 | vector int vec_vctz (vector int); | |
19748 | vector unsigned int vec_vctz (vector int); | |
19749 | vector short vec_vctz (vector short); | |
19750 | vector unsigned short vec_vctz (vector unsigned short); | |
19751 | vector signed char vec_vctz (vector signed char); | |
19752 | vector unsigned char vec_vctz (vector unsigned char); | |
19753 | ||
19754 | vector signed char vec_vctzb (vector signed char); | |
19755 | vector unsigned char vec_vctzb (vector unsigned char); | |
19756 | ||
19757 | vector long long vec_vctzd (vector long long); | |
19758 | vector unsigned long long vec_vctzd (vector unsigned long long); | |
19759 | ||
19760 | vector short vec_vctzh (vector short); | |
19761 | vector unsigned short vec_vctzh (vector unsigned short); | |
19762 | ||
19763 | vector int vec_vctzw (vector int); | |
19764 | vector unsigned int vec_vctzw (vector int); | |
19765 | ||
19766 | vector int vec_vprtyb (vector int); | |
19767 | vector unsigned int vec_vprtyb (vector unsigned int); | |
19768 | vector long long vec_vprtyb (vector long long); | |
19769 | vector unsigned long long vec_vprtyb (vector unsigned long long); | |
19770 | ||
19771 | vector int vec_vprtybw (vector int); | |
19772 | vector unsigned int vec_vprtybw (vector unsigned int); | |
19773 | ||
19774 | vector long long vec_vprtybd (vector long long); | |
19775 | vector unsigned long long vec_vprtybd (vector unsigned long long); | |
19776 | @end smallexample | |
19777 | ||
19778 | On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) | |
19779 | are available: | |
19780 | ||
19781 | @smallexample | |
19782 | vector long vec_vprtyb (vector long); | |
19783 | vector unsigned long vec_vprtyb (vector unsigned long); | |
19784 | vector __int128 vec_vprtyb (vector __int128); | |
19785 | vector __uint128 vec_vprtyb (vector __uint128); | |
19786 | ||
19787 | vector long vec_vprtybd (vector long); | |
19788 | vector unsigned long vec_vprtybd (vector unsigned long); | |
19789 | ||
19790 | vector __int128 vec_vprtybq (vector __int128); | |
19791 | vector __uint128 vec_vprtybd (vector __uint128); | |
19792 | @end smallexample | |
19793 | ||
19794 | The following built-in functions are available for the PowerPC family | |
19795 | of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}). | |
19796 | ||
19797 | Only functions excluded from the PVIPR are listed here. | |
19798 | ||
19799 | @smallexample | |
19800 | __vector unsigned char | |
19801 | vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2); | |
19802 | __vector unsigned short | |
19803 | vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2); | |
19804 | __vector unsigned int | |
19805 | vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2); | |
19806 | @end smallexample | |
19807 | ||
19808 | The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and | |
19809 | @code{vec_absdw} built-in functions each computes the absolute | |
19810 | differences of the pairs of vector elements supplied in its two vector | |
19811 | arguments, placing the absolute differences into the corresponding | |
19812 | elements of the vector result. | |
19813 | ||
19814 | The following built-in functions are available for the PowerPC family | |
19815 | of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): | |
19816 | @smallexample | |
19817 | vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int); | |
19818 | vector unsigned long long vec_vrlnm (vector unsigned long long, | |
19819 | vector unsigned long long); | |
19820 | @end smallexample | |
19821 | ||
19822 | The result of @code{vec_vrlnm} is obtained by rotating each element | |
19823 | of the first argument vector left and ANDing it with a mask. The | |
19824 | second argument vector contains the mask beginning in bits 11:15, | |
19825 | the mask end in bits 19:23, and the shift count in bits 27:31, | |
19826 | of each element. | |
19827 | ||
19828 | If the cryptographic instructions are enabled (@option{-mcrypto} or | |
19829 | @option{-mcpu=power8}), the following builtins are enabled. | |
19830 | ||
19831 | Only functions excluded from the PVIPR are listed here. | |
19832 | ||
19833 | @smallexample | |
19834 | vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long); | |
19835 | ||
19836 | vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long, | |
19837 | vector unsigned long long); | |
19838 | ||
19839 | vector unsigned long long __builtin_crypto_vcipherlast | |
19840 | (vector unsigned long long, | |
19841 | vector unsigned long long); | |
19842 | ||
19843 | vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long, | |
19844 | vector unsigned long long); | |
19845 | ||
19846 | vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long, | |
19847 | vector unsigned long long); | |
19848 | ||
19849 | vector unsigned char __builtin_crypto_vpermxor (vector unsigned char, | |
19850 | vector unsigned char, | |
19851 | vector unsigned char); | |
19852 | ||
19853 | vector unsigned short __builtin_crypto_vpermxor (vector unsigned short, | |
19854 | vector unsigned short, | |
19855 | vector unsigned short); | |
19856 | ||
19857 | vector unsigned int __builtin_crypto_vpermxor (vector unsigned int, | |
19858 | vector unsigned int, | |
19859 | vector unsigned int); | |
19860 | ||
19861 | vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long, | |
19862 | vector unsigned long long, | |
19863 | vector unsigned long long); | |
19864 | ||
19865 | vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char, | |
19866 | vector unsigned char); | |
19867 | ||
19868 | vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short, | |
19869 | vector unsigned short); | |
19870 | ||
19871 | vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int, | |
19872 | vector unsigned int); | |
19873 | ||
19874 | vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long, | |
19875 | vector unsigned long long); | |
19876 | ||
19877 | vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long, | |
19878 | int, int); | |
19879 | ||
19880 | vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int); | |
19881 | @end smallexample | |
19882 | ||
19883 | The second argument to @var{__builtin_crypto_vshasigmad} and | |
19884 | @var{__builtin_crypto_vshasigmaw} must be a constant | |
19885 | integer that is 0 or 1. The third argument to these built-in functions | |
19886 | must be a constant integer in the range of 0 to 15. | |
19887 | ||
19888 | The following sign extension builtins are provided: | |
19889 | ||
19890 | @smallexample | |
19891 | vector signed int vec_signexti (vector signed char a); | |
19892 | vector signed long long vec_signextll (vector signed char a); | |
19893 | vector signed int vec_signexti (vector signed short a); | |
19894 | vector signed long long vec_signextll (vector signed short a); | |
19895 | vector signed long long vec_signextll (vector signed int a); | |
19896 | vector signed long long vec_signextq (vector signed long long a); | |
19897 | @end smallexample | |
19898 | ||
19899 | Each element of the result is produced by sign-extending the element of the | |
19900 | input vector that would fall in the least significant portion of the result | |
19901 | element. For example, a sign-extension of a vector signed char to a vector | |
19902 | signed long long will sign extend the rightmost byte of each doubleword. | |
19903 | ||
19904 | @node PowerPC AltiVec Built-in Functions Available on ISA 3.1 | |
19905 | @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1 | |
19906 | ||
19907 | The following additional built-in functions are also available for the | |
19908 | PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}): | |
19909 | ||
19910 | ||
19911 | @smallexample | |
19912 | @exdent vector unsigned long long int | |
19913 | @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int); | |
19914 | @end smallexample | |
19915 | Perform a vector centrifuge operation, as if implemented by the | |
19916 | @code{vcfuged} instruction. | |
19917 | @findex vec_cfuge | |
19918 | ||
19919 | @smallexample | |
19920 | @exdent vector unsigned long long int | |
19921 | @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int); | |
19922 | @end smallexample | |
19923 | Perform a vector count leading zeros under bit mask operation, as if | |
19924 | implemented by the @code{vclzdm} instruction. | |
19925 | @findex vec_cntlzm | |
19926 | ||
19927 | @smallexample | |
19928 | @exdent vector unsigned long long int | |
19929 | @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int); | |
19930 | @end smallexample | |
19931 | Perform a vector count trailing zeros under bit mask operation, as if | |
19932 | implemented by the @code{vctzdm} instruction. | |
19933 | @findex vec_cnttzm | |
19934 | ||
19935 | @smallexample | |
19936 | @exdent vector signed char | |
19937 | @exdent vec_clrl (vector signed char a, unsigned int n); | |
19938 | @exdent vector unsigned char | |
19939 | @exdent vec_clrl (vector unsigned char a, unsigned int n); | |
19940 | @end smallexample | |
19941 | Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if | |
19942 | implemented by the @code{vclrlb} instruction on a big-endian target | |
19943 | and by the @code{vclrrb} instruction on a little-endian target. A | |
19944 | value of @code{n} that is greater than 16 is treated as if it equaled 16. | |
19945 | @findex vec_clrl | |
19946 | ||
19947 | @smallexample | |
19948 | @exdent vector signed char | |
19949 | @exdent vec_clrr (vector signed char a, unsigned int n); | |
19950 | @exdent vector unsigned char | |
19951 | @exdent vec_clrr (vector unsigned char a, unsigned int n); | |
19952 | @end smallexample | |
19953 | Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if | |
19954 | implemented by the @code{vclrrb} instruction on a big-endian target | |
19955 | and by the @code{vclrlb} instruction on a little-endian target. A | |
19956 | value of @code{n} that is greater than 16 is treated as if it equaled 16. | |
19957 | @findex vec_clrr | |
19958 | ||
19959 | @smallexample | |
19960 | @exdent vector unsigned long long int | |
19961 | @exdent vec_gnb (vector unsigned __int128, const unsigned char); | |
19962 | @end smallexample | |
19963 | Perform a 128-bit vector gather operation, as if implemented by the | |
19964 | @code{vgnb} instruction. The second argument must be a literal | |
19965 | integer value between 2 and 7 inclusive. | |
19966 | @findex vec_gnb | |
19967 | ||
19968 | ||
19969 | Vector Extract | |
19970 | ||
19971 | @smallexample | |
19972 | @exdent vector unsigned long long int | |
19973 | @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int); | |
19974 | @exdent vector unsigned long long int | |
19975 | @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int); | |
19976 | @exdent vector unsigned long long int | |
19977 | @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int); | |
19978 | @exdent vector unsigned long long int | |
19979 | @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int); | |
19980 | @end smallexample | |
19981 | Extract an element from two concatenated vectors starting at the given byte index | |
19982 | in natural-endian order, and place it zero-extended in doubleword 1 of the result | |
19983 | according to natural element order. If the byte index is out of range for the | |
19984 | data type, the intrinsic will be rejected. | |
19985 | For little-endian, this output will match the placement by the hardware | |
19986 | instruction, i.e., dword[0] in RTL notation. For big-endian, an additional | |
19987 | instruction is needed to move it from the "left" doubleword to the "right" one. | |
19988 | For little-endian, semantics matching the @code{vextdubvrx}, | |
19989 | @code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for | |
19990 | big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx}, | |
19991 | @code{vextduwvlx} instructions | |
19992 | will be generated. Note that some fairly anomalous results can be generated if | |
19993 | the byte index is not aligned on an element boundary for the element being | |
19994 | extracted. This is a limitation of the bi-endian vector programming model is | |
19995 | consistent with the limitation on @code{vec_perm}. | |
19996 | @findex vec_extractl | |
19997 | ||
19998 | @smallexample | |
19999 | @exdent vector unsigned long long int | |
20000 | @exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int); | |
20001 | @exdent vector unsigned long long int | |
20002 | @exdent vec_extracth (vector unsigned short, vector unsigned short, | |
20003 | unsigned int); | |
20004 | @exdent vector unsigned long long int | |
20005 | @exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int); | |
20006 | @exdent vector unsigned long long int | |
20007 | @exdent vec_extracth (vector unsigned long long, vector unsigned long long, | |
20008 | unsigned int); | |
20009 | @end smallexample | |
20010 | Extract an element from two concatenated vectors starting at the given byte | |
20011 | index. The index is based on big endian order for a little endian system. | |
20012 | Similarly, the index is based on little endian order for a big endian system. | |
20013 | The extraced elements are zero-extended and put in doubleword 1 | |
20014 | according to natural element order. If the byte index is out of range for the | |
20015 | data type, the intrinsic will be rejected. For little-endian, this output | |
20016 | will match the placement by the hardware instruction (vextdubvrx, vextduhvrx, | |
20017 | vextduwvrx, vextddvrx) i.e., dword[0] in RTL | |
20018 | notation. For big-endian, an additional instruction is needed to move it | |
20019 | from the "left" doubleword to the "right" one. For little-endian, semantics | |
20020 | matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx} | |
20021 | instructions will be generated, while for big-endian, semantics matching the | |
20022 | @code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will | |
20023 | be generated. Note that some fairly anomalous | |
20024 | results can be generated if the byte index is not aligned on the | |
20025 | element boundary for the element being extracted. This is a | |
20026 | limitation of the bi-endian vector programming model consistent with the | |
20027 | limitation on @code{vec_perm}. | |
20028 | @findex vec_extracth | |
20029 | @smallexample | |
20030 | @exdent vector unsigned long long int | |
20031 | @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int); | |
20032 | @end smallexample | |
20033 | Perform a vector parallel bits deposit operation, as if implemented by | |
20034 | the @code{vpdepd} instruction. | |
20035 | @findex vec_pdep | |
20036 | ||
20037 | Vector Insert | |
20038 | ||
20039 | @smallexample | |
20040 | @exdent vector unsigned char | |
20041 | @exdent vec_insertl (unsigned char, vector unsigned char, unsigned int); | |
20042 | @exdent vector unsigned short | |
20043 | @exdent vec_insertl (unsigned short, vector unsigned short, unsigned int); | |
20044 | @exdent vector unsigned int | |
20045 | @exdent vec_insertl (unsigned int, vector unsigned int, unsigned int); | |
20046 | @exdent vector unsigned long long | |
20047 | @exdent vec_insertl (unsigned long long, vector unsigned long long, | |
20048 | unsigned int); | |
20049 | @exdent vector unsigned char | |
20050 | @exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int; | |
20051 | @exdent vector unsigned short | |
20052 | @exdent vec_insertl (vector unsigned short, vector unsigned short, | |
20053 | unsigned int); | |
20054 | @exdent vector unsigned int | |
20055 | @exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int); | |
20056 | @end smallexample | |
20057 | ||
20058 | Let src be the first argument, when the first argument is a scalar, or the | |
20059 | rightmost element of the left doubleword of the first argument, when the first | |
20060 | argument is a vector. Insert the source into the destination at the position | |
20061 | given by the third argument, using natural element order in the second | |
20062 | argument. The rest of the second argument is unchanged. If the byte | |
20063 | index is greater than 14 for halfwords, greater than 12 for words, or | |
20064 | greater than 8 for doublewords the result is undefined. For little-endian, | |
20065 | the generated code will be semantically equivalent to @code{vins[bhwd]rx} | |
20066 | instructions. Similarly for big-endian it will be semantically equivalent | |
20067 | to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be | |
20068 | generated if the byte index is not aligned on an element boundary for the | |
20069 | type of element being inserted. | |
20070 | @findex vec_insertl | |
20071 | ||
20072 | @smallexample | |
20073 | @exdent vector unsigned char | |
20074 | @exdent vec_inserth (unsigned char, vector unsigned char, unsigned int); | |
20075 | @exdent vector unsigned short | |
20076 | @exdent vec_inserth (unsigned short, vector unsigned short, unsigned int); | |
20077 | @exdent vector unsigned int | |
20078 | @exdent vec_inserth (unsigned int, vector unsigned int, unsigned int); | |
20079 | @exdent vector unsigned long long | |
20080 | @exdent vec_inserth (unsigned long long, vector unsigned long long, | |
20081 | unsigned int); | |
20082 | @exdent vector unsigned char | |
20083 | @exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int); | |
20084 | @exdent vector unsigned short | |
20085 | @exdent vec_inserth (vector unsigned short, vector unsigned short, | |
20086 | unsigned int); | |
20087 | @exdent vector unsigned int | |
20088 | @exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int); | |
20089 | @end smallexample | |
20090 | ||
20091 | Let src be the first argument, when the first argument is a scalar, or the | |
20092 | rightmost element of the first argument, when the first argument is a vector. | |
20093 | Insert src into the second argument at the position identified by the third | |
20094 | argument, using opposite element order in the second argument, and leaving the | |
20095 | rest of the second argument unchanged. If the byte index is greater than 14 | |
20096 | for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be | |
20097 | rejected. Note that the underlying hardware instruction uses the same register | |
20098 | for the second argument and the result. | |
20099 | For little-endian, the code generation will be semantically equivalent to | |
20100 | @code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to | |
20101 | @code{vins[bhwd]rx}. | |
20102 | Note that some fairly anomalous results can be generated if the byte index is | |
20103 | not aligned on an element boundary for the sort of element being inserted. | |
20104 | @findex vec_inserth | |
20105 | ||
20106 | Vector Replace Element | |
20107 | @smallexample | |
20108 | @exdent vector signed int vec_replace_elt (vector signed int, signed int, | |
20109 | const int); | |
20110 | @exdent vector unsigned int vec_replace_elt (vector unsigned int, | |
20111 | unsigned int, const int); | |
20112 | @exdent vector float vec_replace_elt (vector float, float, const int); | |
20113 | @exdent vector signed long long vec_replace_elt (vector signed long long, | |
20114 | signed long long, const int); | |
20115 | @exdent vector unsigned long long vec_replace_elt (vector unsigned long long, | |
20116 | unsigned long long, const int); | |
20117 | @exdent vector double rec_replace_elt (vector double, double, const int); | |
20118 | @end smallexample | |
20119 | The third argument (constrained to [0,3]) identifies the natural-endian | |
20120 | element number of the first argument that will be replaced by the second | |
20121 | argument to produce the result. The other elements of the first argument will | |
20122 | remain unchanged in the result. | |
20123 | ||
20124 | If it's desirable to insert a word at an unaligned position, use | |
20125 | vec_replace_unaligned instead. | |
20126 | ||
20127 | @findex vec_replace_element | |
20128 | ||
20129 | Vector Replace Unaligned | |
20130 | @smallexample | |
20131 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
20132 | signed int, const int); | |
20133 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
20134 | unsigned int, const int); | |
20135 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
20136 | float, const int); | |
20137 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
20138 | signed long long, const int); | |
20139 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
20140 | unsigned long long, const int); | |
20141 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
20142 | double, const int); | |
20143 | @end smallexample | |
20144 | ||
20145 | The second argument replaces a portion of the first argument to produce the | |
20146 | result, with the rest of the first argument unchanged in the result. The | |
20147 | third argument identifies the byte index (using left-to-right, or big-endian | |
20148 | order) where the high-order byte of the second argument will be placed, with | |
20149 | the remaining bytes of the second argument placed naturally "to the right" | |
20150 | of the high-order byte. | |
20151 | ||
20152 | The programmer is responsible for understanding the endianness issues involved | |
20153 | with the first argument and the result. | |
20154 | @findex vec_replace_unaligned | |
20155 | ||
20156 | Vector Shift Left Double Bit Immediate | |
20157 | @smallexample | |
20158 | @exdent vector signed char vec_sldb (vector signed char, vector signed char, | |
20159 | const unsigned int); | |
20160 | @exdent vector unsigned char vec_sldb (vector unsigned char, | |
20161 | vector unsigned char, const unsigned int); | |
20162 | @exdent vector signed short vec_sldb (vector signed short, vector signed short, | |
20163 | const unsigned int); | |
20164 | @exdent vector unsigned short vec_sldb (vector unsigned short, | |
20165 | vector unsigned short, const unsigned int); | |
20166 | @exdent vector signed int vec_sldb (vector signed int, vector signed int, | |
20167 | const unsigned int); | |
20168 | @exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int, | |
20169 | const unsigned int); | |
20170 | @exdent vector signed long long vec_sldb (vector signed long long, | |
20171 | vector signed long long, const unsigned int); | |
20172 | @exdent vector unsigned long long vec_sldb (vector unsigned long long, | |
20173 | vector unsigned long long, const unsigned int); | |
20174 | @end smallexample | |
20175 | ||
20176 | Shift the combined input vectors left by the amount specified by the low-order | |
20177 | three bits of the third argument, and return the leftmost remaining 128 bits. | |
20178 | Code using this instruction must be endian-aware. | |
20179 | ||
20180 | @findex vec_sldb | |
20181 | ||
20182 | Vector Shift Right Double Bit Immediate | |
20183 | ||
20184 | @smallexample | |
20185 | @exdent vector signed char vec_srdb (vector signed char, vector signed char, | |
20186 | const unsigned int); | |
20187 | @exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char, | |
20188 | const unsigned int); | |
20189 | @exdent vector signed short vec_srdb (vector signed short, vector signed short, | |
20190 | const unsigned int); | |
20191 | @exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short, | |
20192 | const unsigned int); | |
20193 | @exdent vector signed int vec_srdb (vector signed int, vector signed int, | |
20194 | const unsigned int); | |
20195 | @exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int, | |
20196 | const unsigned int); | |
20197 | @exdent vector signed long long vec_srdb (vector signed long long, | |
20198 | vector signed long long, const unsigned int); | |
20199 | @exdent vector unsigned long long vec_srdb (vector unsigned long long, | |
20200 | vector unsigned long long, const unsigned int); | |
20201 | @end smallexample | |
20202 | ||
20203 | Shift the combined input vectors right by the amount specified by the low-order | |
20204 | three bits of the third argument, and return the remaining 128 bits. Code | |
20205 | using this built-in must be endian-aware. | |
20206 | ||
20207 | @findex vec_srdb | |
20208 | ||
20209 | Vector Splat | |
20210 | ||
20211 | @smallexample | |
20212 | @exdent vector signed int vec_splati (const signed int); | |
20213 | @exdent vector float vec_splati (const float); | |
20214 | @end smallexample | |
20215 | ||
20216 | Splat a 32-bit immediate into a vector of words. | |
20217 | ||
20218 | @findex vec_splati | |
20219 | ||
20220 | @smallexample | |
20221 | @exdent vector double vec_splatid (const float); | |
20222 | @end smallexample | |
20223 | ||
20224 | Convert a single precision floating-point value to double-precision and splat | |
20225 | the result to a vector of double-precision floats. | |
20226 | ||
20227 | @findex vec_splatid | |
20228 | ||
20229 | @smallexample | |
20230 | @exdent vector signed int vec_splati_ins (vector signed int, | |
20231 | const unsigned int, const signed int); | |
20232 | @exdent vector unsigned int vec_splati_ins (vector unsigned int, | |
20233 | const unsigned int, const unsigned int); | |
20234 | @exdent vector float vec_splati_ins (vector float, const unsigned int, | |
20235 | const float); | |
20236 | @end smallexample | |
20237 | ||
20238 | Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word | |
20239 | identified by argument 2 of each doubleword of argument 1 and return the | |
20240 | result. The other words of argument 1 are unchanged. | |
20241 | ||
20242 | @findex vec_splati_ins | |
20243 | ||
20244 | Vector Blend Variable | |
20245 | ||
20246 | @smallexample | |
20247 | @exdent vector signed char vec_blendv (vector signed char, vector signed char, | |
20248 | vector unsigned char); | |
20249 | @exdent vector unsigned char vec_blendv (vector unsigned char, | |
20250 | vector unsigned char, vector unsigned char); | |
20251 | @exdent vector signed short vec_blendv (vector signed short, | |
20252 | vector signed short, vector unsigned short); | |
20253 | @exdent vector unsigned short vec_blendv (vector unsigned short, | |
20254 | vector unsigned short, vector unsigned short); | |
20255 | @exdent vector signed int vec_blendv (vector signed int, vector signed int, | |
20256 | vector unsigned int); | |
20257 | @exdent vector unsigned int vec_blendv (vector unsigned int, | |
20258 | vector unsigned int, vector unsigned int); | |
20259 | @exdent vector signed long long vec_blendv (vector signed long long, | |
20260 | vector signed long long, vector unsigned long long); | |
20261 | @exdent vector unsigned long long vec_blendv (vector unsigned long long, | |
20262 | vector unsigned long long, vector unsigned long long); | |
20263 | @exdent vector float vec_blendv (vector float, vector float, | |
20264 | vector unsigned int); | |
20265 | @exdent vector double vec_blendv (vector double, vector double, | |
20266 | vector unsigned long long); | |
20267 | @end smallexample | |
20268 | ||
20269 | Blend the first and second argument vectors according to the sign bits of the | |
20270 | corresponding elements of the third argument vector. This is similar to the | |
20271 | @code{vsel} and @code{xxsel} instructions but for bigger elements. | |
20272 | ||
20273 | @findex vec_blendv | |
20274 | ||
20275 | Vector Permute Extended | |
20276 | ||
20277 | @smallexample | |
20278 | @exdent vector signed char vec_permx (vector signed char, vector signed char, | |
20279 | vector unsigned char, const int); | |
20280 | @exdent vector unsigned char vec_permx (vector unsigned char, | |
20281 | vector unsigned char, vector unsigned char, const int); | |
20282 | @exdent vector signed short vec_permx (vector signed short, | |
20283 | vector signed short, vector unsigned char, const int); | |
20284 | @exdent vector unsigned short vec_permx (vector unsigned short, | |
20285 | vector unsigned short, vector unsigned char, const int); | |
20286 | @exdent vector signed int vec_permx (vector signed int, vector signed int, | |
20287 | vector unsigned char, const int); | |
20288 | @exdent vector unsigned int vec_permx (vector unsigned int, | |
20289 | vector unsigned int, vector unsigned char, const int); | |
20290 | @exdent vector signed long long vec_permx (vector signed long long, | |
20291 | vector signed long long, vector unsigned char, const int); | |
20292 | @exdent vector unsigned long long vec_permx (vector unsigned long long, | |
20293 | vector unsigned long long, vector unsigned char, const int); | |
20294 | @exdent vector float (vector float, vector float, vector unsigned char, | |
20295 | const int); | |
20296 | @exdent vector double (vector double, vector double, vector unsigned char, | |
20297 | const int); | |
20298 | @end smallexample | |
20299 | ||
20300 | Perform a partial permute of the first two arguments, which form a 32-byte | |
20301 | section of an emulated vector up to 256 bytes wide, using the partial permute | |
20302 | control vector in the third argument. The fourth argument (constrained to | |
20303 | values of 0-7) identifies which 32-byte section of the emulated vector is | |
20304 | contained in the first two arguments. | |
20305 | @findex vec_permx | |
20306 | ||
20307 | @smallexample | |
20308 | @exdent vector unsigned long long int | |
20309 | @exdent vec_pext (vector unsigned long long int, vector unsigned long long int); | |
20310 | @end smallexample | |
20311 | Perform a vector parallel bit extract operation, as if implemented by | |
20312 | the @code{vpextd} instruction. | |
20313 | @findex vec_pext | |
20314 | ||
20315 | @smallexample | |
20316 | @exdent vector unsigned char vec_stril (vector unsigned char); | |
20317 | @exdent vector signed char vec_stril (vector signed char); | |
20318 | @exdent vector unsigned short vec_stril (vector unsigned short); | |
20319 | @exdent vector signed short vec_stril (vector signed short); | |
20320 | @end smallexample | |
20321 | Isolate the left-most non-zero elements of the incoming vector argument, | |
20322 | replacing all elements to the right of the left-most zero element | |
20323 | found within the argument with zero. The typical implementation uses | |
20324 | the @code{vstribl} or @code{vstrihl} instruction on big-endian targets | |
20325 | and uses the @code{vstribr} or @code{vstrihr} instruction on | |
20326 | little-endian targets. | |
20327 | @findex vec_stril | |
20328 | ||
20329 | @smallexample | |
20330 | @exdent int vec_stril_p (vector unsigned char); | |
20331 | @exdent int vec_stril_p (vector signed char); | |
20332 | @exdent int short vec_stril_p (vector unsigned short); | |
20333 | @exdent int vec_stril_p (vector signed short); | |
20334 | @end smallexample | |
20335 | Return a non-zero value if and only if the argument contains a zero | |
20336 | element. The typical implementation uses | |
20337 | the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets | |
20338 | and uses the @code{vstribr.} or @code{vstrihr.} instruction on | |
20339 | little-endian targets. Choose this built-in to check for presence of | |
20340 | zero element if the same argument is also passed to @code{vec_stril}. | |
20341 | @findex vec_stril_p | |
20342 | ||
20343 | @smallexample | |
20344 | @exdent vector unsigned char vec_strir (vector unsigned char); | |
20345 | @exdent vector signed char vec_strir (vector signed char); | |
20346 | @exdent vector unsigned short vec_strir (vector unsigned short); | |
20347 | @exdent vector signed short vec_strir (vector signed short); | |
20348 | @end smallexample | |
20349 | Isolate the right-most non-zero elements of the incoming vector argument, | |
20350 | replacing all elements to the left of the right-most zero element | |
20351 | found within the argument with zero. The typical implementation uses | |
20352 | the @code{vstribr} or @code{vstrihr} instruction on big-endian targets | |
20353 | and uses the @code{vstribl} or @code{vstrihl} instruction on | |
20354 | little-endian targets. | |
20355 | @findex vec_strir | |
20356 | ||
20357 | @smallexample | |
20358 | @exdent int vec_strir_p (vector unsigned char); | |
20359 | @exdent int vec_strir_p (vector signed char); | |
20360 | @exdent int short vec_strir_p (vector unsigned short); | |
20361 | @exdent int vec_strir_p (vector signed short); | |
20362 | @end smallexample | |
20363 | Return a non-zero value if and only if the argument contains a zero | |
20364 | element. The typical implementation uses | |
20365 | the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets | |
20366 | and uses the @code{vstribl.} or @code{vstrihl.} instruction on | |
20367 | little-endian targets. Choose this built-in to check for presence of | |
20368 | zero element if the same argument is also passed to @code{vec_strir}. | |
20369 | @findex vec_strir_p | |
20370 | ||
20371 | @smallexample | |
20372 | @exdent vector unsigned char | |
20373 | @exdent vec_ternarylogic (vector unsigned char, vector unsigned char, | |
20374 | vector unsigned char, const unsigned int); | |
20375 | @exdent vector unsigned short | |
20376 | @exdent vec_ternarylogic (vector unsigned short, vector unsigned short, | |
20377 | vector unsigned short, const unsigned int); | |
20378 | @exdent vector unsigned int | |
20379 | @exdent vec_ternarylogic (vector unsigned int, vector unsigned int, | |
20380 | vector unsigned int, const unsigned int); | |
20381 | @exdent vector unsigned long long int | |
20382 | @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int, | |
20383 | vector unsigned long long int, const unsigned int); | |
20384 | @exdent vector unsigned __int128 | |
20385 | @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128, | |
20386 | vector unsigned __int128, const unsigned int); | |
20387 | @end smallexample | |
20388 | Perform a 128-bit vector evaluate operation, as if implemented by the | |
20389 | @code{xxeval} instruction. The fourth argument must be a literal | |
20390 | integer value between 0 and 255 inclusive. | |
20391 | @findex vec_ternarylogic | |
20392 | ||
20393 | @smallexample | |
20394 | @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int); | |
20395 | @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int); | |
20396 | @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int); | |
20397 | @exdent vector unsigned int vec_genpcvm (vector unsigned long long int, | |
20398 | const int); | |
20399 | @end smallexample | |
20400 | ||
20401 | Vector Integer Multiply/Divide/Modulo | |
20402 | ||
20403 | @smallexample | |
20404 | @exdent vector signed int | |
20405 | @exdent vec_mulh (vector signed int a, vector signed int b); | |
20406 | @exdent vector unsigned int | |
20407 | @exdent vec_mulh (vector unsigned int a, vector unsigned int b); | |
20408 | @end smallexample | |
20409 | ||
20410 | For each integer value @code{i} from 0 to 3, do the following. The integer | |
20411 | value in word element @code{i} of a is multiplied by the integer value in word | |
20412 | element @code{i} of b. The high-order 32 bits of the 64-bit product are placed | |
20413 | into word element @code{i} of the vector returned. | |
20414 | ||
20415 | @smallexample | |
20416 | @exdent vector signed long long | |
20417 | @exdent vec_mulh (vector signed long long a, vector signed long long b); | |
20418 | @exdent vector unsigned long long | |
20419 | @exdent vec_mulh (vector unsigned long long a, vector unsigned long long b); | |
20420 | @end smallexample | |
20421 | ||
20422 | For each integer value @code{i} from 0 to 1, do the following. The integer | |
20423 | value in doubleword element @code{i} of a is multiplied by the integer value in | |
20424 | doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product | |
20425 | are placed into doubleword element @code{i} of the vector returned. | |
20426 | ||
20427 | @smallexample | |
20428 | @exdent vector unsigned long long | |
20429 | @exdent vec_mul (vector unsigned long long a, vector unsigned long long b); | |
20430 | @exdent vector signed long long | |
20431 | @exdent vec_mul (vector signed long long a, vector signed long long b); | |
20432 | @end smallexample | |
20433 | ||
20434 | For each integer value @code{i} from 0 to 1, do the following. The integer | |
20435 | value in doubleword element @code{i} of a is multiplied by the integer value in | |
20436 | doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product | |
20437 | are placed into doubleword element @code{i} of the vector returned. | |
20438 | ||
20439 | @smallexample | |
20440 | @exdent vector signed int | |
20441 | @exdent vec_div (vector signed int a, vector signed int b); | |
20442 | @exdent vector unsigned int | |
20443 | @exdent vec_div (vector unsigned int a, vector unsigned int b); | |
20444 | @end smallexample | |
20445 | ||
20446 | For each integer value @code{i} from 0 to 3, do the following. The integer in | |
20447 | word element @code{i} of a is divided by the integer in word element @code{i} | |
20448 | of b. The unique integer quotient is placed into the word element @code{i} of | |
20449 | the vector returned. If an attempt is made to perform any of the divisions | |
20450 | <anything> ÷ 0 then the quotient is undefined. | |
20451 | ||
20452 | @smallexample | |
20453 | @exdent vector signed long long | |
20454 | @exdent vec_div (vector signed long long a, vector signed long long b); | |
20455 | @exdent vector unsigned long long | |
20456 | @exdent vec_div (vector unsigned long long a, vector unsigned long long b); | |
20457 | @end smallexample | |
20458 | ||
20459 | For each integer value @code{i} from 0 to 1, do the following. The integer in | |
20460 | doubleword element @code{i} of a is divided by the integer in doubleword | |
20461 | element @code{i} of b. The unique integer quotient is placed into the | |
20462 | doubleword element @code{i} of the vector returned. If an attempt is made to | |
20463 | perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then | |
20464 | the quotient is undefined. | |
20465 | ||
20466 | @smallexample | |
20467 | @exdent vector signed int | |
20468 | @exdent vec_dive (vector signed int a, vector signed int b); | |
20469 | @exdent vector unsigned int | |
20470 | @exdent vec_dive (vector unsigned int a, vector unsigned int b); | |
20471 | @end smallexample | |
20472 | ||
20473 | For each integer value @code{i} from 0 to 3, do the following. The integer in | |
20474 | word element @code{i} of a is shifted left by 32 bits, then divided by the | |
20475 | integer in word element @code{i} of b. The unique integer quotient is placed | |
20476 | into the word element @code{i} of the vector returned. If the quotient cannot | |
20477 | be represented in 32 bits, or if an attempt is made to perform any of the | |
20478 | divisions <anything> ÷ 0 then the quotient is undefined. | |
20479 | ||
20480 | @smallexample | |
20481 | @exdent vector signed long long | |
20482 | @exdent vec_dive (vector signed long long a, vector signed long long b); | |
20483 | @exdent vector unsigned long long | |
20484 | @exdent vec_dive (vector unsigned long long a, vector unsigned long long b); | |
20485 | @end smallexample | |
20486 | ||
20487 | For each integer value @code{i} from 0 to 1, do the following. The integer in | |
20488 | doubleword element @code{i} of a is shifted left by 64 bits, then divided by | |
20489 | the integer in doubleword element @code{i} of b. The unique integer quotient is | |
20490 | placed into the doubleword element @code{i} of the vector returned. If the | |
20491 | quotient cannot be represented in 64 bits, or if an attempt is made to perform | |
20492 | <anything> ÷ 0 then the quotient is undefined. | |
20493 | ||
20494 | @smallexample | |
20495 | @exdent vector signed int | |
20496 | @exdent vec_mod (vector signed int a, vector signed int b); | |
20497 | @exdent vector unsigned int | |
20498 | @exdent vec_mod (vector unsigned int a, vector unsigned int b); | |
20499 | @end smallexample | |
20500 | ||
20501 | For each integer value @code{i} from 0 to 3, do the following. The integer in | |
20502 | word element @code{i} of a is divided by the integer in word element @code{i} | |
20503 | of b. The unique integer remainder is placed into the word element @code{i} of | |
20504 | the vector returned. If an attempt is made to perform any of the divisions | |
20505 | 0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined. | |
20506 | ||
20507 | @smallexample | |
20508 | @exdent vector signed long long | |
20509 | @exdent vec_mod (vector signed long long a, vector signed long long b); | |
20510 | @exdent vector unsigned long long | |
20511 | @exdent vec_mod (vector unsigned long long a, vector unsigned long long b); | |
20512 | @end smallexample | |
20513 | ||
20514 | For each integer value @code{i} from 0 to 1, do the following. The integer in | |
20515 | doubleword element @code{i} of a is divided by the integer in doubleword | |
20516 | element @code{i} of b. The unique integer remainder is placed into the | |
20517 | doubleword element @code{i} of the vector returned. If an attempt is made to | |
20518 | perform <anything> ÷ 0 then the remainder is undefined. | |
20519 | ||
20520 | Generate PCV from specified Mask size, as if implemented by the | |
20521 | @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where | |
20522 | immediate value is either 0, 1, 2 or 3. | |
20523 | @findex vec_genpcvm | |
20524 | ||
20525 | @smallexample | |
20526 | @exdent vector unsigned __int128 vec_rl (vector unsigned __int128 A, | |
20527 | vector unsigned __int128 B); | |
20528 | @exdent vector signed __int128 vec_rl (vector signed __int128 A, | |
20529 | vector unsigned __int128 B); | |
20530 | @end smallexample | |
20531 | ||
20532 | Result value: Each element of R is obtained by rotating the corresponding element | |
20533 | of A left by the number of bits specified by the corresponding element of B. | |
20534 | ||
20535 | ||
20536 | @smallexample | |
20537 | @exdent vector unsigned __int128 vec_rlmi (vector unsigned __int128, | |
20538 | vector unsigned __int128, | |
20539 | vector unsigned __int128); | |
20540 | @exdent vector signed __int128 vec_rlmi (vector signed __int128, | |
20541 | vector signed __int128, | |
20542 | vector unsigned __int128); | |
20543 | @end smallexample | |
20544 | ||
20545 | Returns the result of rotating the first input and inserting it under mask | |
20546 | into the second input. The first bit in the mask, the last bit in the mask are | |
20547 | obtained from the two 7-bit fields bits [108:115] and bits [117:123] | |
20548 | respectively of the second input. The shift is obtained from the third input | |
20549 | in the 7-bit field [125:131] where all bits counted from zero at the left. | |
20550 | ||
20551 | @smallexample | |
20552 | @exdent vector unsigned __int128 vec_rlnm (vector unsigned __int128, | |
20553 | vector unsigned __int128, | |
20554 | vector unsigned __int128); | |
20555 | @exdent vector signed __int128 vec_rlnm (vector signed __int128, | |
20556 | vector unsigned __int128, | |
20557 | vector unsigned __int128); | |
20558 | @end smallexample | |
20559 | ||
20560 | Returns the result of rotating the first input and ANDing it with a mask. The | |
20561 | first bit in the mask and the last bit in the mask are obtained from the two | |
20562 | 7-bit fields bits [117:123] and bits [125:131] respectively of the second | |
20563 | input. The shift is obtained from the third input in the 7-bit field bits | |
20564 | [125:131] where all bits counted from zero at the left. | |
20565 | ||
20566 | @smallexample | |
20567 | @exdent vector unsigned __int128 vec_sl(vector unsigned __int128 A, vector unsigned __int128 B); | |
20568 | @exdent vector signed __int128 vec_sl(vector signed __int128 A, vector unsigned __int128 B); | |
20569 | @end smallexample | |
20570 | ||
20571 | Result value: Each element of R is obtained by shifting the corresponding element of | |
20572 | A left by the number of bits specified by the corresponding element of B. | |
20573 | ||
20574 | @smallexample | |
20575 | @exdent vector unsigned __int128 vec_sr(vector unsigned __int128 A, vector unsigned __int128 B); | |
20576 | @exdent vector signed __int128 vec_sr(vector signed __int128 A, vector unsigned __int128 B); | |
20577 | @end smallexample | |
20578 | ||
20579 | Result value: Each element of R is obtained by shifting the corresponding element of | |
20580 | A right by the number of bits specified by the corresponding element of B. | |
20581 | ||
20582 | @smallexample | |
20583 | @exdent vector unsigned __int128 vec_sra(vector unsigned __int128 A, vector unsigned __int128 B); | |
20584 | @exdent vector signed __int128 vec_sra(vector signed __int128 A, vector unsigned __int128 B); | |
20585 | @end smallexample | |
20586 | ||
20587 | Result value: Each element of R is obtained by arithmetic shifting the corresponding | |
20588 | element of A right by the number of bits specified by the corresponding element of B. | |
20589 | ||
20590 | @smallexample | |
20591 | @exdent vector unsigned __int128 vec_mule (vector unsigned long long, | |
20592 | vector unsigned long long); | |
20593 | @exdent vector signed __int128 vec_mule (vector signed long long, | |
20594 | vector signed long long); | |
20595 | @end smallexample | |
20596 | ||
20597 | Returns a vector containing a 128-bit integer result of multiplying the even | |
20598 | doubleword elements of the two inputs. | |
20599 | ||
20600 | @smallexample | |
20601 | @exdent vector unsigned __int128 vec_mulo (vector unsigned long long, | |
20602 | vector unsigned long long); | |
20603 | @exdent vector signed __int128 vec_mulo (vector signed long long, | |
20604 | vector signed long long); | |
20605 | @end smallexample | |
20606 | ||
20607 | Returns a vector containing a 128-bit integer result of multiplying the odd | |
20608 | doubleword elements of the two inputs. | |
20609 | ||
20610 | @smallexample | |
20611 | @exdent vector unsigned __int128 vec_div (vector unsigned __int128, | |
20612 | vector unsigned __int128); | |
20613 | @exdent vector signed __int128 vec_div (vector signed __int128, | |
20614 | vector signed __int128); | |
20615 | @end smallexample | |
20616 | ||
20617 | Returns the result of dividing the first operand by the second operand. An | |
20618 | attempt to divide any value by zero or to divide the most negative signed | |
20619 | 128-bit integer by negative one results in an undefined value. | |
20620 | ||
20621 | @smallexample | |
20622 | @exdent vector unsigned __int128 vec_dive (vector unsigned __int128, | |
20623 | vector unsigned __int128); | |
20624 | @exdent vector signed __int128 vec_dive (vector signed __int128, | |
20625 | vector signed __int128); | |
20626 | @end smallexample | |
20627 | ||
20628 | The result is produced by shifting the first input left by 128 bits and | |
20629 | dividing by the second. If an attempt is made to divide by zero or the result | |
20630 | is larger than 128 bits, the result is undefined. | |
20631 | ||
20632 | @smallexample | |
20633 | @exdent vector unsigned __int128 vec_mod (vector unsigned __int128, | |
20634 | vector unsigned __int128); | |
20635 | @exdent vector signed __int128 vec_mod (vector signed __int128, | |
20636 | vector signed __int128); | |
20637 | @end smallexample | |
20638 | ||
20639 | The result is the modulo result of dividing the first input by the second | |
20640 | input. | |
20641 | ||
20642 | The following builtins perform 128-bit vector comparisons. The | |
20643 | @code{vec_all_xx}, @code{vec_any_xx}, and @code{vec_cmpxx}, where @code{xx} is | |
20644 | one of the operations @code{eq, ne, gt, lt, ge, le} perform pairwise | |
20645 | comparisons between the elements at the same positions within their two vector | |
20646 | arguments. The @code{vec_all_xx}function returns a non-zero value if and only | |
20647 | if all pairwise comparisons are true. The @code{vec_any_xx} function returns | |
20648 | a non-zero value if and only if at least one pairwise comparison is true. The | |
20649 | @code{vec_cmpxx}function returns a vector of the same type as its two | |
20650 | arguments, within which each element consists of all ones to denote that | |
20651 | specified logical comparison of the corresponding elements was true. | |
20652 | Otherwise, the element of the returned vector contains all zeros. | |
20653 | ||
20654 | @smallexample | |
20655 | vector bool __int128 vec_cmpeq (vector signed __int128, vector signed __int128); | |
20656 | vector bool __int128 vec_cmpeq (vector unsigned __int128, vector unsigned __int128); | |
20657 | vector bool __int128 vec_cmpne (vector signed __int128, vector signed __int128); | |
20658 | vector bool __int128 vec_cmpne (vector unsigned __int128, vector unsigned __int128); | |
20659 | vector bool __int128 vec_cmpgt (vector signed __int128, vector signed __int128); | |
20660 | vector bool __int128 vec_cmpgt (vector unsigned __int128, vector unsigned __int128); | |
20661 | vector bool __int128 vec_cmplt (vector signed __int128, vector signed __int128); | |
20662 | vector bool __int128 vec_cmplt (vector unsigned __int128, vector unsigned __int128); | |
20663 | vector bool __int128 vec_cmpge (vector signed __int128, vector signed __int128); | |
20664 | vector bool __int128 vec_cmpge (vector unsigned __int128, vector unsigned __int128); | |
20665 | vector bool __int128 vec_cmple (vector signed __int128, vector signed __int128); | |
20666 | vector bool __int128 vec_cmple (vector unsigned __int128, vector unsigned __int128); | |
20667 | ||
20668 | int vec_all_eq (vector signed __int128, vector signed __int128); | |
20669 | int vec_all_eq (vector unsigned __int128, vector unsigned __int128); | |
20670 | int vec_all_ne (vector signed __int128, vector signed __int128); | |
20671 | int vec_all_ne (vector unsigned __int128, vector unsigned __int128); | |
20672 | int vec_all_gt (vector signed __int128, vector signed __int128); | |
20673 | int vec_all_gt (vector unsigned __int128, vector unsigned __int128); | |
20674 | int vec_all_lt (vector signed __int128, vector signed __int128); | |
20675 | int vec_all_lt (vector unsigned __int128, vector unsigned __int128); | |
20676 | int vec_all_ge (vector signed __int128, vector signed __int128); | |
20677 | int vec_all_ge (vector unsigned __int128, vector unsigned __int128); | |
20678 | int vec_all_le (vector signed __int128, vector signed __int128); | |
20679 | int vec_all_le (vector unsigned __int128, vector unsigned __int128); | |
20680 | ||
20681 | int vec_any_eq (vector signed __int128, vector signed __int128); | |
20682 | int vec_any_eq (vector unsigned __int128, vector unsigned __int128); | |
20683 | int vec_any_ne (vector signed __int128, vector signed __int128); | |
20684 | int vec_any_ne (vector unsigned __int128, vector unsigned __int128); | |
20685 | int vec_any_gt (vector signed __int128, vector signed __int128); | |
20686 | int vec_any_gt (vector unsigned __int128, vector unsigned __int128); | |
20687 | int vec_any_lt (vector signed __int128, vector signed __int128); | |
20688 | int vec_any_lt (vector unsigned __int128, vector unsigned __int128); | |
20689 | int vec_any_ge (vector signed __int128, vector signed __int128); | |
20690 | int vec_any_ge (vector unsigned __int128, vector unsigned __int128); | |
20691 | int vec_any_le (vector signed __int128, vector signed __int128); | |
20692 | int vec_any_le (vector unsigned __int128, vector unsigned __int128); | |
20693 | @end smallexample | |
20694 | ||
20695 | ||
20696 | @node PowerPC Hardware Transactional Memory Built-in Functions | |
20697 | @subsection PowerPC Hardware Transactional Memory Built-in Functions | |
20698 | GCC provides two interfaces for accessing the Hardware Transactional | |
20699 | Memory (HTM) instructions available on some of the PowerPC family | |
20700 | of processors (eg, POWER8). The two interfaces come in a low level | |
20701 | interface, consisting of built-in functions specific to PowerPC and a | |
20702 | higher level interface consisting of inline functions that are common | |
20703 | between PowerPC and S/390. | |
20704 | ||
20705 | @subsubsection PowerPC HTM Low Level Built-in Functions | |
20706 | ||
20707 | The following low level built-in functions are available with | |
20708 | @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. | |
20709 | They all generate the machine instruction that is part of the name. | |
20710 | ||
20711 | The HTM builtins (with the exception of @code{__builtin_tbegin}) return | |
20712 | the full 4-bit condition register value set by their associated hardware | |
20713 | instruction. The header file @code{htmintrin.h} defines some macros that can | |
20714 | be used to decipher the return value. The @code{__builtin_tbegin} builtin | |
20715 | returns a simple @code{true} or @code{false} value depending on whether a transaction was | |
20716 | successfully started or not. The arguments of the builtins match exactly the | |
20717 | type and order of the associated hardware instruction's operands, except for | |
20718 | the @code{__builtin_tcheck} builtin, which does not take any input arguments. | |
20719 | Refer to the ISA manual for a description of each instruction's operands. | |
20720 | ||
20721 | @smallexample | |
20722 | unsigned int __builtin_tbegin (unsigned int); | |
20723 | unsigned int __builtin_tend (unsigned int); | |
20724 | ||
20725 | unsigned int __builtin_tabort (unsigned int); | |
20726 | unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int); | |
20727 | unsigned int __builtin_tabortdci (unsigned int, unsigned int, int); | |
20728 | unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int); | |
20729 | unsigned int __builtin_tabortwci (unsigned int, unsigned int, int); | |
20730 | ||
20731 | unsigned int __builtin_tcheck (void); | |
20732 | unsigned int __builtin_treclaim (unsigned int); | |
20733 | unsigned int __builtin_trechkpt (void); | |
20734 | unsigned int __builtin_tsr (unsigned int); | |
20735 | @end smallexample | |
20736 | ||
20737 | In addition to the above HTM built-ins, we have added built-ins for | |
20738 | some common extended mnemonics of the HTM instructions: | |
20739 | ||
20740 | @smallexample | |
20741 | unsigned int __builtin_tendall (void); | |
20742 | unsigned int __builtin_tresume (void); | |
20743 | unsigned int __builtin_tsuspend (void); | |
20744 | @end smallexample | |
20745 | ||
20746 | Note that the semantics of the above HTM builtins are required to mimic | |
20747 | the locking semantics used for critical sections. Builtins that are used | |
20748 | to create a new transaction or restart a suspended transaction must have | |
20749 | lock acquisition like semantics while those builtins that end or suspend a | |
20750 | transaction must have lock release like semantics. Specifically, this must | |
20751 | mimic lock semantics as specified by C++11, for example: Lock acquisition is | |
20752 | as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) | |
20753 | that returns 0, and lock release is as-if an execution of | |
20754 | __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an | |
20755 | implicit implementation-defined lock used for all transactions. The HTM | |
20756 | instructions associated with with the builtins inherently provide the | |
20757 | correct acquisition and release hardware barriers required. However, | |
20758 | the compiler must also be prohibited from moving loads and stores across | |
20759 | the builtins in a way that would violate their semantics. This has been | |
20760 | accomplished by adding memory barriers to the associated HTM instructions | |
20761 | (which is a conservative approach to provide acquire and release semantics). | |
20762 | Earlier versions of the compiler did not treat the HTM instructions as | |
20763 | memory barriers. A @code{__TM_FENCE__} macro has been added, which can | |
20764 | be used to determine whether the current compiler treats HTM instructions | |
20765 | as memory barriers or not. This allows the user to explicitly add memory | |
20766 | barriers to their code when using an older version of the compiler. | |
20767 | ||
20768 | The following set of built-in functions are available to gain access | |
20769 | to the HTM specific special purpose registers. | |
20770 | ||
20771 | @smallexample | |
20772 | unsigned long __builtin_get_texasr (void); | |
20773 | unsigned long __builtin_get_texasru (void); | |
20774 | unsigned long __builtin_get_tfhar (void); | |
20775 | unsigned long __builtin_get_tfiar (void); | |
20776 | ||
20777 | void __builtin_set_texasr (unsigned long); | |
20778 | void __builtin_set_texasru (unsigned long); | |
20779 | void __builtin_set_tfhar (unsigned long); | |
20780 | void __builtin_set_tfiar (unsigned long); | |
20781 | @end smallexample | |
20782 | ||
20783 | Example usage of these low level built-in functions may look like: | |
20784 | ||
20785 | @smallexample | |
20786 | #include <htmintrin.h> | |
20787 | ||
20788 | int num_retries = 10; | |
20789 | ||
20790 | while (1) | |
20791 | @{ | |
20792 | if (__builtin_tbegin (0)) | |
20793 | @{ | |
20794 | /* Transaction State Initiated. */ | |
20795 | if (is_locked (lock)) | |
20796 | __builtin_tabort (0); | |
20797 | ... transaction code... | |
20798 | __builtin_tend (0); | |
20799 | break; | |
20800 | @} | |
20801 | else | |
20802 | @{ | |
20803 | /* Transaction State Failed. Use locks if the transaction | |
20804 | failure is "persistent" or we've tried too many times. */ | |
20805 | if (num_retries-- <= 0 | |
20806 | || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) | |
20807 | @{ | |
20808 | acquire_lock (lock); | |
20809 | ... non transactional fallback path... | |
20810 | release_lock (lock); | |
20811 | break; | |
20812 | @} | |
20813 | @} | |
20814 | @} | |
20815 | @end smallexample | |
20816 | ||
20817 | One final built-in function has been added that returns the value of | |
20818 | the 2-bit Transaction State field of the Machine Status Register (MSR) | |
20819 | as stored in @code{CR0}. | |
20820 | ||
20821 | @smallexample | |
20822 | unsigned long __builtin_ttest (void) | |
20823 | @end smallexample | |
20824 | ||
20825 | This built-in can be used to determine the current transaction state | |
20826 | using the following code example: | |
20827 | ||
20828 | @smallexample | |
20829 | #include <htmintrin.h> | |
20830 | ||
20831 | unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); | |
20832 | ||
20833 | if (tx_state == _HTM_TRANSACTIONAL) | |
20834 | @{ | |
20835 | /* Code to use in transactional state. */ | |
20836 | @} | |
20837 | else if (tx_state == _HTM_NONTRANSACTIONAL) | |
20838 | @{ | |
20839 | /* Code to use in non-transactional state. */ | |
20840 | @} | |
20841 | else if (tx_state == _HTM_SUSPENDED) | |
20842 | @{ | |
20843 | /* Code to use in transaction suspended state. */ | |
20844 | @} | |
20845 | @end smallexample | |
20846 | ||
20847 | @subsubsection PowerPC HTM High Level Inline Functions | |
20848 | ||
20849 | The following high level HTM interface is made available by including | |
20850 | @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU} | |
20851 | where CPU is `power8' or later. This interface is common between PowerPC | |
20852 | and S/390, allowing users to write one HTM source implementation that | |
20853 | can be compiled and executed on either system. | |
20854 | ||
20855 | @smallexample | |
20856 | long __TM_simple_begin (void); | |
20857 | long __TM_begin (void* const TM_buff); | |
20858 | long __TM_end (void); | |
20859 | void __TM_abort (void); | |
20860 | void __TM_named_abort (unsigned char const code); | |
20861 | void __TM_resume (void); | |
20862 | void __TM_suspend (void); | |
20863 | ||
20864 | long __TM_is_user_abort (void* const TM_buff); | |
20865 | long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code); | |
20866 | long __TM_is_illegal (void* const TM_buff); | |
20867 | long __TM_is_footprint_exceeded (void* const TM_buff); | |
20868 | long __TM_nesting_depth (void* const TM_buff); | |
20869 | long __TM_is_nested_too_deep(void* const TM_buff); | |
20870 | long __TM_is_conflict(void* const TM_buff); | |
20871 | long __TM_is_failure_persistent(void* const TM_buff); | |
20872 | long __TM_failure_address(void* const TM_buff); | |
20873 | long long __TM_failure_code(void* const TM_buff); | |
20874 | @end smallexample | |
20875 | ||
20876 | Using these common set of HTM inline functions, we can create | |
20877 | a more portable version of the HTM example in the previous | |
20878 | section that will work on either PowerPC or S/390: | |
20879 | ||
20880 | @smallexample | |
20881 | #include <htmxlintrin.h> | |
20882 | ||
20883 | int num_retries = 10; | |
20884 | TM_buff_type TM_buff; | |
20885 | ||
20886 | while (1) | |
20887 | @{ | |
20888 | if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED) | |
20889 | @{ | |
20890 | /* Transaction State Initiated. */ | |
20891 | if (is_locked (lock)) | |
20892 | __TM_abort (); | |
20893 | ... transaction code... | |
20894 | __TM_end (); | |
20895 | break; | |
20896 | @} | |
20897 | else | |
20898 | @{ | |
20899 | /* Transaction State Failed. Use locks if the transaction | |
20900 | failure is "persistent" or we've tried too many times. */ | |
20901 | if (num_retries-- <= 0 | |
20902 | || __TM_is_failure_persistent (TM_buff)) | |
20903 | @{ | |
20904 | acquire_lock (lock); | |
20905 | ... non transactional fallback path... | |
20906 | release_lock (lock); | |
20907 | break; | |
20908 | @} | |
20909 | @} | |
20910 | @} | |
20911 | @end smallexample | |
20912 | ||
20913 | @node PowerPC Atomic Memory Operation Functions | |
20914 | @subsection PowerPC Atomic Memory Operation Functions | |
20915 | ISA 3.0 of the PowerPC added new atomic memory operation (amo) | |
20916 | instructions. GCC provides support for these instructions in 64-bit | |
20917 | environments. All of the functions are declared in the include file | |
20918 | @code{amo.h}. | |
20919 | ||
20920 | The functions supported are: | |
20921 | ||
20922 | @smallexample | |
20923 | #include <amo.h> | |
20924 | ||
20925 | uint32_t amo_lwat_add (uint32_t *, uint32_t); | |
20926 | uint32_t amo_lwat_xor (uint32_t *, uint32_t); | |
20927 | uint32_t amo_lwat_ior (uint32_t *, uint32_t); | |
20928 | uint32_t amo_lwat_and (uint32_t *, uint32_t); | |
20929 | uint32_t amo_lwat_umax (uint32_t *, uint32_t); | |
20930 | uint32_t amo_lwat_umin (uint32_t *, uint32_t); | |
20931 | uint32_t amo_lwat_swap (uint32_t *, uint32_t); | |
20932 | ||
20933 | int32_t amo_lwat_sadd (int32_t *, int32_t); | |
20934 | int32_t amo_lwat_smax (int32_t *, int32_t); | |
20935 | int32_t amo_lwat_smin (int32_t *, int32_t); | |
20936 | int32_t amo_lwat_sswap (int32_t *, int32_t); | |
20937 | ||
20938 | uint64_t amo_ldat_add (uint64_t *, uint64_t); | |
20939 | uint64_t amo_ldat_xor (uint64_t *, uint64_t); | |
20940 | uint64_t amo_ldat_ior (uint64_t *, uint64_t); | |
20941 | uint64_t amo_ldat_and (uint64_t *, uint64_t); | |
20942 | uint64_t amo_ldat_umax (uint64_t *, uint64_t); | |
20943 | uint64_t amo_ldat_umin (uint64_t *, uint64_t); | |
20944 | uint64_t amo_ldat_swap (uint64_t *, uint64_t); | |
20945 | ||
20946 | int64_t amo_ldat_sadd (int64_t *, int64_t); | |
20947 | int64_t amo_ldat_smax (int64_t *, int64_t); | |
20948 | int64_t amo_ldat_smin (int64_t *, int64_t); | |
20949 | int64_t amo_ldat_sswap (int64_t *, int64_t); | |
20950 | ||
20951 | void amo_stwat_add (uint32_t *, uint32_t); | |
20952 | void amo_stwat_xor (uint32_t *, uint32_t); | |
20953 | void amo_stwat_ior (uint32_t *, uint32_t); | |
20954 | void amo_stwat_and (uint32_t *, uint32_t); | |
20955 | void amo_stwat_umax (uint32_t *, uint32_t); | |
20956 | void amo_stwat_umin (uint32_t *, uint32_t); | |
20957 | ||
20958 | void amo_stwat_sadd (int32_t *, int32_t); | |
20959 | void amo_stwat_smax (int32_t *, int32_t); | |
20960 | void amo_stwat_smin (int32_t *, int32_t); | |
20961 | ||
20962 | void amo_stdat_add (uint64_t *, uint64_t); | |
20963 | void amo_stdat_xor (uint64_t *, uint64_t); | |
20964 | void amo_stdat_ior (uint64_t *, uint64_t); | |
20965 | void amo_stdat_and (uint64_t *, uint64_t); | |
20966 | void amo_stdat_umax (uint64_t *, uint64_t); | |
20967 | void amo_stdat_umin (uint64_t *, uint64_t); | |
20968 | ||
20969 | void amo_stdat_sadd (int64_t *, int64_t); | |
20970 | void amo_stdat_smax (int64_t *, int64_t); | |
20971 | void amo_stdat_smin (int64_t *, int64_t); | |
20972 | @end smallexample | |
20973 | ||
20974 | @node PowerPC Matrix-Multiply Assist Built-in Functions | |
20975 | @subsection PowerPC Matrix-Multiply Assist Built-in Functions | |
20976 | ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions. | |
20977 | GCC provides support for these instructions through the following built-in | |
20978 | functions which are enabled with the @code{-mmma} option. The vec_t type | |
20979 | below is defined to be a normal vector unsigned char type. The uint2, uint4 | |
20980 | and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants | |
20981 | respectively. The compiler will verify that they are constants and that | |
20982 | their values are within range. | |
20983 | ||
20984 | The built-in functions supported are: | |
20985 | ||
20986 | @smallexample | |
20987 | void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t); | |
20988 | void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t); | |
20989 | void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t); | |
20990 | void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t); | |
20991 | void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t); | |
20992 | void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t); | |
20993 | void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t); | |
20994 | ||
20995 | void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t); | |
20996 | void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t); | |
20997 | void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t); | |
20998 | void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t); | |
20999 | void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t); | |
21000 | void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t); | |
21001 | void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t); | |
21002 | void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t); | |
21003 | void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t); | |
21004 | void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t); | |
21005 | void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t); | |
21006 | void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t); | |
21007 | void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t); | |
21008 | void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t); | |
21009 | void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t); | |
21010 | void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t); | |
21011 | void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t); | |
21012 | ||
21013 | void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8); | |
21014 | void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8); | |
21015 | ||
21016 | void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); | |
21017 | void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); | |
21018 | void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); | |
21019 | ||
21020 | void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21021 | void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21022 | void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21023 | void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21024 | ||
21025 | void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21026 | void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21027 | void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21028 | void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21029 | void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21030 | void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21031 | void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21032 | void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21033 | void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21034 | void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
21035 | ||
21036 | void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
21037 | void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
21038 | void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
21039 | void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
21040 | void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
21041 | ||
21042 | void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t); | |
21043 | void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t); | |
21044 | void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t); | |
21045 | void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t); | |
21046 | void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t); | |
21047 | ||
21048 | void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
21049 | void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
21050 | void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
21051 | void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
21052 | void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
21053 | ||
21054 | void __builtin_mma_xxmtacc (__vector_quad *); | |
21055 | void __builtin_mma_xxmfacc (__vector_quad *); | |
21056 | void __builtin_mma_xxsetaccz (__vector_quad *); | |
21057 | ||
21058 | void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t); | |
21059 | void __builtin_mma_disassemble_acc (void *, __vector_quad *); | |
21060 | ||
21061 | void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t); | |
21062 | void __builtin_vsx_disassemble_pair (void *, __vector_pair *); | |
21063 | ||
21064 | vec_t __builtin_vsx_xvcvspbf16 (vec_t); | |
21065 | vec_t __builtin_vsx_xvcvbf16spn (vec_t); | |
21066 | ||
21067 | __vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *); | |
21068 | void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *); | |
21069 | @end smallexample | |
21070 | ||
21071 | @node PRU Built-in Functions | |
21072 | @subsection PRU Built-in Functions | |
21073 | ||
21074 | GCC provides a couple of special builtin functions to aid in utilizing | |
21075 | special PRU instructions. | |
21076 | ||
21077 | The built-in functions supported are: | |
21078 | ||
f25efe50 | 21079 | @defbuiltin{void __delay_cycles (constant long long @var{cycles})} |
d77de738 ML |
21080 | This inserts an instruction sequence that takes exactly @var{cycles} |
21081 | cycles (between 0 and 0xffffffff) to complete. The inserted sequence | |
21082 | may use jumps, loops, or no-ops, and does not interfere with any other | |
21083 | instructions. Note that @var{cycles} must be a compile-time constant | |
21084 | integer - that is, you must pass a number, not a variable that may be | |
21085 | optimized to a constant later. The number of cycles delayed by this | |
21086 | builtin is exact. | |
f25efe50 | 21087 | @enddefbuiltin |
d77de738 | 21088 | |
f25efe50 | 21089 | @defbuiltin{void __halt (void)} |
d77de738 | 21090 | This inserts a HALT instruction to stop processor execution. |
f25efe50 | 21091 | @enddefbuiltin |
d77de738 | 21092 | |
f25efe50 AA |
21093 | @defbuiltin{{unsigned int} @ |
21094 | __lmbd (unsigned int @var{wordval}, @ | |
21095 | unsigned int @var{bitval})} | |
d77de738 ML |
21096 | This inserts LMBD instruction to calculate the left-most bit with value |
21097 | @var{bitval} in value @var{wordval}. Only the least significant bit | |
21098 | of @var{bitval} is taken into account. | |
f25efe50 | 21099 | @enddefbuiltin |
d77de738 ML |
21100 | |
21101 | @node RISC-V Built-in Functions | |
21102 | @subsection RISC-V Built-in Functions | |
21103 | ||
21104 | These built-in functions are available for the RISC-V family of | |
21105 | processors. | |
21106 | ||
f25efe50 | 21107 | @defbuiltin{{void *} __builtin_thread_pointer (void)} |
d77de738 | 21108 | Returns the value that is currently set in the @samp{tp} register. |
f25efe50 | 21109 | @enddefbuiltin |
d77de738 | 21110 | |
f25efe50 | 21111 | @defbuiltin{void __builtin_riscv_pause (void)} |
df049cb2 PD |
21112 | Generates the @code{pause} (hint) machine instruction. This implies the |
21113 | Xgnuzihintpausestate extension, which redefines the @code{pause} instruction to | |
21114 | change architectural state. | |
f25efe50 | 21115 | @enddefbuiltin |
c717a92d | 21116 | |
d77de738 ML |
21117 | @node RX Built-in Functions |
21118 | @subsection RX Built-in Functions | |
21119 | GCC supports some of the RX instructions which cannot be expressed in | |
21120 | the C programming language via the use of built-in functions. The | |
21121 | following functions are supported: | |
21122 | ||
f25efe50 | 21123 | @defbuiltin{void __builtin_rx_brk (void)} |
d77de738 | 21124 | Generates the @code{brk} machine instruction. |
f25efe50 | 21125 | @enddefbuiltin |
d77de738 | 21126 | |
f25efe50 | 21127 | @defbuiltin{void __builtin_rx_clrpsw (int)} |
d77de738 ML |
21128 | Generates the @code{clrpsw} machine instruction to clear the specified |
21129 | bit in the processor status word. | |
f25efe50 | 21130 | @enddefbuiltin |
d77de738 | 21131 | |
f25efe50 | 21132 | @defbuiltin{void __builtin_rx_int (int)} |
d77de738 ML |
21133 | Generates the @code{int} machine instruction to generate an interrupt |
21134 | with the specified value. | |
f25efe50 | 21135 | @enddefbuiltin |
d77de738 | 21136 | |
f25efe50 | 21137 | @defbuiltin{void __builtin_rx_machi (int, int)} |
d77de738 ML |
21138 | Generates the @code{machi} machine instruction to add the result of |
21139 | multiplying the top 16 bits of the two arguments into the | |
21140 | accumulator. | |
f25efe50 | 21141 | @enddefbuiltin |
d77de738 | 21142 | |
f25efe50 | 21143 | @defbuiltin{void __builtin_rx_maclo (int, int)} |
d77de738 ML |
21144 | Generates the @code{maclo} machine instruction to add the result of |
21145 | multiplying the bottom 16 bits of the two arguments into the | |
21146 | accumulator. | |
f25efe50 | 21147 | @enddefbuiltin |
d77de738 | 21148 | |
f25efe50 | 21149 | @defbuiltin{void __builtin_rx_mulhi (int, int)} |
d77de738 ML |
21150 | Generates the @code{mulhi} machine instruction to place the result of |
21151 | multiplying the top 16 bits of the two arguments into the | |
21152 | accumulator. | |
f25efe50 | 21153 | @enddefbuiltin |
d77de738 | 21154 | |
f25efe50 | 21155 | @defbuiltin{void __builtin_rx_mullo (int, int)} |
d77de738 ML |
21156 | Generates the @code{mullo} machine instruction to place the result of |
21157 | multiplying the bottom 16 bits of the two arguments into the | |
21158 | accumulator. | |
f25efe50 | 21159 | @enddefbuiltin |
d77de738 | 21160 | |
f25efe50 | 21161 | @defbuiltin{int __builtin_rx_mvfachi (void)} |
d77de738 ML |
21162 | Generates the @code{mvfachi} machine instruction to read the top |
21163 | 32 bits of the accumulator. | |
f25efe50 | 21164 | @enddefbuiltin |
d77de738 | 21165 | |
f25efe50 | 21166 | @defbuiltin{int __builtin_rx_mvfacmi (void)} |
d77de738 ML |
21167 | Generates the @code{mvfacmi} machine instruction to read the middle |
21168 | 32 bits of the accumulator. | |
f25efe50 | 21169 | @enddefbuiltin |
d77de738 | 21170 | |
f25efe50 | 21171 | @defbuiltin{int __builtin_rx_mvfc (int)} |
d77de738 ML |
21172 | Generates the @code{mvfc} machine instruction which reads the control |
21173 | register specified in its argument and returns its value. | |
f25efe50 | 21174 | @enddefbuiltin |
d77de738 | 21175 | |
f25efe50 | 21176 | @defbuiltin{void __builtin_rx_mvtachi (int)} |
d77de738 ML |
21177 | Generates the @code{mvtachi} machine instruction to set the top |
21178 | 32 bits of the accumulator. | |
f25efe50 | 21179 | @enddefbuiltin |
d77de738 | 21180 | |
f25efe50 | 21181 | @defbuiltin{void __builtin_rx_mvtaclo (int)} |
d77de738 ML |
21182 | Generates the @code{mvtaclo} machine instruction to set the bottom |
21183 | 32 bits of the accumulator. | |
f25efe50 | 21184 | @enddefbuiltin |
d77de738 | 21185 | |
f25efe50 | 21186 | @defbuiltin{void __builtin_rx_mvtc (int reg, int val)} |
d77de738 ML |
21187 | Generates the @code{mvtc} machine instruction which sets control |
21188 | register number @code{reg} to @code{val}. | |
f25efe50 | 21189 | @enddefbuiltin |
d77de738 | 21190 | |
f25efe50 | 21191 | @defbuiltin{void __builtin_rx_mvtipl (int)} |
d77de738 ML |
21192 | Generates the @code{mvtipl} machine instruction set the interrupt |
21193 | priority level. | |
f25efe50 | 21194 | @enddefbuiltin |
d77de738 | 21195 | |
f25efe50 | 21196 | @defbuiltin{void __builtin_rx_racw (int)} |
d77de738 ML |
21197 | Generates the @code{racw} machine instruction to round the accumulator |
21198 | according to the specified mode. | |
f25efe50 | 21199 | @enddefbuiltin |
d77de738 | 21200 | |
f25efe50 | 21201 | @defbuiltin{int __builtin_rx_revw (int)} |
d77de738 ML |
21202 | Generates the @code{revw} machine instruction which swaps the bytes in |
21203 | the argument so that bits 0--7 now occupy bits 8--15 and vice versa, | |
21204 | and also bits 16--23 occupy bits 24--31 and vice versa. | |
f25efe50 | 21205 | @enddefbuiltin |
d77de738 | 21206 | |
f25efe50 | 21207 | @defbuiltin{void __builtin_rx_rmpa (void)} |
d77de738 ML |
21208 | Generates the @code{rmpa} machine instruction which initiates a |
21209 | repeated multiply and accumulate sequence. | |
f25efe50 | 21210 | @enddefbuiltin |
d77de738 | 21211 | |
f25efe50 | 21212 | @defbuiltin{void __builtin_rx_round (float)} |
d77de738 ML |
21213 | Generates the @code{round} machine instruction which returns the |
21214 | floating-point argument rounded according to the current rounding mode | |
21215 | set in the floating-point status word register. | |
f25efe50 | 21216 | @enddefbuiltin |
d77de738 | 21217 | |
f25efe50 | 21218 | @defbuiltin{int __builtin_rx_sat (int)} |
d77de738 ML |
21219 | Generates the @code{sat} machine instruction which returns the |
21220 | saturated value of the argument. | |
f25efe50 | 21221 | @enddefbuiltin |
d77de738 | 21222 | |
f25efe50 | 21223 | @defbuiltin{void __builtin_rx_setpsw (int)} |
d77de738 ML |
21224 | Generates the @code{setpsw} machine instruction to set the specified |
21225 | bit in the processor status word. | |
f25efe50 | 21226 | @enddefbuiltin |
d77de738 | 21227 | |
f25efe50 | 21228 | @defbuiltin{void __builtin_rx_wait (void)} |
d77de738 | 21229 | Generates the @code{wait} machine instruction. |
f25efe50 | 21230 | @enddefbuiltin |
d77de738 ML |
21231 | |
21232 | @node S/390 System z Built-in Functions | |
21233 | @subsection S/390 System z Built-in Functions | |
f25efe50 | 21234 | @defbuiltin{int __builtin_tbegin (void*)} |
d77de738 ML |
21235 | Generates the @code{tbegin} machine instruction starting a |
21236 | non-constrained hardware transaction. If the parameter is non-NULL the | |
21237 | memory area is used to store the transaction diagnostic buffer and | |
21238 | will be passed as first operand to @code{tbegin}. This buffer can be | |
21239 | defined using the @code{struct __htm_tdb} C struct defined in | |
21240 | @code{htmintrin.h} and must reside on a double-word boundary. The | |
21241 | second tbegin operand is set to @code{0xff0c}. This enables | |
21242 | save/restore of all GPRs and disables aborts for FPR and AR | |
21243 | manipulations inside the transaction body. The condition code set by | |
21244 | the tbegin instruction is returned as integer value. The tbegin | |
21245 | instruction by definition overwrites the content of all FPRs. The | |
21246 | compiler will generate code which saves and restores the FPRs. For | |
21247 | soft-float code it is recommended to used the @code{*_nofloat} | |
21248 | variant. In order to prevent a TDB from being written it is required | |
21249 | to pass a constant zero value as parameter. Passing a zero value | |
21250 | through a variable is not sufficient. Although modifications of | |
21251 | access registers inside the transaction will not trigger an | |
21252 | transaction abort it is not supported to actually modify them. Access | |
21253 | registers do not get saved when entering a transaction. They will have | |
21254 | undefined state when reaching the abort code. | |
f25efe50 | 21255 | @enddefbuiltin |
d77de738 ML |
21256 | |
21257 | Macros for the possible return codes of tbegin are defined in the | |
21258 | @code{htmintrin.h} header file: | |
21259 | ||
f25efe50 | 21260 | @defmac _HTM_TBEGIN_STARTED |
d77de738 ML |
21261 | @code{tbegin} has been executed as part of normal processing. The |
21262 | transaction body is supposed to be executed. | |
f25efe50 AA |
21263 | @end defmac |
21264 | ||
21265 | @defmac _HTM_TBEGIN_INDETERMINATE | |
d77de738 ML |
21266 | The transaction was aborted due to an indeterminate condition which |
21267 | might be persistent. | |
f25efe50 AA |
21268 | @end defmac |
21269 | ||
21270 | @defmac _HTM_TBEGIN_TRANSIENT | |
d77de738 ML |
21271 | The transaction aborted due to a transient failure. The transaction |
21272 | should be re-executed in that case. | |
f25efe50 AA |
21273 | @end defmac |
21274 | ||
21275 | @defmac _HTM_TBEGIN_PERSISTENT | |
d77de738 ML |
21276 | The transaction aborted due to a persistent failure. Re-execution |
21277 | under same circumstances will not be productive. | |
f25efe50 | 21278 | @end defmac |
d77de738 ML |
21279 | |
21280 | @defmac _HTM_FIRST_USER_ABORT_CODE | |
21281 | The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h} | |
21282 | specifies the first abort code which can be used for | |
21283 | @code{__builtin_tabort}. Values below this threshold are reserved for | |
21284 | machine use. | |
21285 | @end defmac | |
21286 | ||
21287 | @deftp {Data type} {struct __htm_tdb} | |
21288 | The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes | |
21289 | the structure of the transaction diagnostic block as specified in the | |
21290 | Principles of Operation manual chapter 5-91. | |
21291 | @end deftp | |
21292 | ||
f25efe50 | 21293 | @defbuiltin{int __builtin_tbegin_nofloat (void*)} |
d77de738 ML |
21294 | Same as @code{__builtin_tbegin} but without FPR saves and restores. |
21295 | Using this variant in code making use of FPRs will leave the FPRs in | |
21296 | undefined state when entering the transaction abort handler code. | |
f25efe50 | 21297 | @enddefbuiltin |
d77de738 | 21298 | |
f25efe50 | 21299 | @defbuiltin{int __builtin_tbegin_retry (void*, int)} |
d77de738 ML |
21300 | In addition to @code{__builtin_tbegin} a loop for transient failures |
21301 | is generated. If tbegin returns a condition code of 2 the transaction | |
21302 | will be retried as often as specified in the second argument. The | |
21303 | perform processor assist instruction is used to tell the CPU about the | |
21304 | number of fails so far. | |
f25efe50 | 21305 | @enddefbuiltin |
d77de738 | 21306 | |
f25efe50 | 21307 | @defbuiltin{int __builtin_tbegin_retry_nofloat (void*, int)} |
d77de738 ML |
21308 | Same as @code{__builtin_tbegin_retry} but without FPR saves and |
21309 | restores. Using this variant in code making use of FPRs will leave | |
21310 | the FPRs in undefined state when entering the transaction abort | |
21311 | handler code. | |
f25efe50 | 21312 | @enddefbuiltin |
d77de738 | 21313 | |
f25efe50 | 21314 | @defbuiltin{void __builtin_tbeginc (void)} |
d77de738 ML |
21315 | Generates the @code{tbeginc} machine instruction starting a constrained |
21316 | hardware transaction. The second operand is set to @code{0xff08}. | |
f25efe50 | 21317 | @enddefbuiltin |
d77de738 | 21318 | |
f25efe50 | 21319 | @defbuiltin{int __builtin_tend (void)} |
d77de738 ML |
21320 | Generates the @code{tend} machine instruction finishing a transaction |
21321 | and making the changes visible to other threads. The condition code | |
21322 | generated by tend is returned as integer value. | |
f25efe50 | 21323 | @enddefbuiltin |
d77de738 | 21324 | |
f25efe50 | 21325 | @defbuiltin{void __builtin_tabort (int)} |
d77de738 ML |
21326 | Generates the @code{tabort} machine instruction with the specified |
21327 | abort code. Abort codes from 0 through 255 are reserved and will | |
21328 | result in an error message. | |
f25efe50 | 21329 | @enddefbuiltin |
d77de738 | 21330 | |
f25efe50 | 21331 | @defbuiltin{void __builtin_tx_assist (int)} |
d77de738 ML |
21332 | Generates the @code{ppa rX,rY,1} machine instruction. Where the |
21333 | integer parameter is loaded into rX and a value of zero is loaded into | |
21334 | rY. The integer parameter specifies the number of times the | |
21335 | transaction repeatedly aborted. | |
f25efe50 | 21336 | @enddefbuiltin |
d77de738 | 21337 | |
f25efe50 | 21338 | @defbuiltin{int __builtin_tx_nesting_depth (void)} |
d77de738 ML |
21339 | Generates the @code{etnd} machine instruction. The current nesting |
21340 | depth is returned as integer value. For a nesting depth of 0 the code | |
21341 | is not executed as part of an transaction. | |
f25efe50 | 21342 | @enddefbuiltin |
d77de738 | 21343 | |
f25efe50 | 21344 | @defbuiltin{void __builtin_non_tx_store (uint64_t *, uint64_t)} |
d77de738 ML |
21345 | |
21346 | Generates the @code{ntstg} machine instruction. The second argument | |
21347 | is written to the first arguments location. The store operation will | |
21348 | not be rolled-back in case of an transaction abort. | |
f25efe50 | 21349 | @enddefbuiltin |
d77de738 ML |
21350 | |
21351 | @node SH Built-in Functions | |
21352 | @subsection SH Built-in Functions | |
21353 | The following built-in functions are supported on the SH1, SH2, SH3 and SH4 | |
21354 | families of processors: | |
21355 | ||
f25efe50 | 21356 | @defbuiltin{{void} __builtin_set_thread_pointer (void *@var{ptr})} |
d77de738 ML |
21357 | Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually |
21358 | used by system code that manages threads and execution contexts. The compiler | |
21359 | normally does not generate code that modifies the contents of @samp{GBR} and | |
21360 | thus the value is preserved across function calls. Changing the @samp{GBR} | |
21361 | value in user code must be done with caution, since the compiler might use | |
21362 | @samp{GBR} in order to access thread local variables. | |
21363 | ||
f25efe50 | 21364 | @enddefbuiltin |
d77de738 | 21365 | |
f25efe50 | 21366 | @defbuiltin{{void *} __builtin_thread_pointer (void)} |
d77de738 ML |
21367 | Returns the value that is currently set in the @samp{GBR} register. |
21368 | Memory loads and stores that use the thread pointer as a base address are | |
21369 | turned into @samp{GBR} based displacement loads and stores, if possible. | |
21370 | For example: | |
21371 | @smallexample | |
21372 | struct my_tcb | |
21373 | @{ | |
21374 | int a, b, c, d, e; | |
21375 | @}; | |
21376 | ||
21377 | int get_tcb_value (void) | |
21378 | @{ | |
21379 | // Generate @samp{mov.l @@(8,gbr),r0} instruction | |
21380 | return ((my_tcb*)__builtin_thread_pointer ())->c; | |
21381 | @} | |
21382 | ||
21383 | @end smallexample | |
f25efe50 | 21384 | @enddefbuiltin |
d77de738 | 21385 | |
f25efe50 | 21386 | @defbuiltin{{unsigned int} __builtin_sh_get_fpscr (void)} |
d77de738 | 21387 | Returns the value that is currently set in the @samp{FPSCR} register. |
f25efe50 | 21388 | @enddefbuiltin |
d77de738 | 21389 | |
f25efe50 | 21390 | @defbuiltin{{void} __builtin_sh_set_fpscr (unsigned int @var{val})} |
d77de738 ML |
21391 | Sets the @samp{FPSCR} register to the specified value @var{val}, while |
21392 | preserving the current values of the FR, SZ and PR bits. | |
f25efe50 | 21393 | @enddefbuiltin |
d77de738 ML |
21394 | |
21395 | @node SPARC VIS Built-in Functions | |
21396 | @subsection SPARC VIS Built-in Functions | |
21397 | ||
21398 | GCC supports SIMD operations on the SPARC using both the generic vector | |
21399 | extensions (@pxref{Vector Extensions}) as well as built-in functions for | |
21400 | the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} | |
21401 | switch, the VIS extension is exposed as the following built-in functions: | |
21402 | ||
21403 | @smallexample | |
21404 | typedef int v1si __attribute__ ((vector_size (4))); | |
21405 | typedef int v2si __attribute__ ((vector_size (8))); | |
21406 | typedef short v4hi __attribute__ ((vector_size (8))); | |
21407 | typedef short v2hi __attribute__ ((vector_size (4))); | |
21408 | typedef unsigned char v8qi __attribute__ ((vector_size (8))); | |
21409 | typedef unsigned char v4qi __attribute__ ((vector_size (4))); | |
21410 | ||
21411 | void __builtin_vis_write_gsr (int64_t); | |
21412 | int64_t __builtin_vis_read_gsr (void); | |
21413 | ||
21414 | void * __builtin_vis_alignaddr (void *, long); | |
21415 | void * __builtin_vis_alignaddrl (void *, long); | |
21416 | int64_t __builtin_vis_faligndatadi (int64_t, int64_t); | |
21417 | v2si __builtin_vis_faligndatav2si (v2si, v2si); | |
21418 | v4hi __builtin_vis_faligndatav4hi (v4si, v4si); | |
21419 | v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); | |
21420 | ||
21421 | v4hi __builtin_vis_fexpand (v4qi); | |
21422 | ||
21423 | v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); | |
21424 | v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); | |
21425 | v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); | |
21426 | v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); | |
21427 | v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); | |
21428 | v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); | |
21429 | v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); | |
21430 | ||
21431 | v4qi __builtin_vis_fpack16 (v4hi); | |
21432 | v8qi __builtin_vis_fpack32 (v2si, v8qi); | |
21433 | v2hi __builtin_vis_fpackfix (v2si); | |
21434 | v8qi __builtin_vis_fpmerge (v4qi, v4qi); | |
21435 | ||
21436 | int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); | |
21437 | ||
21438 | long __builtin_vis_edge8 (void *, void *); | |
21439 | long __builtin_vis_edge8l (void *, void *); | |
21440 | long __builtin_vis_edge16 (void *, void *); | |
21441 | long __builtin_vis_edge16l (void *, void *); | |
21442 | long __builtin_vis_edge32 (void *, void *); | |
21443 | long __builtin_vis_edge32l (void *, void *); | |
21444 | ||
21445 | long __builtin_vis_fcmple16 (v4hi, v4hi); | |
21446 | long __builtin_vis_fcmple32 (v2si, v2si); | |
21447 | long __builtin_vis_fcmpne16 (v4hi, v4hi); | |
21448 | long __builtin_vis_fcmpne32 (v2si, v2si); | |
21449 | long __builtin_vis_fcmpgt16 (v4hi, v4hi); | |
21450 | long __builtin_vis_fcmpgt32 (v2si, v2si); | |
21451 | long __builtin_vis_fcmpeq16 (v4hi, v4hi); | |
21452 | long __builtin_vis_fcmpeq32 (v2si, v2si); | |
21453 | ||
21454 | v4hi __builtin_vis_fpadd16 (v4hi, v4hi); | |
21455 | v2hi __builtin_vis_fpadd16s (v2hi, v2hi); | |
21456 | v2si __builtin_vis_fpadd32 (v2si, v2si); | |
21457 | v1si __builtin_vis_fpadd32s (v1si, v1si); | |
21458 | v4hi __builtin_vis_fpsub16 (v4hi, v4hi); | |
21459 | v2hi __builtin_vis_fpsub16s (v2hi, v2hi); | |
21460 | v2si __builtin_vis_fpsub32 (v2si, v2si); | |
21461 | v1si __builtin_vis_fpsub32s (v1si, v1si); | |
21462 | ||
21463 | long __builtin_vis_array8 (long, long); | |
21464 | long __builtin_vis_array16 (long, long); | |
21465 | long __builtin_vis_array32 (long, long); | |
21466 | @end smallexample | |
21467 | ||
21468 | When you use the @option{-mvis2} switch, the VIS version 2.0 built-in | |
21469 | functions also become available: | |
21470 | ||
21471 | @smallexample | |
21472 | long __builtin_vis_bmask (long, long); | |
21473 | int64_t __builtin_vis_bshuffledi (int64_t, int64_t); | |
21474 | v2si __builtin_vis_bshufflev2si (v2si, v2si); | |
21475 | v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); | |
21476 | v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); | |
21477 | ||
21478 | long __builtin_vis_edge8n (void *, void *); | |
21479 | long __builtin_vis_edge8ln (void *, void *); | |
21480 | long __builtin_vis_edge16n (void *, void *); | |
21481 | long __builtin_vis_edge16ln (void *, void *); | |
21482 | long __builtin_vis_edge32n (void *, void *); | |
21483 | long __builtin_vis_edge32ln (void *, void *); | |
21484 | @end smallexample | |
21485 | ||
21486 | When you use the @option{-mvis3} switch, the VIS version 3.0 built-in | |
21487 | functions also become available: | |
21488 | ||
21489 | @smallexample | |
21490 | void __builtin_vis_cmask8 (long); | |
21491 | void __builtin_vis_cmask16 (long); | |
21492 | void __builtin_vis_cmask32 (long); | |
21493 | ||
21494 | v4hi __builtin_vis_fchksm16 (v4hi, v4hi); | |
21495 | ||
21496 | v4hi __builtin_vis_fsll16 (v4hi, v4hi); | |
21497 | v4hi __builtin_vis_fslas16 (v4hi, v4hi); | |
21498 | v4hi __builtin_vis_fsrl16 (v4hi, v4hi); | |
21499 | v4hi __builtin_vis_fsra16 (v4hi, v4hi); | |
21500 | v2si __builtin_vis_fsll16 (v2si, v2si); | |
21501 | v2si __builtin_vis_fslas16 (v2si, v2si); | |
21502 | v2si __builtin_vis_fsrl16 (v2si, v2si); | |
21503 | v2si __builtin_vis_fsra16 (v2si, v2si); | |
21504 | ||
21505 | long __builtin_vis_pdistn (v8qi, v8qi); | |
21506 | ||
21507 | v4hi __builtin_vis_fmean16 (v4hi, v4hi); | |
21508 | ||
21509 | int64_t __builtin_vis_fpadd64 (int64_t, int64_t); | |
21510 | int64_t __builtin_vis_fpsub64 (int64_t, int64_t); | |
21511 | ||
21512 | v4hi __builtin_vis_fpadds16 (v4hi, v4hi); | |
21513 | v2hi __builtin_vis_fpadds16s (v2hi, v2hi); | |
21514 | v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); | |
21515 | v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); | |
21516 | v2si __builtin_vis_fpadds32 (v2si, v2si); | |
21517 | v1si __builtin_vis_fpadds32s (v1si, v1si); | |
21518 | v2si __builtin_vis_fpsubs32 (v2si, v2si); | |
21519 | v1si __builtin_vis_fpsubs32s (v1si, v1si); | |
21520 | ||
21521 | long __builtin_vis_fucmple8 (v8qi, v8qi); | |
21522 | long __builtin_vis_fucmpne8 (v8qi, v8qi); | |
21523 | long __builtin_vis_fucmpgt8 (v8qi, v8qi); | |
21524 | long __builtin_vis_fucmpeq8 (v8qi, v8qi); | |
21525 | ||
21526 | float __builtin_vis_fhadds (float, float); | |
21527 | double __builtin_vis_fhaddd (double, double); | |
21528 | float __builtin_vis_fhsubs (float, float); | |
21529 | double __builtin_vis_fhsubd (double, double); | |
21530 | float __builtin_vis_fnhadds (float, float); | |
21531 | double __builtin_vis_fnhaddd (double, double); | |
21532 | ||
21533 | int64_t __builtin_vis_umulxhi (int64_t, int64_t); | |
21534 | int64_t __builtin_vis_xmulx (int64_t, int64_t); | |
21535 | int64_t __builtin_vis_xmulxhi (int64_t, int64_t); | |
21536 | @end smallexample | |
21537 | ||
21538 | When you use the @option{-mvis4} switch, the VIS version 4.0 built-in | |
21539 | functions also become available: | |
21540 | ||
21541 | @smallexample | |
21542 | v8qi __builtin_vis_fpadd8 (v8qi, v8qi); | |
21543 | v8qi __builtin_vis_fpadds8 (v8qi, v8qi); | |
21544 | v8qi __builtin_vis_fpaddus8 (v8qi, v8qi); | |
21545 | v4hi __builtin_vis_fpaddus16 (v4hi, v4hi); | |
21546 | ||
21547 | v8qi __builtin_vis_fpsub8 (v8qi, v8qi); | |
21548 | v8qi __builtin_vis_fpsubs8 (v8qi, v8qi); | |
21549 | v8qi __builtin_vis_fpsubus8 (v8qi, v8qi); | |
21550 | v4hi __builtin_vis_fpsubus16 (v4hi, v4hi); | |
21551 | ||
21552 | long __builtin_vis_fpcmple8 (v8qi, v8qi); | |
21553 | long __builtin_vis_fpcmpgt8 (v8qi, v8qi); | |
21554 | long __builtin_vis_fpcmpule16 (v4hi, v4hi); | |
21555 | long __builtin_vis_fpcmpugt16 (v4hi, v4hi); | |
21556 | long __builtin_vis_fpcmpule32 (v2si, v2si); | |
21557 | long __builtin_vis_fpcmpugt32 (v2si, v2si); | |
21558 | ||
21559 | v8qi __builtin_vis_fpmax8 (v8qi, v8qi); | |
21560 | v4hi __builtin_vis_fpmax16 (v4hi, v4hi); | |
21561 | v2si __builtin_vis_fpmax32 (v2si, v2si); | |
21562 | ||
21563 | v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi); | |
21564 | v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi); | |
21565 | v2si __builtin_vis_fpmaxu32 (v2si, v2si); | |
21566 | ||
21567 | v8qi __builtin_vis_fpmin8 (v8qi, v8qi); | |
21568 | v4hi __builtin_vis_fpmin16 (v4hi, v4hi); | |
21569 | v2si __builtin_vis_fpmin32 (v2si, v2si); | |
21570 | ||
21571 | v8qi __builtin_vis_fpminu8 (v8qi, v8qi); | |
21572 | v4hi __builtin_vis_fpminu16 (v4hi, v4hi); | |
21573 | v2si __builtin_vis_fpminu32 (v2si, v2si); | |
21574 | @end smallexample | |
21575 | ||
21576 | When you use the @option{-mvis4b} switch, the VIS version 4.0B | |
21577 | built-in functions also become available: | |
21578 | ||
21579 | @smallexample | |
21580 | v8qi __builtin_vis_dictunpack8 (double, int); | |
21581 | v4hi __builtin_vis_dictunpack16 (double, int); | |
21582 | v2si __builtin_vis_dictunpack32 (double, int); | |
21583 | ||
21584 | long __builtin_vis_fpcmple8shl (v8qi, v8qi, int); | |
21585 | long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int); | |
21586 | long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int); | |
21587 | long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int); | |
21588 | ||
21589 | long __builtin_vis_fpcmple16shl (v4hi, v4hi, int); | |
21590 | long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int); | |
21591 | long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int); | |
21592 | long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int); | |
21593 | ||
21594 | long __builtin_vis_fpcmple32shl (v2si, v2si, int); | |
21595 | long __builtin_vis_fpcmpgt32shl (v2si, v2si, int); | |
21596 | long __builtin_vis_fpcmpeq32shl (v2si, v2si, int); | |
21597 | long __builtin_vis_fpcmpne32shl (v2si, v2si, int); | |
21598 | ||
21599 | long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int); | |
21600 | long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int); | |
21601 | long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int); | |
21602 | long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int); | |
21603 | long __builtin_vis_fpcmpule32shl (v2si, v2si, int); | |
21604 | long __builtin_vis_fpcmpugt32shl (v2si, v2si, int); | |
21605 | ||
21606 | long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int); | |
21607 | long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int); | |
21608 | long __builtin_vis_fpcmpde32shl (v2si, v2si, int); | |
21609 | ||
21610 | long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int); | |
21611 | long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int); | |
21612 | long __builtin_vis_fpcmpur32shl (v2si, v2si, int); | |
21613 | @end smallexample | |
21614 | ||
21615 | @node TI C6X Built-in Functions | |
21616 | @subsection TI C6X Built-in Functions | |
21617 | ||
21618 | GCC provides intrinsics to access certain instructions of the TI C6X | |
21619 | processors. These intrinsics, listed below, are available after | |
21620 | inclusion of the @code{c6x_intrinsics.h} header file. They map directly | |
21621 | to C6X instructions. | |
21622 | ||
21623 | @smallexample | |
21624 | int _sadd (int, int); | |
21625 | int _ssub (int, int); | |
21626 | int _sadd2 (int, int); | |
21627 | int _ssub2 (int, int); | |
21628 | long long _mpy2 (int, int); | |
21629 | long long _smpy2 (int, int); | |
21630 | int _add4 (int, int); | |
21631 | int _sub4 (int, int); | |
21632 | int _saddu4 (int, int); | |
21633 | ||
21634 | int _smpy (int, int); | |
21635 | int _smpyh (int, int); | |
21636 | int _smpyhl (int, int); | |
21637 | int _smpylh (int, int); | |
21638 | ||
21639 | int _sshl (int, int); | |
21640 | int _subc (int, int); | |
21641 | ||
21642 | int _avg2 (int, int); | |
21643 | int _avgu4 (int, int); | |
21644 | ||
21645 | int _clrr (int, int); | |
21646 | int _extr (int, int); | |
21647 | int _extru (int, int); | |
21648 | int _abs (int); | |
21649 | int _abs2 (int); | |
21650 | @end smallexample | |
21651 | ||
21652 | @node x86 Built-in Functions | |
21653 | @subsection x86 Built-in Functions | |
21654 | ||
21655 | These built-in functions are available for the x86-32 and x86-64 family | |
21656 | of computers, depending on the command-line switches used. | |
21657 | ||
21658 | If you specify command-line switches such as @option{-msse}, | |
21659 | the compiler could use the extended instruction sets even if the built-ins | |
21660 | are not used explicitly in the program. For this reason, applications | |
21661 | that perform run-time CPU detection must compile separate files for each | |
21662 | supported architecture, using the appropriate flags. In particular, | |
21663 | the file containing the CPU detection code should be compiled without | |
21664 | these options. | |
21665 | ||
21666 | The following machine modes are available for use with MMX built-in functions | |
21667 | (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, | |
21668 | @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a | |
21669 | vector of eight 8-bit integers. Some of the built-in functions operate on | |
21670 | MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. | |
21671 | ||
21672 | If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector | |
21673 | of two 32-bit floating-point values. | |
21674 | ||
21675 | If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit | |
21676 | floating-point values. Some instructions use a vector of four 32-bit | |
21677 | integers, these use @code{V4SI}. Finally, some instructions operate on an | |
21678 | entire vector register, interpreting it as a 128-bit integer, these use mode | |
21679 | @code{TI}. | |
21680 | ||
21681 | The x86-32 and x86-64 family of processors use additional built-in | |
21682 | functions for efficient use of @code{TF} (@code{__float128}) 128-bit | |
21683 | floating point and @code{TC} 128-bit complex floating-point values. | |
21684 | ||
f25efe50 | 21685 | The following floating-point built-in functions are always available: |
d77de738 | 21686 | |
f25efe50 AA |
21687 | @defbuiltin{__float128 __builtin_fabsq (__float128 @var{x}))} |
21688 | Computes the absolute value of @var{x}. | |
21689 | @enddefbuiltin | |
d77de738 | 21690 | |
f25efe50 AA |
21691 | @defbuiltin{__float128 __builtin_copysignq (__float128 @var{x}, @ |
21692 | __float128 @var{y})} | |
21693 | Copies the sign of @var{y} into @var{x} and returns the new value of | |
21694 | @var{x}. | |
21695 | @enddefbuiltin | |
d77de738 | 21696 | |
f25efe50 | 21697 | @defbuiltin{__float128 __builtin_infq (void)} |
d77de738 | 21698 | Similar to @code{__builtin_inf}, except the return type is @code{__float128}. |
f25efe50 | 21699 | @enddefbuiltin |
d77de738 | 21700 | |
f25efe50 | 21701 | @defbuiltin{__float128 __builtin_huge_valq (void)} |
d77de738 | 21702 | Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. |
f25efe50 | 21703 | @enddefbuiltin |
d77de738 | 21704 | |
f25efe50 | 21705 | @defbuiltin{__float128 __builtin_nanq (void)} |
d77de738 | 21706 | Similar to @code{__builtin_nan}, except the return type is @code{__float128}. |
f25efe50 | 21707 | @enddefbuiltin |
d77de738 | 21708 | |
f25efe50 | 21709 | @defbuiltin{__float128 __builtin_nansq (void)} |
d77de738 | 21710 | Similar to @code{__builtin_nans}, except the return type is @code{__float128}. |
f25efe50 | 21711 | @enddefbuiltin |
d77de738 ML |
21712 | |
21713 | The following built-in function is always available. | |
21714 | ||
f25efe50 | 21715 | @defbuiltin{void __builtin_ia32_pause (void)} |
d77de738 ML |
21716 | Generates the @code{pause} machine instruction with a compiler memory |
21717 | barrier. | |
f25efe50 | 21718 | @enddefbuiltin |
d77de738 ML |
21719 | |
21720 | The following built-in functions are always available and can be used to | |
21721 | check the target platform type. | |
21722 | ||
f25efe50 | 21723 | @defbuiltin{void __builtin_cpu_init (void)} |
d77de738 ML |
21724 | This function runs the CPU detection code to check the type of CPU and the |
21725 | features supported. This built-in function needs to be invoked along with the built-in functions | |
21726 | to check CPU type and features, @code{__builtin_cpu_is} and | |
21727 | @code{__builtin_cpu_supports}, only when used in a function that is | |
21728 | executed before any constructors are called. The CPU detection code is | |
21729 | automatically executed in a very high priority constructor. | |
21730 | ||
21731 | For example, this function has to be used in @code{ifunc} resolvers that | |
21732 | check for CPU type using the built-in functions @code{__builtin_cpu_is} | |
21733 | and @code{__builtin_cpu_supports}, or in constructors on targets that | |
21734 | don't support constructor priority. | |
21735 | @smallexample | |
21736 | ||
21737 | static void (*resolve_memcpy (void)) (void) | |
21738 | @{ | |
21739 | // ifunc resolvers fire before constructors, explicitly call the init | |
21740 | // function. | |
21741 | __builtin_cpu_init (); | |
21742 | if (__builtin_cpu_supports ("ssse3")) | |
21743 | return ssse3_memcpy; // super fast memcpy with ssse3 instructions. | |
21744 | else | |
21745 | return default_memcpy; | |
21746 | @} | |
21747 | ||
21748 | void *memcpy (void *, const void *, size_t) | |
21749 | __attribute__ ((ifunc ("resolve_memcpy"))); | |
21750 | @end smallexample | |
21751 | ||
f25efe50 | 21752 | @enddefbuiltin |
d77de738 | 21753 | |
f25efe50 | 21754 | @defbuiltin{int __builtin_cpu_is (const char *@var{cpuname})} |
d77de738 ML |
21755 | This function returns a positive integer if the run-time CPU |
21756 | is of type @var{cpuname} | |
21757 | and returns @code{0} otherwise. The following CPU names can be detected: | |
21758 | ||
21759 | @table @samp | |
21760 | @item amd | |
21761 | AMD CPU. | |
21762 | ||
21763 | @item intel | |
21764 | Intel CPU. | |
21765 | ||
21766 | @item atom | |
21767 | Intel Atom CPU. | |
21768 | ||
21769 | @item slm | |
21770 | Intel Silvermont CPU. | |
21771 | ||
21772 | @item core2 | |
21773 | Intel Core 2 CPU. | |
21774 | ||
21775 | @item corei7 | |
21776 | Intel Core i7 CPU. | |
21777 | ||
21778 | @item nehalem | |
21779 | Intel Core i7 Nehalem CPU. | |
21780 | ||
21781 | @item westmere | |
21782 | Intel Core i7 Westmere CPU. | |
21783 | ||
21784 | @item sandybridge | |
21785 | Intel Core i7 Sandy Bridge CPU. | |
21786 | ||
21787 | @item ivybridge | |
21788 | Intel Core i7 Ivy Bridge CPU. | |
21789 | ||
21790 | @item haswell | |
21791 | Intel Core i7 Haswell CPU. | |
21792 | ||
21793 | @item broadwell | |
21794 | Intel Core i7 Broadwell CPU. | |
21795 | ||
21796 | @item skylake | |
21797 | Intel Core i7 Skylake CPU. | |
21798 | ||
21799 | @item skylake-avx512 | |
21800 | Intel Core i7 Skylake AVX512 CPU. | |
21801 | ||
21802 | @item cannonlake | |
21803 | Intel Core i7 Cannon Lake CPU. | |
21804 | ||
21805 | @item icelake-client | |
21806 | Intel Core i7 Ice Lake Client CPU. | |
21807 | ||
21808 | @item icelake-server | |
21809 | Intel Core i7 Ice Lake Server CPU. | |
21810 | ||
21811 | @item cascadelake | |
21812 | Intel Core i7 Cascadelake CPU. | |
21813 | ||
21814 | @item tigerlake | |
21815 | Intel Core i7 Tigerlake CPU. | |
21816 | ||
21817 | @item cooperlake | |
21818 | Intel Core i7 Cooperlake CPU. | |
21819 | ||
21820 | @item sapphirerapids | |
21821 | Intel Core i7 sapphirerapids CPU. | |
21822 | ||
21823 | @item alderlake | |
21824 | Intel Core i7 Alderlake CPU. | |
21825 | ||
21826 | @item rocketlake | |
21827 | Intel Core i7 Rocketlake CPU. | |
21828 | ||
21829 | @item graniterapids | |
21830 | Intel Core i7 graniterapids CPU. | |
21831 | ||
21832 | @item bonnell | |
21833 | Intel Atom Bonnell CPU. | |
21834 | ||
21835 | @item silvermont | |
21836 | Intel Atom Silvermont CPU. | |
21837 | ||
21838 | @item goldmont | |
21839 | Intel Atom Goldmont CPU. | |
21840 | ||
21841 | @item goldmont-plus | |
21842 | Intel Atom Goldmont Plus CPU. | |
21843 | ||
21844 | @item tremont | |
21845 | Intel Atom Tremont CPU. | |
21846 | ||
21847 | @item sierraforest | |
21848 | Intel Atom Sierra Forest CPU. | |
21849 | ||
21850 | @item grandridge | |
21851 | Intel Atom Grand Ridge CPU. | |
21852 | ||
21853 | @item knl | |
21854 | Intel Knights Landing CPU. | |
21855 | ||
21856 | @item knm | |
21857 | Intel Knights Mill CPU. | |
21858 | ||
21859 | @item lujiazui | |
21860 | ZHAOXIN lujiazui CPU. | |
21861 | ||
21862 | @item amdfam10h | |
21863 | AMD Family 10h CPU. | |
21864 | ||
21865 | @item barcelona | |
21866 | AMD Family 10h Barcelona CPU. | |
21867 | ||
21868 | @item shanghai | |
21869 | AMD Family 10h Shanghai CPU. | |
21870 | ||
21871 | @item istanbul | |
21872 | AMD Family 10h Istanbul CPU. | |
21873 | ||
21874 | @item btver1 | |
21875 | AMD Family 14h CPU. | |
21876 | ||
21877 | @item amdfam15h | |
21878 | AMD Family 15h CPU. | |
21879 | ||
21880 | @item bdver1 | |
21881 | AMD Family 15h Bulldozer version 1. | |
21882 | ||
21883 | @item bdver2 | |
21884 | AMD Family 15h Bulldozer version 2. | |
21885 | ||
21886 | @item bdver3 | |
21887 | AMD Family 15h Bulldozer version 3. | |
21888 | ||
21889 | @item bdver4 | |
21890 | AMD Family 15h Bulldozer version 4. | |
21891 | ||
21892 | @item btver2 | |
21893 | AMD Family 16h CPU. | |
21894 | ||
21895 | @item amdfam17h | |
21896 | AMD Family 17h CPU. | |
21897 | ||
21898 | @item znver1 | |
21899 | AMD Family 17h Zen version 1. | |
21900 | ||
21901 | @item znver2 | |
21902 | AMD Family 17h Zen version 2. | |
21903 | ||
21904 | @item amdfam19h | |
21905 | AMD Family 19h CPU. | |
21906 | ||
21907 | @item znver3 | |
21908 | AMD Family 19h Zen version 3. | |
21909 | ||
21910 | @item znver4 | |
21911 | AMD Family 19h Zen version 4. | |
d77de738 ML |
21912 | @end table |
21913 | ||
21914 | Here is an example: | |
21915 | @smallexample | |
21916 | if (__builtin_cpu_is ("corei7")) | |
21917 | @{ | |
21918 | do_corei7 (); // Core i7 specific implementation. | |
21919 | @} | |
21920 | else | |
21921 | @{ | |
21922 | do_generic (); // Generic implementation. | |
21923 | @} | |
21924 | @end smallexample | |
f25efe50 | 21925 | @enddefbuiltin |
d77de738 | 21926 | |
f25efe50 | 21927 | @defbuiltin{int __builtin_cpu_supports (const char *@var{feature})} |
d77de738 ML |
21928 | This function returns a positive integer if the run-time CPU |
21929 | supports @var{feature} | |
21930 | and returns @code{0} otherwise. The following features can be detected: | |
21931 | ||
21932 | @table @samp | |
21933 | @item cmov | |
21934 | CMOV instruction. | |
21935 | @item mmx | |
21936 | MMX instructions. | |
21937 | @item popcnt | |
21938 | POPCNT instruction. | |
21939 | @item sse | |
21940 | SSE instructions. | |
21941 | @item sse2 | |
21942 | SSE2 instructions. | |
21943 | @item sse3 | |
21944 | SSE3 instructions. | |
21945 | @item ssse3 | |
21946 | SSSE3 instructions. | |
21947 | @item sse4.1 | |
21948 | SSE4.1 instructions. | |
21949 | @item sse4.2 | |
21950 | SSE4.2 instructions. | |
21951 | @item avx | |
21952 | AVX instructions. | |
21953 | @item avx2 | |
21954 | AVX2 instructions. | |
21955 | @item sse4a | |
21956 | SSE4A instructions. | |
21957 | @item fma4 | |
21958 | FMA4 instructions. | |
21959 | @item xop | |
21960 | XOP instructions. | |
21961 | @item fma | |
21962 | FMA instructions. | |
21963 | @item avx512f | |
21964 | AVX512F instructions. | |
21965 | @item bmi | |
21966 | BMI instructions. | |
21967 | @item bmi2 | |
21968 | BMI2 instructions. | |
21969 | @item aes | |
21970 | AES instructions. | |
21971 | @item pclmul | |
21972 | PCLMUL instructions. | |
21973 | @item avx512vl | |
21974 | AVX512VL instructions. | |
21975 | @item avx512bw | |
21976 | AVX512BW instructions. | |
21977 | @item avx512dq | |
21978 | AVX512DQ instructions. | |
21979 | @item avx512cd | |
21980 | AVX512CD instructions. | |
21981 | @item avx512er | |
21982 | AVX512ER instructions. | |
21983 | @item avx512pf | |
21984 | AVX512PF instructions. | |
21985 | @item avx512vbmi | |
21986 | AVX512VBMI instructions. | |
21987 | @item avx512ifma | |
21988 | AVX512IFMA instructions. | |
21989 | @item avx5124vnniw | |
21990 | AVX5124VNNIW instructions. | |
21991 | @item avx5124fmaps | |
21992 | AVX5124FMAPS instructions. | |
21993 | @item avx512vpopcntdq | |
21994 | AVX512VPOPCNTDQ instructions. | |
21995 | @item avx512vbmi2 | |
21996 | AVX512VBMI2 instructions. | |
21997 | @item gfni | |
21998 | GFNI instructions. | |
21999 | @item vpclmulqdq | |
22000 | VPCLMULQDQ instructions. | |
22001 | @item avx512vnni | |
22002 | AVX512VNNI instructions. | |
22003 | @item avx512bitalg | |
22004 | AVX512BITALG instructions. | |
d71b20fc ML |
22005 | @item x86-64 |
22006 | Baseline x86-64 microarchitecture level (as defined in x86-64 psABI). | |
22007 | @item x86-64-v2 | |
22008 | x86-64-v2 microarchitecture level. | |
22009 | @item x86-64-v3 | |
22010 | x86-64-v3 microarchitecture level. | |
22011 | @item x86-64-v4 | |
22012 | x86-64-v4 microarchitecture level. | |
22013 | ||
22014 | ||
d77de738 ML |
22015 | @end table |
22016 | ||
22017 | Here is an example: | |
22018 | @smallexample | |
22019 | if (__builtin_cpu_supports ("popcnt")) | |
22020 | @{ | |
22021 | asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc"); | |
22022 | @} | |
22023 | else | |
22024 | @{ | |
22025 | count = generic_countbits (n); //generic implementation. | |
22026 | @} | |
22027 | @end smallexample | |
f25efe50 | 22028 | @enddefbuiltin |
d77de738 ML |
22029 | |
22030 | The following built-in functions are made available by @option{-mmmx}. | |
22031 | All of them generate the machine instruction that is part of the name. | |
22032 | ||
22033 | @smallexample | |
22034 | v8qi __builtin_ia32_paddb (v8qi, v8qi); | |
22035 | v4hi __builtin_ia32_paddw (v4hi, v4hi); | |
22036 | v2si __builtin_ia32_paddd (v2si, v2si); | |
22037 | v8qi __builtin_ia32_psubb (v8qi, v8qi); | |
22038 | v4hi __builtin_ia32_psubw (v4hi, v4hi); | |
22039 | v2si __builtin_ia32_psubd (v2si, v2si); | |
22040 | v8qi __builtin_ia32_paddsb (v8qi, v8qi); | |
22041 | v4hi __builtin_ia32_paddsw (v4hi, v4hi); | |
22042 | v8qi __builtin_ia32_psubsb (v8qi, v8qi); | |
22043 | v4hi __builtin_ia32_psubsw (v4hi, v4hi); | |
22044 | v8qi __builtin_ia32_paddusb (v8qi, v8qi); | |
22045 | v4hi __builtin_ia32_paddusw (v4hi, v4hi); | |
22046 | v8qi __builtin_ia32_psubusb (v8qi, v8qi); | |
22047 | v4hi __builtin_ia32_psubusw (v4hi, v4hi); | |
22048 | v4hi __builtin_ia32_pmullw (v4hi, v4hi); | |
22049 | v4hi __builtin_ia32_pmulhw (v4hi, v4hi); | |
22050 | di __builtin_ia32_pand (di, di); | |
22051 | di __builtin_ia32_pandn (di,di); | |
22052 | di __builtin_ia32_por (di, di); | |
22053 | di __builtin_ia32_pxor (di, di); | |
22054 | v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi); | |
22055 | v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi); | |
22056 | v2si __builtin_ia32_pcmpeqd (v2si, v2si); | |
22057 | v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi); | |
22058 | v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi); | |
22059 | v2si __builtin_ia32_pcmpgtd (v2si, v2si); | |
22060 | v8qi __builtin_ia32_punpckhbw (v8qi, v8qi); | |
22061 | v4hi __builtin_ia32_punpckhwd (v4hi, v4hi); | |
22062 | v2si __builtin_ia32_punpckhdq (v2si, v2si); | |
22063 | v8qi __builtin_ia32_punpcklbw (v8qi, v8qi); | |
22064 | v4hi __builtin_ia32_punpcklwd (v4hi, v4hi); | |
22065 | v2si __builtin_ia32_punpckldq (v2si, v2si); | |
22066 | v8qi __builtin_ia32_packsswb (v4hi, v4hi); | |
22067 | v4hi __builtin_ia32_packssdw (v2si, v2si); | |
22068 | v8qi __builtin_ia32_packuswb (v4hi, v4hi); | |
22069 | ||
22070 | v4hi __builtin_ia32_psllw (v4hi, v4hi); | |
22071 | v2si __builtin_ia32_pslld (v2si, v2si); | |
22072 | v1di __builtin_ia32_psllq (v1di, v1di); | |
22073 | v4hi __builtin_ia32_psrlw (v4hi, v4hi); | |
22074 | v2si __builtin_ia32_psrld (v2si, v2si); | |
22075 | v1di __builtin_ia32_psrlq (v1di, v1di); | |
22076 | v4hi __builtin_ia32_psraw (v4hi, v4hi); | |
22077 | v2si __builtin_ia32_psrad (v2si, v2si); | |
22078 | v4hi __builtin_ia32_psllwi (v4hi, int); | |
22079 | v2si __builtin_ia32_pslldi (v2si, int); | |
22080 | v1di __builtin_ia32_psllqi (v1di, int); | |
22081 | v4hi __builtin_ia32_psrlwi (v4hi, int); | |
22082 | v2si __builtin_ia32_psrldi (v2si, int); | |
22083 | v1di __builtin_ia32_psrlqi (v1di, int); | |
22084 | v4hi __builtin_ia32_psrawi (v4hi, int); | |
22085 | v2si __builtin_ia32_psradi (v2si, int); | |
22086 | @end smallexample | |
22087 | ||
22088 | The following built-in functions are made available either with | |
22089 | @option{-msse}, or with @option{-m3dnowa}. All of them generate | |
22090 | the machine instruction that is part of the name. | |
22091 | ||
22092 | @smallexample | |
22093 | v4hi __builtin_ia32_pmulhuw (v4hi, v4hi); | |
22094 | v8qi __builtin_ia32_pavgb (v8qi, v8qi); | |
22095 | v4hi __builtin_ia32_pavgw (v4hi, v4hi); | |
22096 | v1di __builtin_ia32_psadbw (v8qi, v8qi); | |
22097 | v8qi __builtin_ia32_pmaxub (v8qi, v8qi); | |
22098 | v4hi __builtin_ia32_pmaxsw (v4hi, v4hi); | |
22099 | v8qi __builtin_ia32_pminub (v8qi, v8qi); | |
22100 | v4hi __builtin_ia32_pminsw (v4hi, v4hi); | |
22101 | int __builtin_ia32_pmovmskb (v8qi); | |
22102 | void __builtin_ia32_maskmovq (v8qi, v8qi, char *); | |
22103 | void __builtin_ia32_movntq (di *, di); | |
22104 | void __builtin_ia32_sfence (void); | |
22105 | @end smallexample | |
22106 | ||
22107 | The following built-in functions are available when @option{-msse} is used. | |
22108 | All of them generate the machine instruction that is part of the name. | |
22109 | ||
22110 | @smallexample | |
22111 | int __builtin_ia32_comieq (v4sf, v4sf); | |
22112 | int __builtin_ia32_comineq (v4sf, v4sf); | |
22113 | int __builtin_ia32_comilt (v4sf, v4sf); | |
22114 | int __builtin_ia32_comile (v4sf, v4sf); | |
22115 | int __builtin_ia32_comigt (v4sf, v4sf); | |
22116 | int __builtin_ia32_comige (v4sf, v4sf); | |
22117 | int __builtin_ia32_ucomieq (v4sf, v4sf); | |
22118 | int __builtin_ia32_ucomineq (v4sf, v4sf); | |
22119 | int __builtin_ia32_ucomilt (v4sf, v4sf); | |
22120 | int __builtin_ia32_ucomile (v4sf, v4sf); | |
22121 | int __builtin_ia32_ucomigt (v4sf, v4sf); | |
22122 | int __builtin_ia32_ucomige (v4sf, v4sf); | |
22123 | v4sf __builtin_ia32_addps (v4sf, v4sf); | |
22124 | v4sf __builtin_ia32_subps (v4sf, v4sf); | |
22125 | v4sf __builtin_ia32_mulps (v4sf, v4sf); | |
22126 | v4sf __builtin_ia32_divps (v4sf, v4sf); | |
22127 | v4sf __builtin_ia32_addss (v4sf, v4sf); | |
22128 | v4sf __builtin_ia32_subss (v4sf, v4sf); | |
22129 | v4sf __builtin_ia32_mulss (v4sf, v4sf); | |
22130 | v4sf __builtin_ia32_divss (v4sf, v4sf); | |
22131 | v4sf __builtin_ia32_cmpeqps (v4sf, v4sf); | |
22132 | v4sf __builtin_ia32_cmpltps (v4sf, v4sf); | |
22133 | v4sf __builtin_ia32_cmpleps (v4sf, v4sf); | |
22134 | v4sf __builtin_ia32_cmpgtps (v4sf, v4sf); | |
22135 | v4sf __builtin_ia32_cmpgeps (v4sf, v4sf); | |
22136 | v4sf __builtin_ia32_cmpunordps (v4sf, v4sf); | |
22137 | v4sf __builtin_ia32_cmpneqps (v4sf, v4sf); | |
22138 | v4sf __builtin_ia32_cmpnltps (v4sf, v4sf); | |
22139 | v4sf __builtin_ia32_cmpnleps (v4sf, v4sf); | |
22140 | v4sf __builtin_ia32_cmpngtps (v4sf, v4sf); | |
22141 | v4sf __builtin_ia32_cmpngeps (v4sf, v4sf); | |
22142 | v4sf __builtin_ia32_cmpordps (v4sf, v4sf); | |
22143 | v4sf __builtin_ia32_cmpeqss (v4sf, v4sf); | |
22144 | v4sf __builtin_ia32_cmpltss (v4sf, v4sf); | |
22145 | v4sf __builtin_ia32_cmpless (v4sf, v4sf); | |
22146 | v4sf __builtin_ia32_cmpunordss (v4sf, v4sf); | |
22147 | v4sf __builtin_ia32_cmpneqss (v4sf, v4sf); | |
22148 | v4sf __builtin_ia32_cmpnltss (v4sf, v4sf); | |
22149 | v4sf __builtin_ia32_cmpnless (v4sf, v4sf); | |
22150 | v4sf __builtin_ia32_cmpordss (v4sf, v4sf); | |
22151 | v4sf __builtin_ia32_maxps (v4sf, v4sf); | |
22152 | v4sf __builtin_ia32_maxss (v4sf, v4sf); | |
22153 | v4sf __builtin_ia32_minps (v4sf, v4sf); | |
22154 | v4sf __builtin_ia32_minss (v4sf, v4sf); | |
22155 | v4sf __builtin_ia32_andps (v4sf, v4sf); | |
22156 | v4sf __builtin_ia32_andnps (v4sf, v4sf); | |
22157 | v4sf __builtin_ia32_orps (v4sf, v4sf); | |
22158 | v4sf __builtin_ia32_xorps (v4sf, v4sf); | |
22159 | v4sf __builtin_ia32_movss (v4sf, v4sf); | |
22160 | v4sf __builtin_ia32_movhlps (v4sf, v4sf); | |
22161 | v4sf __builtin_ia32_movlhps (v4sf, v4sf); | |
22162 | v4sf __builtin_ia32_unpckhps (v4sf, v4sf); | |
22163 | v4sf __builtin_ia32_unpcklps (v4sf, v4sf); | |
22164 | v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si); | |
22165 | v4sf __builtin_ia32_cvtsi2ss (v4sf, int); | |
22166 | v2si __builtin_ia32_cvtps2pi (v4sf); | |
22167 | int __builtin_ia32_cvtss2si (v4sf); | |
22168 | v2si __builtin_ia32_cvttps2pi (v4sf); | |
22169 | int __builtin_ia32_cvttss2si (v4sf); | |
22170 | v4sf __builtin_ia32_rcpps (v4sf); | |
22171 | v4sf __builtin_ia32_rsqrtps (v4sf); | |
22172 | v4sf __builtin_ia32_sqrtps (v4sf); | |
22173 | v4sf __builtin_ia32_rcpss (v4sf); | |
22174 | v4sf __builtin_ia32_rsqrtss (v4sf); | |
22175 | v4sf __builtin_ia32_sqrtss (v4sf); | |
22176 | v4sf __builtin_ia32_shufps (v4sf, v4sf, int); | |
22177 | void __builtin_ia32_movntps (float *, v4sf); | |
22178 | int __builtin_ia32_movmskps (v4sf); | |
22179 | @end smallexample | |
22180 | ||
22181 | The following built-in functions are available when @option{-msse} is used. | |
22182 | ||
f25efe50 | 22183 | @defbuiltin{v4sf __builtin_ia32_loadups (float *)} |
d77de738 | 22184 | Generates the @code{movups} machine instruction as a load from memory. |
f25efe50 AA |
22185 | @enddefbuiltin |
22186 | ||
22187 | @defbuiltin{void __builtin_ia32_storeups (float *, v4sf)} | |
d77de738 | 22188 | Generates the @code{movups} machine instruction as a store to memory. |
f25efe50 AA |
22189 | @enddefbuiltin |
22190 | ||
22191 | @defbuiltin{v4sf __builtin_ia32_loadss (float *)} | |
d77de738 | 22192 | Generates the @code{movss} machine instruction as a load from memory. |
f25efe50 AA |
22193 | @enddefbuiltin |
22194 | ||
22195 | @defbuiltin{v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)} | |
d77de738 | 22196 | Generates the @code{movhps} machine instruction as a load from memory. |
f25efe50 AA |
22197 | @enddefbuiltin |
22198 | ||
22199 | @defbuiltin{v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)} | |
d77de738 | 22200 | Generates the @code{movlps} machine instruction as a load from memory |
f25efe50 AA |
22201 | @enddefbuiltin |
22202 | ||
22203 | @defbuiltin{void __builtin_ia32_storehps (v2sf *, v4sf)} | |
d77de738 | 22204 | Generates the @code{movhps} machine instruction as a store to memory. |
f25efe50 AA |
22205 | @enddefbuiltin |
22206 | ||
22207 | @defbuiltin{void __builtin_ia32_storelps (v2sf *, v4sf)} | |
d77de738 | 22208 | Generates the @code{movlps} machine instruction as a store to memory. |
f25efe50 | 22209 | @enddefbuiltin |
d77de738 ML |
22210 | |
22211 | The following built-in functions are available when @option{-msse2} is used. | |
22212 | All of them generate the machine instruction that is part of the name. | |
22213 | ||
22214 | @smallexample | |
22215 | int __builtin_ia32_comisdeq (v2df, v2df); | |
22216 | int __builtin_ia32_comisdlt (v2df, v2df); | |
22217 | int __builtin_ia32_comisdle (v2df, v2df); | |
22218 | int __builtin_ia32_comisdgt (v2df, v2df); | |
22219 | int __builtin_ia32_comisdge (v2df, v2df); | |
22220 | int __builtin_ia32_comisdneq (v2df, v2df); | |
22221 | int __builtin_ia32_ucomisdeq (v2df, v2df); | |
22222 | int __builtin_ia32_ucomisdlt (v2df, v2df); | |
22223 | int __builtin_ia32_ucomisdle (v2df, v2df); | |
22224 | int __builtin_ia32_ucomisdgt (v2df, v2df); | |
22225 | int __builtin_ia32_ucomisdge (v2df, v2df); | |
22226 | int __builtin_ia32_ucomisdneq (v2df, v2df); | |
22227 | v2df __builtin_ia32_cmpeqpd (v2df, v2df); | |
22228 | v2df __builtin_ia32_cmpltpd (v2df, v2df); | |
22229 | v2df __builtin_ia32_cmplepd (v2df, v2df); | |
22230 | v2df __builtin_ia32_cmpgtpd (v2df, v2df); | |
22231 | v2df __builtin_ia32_cmpgepd (v2df, v2df); | |
22232 | v2df __builtin_ia32_cmpunordpd (v2df, v2df); | |
22233 | v2df __builtin_ia32_cmpneqpd (v2df, v2df); | |
22234 | v2df __builtin_ia32_cmpnltpd (v2df, v2df); | |
22235 | v2df __builtin_ia32_cmpnlepd (v2df, v2df); | |
22236 | v2df __builtin_ia32_cmpngtpd (v2df, v2df); | |
22237 | v2df __builtin_ia32_cmpngepd (v2df, v2df); | |
22238 | v2df __builtin_ia32_cmpordpd (v2df, v2df); | |
22239 | v2df __builtin_ia32_cmpeqsd (v2df, v2df); | |
22240 | v2df __builtin_ia32_cmpltsd (v2df, v2df); | |
22241 | v2df __builtin_ia32_cmplesd (v2df, v2df); | |
22242 | v2df __builtin_ia32_cmpunordsd (v2df, v2df); | |
22243 | v2df __builtin_ia32_cmpneqsd (v2df, v2df); | |
22244 | v2df __builtin_ia32_cmpnltsd (v2df, v2df); | |
22245 | v2df __builtin_ia32_cmpnlesd (v2df, v2df); | |
22246 | v2df __builtin_ia32_cmpordsd (v2df, v2df); | |
22247 | v2di __builtin_ia32_paddq (v2di, v2di); | |
22248 | v2di __builtin_ia32_psubq (v2di, v2di); | |
22249 | v2df __builtin_ia32_addpd (v2df, v2df); | |
22250 | v2df __builtin_ia32_subpd (v2df, v2df); | |
22251 | v2df __builtin_ia32_mulpd (v2df, v2df); | |
22252 | v2df __builtin_ia32_divpd (v2df, v2df); | |
22253 | v2df __builtin_ia32_addsd (v2df, v2df); | |
22254 | v2df __builtin_ia32_subsd (v2df, v2df); | |
22255 | v2df __builtin_ia32_mulsd (v2df, v2df); | |
22256 | v2df __builtin_ia32_divsd (v2df, v2df); | |
22257 | v2df __builtin_ia32_minpd (v2df, v2df); | |
22258 | v2df __builtin_ia32_maxpd (v2df, v2df); | |
22259 | v2df __builtin_ia32_minsd (v2df, v2df); | |
22260 | v2df __builtin_ia32_maxsd (v2df, v2df); | |
22261 | v2df __builtin_ia32_andpd (v2df, v2df); | |
22262 | v2df __builtin_ia32_andnpd (v2df, v2df); | |
22263 | v2df __builtin_ia32_orpd (v2df, v2df); | |
22264 | v2df __builtin_ia32_xorpd (v2df, v2df); | |
22265 | v2df __builtin_ia32_movsd (v2df, v2df); | |
22266 | v2df __builtin_ia32_unpckhpd (v2df, v2df); | |
22267 | v2df __builtin_ia32_unpcklpd (v2df, v2df); | |
22268 | v16qi __builtin_ia32_paddb128 (v16qi, v16qi); | |
22269 | v8hi __builtin_ia32_paddw128 (v8hi, v8hi); | |
22270 | v4si __builtin_ia32_paddd128 (v4si, v4si); | |
22271 | v2di __builtin_ia32_paddq128 (v2di, v2di); | |
22272 | v16qi __builtin_ia32_psubb128 (v16qi, v16qi); | |
22273 | v8hi __builtin_ia32_psubw128 (v8hi, v8hi); | |
22274 | v4si __builtin_ia32_psubd128 (v4si, v4si); | |
22275 | v2di __builtin_ia32_psubq128 (v2di, v2di); | |
22276 | v8hi __builtin_ia32_pmullw128 (v8hi, v8hi); | |
22277 | v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi); | |
22278 | v2di __builtin_ia32_pand128 (v2di, v2di); | |
22279 | v2di __builtin_ia32_pandn128 (v2di, v2di); | |
22280 | v2di __builtin_ia32_por128 (v2di, v2di); | |
22281 | v2di __builtin_ia32_pxor128 (v2di, v2di); | |
22282 | v16qi __builtin_ia32_pavgb128 (v16qi, v16qi); | |
22283 | v8hi __builtin_ia32_pavgw128 (v8hi, v8hi); | |
22284 | v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi); | |
22285 | v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi); | |
22286 | v4si __builtin_ia32_pcmpeqd128 (v4si, v4si); | |
22287 | v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi); | |
22288 | v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi); | |
22289 | v4si __builtin_ia32_pcmpgtd128 (v4si, v4si); | |
22290 | v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi); | |
22291 | v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi); | |
22292 | v16qi __builtin_ia32_pminub128 (v16qi, v16qi); | |
22293 | v8hi __builtin_ia32_pminsw128 (v8hi, v8hi); | |
22294 | v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi); | |
22295 | v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi); | |
22296 | v4si __builtin_ia32_punpckhdq128 (v4si, v4si); | |
22297 | v2di __builtin_ia32_punpckhqdq128 (v2di, v2di); | |
22298 | v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi); | |
22299 | v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi); | |
22300 | v4si __builtin_ia32_punpckldq128 (v4si, v4si); | |
22301 | v2di __builtin_ia32_punpcklqdq128 (v2di, v2di); | |
22302 | v16qi __builtin_ia32_packsswb128 (v8hi, v8hi); | |
22303 | v8hi __builtin_ia32_packssdw128 (v4si, v4si); | |
22304 | v16qi __builtin_ia32_packuswb128 (v8hi, v8hi); | |
22305 | v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi); | |
22306 | void __builtin_ia32_maskmovdqu (v16qi, v16qi); | |
22307 | v2df __builtin_ia32_loadupd (double *); | |
22308 | void __builtin_ia32_storeupd (double *, v2df); | |
22309 | v2df __builtin_ia32_loadhpd (v2df, double const *); | |
22310 | v2df __builtin_ia32_loadlpd (v2df, double const *); | |
22311 | int __builtin_ia32_movmskpd (v2df); | |
22312 | int __builtin_ia32_pmovmskb128 (v16qi); | |
22313 | void __builtin_ia32_movnti (int *, int); | |
22314 | void __builtin_ia32_movnti64 (long long int *, long long int); | |
22315 | void __builtin_ia32_movntpd (double *, v2df); | |
22316 | void __builtin_ia32_movntdq (v2df *, v2df); | |
22317 | v4si __builtin_ia32_pshufd (v4si, int); | |
22318 | v8hi __builtin_ia32_pshuflw (v8hi, int); | |
22319 | v8hi __builtin_ia32_pshufhw (v8hi, int); | |
22320 | v2di __builtin_ia32_psadbw128 (v16qi, v16qi); | |
22321 | v2df __builtin_ia32_sqrtpd (v2df); | |
22322 | v2df __builtin_ia32_sqrtsd (v2df); | |
22323 | v2df __builtin_ia32_shufpd (v2df, v2df, int); | |
22324 | v2df __builtin_ia32_cvtdq2pd (v4si); | |
22325 | v4sf __builtin_ia32_cvtdq2ps (v4si); | |
22326 | v4si __builtin_ia32_cvtpd2dq (v2df); | |
22327 | v2si __builtin_ia32_cvtpd2pi (v2df); | |
22328 | v4sf __builtin_ia32_cvtpd2ps (v2df); | |
22329 | v4si __builtin_ia32_cvttpd2dq (v2df); | |
22330 | v2si __builtin_ia32_cvttpd2pi (v2df); | |
22331 | v2df __builtin_ia32_cvtpi2pd (v2si); | |
22332 | int __builtin_ia32_cvtsd2si (v2df); | |
22333 | int __builtin_ia32_cvttsd2si (v2df); | |
22334 | long long __builtin_ia32_cvtsd2si64 (v2df); | |
22335 | long long __builtin_ia32_cvttsd2si64 (v2df); | |
22336 | v4si __builtin_ia32_cvtps2dq (v4sf); | |
22337 | v2df __builtin_ia32_cvtps2pd (v4sf); | |
22338 | v4si __builtin_ia32_cvttps2dq (v4sf); | |
22339 | v2df __builtin_ia32_cvtsi2sd (v2df, int); | |
22340 | v2df __builtin_ia32_cvtsi642sd (v2df, long long); | |
22341 | v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df); | |
22342 | v2df __builtin_ia32_cvtss2sd (v2df, v4sf); | |
22343 | void __builtin_ia32_clflush (const void *); | |
22344 | void __builtin_ia32_lfence (void); | |
22345 | void __builtin_ia32_mfence (void); | |
22346 | v16qi __builtin_ia32_loaddqu (const char *); | |
22347 | void __builtin_ia32_storedqu (char *, v16qi); | |
22348 | v1di __builtin_ia32_pmuludq (v2si, v2si); | |
22349 | v2di __builtin_ia32_pmuludq128 (v4si, v4si); | |
22350 | v8hi __builtin_ia32_psllw128 (v8hi, v8hi); | |
22351 | v4si __builtin_ia32_pslld128 (v4si, v4si); | |
22352 | v2di __builtin_ia32_psllq128 (v2di, v2di); | |
22353 | v8hi __builtin_ia32_psrlw128 (v8hi, v8hi); | |
22354 | v4si __builtin_ia32_psrld128 (v4si, v4si); | |
22355 | v2di __builtin_ia32_psrlq128 (v2di, v2di); | |
22356 | v8hi __builtin_ia32_psraw128 (v8hi, v8hi); | |
22357 | v4si __builtin_ia32_psrad128 (v4si, v4si); | |
22358 | v2di __builtin_ia32_pslldqi128 (v2di, int); | |
22359 | v8hi __builtin_ia32_psllwi128 (v8hi, int); | |
22360 | v4si __builtin_ia32_pslldi128 (v4si, int); | |
22361 | v2di __builtin_ia32_psllqi128 (v2di, int); | |
22362 | v2di __builtin_ia32_psrldqi128 (v2di, int); | |
22363 | v8hi __builtin_ia32_psrlwi128 (v8hi, int); | |
22364 | v4si __builtin_ia32_psrldi128 (v4si, int); | |
22365 | v2di __builtin_ia32_psrlqi128 (v2di, int); | |
22366 | v8hi __builtin_ia32_psrawi128 (v8hi, int); | |
22367 | v4si __builtin_ia32_psradi128 (v4si, int); | |
22368 | v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi); | |
22369 | v2di __builtin_ia32_movq128 (v2di); | |
22370 | @end smallexample | |
22371 | ||
22372 | The following built-in functions are available when @option{-msse3} is used. | |
22373 | All of them generate the machine instruction that is part of the name. | |
22374 | ||
22375 | @smallexample | |
22376 | v2df __builtin_ia32_addsubpd (v2df, v2df); | |
22377 | v4sf __builtin_ia32_addsubps (v4sf, v4sf); | |
22378 | v2df __builtin_ia32_haddpd (v2df, v2df); | |
22379 | v4sf __builtin_ia32_haddps (v4sf, v4sf); | |
22380 | v2df __builtin_ia32_hsubpd (v2df, v2df); | |
22381 | v4sf __builtin_ia32_hsubps (v4sf, v4sf); | |
22382 | v16qi __builtin_ia32_lddqu (char const *); | |
22383 | void __builtin_ia32_monitor (void *, unsigned int, unsigned int); | |
22384 | v4sf __builtin_ia32_movshdup (v4sf); | |
22385 | v4sf __builtin_ia32_movsldup (v4sf); | |
22386 | void __builtin_ia32_mwait (unsigned int, unsigned int); | |
22387 | @end smallexample | |
22388 | ||
22389 | The following built-in functions are available when @option{-mssse3} is used. | |
22390 | All of them generate the machine instruction that is part of the name. | |
22391 | ||
22392 | @smallexample | |
22393 | v2si __builtin_ia32_phaddd (v2si, v2si); | |
22394 | v4hi __builtin_ia32_phaddw (v4hi, v4hi); | |
22395 | v4hi __builtin_ia32_phaddsw (v4hi, v4hi); | |
22396 | v2si __builtin_ia32_phsubd (v2si, v2si); | |
22397 | v4hi __builtin_ia32_phsubw (v4hi, v4hi); | |
22398 | v4hi __builtin_ia32_phsubsw (v4hi, v4hi); | |
22399 | v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi); | |
22400 | v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi); | |
22401 | v8qi __builtin_ia32_pshufb (v8qi, v8qi); | |
22402 | v8qi __builtin_ia32_psignb (v8qi, v8qi); | |
22403 | v2si __builtin_ia32_psignd (v2si, v2si); | |
22404 | v4hi __builtin_ia32_psignw (v4hi, v4hi); | |
22405 | v1di __builtin_ia32_palignr (v1di, v1di, int); | |
22406 | v8qi __builtin_ia32_pabsb (v8qi); | |
22407 | v2si __builtin_ia32_pabsd (v2si); | |
22408 | v4hi __builtin_ia32_pabsw (v4hi); | |
22409 | @end smallexample | |
22410 | ||
22411 | The following built-in functions are available when @option{-mssse3} is used. | |
22412 | All of them generate the machine instruction that is part of the name. | |
22413 | ||
22414 | @smallexample | |
22415 | v4si __builtin_ia32_phaddd128 (v4si, v4si); | |
22416 | v8hi __builtin_ia32_phaddw128 (v8hi, v8hi); | |
22417 | v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi); | |
22418 | v4si __builtin_ia32_phsubd128 (v4si, v4si); | |
22419 | v8hi __builtin_ia32_phsubw128 (v8hi, v8hi); | |
22420 | v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi); | |
22421 | v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi); | |
22422 | v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi); | |
22423 | v16qi __builtin_ia32_pshufb128 (v16qi, v16qi); | |
22424 | v16qi __builtin_ia32_psignb128 (v16qi, v16qi); | |
22425 | v4si __builtin_ia32_psignd128 (v4si, v4si); | |
22426 | v8hi __builtin_ia32_psignw128 (v8hi, v8hi); | |
22427 | v2di __builtin_ia32_palignr128 (v2di, v2di, int); | |
22428 | v16qi __builtin_ia32_pabsb128 (v16qi); | |
22429 | v4si __builtin_ia32_pabsd128 (v4si); | |
22430 | v8hi __builtin_ia32_pabsw128 (v8hi); | |
22431 | @end smallexample | |
22432 | ||
22433 | The following built-in functions are available when @option{-msse4.1} is | |
22434 | used. All of them generate the machine instruction that is part of the | |
22435 | name. | |
22436 | ||
22437 | @smallexample | |
22438 | v2df __builtin_ia32_blendpd (v2df, v2df, const int); | |
22439 | v4sf __builtin_ia32_blendps (v4sf, v4sf, const int); | |
22440 | v2df __builtin_ia32_blendvpd (v2df, v2df, v2df); | |
22441 | v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf); | |
22442 | v2df __builtin_ia32_dppd (v2df, v2df, const int); | |
22443 | v4sf __builtin_ia32_dpps (v4sf, v4sf, const int); | |
22444 | v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int); | |
22445 | v2di __builtin_ia32_movntdqa (v2di *); | |
22446 | v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int); | |
22447 | v8hi __builtin_ia32_packusdw128 (v4si, v4si); | |
22448 | v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi); | |
22449 | v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int); | |
22450 | v2di __builtin_ia32_pcmpeqq (v2di, v2di); | |
22451 | v8hi __builtin_ia32_phminposuw128 (v8hi); | |
22452 | v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi); | |
22453 | v4si __builtin_ia32_pmaxsd128 (v4si, v4si); | |
22454 | v4si __builtin_ia32_pmaxud128 (v4si, v4si); | |
22455 | v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi); | |
22456 | v16qi __builtin_ia32_pminsb128 (v16qi, v16qi); | |
22457 | v4si __builtin_ia32_pminsd128 (v4si, v4si); | |
22458 | v4si __builtin_ia32_pminud128 (v4si, v4si); | |
22459 | v8hi __builtin_ia32_pminuw128 (v8hi, v8hi); | |
22460 | v4si __builtin_ia32_pmovsxbd128 (v16qi); | |
22461 | v2di __builtin_ia32_pmovsxbq128 (v16qi); | |
22462 | v8hi __builtin_ia32_pmovsxbw128 (v16qi); | |
22463 | v2di __builtin_ia32_pmovsxdq128 (v4si); | |
22464 | v4si __builtin_ia32_pmovsxwd128 (v8hi); | |
22465 | v2di __builtin_ia32_pmovsxwq128 (v8hi); | |
22466 | v4si __builtin_ia32_pmovzxbd128 (v16qi); | |
22467 | v2di __builtin_ia32_pmovzxbq128 (v16qi); | |
22468 | v8hi __builtin_ia32_pmovzxbw128 (v16qi); | |
22469 | v2di __builtin_ia32_pmovzxdq128 (v4si); | |
22470 | v4si __builtin_ia32_pmovzxwd128 (v8hi); | |
22471 | v2di __builtin_ia32_pmovzxwq128 (v8hi); | |
22472 | v2di __builtin_ia32_pmuldq128 (v4si, v4si); | |
22473 | v4si __builtin_ia32_pmulld128 (v4si, v4si); | |
22474 | int __builtin_ia32_ptestc128 (v2di, v2di); | |
22475 | int __builtin_ia32_ptestnzc128 (v2di, v2di); | |
22476 | int __builtin_ia32_ptestz128 (v2di, v2di); | |
22477 | v2df __builtin_ia32_roundpd (v2df, const int); | |
22478 | v4sf __builtin_ia32_roundps (v4sf, const int); | |
22479 | v2df __builtin_ia32_roundsd (v2df, v2df, const int); | |
22480 | v4sf __builtin_ia32_roundss (v4sf, v4sf, const int); | |
22481 | @end smallexample | |
22482 | ||
22483 | The following built-in functions are available when @option{-msse4.1} is | |
22484 | used. | |
22485 | ||
f25efe50 | 22486 | @defbuiltin{v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)} |
d77de738 | 22487 | Generates the @code{insertps} machine instruction. |
f25efe50 AA |
22488 | @enddefbuiltin |
22489 | ||
22490 | @defbuiltin{int __builtin_ia32_vec_ext_v16qi (v16qi, const int)} | |
d77de738 | 22491 | Generates the @code{pextrb} machine instruction. |
f25efe50 AA |
22492 | @enddefbuiltin |
22493 | ||
22494 | @defbuiltin{v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)} | |
d77de738 | 22495 | Generates the @code{pinsrb} machine instruction. |
f25efe50 AA |
22496 | @enddefbuiltin |
22497 | ||
22498 | @defbuiltin{v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)} | |
d77de738 | 22499 | Generates the @code{pinsrd} machine instruction. |
f25efe50 AA |
22500 | @enddefbuiltin |
22501 | ||
22502 | @defbuiltin{v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)} | |
d77de738 | 22503 | Generates the @code{pinsrq} machine instruction in 64bit mode. |
f25efe50 | 22504 | @enddefbuiltin |
d77de738 ML |
22505 | |
22506 | The following built-in functions are changed to generate new SSE4.1 | |
22507 | instructions when @option{-msse4.1} is used. | |
22508 | ||
f25efe50 | 22509 | @defbuiltin{float __builtin_ia32_vec_ext_v4sf (v4sf, const int)} |
d77de738 | 22510 | Generates the @code{extractps} machine instruction. |
f25efe50 AA |
22511 | @enddefbuiltin |
22512 | ||
22513 | @defbuiltin{int __builtin_ia32_vec_ext_v4si (v4si, const int)} | |
d77de738 | 22514 | Generates the @code{pextrd} machine instruction. |
f25efe50 AA |
22515 | @enddefbuiltin |
22516 | ||
22517 | @defbuiltin{long long __builtin_ia32_vec_ext_v2di (v2di, const int)} | |
d77de738 | 22518 | Generates the @code{pextrq} machine instruction in 64bit mode. |
f25efe50 | 22519 | @enddefbuiltin |
d77de738 ML |
22520 | |
22521 | The following built-in functions are available when @option{-msse4.2} is | |
22522 | used. All of them generate the machine instruction that is part of the | |
22523 | name. | |
22524 | ||
22525 | @smallexample | |
22526 | v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int); | |
22527 | int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int); | |
22528 | int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int); | |
22529 | int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int); | |
22530 | int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int); | |
22531 | int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int); | |
22532 | int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int); | |
22533 | v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int); | |
22534 | int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int); | |
22535 | int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int); | |
22536 | int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int); | |
22537 | int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int); | |
22538 | int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int); | |
22539 | int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int); | |
22540 | v2di __builtin_ia32_pcmpgtq (v2di, v2di); | |
22541 | @end smallexample | |
22542 | ||
22543 | The following built-in functions are available when @option{-msse4.2} is | |
22544 | used. | |
22545 | ||
f25efe50 | 22546 | @defbuiltin{unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)} |
d77de738 | 22547 | Generates the @code{crc32b} machine instruction. |
f25efe50 AA |
22548 | @enddefbuiltin |
22549 | ||
22550 | @defbuiltin{unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)} | |
d77de738 | 22551 | Generates the @code{crc32w} machine instruction. |
f25efe50 AA |
22552 | @enddefbuiltin |
22553 | ||
22554 | @defbuiltin{unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)} | |
d77de738 | 22555 | Generates the @code{crc32l} machine instruction. |
f25efe50 AA |
22556 | @enddefbuiltin |
22557 | ||
22558 | @defbuiltin{unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)} | |
d77de738 | 22559 | Generates the @code{crc32q} machine instruction. |
f25efe50 | 22560 | @enddefbuiltin |
d77de738 ML |
22561 | |
22562 | The following built-in functions are changed to generate new SSE4.2 | |
22563 | instructions when @option{-msse4.2} is used. | |
22564 | ||
f25efe50 | 22565 | @defbuiltin{int __builtin_popcount (unsigned int)} |
d77de738 | 22566 | Generates the @code{popcntl} machine instruction. |
f25efe50 AA |
22567 | @enddefbuiltin |
22568 | ||
22569 | @defbuiltin{int __builtin_popcountl (unsigned long)} | |
d77de738 ML |
22570 | Generates the @code{popcntl} or @code{popcntq} machine instruction, |
22571 | depending on the size of @code{unsigned long}. | |
f25efe50 AA |
22572 | @enddefbuiltin |
22573 | ||
22574 | @defbuiltin{int __builtin_popcountll (unsigned long long)} | |
d77de738 | 22575 | Generates the @code{popcntq} machine instruction. |
f25efe50 | 22576 | @enddefbuiltin |
d77de738 ML |
22577 | |
22578 | The following built-in functions are available when @option{-mavx} is | |
22579 | used. All of them generate the machine instruction that is part of the | |
22580 | name. | |
22581 | ||
22582 | @smallexample | |
22583 | v4df __builtin_ia32_addpd256 (v4df,v4df); | |
22584 | v8sf __builtin_ia32_addps256 (v8sf,v8sf); | |
22585 | v4df __builtin_ia32_addsubpd256 (v4df,v4df); | |
22586 | v8sf __builtin_ia32_addsubps256 (v8sf,v8sf); | |
22587 | v4df __builtin_ia32_andnpd256 (v4df,v4df); | |
22588 | v8sf __builtin_ia32_andnps256 (v8sf,v8sf); | |
22589 | v4df __builtin_ia32_andpd256 (v4df,v4df); | |
22590 | v8sf __builtin_ia32_andps256 (v8sf,v8sf); | |
22591 | v4df __builtin_ia32_blendpd256 (v4df,v4df,int); | |
22592 | v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int); | |
22593 | v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df); | |
22594 | v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf); | |
22595 | v2df __builtin_ia32_cmppd (v2df,v2df,int); | |
22596 | v4df __builtin_ia32_cmppd256 (v4df,v4df,int); | |
22597 | v4sf __builtin_ia32_cmpps (v4sf,v4sf,int); | |
22598 | v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int); | |
22599 | v2df __builtin_ia32_cmpsd (v2df,v2df,int); | |
22600 | v4sf __builtin_ia32_cmpss (v4sf,v4sf,int); | |
22601 | v4df __builtin_ia32_cvtdq2pd256 (v4si); | |
22602 | v8sf __builtin_ia32_cvtdq2ps256 (v8si); | |
22603 | v4si __builtin_ia32_cvtpd2dq256 (v4df); | |
22604 | v4sf __builtin_ia32_cvtpd2ps256 (v4df); | |
22605 | v8si __builtin_ia32_cvtps2dq256 (v8sf); | |
22606 | v4df __builtin_ia32_cvtps2pd256 (v4sf); | |
22607 | v4si __builtin_ia32_cvttpd2dq256 (v4df); | |
22608 | v8si __builtin_ia32_cvttps2dq256 (v8sf); | |
22609 | v4df __builtin_ia32_divpd256 (v4df,v4df); | |
22610 | v8sf __builtin_ia32_divps256 (v8sf,v8sf); | |
22611 | v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int); | |
22612 | v4df __builtin_ia32_haddpd256 (v4df,v4df); | |
22613 | v8sf __builtin_ia32_haddps256 (v8sf,v8sf); | |
22614 | v4df __builtin_ia32_hsubpd256 (v4df,v4df); | |
22615 | v8sf __builtin_ia32_hsubps256 (v8sf,v8sf); | |
22616 | v32qi __builtin_ia32_lddqu256 (pcchar); | |
22617 | v32qi __builtin_ia32_loaddqu256 (pcchar); | |
22618 | v4df __builtin_ia32_loadupd256 (pcdouble); | |
22619 | v8sf __builtin_ia32_loadups256 (pcfloat); | |
22620 | v2df __builtin_ia32_maskloadpd (pcv2df,v2df); | |
22621 | v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df); | |
22622 | v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf); | |
22623 | v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf); | |
22624 | void __builtin_ia32_maskstorepd (pv2df,v2df,v2df); | |
22625 | void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df); | |
22626 | void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf); | |
22627 | void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf); | |
22628 | v4df __builtin_ia32_maxpd256 (v4df,v4df); | |
22629 | v8sf __builtin_ia32_maxps256 (v8sf,v8sf); | |
22630 | v4df __builtin_ia32_minpd256 (v4df,v4df); | |
22631 | v8sf __builtin_ia32_minps256 (v8sf,v8sf); | |
22632 | v4df __builtin_ia32_movddup256 (v4df); | |
22633 | int __builtin_ia32_movmskpd256 (v4df); | |
22634 | int __builtin_ia32_movmskps256 (v8sf); | |
22635 | v8sf __builtin_ia32_movshdup256 (v8sf); | |
22636 | v8sf __builtin_ia32_movsldup256 (v8sf); | |
22637 | v4df __builtin_ia32_mulpd256 (v4df,v4df); | |
22638 | v8sf __builtin_ia32_mulps256 (v8sf,v8sf); | |
22639 | v4df __builtin_ia32_orpd256 (v4df,v4df); | |
22640 | v8sf __builtin_ia32_orps256 (v8sf,v8sf); | |
22641 | v2df __builtin_ia32_pd_pd256 (v4df); | |
22642 | v4df __builtin_ia32_pd256_pd (v2df); | |
22643 | v4sf __builtin_ia32_ps_ps256 (v8sf); | |
22644 | v8sf __builtin_ia32_ps256_ps (v4sf); | |
22645 | int __builtin_ia32_ptestc256 (v4di,v4di,ptest); | |
22646 | int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest); | |
22647 | int __builtin_ia32_ptestz256 (v4di,v4di,ptest); | |
22648 | v8sf __builtin_ia32_rcpps256 (v8sf); | |
22649 | v4df __builtin_ia32_roundpd256 (v4df,int); | |
22650 | v8sf __builtin_ia32_roundps256 (v8sf,int); | |
22651 | v8sf __builtin_ia32_rsqrtps_nr256 (v8sf); | |
22652 | v8sf __builtin_ia32_rsqrtps256 (v8sf); | |
22653 | v4df __builtin_ia32_shufpd256 (v4df,v4df,int); | |
22654 | v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int); | |
22655 | v4si __builtin_ia32_si_si256 (v8si); | |
22656 | v8si __builtin_ia32_si256_si (v4si); | |
22657 | v4df __builtin_ia32_sqrtpd256 (v4df); | |
22658 | v8sf __builtin_ia32_sqrtps_nr256 (v8sf); | |
22659 | v8sf __builtin_ia32_sqrtps256 (v8sf); | |
22660 | void __builtin_ia32_storedqu256 (pchar,v32qi); | |
22661 | void __builtin_ia32_storeupd256 (pdouble,v4df); | |
22662 | void __builtin_ia32_storeups256 (pfloat,v8sf); | |
22663 | v4df __builtin_ia32_subpd256 (v4df,v4df); | |
22664 | v8sf __builtin_ia32_subps256 (v8sf,v8sf); | |
22665 | v4df __builtin_ia32_unpckhpd256 (v4df,v4df); | |
22666 | v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf); | |
22667 | v4df __builtin_ia32_unpcklpd256 (v4df,v4df); | |
22668 | v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf); | |
22669 | v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df); | |
22670 | v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf); | |
22671 | v4df __builtin_ia32_vbroadcastsd256 (pcdouble); | |
22672 | v4sf __builtin_ia32_vbroadcastss (pcfloat); | |
22673 | v8sf __builtin_ia32_vbroadcastss256 (pcfloat); | |
22674 | v2df __builtin_ia32_vextractf128_pd256 (v4df,int); | |
22675 | v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int); | |
22676 | v4si __builtin_ia32_vextractf128_si256 (v8si,int); | |
22677 | v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int); | |
22678 | v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int); | |
22679 | v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int); | |
22680 | v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int); | |
22681 | v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int); | |
22682 | v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int); | |
22683 | v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int); | |
22684 | v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int); | |
22685 | v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int); | |
22686 | v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int); | |
22687 | v2df __builtin_ia32_vpermilpd (v2df,int); | |
22688 | v4df __builtin_ia32_vpermilpd256 (v4df,int); | |
22689 | v4sf __builtin_ia32_vpermilps (v4sf,int); | |
22690 | v8sf __builtin_ia32_vpermilps256 (v8sf,int); | |
22691 | v2df __builtin_ia32_vpermilvarpd (v2df,v2di); | |
22692 | v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di); | |
22693 | v4sf __builtin_ia32_vpermilvarps (v4sf,v4si); | |
22694 | v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si); | |
22695 | int __builtin_ia32_vtestcpd (v2df,v2df,ptest); | |
22696 | int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest); | |
22697 | int __builtin_ia32_vtestcps (v4sf,v4sf,ptest); | |
22698 | int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest); | |
22699 | int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest); | |
22700 | int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest); | |
22701 | int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest); | |
22702 | int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest); | |
22703 | int __builtin_ia32_vtestzpd (v2df,v2df,ptest); | |
22704 | int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest); | |
22705 | int __builtin_ia32_vtestzps (v4sf,v4sf,ptest); | |
22706 | int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest); | |
22707 | void __builtin_ia32_vzeroall (void); | |
22708 | void __builtin_ia32_vzeroupper (void); | |
22709 | v4df __builtin_ia32_xorpd256 (v4df,v4df); | |
22710 | v8sf __builtin_ia32_xorps256 (v8sf,v8sf); | |
22711 | @end smallexample | |
22712 | ||
22713 | The following built-in functions are available when @option{-mavx2} is | |
22714 | used. All of them generate the machine instruction that is part of the | |
22715 | name. | |
22716 | ||
22717 | @smallexample | |
22718 | v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int); | |
22719 | v32qi __builtin_ia32_pabsb256 (v32qi); | |
22720 | v16hi __builtin_ia32_pabsw256 (v16hi); | |
22721 | v8si __builtin_ia32_pabsd256 (v8si); | |
22722 | v16hi __builtin_ia32_packssdw256 (v8si,v8si); | |
22723 | v32qi __builtin_ia32_packsswb256 (v16hi,v16hi); | |
22724 | v16hi __builtin_ia32_packusdw256 (v8si,v8si); | |
22725 | v32qi __builtin_ia32_packuswb256 (v16hi,v16hi); | |
22726 | v32qi __builtin_ia32_paddb256 (v32qi,v32qi); | |
22727 | v16hi __builtin_ia32_paddw256 (v16hi,v16hi); | |
22728 | v8si __builtin_ia32_paddd256 (v8si,v8si); | |
22729 | v4di __builtin_ia32_paddq256 (v4di,v4di); | |
22730 | v32qi __builtin_ia32_paddsb256 (v32qi,v32qi); | |
22731 | v16hi __builtin_ia32_paddsw256 (v16hi,v16hi); | |
22732 | v32qi __builtin_ia32_paddusb256 (v32qi,v32qi); | |
22733 | v16hi __builtin_ia32_paddusw256 (v16hi,v16hi); | |
22734 | v4di __builtin_ia32_palignr256 (v4di,v4di,int); | |
22735 | v4di __builtin_ia32_andsi256 (v4di,v4di); | |
22736 | v4di __builtin_ia32_andnotsi256 (v4di,v4di); | |
22737 | v32qi __builtin_ia32_pavgb256 (v32qi,v32qi); | |
22738 | v16hi __builtin_ia32_pavgw256 (v16hi,v16hi); | |
22739 | v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi); | |
22740 | v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int); | |
22741 | v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi); | |
22742 | v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi); | |
22743 | v8si __builtin_ia32_pcmpeqd256 (c8si,v8si); | |
22744 | v4di __builtin_ia32_pcmpeqq256 (v4di,v4di); | |
22745 | v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi); | |
22746 | v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi); | |
22747 | v8si __builtin_ia32_pcmpgtd256 (v8si,v8si); | |
22748 | v4di __builtin_ia32_pcmpgtq256 (v4di,v4di); | |
22749 | v16hi __builtin_ia32_phaddw256 (v16hi,v16hi); | |
22750 | v8si __builtin_ia32_phaddd256 (v8si,v8si); | |
22751 | v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi); | |
22752 | v16hi __builtin_ia32_phsubw256 (v16hi,v16hi); | |
22753 | v8si __builtin_ia32_phsubd256 (v8si,v8si); | |
22754 | v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi); | |
22755 | v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi); | |
22756 | v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi); | |
22757 | v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi); | |
22758 | v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi); | |
22759 | v8si __builtin_ia32_pmaxsd256 (v8si,v8si); | |
22760 | v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi); | |
22761 | v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi); | |
22762 | v8si __builtin_ia32_pmaxud256 (v8si,v8si); | |
22763 | v32qi __builtin_ia32_pminsb256 (v32qi,v32qi); | |
22764 | v16hi __builtin_ia32_pminsw256 (v16hi,v16hi); | |
22765 | v8si __builtin_ia32_pminsd256 (v8si,v8si); | |
22766 | v32qi __builtin_ia32_pminub256 (v32qi,v32qi); | |
22767 | v16hi __builtin_ia32_pminuw256 (v16hi,v16hi); | |
22768 | v8si __builtin_ia32_pminud256 (v8si,v8si); | |
22769 | int __builtin_ia32_pmovmskb256 (v32qi); | |
22770 | v16hi __builtin_ia32_pmovsxbw256 (v16qi); | |
22771 | v8si __builtin_ia32_pmovsxbd256 (v16qi); | |
22772 | v4di __builtin_ia32_pmovsxbq256 (v16qi); | |
22773 | v8si __builtin_ia32_pmovsxwd256 (v8hi); | |
22774 | v4di __builtin_ia32_pmovsxwq256 (v8hi); | |
22775 | v4di __builtin_ia32_pmovsxdq256 (v4si); | |
22776 | v16hi __builtin_ia32_pmovzxbw256 (v16qi); | |
22777 | v8si __builtin_ia32_pmovzxbd256 (v16qi); | |
22778 | v4di __builtin_ia32_pmovzxbq256 (v16qi); | |
22779 | v8si __builtin_ia32_pmovzxwd256 (v8hi); | |
22780 | v4di __builtin_ia32_pmovzxwq256 (v8hi); | |
22781 | v4di __builtin_ia32_pmovzxdq256 (v4si); | |
22782 | v4di __builtin_ia32_pmuldq256 (v8si,v8si); | |
22783 | v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi); | |
22784 | v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi); | |
22785 | v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi); | |
22786 | v16hi __builtin_ia32_pmullw256 (v16hi,v16hi); | |
22787 | v8si __builtin_ia32_pmulld256 (v8si,v8si); | |
22788 | v4di __builtin_ia32_pmuludq256 (v8si,v8si); | |
22789 | v4di __builtin_ia32_por256 (v4di,v4di); | |
22790 | v16hi __builtin_ia32_psadbw256 (v32qi,v32qi); | |
22791 | v32qi __builtin_ia32_pshufb256 (v32qi,v32qi); | |
22792 | v8si __builtin_ia32_pshufd256 (v8si,int); | |
22793 | v16hi __builtin_ia32_pshufhw256 (v16hi,int); | |
22794 | v16hi __builtin_ia32_pshuflw256 (v16hi,int); | |
22795 | v32qi __builtin_ia32_psignb256 (v32qi,v32qi); | |
22796 | v16hi __builtin_ia32_psignw256 (v16hi,v16hi); | |
22797 | v8si __builtin_ia32_psignd256 (v8si,v8si); | |
22798 | v4di __builtin_ia32_pslldqi256 (v4di,int); | |
22799 | v16hi __builtin_ia32_psllwi256 (16hi,int); | |
22800 | v16hi __builtin_ia32_psllw256(v16hi,v8hi); | |
22801 | v8si __builtin_ia32_pslldi256 (v8si,int); | |
22802 | v8si __builtin_ia32_pslld256(v8si,v4si); | |
22803 | v4di __builtin_ia32_psllqi256 (v4di,int); | |
22804 | v4di __builtin_ia32_psllq256(v4di,v2di); | |
22805 | v16hi __builtin_ia32_psrawi256 (v16hi,int); | |
22806 | v16hi __builtin_ia32_psraw256 (v16hi,v8hi); | |
22807 | v8si __builtin_ia32_psradi256 (v8si,int); | |
22808 | v8si __builtin_ia32_psrad256 (v8si,v4si); | |
22809 | v4di __builtin_ia32_psrldqi256 (v4di, int); | |
22810 | v16hi __builtin_ia32_psrlwi256 (v16hi,int); | |
22811 | v16hi __builtin_ia32_psrlw256 (v16hi,v8hi); | |
22812 | v8si __builtin_ia32_psrldi256 (v8si,int); | |
22813 | v8si __builtin_ia32_psrld256 (v8si,v4si); | |
22814 | v4di __builtin_ia32_psrlqi256 (v4di,int); | |
22815 | v4di __builtin_ia32_psrlq256(v4di,v2di); | |
22816 | v32qi __builtin_ia32_psubb256 (v32qi,v32qi); | |
22817 | v32hi __builtin_ia32_psubw256 (v16hi,v16hi); | |
22818 | v8si __builtin_ia32_psubd256 (v8si,v8si); | |
22819 | v4di __builtin_ia32_psubq256 (v4di,v4di); | |
22820 | v32qi __builtin_ia32_psubsb256 (v32qi,v32qi); | |
22821 | v16hi __builtin_ia32_psubsw256 (v16hi,v16hi); | |
22822 | v32qi __builtin_ia32_psubusb256 (v32qi,v32qi); | |
22823 | v16hi __builtin_ia32_psubusw256 (v16hi,v16hi); | |
22824 | v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi); | |
22825 | v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi); | |
22826 | v8si __builtin_ia32_punpckhdq256 (v8si,v8si); | |
22827 | v4di __builtin_ia32_punpckhqdq256 (v4di,v4di); | |
22828 | v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi); | |
22829 | v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi); | |
22830 | v8si __builtin_ia32_punpckldq256 (v8si,v8si); | |
22831 | v4di __builtin_ia32_punpcklqdq256 (v4di,v4di); | |
22832 | v4di __builtin_ia32_pxor256 (v4di,v4di); | |
22833 | v4di __builtin_ia32_movntdqa256 (pv4di); | |
22834 | v4sf __builtin_ia32_vbroadcastss_ps (v4sf); | |
22835 | v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf); | |
22836 | v4df __builtin_ia32_vbroadcastsd_pd256 (v2df); | |
22837 | v4di __builtin_ia32_vbroadcastsi256 (v2di); | |
22838 | v4si __builtin_ia32_pblendd128 (v4si,v4si); | |
22839 | v8si __builtin_ia32_pblendd256 (v8si,v8si); | |
22840 | v32qi __builtin_ia32_pbroadcastb256 (v16qi); | |
22841 | v16hi __builtin_ia32_pbroadcastw256 (v8hi); | |
22842 | v8si __builtin_ia32_pbroadcastd256 (v4si); | |
22843 | v4di __builtin_ia32_pbroadcastq256 (v2di); | |
22844 | v16qi __builtin_ia32_pbroadcastb128 (v16qi); | |
22845 | v8hi __builtin_ia32_pbroadcastw128 (v8hi); | |
22846 | v4si __builtin_ia32_pbroadcastd128 (v4si); | |
22847 | v2di __builtin_ia32_pbroadcastq128 (v2di); | |
22848 | v8si __builtin_ia32_permvarsi256 (v8si,v8si); | |
22849 | v4df __builtin_ia32_permdf256 (v4df,int); | |
22850 | v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf); | |
22851 | v4di __builtin_ia32_permdi256 (v4di,int); | |
22852 | v4di __builtin_ia32_permti256 (v4di,v4di,int); | |
22853 | v4di __builtin_ia32_extract128i256 (v4di,int); | |
22854 | v4di __builtin_ia32_insert128i256 (v4di,v2di,int); | |
22855 | v8si __builtin_ia32_maskloadd256 (pcv8si,v8si); | |
22856 | v4di __builtin_ia32_maskloadq256 (pcv4di,v4di); | |
22857 | v4si __builtin_ia32_maskloadd (pcv4si,v4si); | |
22858 | v2di __builtin_ia32_maskloadq (pcv2di,v2di); | |
22859 | void __builtin_ia32_maskstored256 (pv8si,v8si,v8si); | |
22860 | void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di); | |
22861 | void __builtin_ia32_maskstored (pv4si,v4si,v4si); | |
22862 | void __builtin_ia32_maskstoreq (pv2di,v2di,v2di); | |
22863 | v8si __builtin_ia32_psllv8si (v8si,v8si); | |
22864 | v4si __builtin_ia32_psllv4si (v4si,v4si); | |
22865 | v4di __builtin_ia32_psllv4di (v4di,v4di); | |
22866 | v2di __builtin_ia32_psllv2di (v2di,v2di); | |
22867 | v8si __builtin_ia32_psrav8si (v8si,v8si); | |
22868 | v4si __builtin_ia32_psrav4si (v4si,v4si); | |
22869 | v8si __builtin_ia32_psrlv8si (v8si,v8si); | |
22870 | v4si __builtin_ia32_psrlv4si (v4si,v4si); | |
22871 | v4di __builtin_ia32_psrlv4di (v4di,v4di); | |
22872 | v2di __builtin_ia32_psrlv2di (v2di,v2di); | |
22873 | v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int); | |
22874 | v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int); | |
22875 | v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int); | |
22876 | v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int); | |
22877 | v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int); | |
22878 | v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int); | |
22879 | v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int); | |
22880 | v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int); | |
22881 | v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int); | |
22882 | v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int); | |
22883 | v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int); | |
22884 | v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int); | |
22885 | v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int); | |
22886 | v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int); | |
22887 | v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int); | |
22888 | v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int); | |
22889 | @end smallexample | |
22890 | ||
22891 | The following built-in functions are available when @option{-maes} is | |
22892 | used. All of them generate the machine instruction that is part of the | |
22893 | name. | |
22894 | ||
22895 | @smallexample | |
22896 | v2di __builtin_ia32_aesenc128 (v2di, v2di); | |
22897 | v2di __builtin_ia32_aesenclast128 (v2di, v2di); | |
22898 | v2di __builtin_ia32_aesdec128 (v2di, v2di); | |
22899 | v2di __builtin_ia32_aesdeclast128 (v2di, v2di); | |
22900 | v2di __builtin_ia32_aeskeygenassist128 (v2di, const int); | |
22901 | v2di __builtin_ia32_aesimc128 (v2di); | |
22902 | @end smallexample | |
22903 | ||
22904 | The following built-in function is available when @option{-mpclmul} is | |
22905 | used. | |
22906 | ||
f25efe50 | 22907 | @defbuiltin{v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)} |
d77de738 | 22908 | Generates the @code{pclmulqdq} machine instruction. |
f25efe50 | 22909 | @enddefbuiltin |
d77de738 ML |
22910 | |
22911 | The following built-in function is available when @option{-mfsgsbase} is | |
22912 | used. All of them generate the machine instruction that is part of the | |
22913 | name. | |
22914 | ||
22915 | @smallexample | |
22916 | unsigned int __builtin_ia32_rdfsbase32 (void); | |
22917 | unsigned long long __builtin_ia32_rdfsbase64 (void); | |
22918 | unsigned int __builtin_ia32_rdgsbase32 (void); | |
22919 | unsigned long long __builtin_ia32_rdgsbase64 (void); | |
22920 | void _writefsbase_u32 (unsigned int); | |
22921 | void _writefsbase_u64 (unsigned long long); | |
22922 | void _writegsbase_u32 (unsigned int); | |
22923 | void _writegsbase_u64 (unsigned long long); | |
22924 | @end smallexample | |
22925 | ||
22926 | The following built-in function is available when @option{-mrdrnd} is | |
22927 | used. All of them generate the machine instruction that is part of the | |
22928 | name. | |
22929 | ||
22930 | @smallexample | |
22931 | unsigned int __builtin_ia32_rdrand16_step (unsigned short *); | |
22932 | unsigned int __builtin_ia32_rdrand32_step (unsigned int *); | |
22933 | unsigned int __builtin_ia32_rdrand64_step (unsigned long long *); | |
22934 | @end smallexample | |
22935 | ||
22936 | The following built-in function is available when @option{-mptwrite} is | |
22937 | used. All of them generate the machine instruction that is part of the | |
22938 | name. | |
22939 | ||
22940 | @smallexample | |
22941 | void __builtin_ia32_ptwrite32 (unsigned); | |
22942 | void __builtin_ia32_ptwrite64 (unsigned long long); | |
22943 | @end smallexample | |
22944 | ||
22945 | The following built-in functions are available when @option{-msse4a} is used. | |
22946 | All of them generate the machine instruction that is part of the name. | |
22947 | ||
22948 | @smallexample | |
22949 | void __builtin_ia32_movntsd (double *, v2df); | |
22950 | void __builtin_ia32_movntss (float *, v4sf); | |
22951 | v2di __builtin_ia32_extrq (v2di, v16qi); | |
22952 | v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int); | |
22953 | v2di __builtin_ia32_insertq (v2di, v2di); | |
22954 | v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int); | |
22955 | @end smallexample | |
22956 | ||
22957 | The following built-in functions are available when @option{-mxop} is used. | |
22958 | @smallexample | |
22959 | v2df __builtin_ia32_vfrczpd (v2df); | |
22960 | v4sf __builtin_ia32_vfrczps (v4sf); | |
22961 | v2df __builtin_ia32_vfrczsd (v2df); | |
22962 | v4sf __builtin_ia32_vfrczss (v4sf); | |
22963 | v4df __builtin_ia32_vfrczpd256 (v4df); | |
22964 | v8sf __builtin_ia32_vfrczps256 (v8sf); | |
22965 | v2di __builtin_ia32_vpcmov (v2di, v2di, v2di); | |
22966 | v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di); | |
22967 | v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si); | |
22968 | v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi); | |
22969 | v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi); | |
22970 | v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df); | |
22971 | v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf); | |
22972 | v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di); | |
22973 | v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si); | |
22974 | v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi); | |
22975 | v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi); | |
22976 | v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df); | |
22977 | v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf); | |
22978 | v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi); | |
22979 | v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi); | |
22980 | v4si __builtin_ia32_vpcomeqd (v4si, v4si); | |
22981 | v2di __builtin_ia32_vpcomeqq (v2di, v2di); | |
22982 | v16qi __builtin_ia32_vpcomequb (v16qi, v16qi); | |
22983 | v4si __builtin_ia32_vpcomequd (v4si, v4si); | |
22984 | v2di __builtin_ia32_vpcomequq (v2di, v2di); | |
22985 | v8hi __builtin_ia32_vpcomequw (v8hi, v8hi); | |
22986 | v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi); | |
22987 | v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi); | |
22988 | v4si __builtin_ia32_vpcomfalsed (v4si, v4si); | |
22989 | v2di __builtin_ia32_vpcomfalseq (v2di, v2di); | |
22990 | v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi); | |
22991 | v4si __builtin_ia32_vpcomfalseud (v4si, v4si); | |
22992 | v2di __builtin_ia32_vpcomfalseuq (v2di, v2di); | |
22993 | v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi); | |
22994 | v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi); | |
22995 | v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi); | |
22996 | v4si __builtin_ia32_vpcomged (v4si, v4si); | |
22997 | v2di __builtin_ia32_vpcomgeq (v2di, v2di); | |
22998 | v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi); | |
22999 | v4si __builtin_ia32_vpcomgeud (v4si, v4si); | |
23000 | v2di __builtin_ia32_vpcomgeuq (v2di, v2di); | |
23001 | v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi); | |
23002 | v8hi __builtin_ia32_vpcomgew (v8hi, v8hi); | |
23003 | v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi); | |
23004 | v4si __builtin_ia32_vpcomgtd (v4si, v4si); | |
23005 | v2di __builtin_ia32_vpcomgtq (v2di, v2di); | |
23006 | v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi); | |
23007 | v4si __builtin_ia32_vpcomgtud (v4si, v4si); | |
23008 | v2di __builtin_ia32_vpcomgtuq (v2di, v2di); | |
23009 | v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi); | |
23010 | v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi); | |
23011 | v16qi __builtin_ia32_vpcomleb (v16qi, v16qi); | |
23012 | v4si __builtin_ia32_vpcomled (v4si, v4si); | |
23013 | v2di __builtin_ia32_vpcomleq (v2di, v2di); | |
23014 | v16qi __builtin_ia32_vpcomleub (v16qi, v16qi); | |
23015 | v4si __builtin_ia32_vpcomleud (v4si, v4si); | |
23016 | v2di __builtin_ia32_vpcomleuq (v2di, v2di); | |
23017 | v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi); | |
23018 | v8hi __builtin_ia32_vpcomlew (v8hi, v8hi); | |
23019 | v16qi __builtin_ia32_vpcomltb (v16qi, v16qi); | |
23020 | v4si __builtin_ia32_vpcomltd (v4si, v4si); | |
23021 | v2di __builtin_ia32_vpcomltq (v2di, v2di); | |
23022 | v16qi __builtin_ia32_vpcomltub (v16qi, v16qi); | |
23023 | v4si __builtin_ia32_vpcomltud (v4si, v4si); | |
23024 | v2di __builtin_ia32_vpcomltuq (v2di, v2di); | |
23025 | v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi); | |
23026 | v8hi __builtin_ia32_vpcomltw (v8hi, v8hi); | |
23027 | v16qi __builtin_ia32_vpcomneb (v16qi, v16qi); | |
23028 | v4si __builtin_ia32_vpcomned (v4si, v4si); | |
23029 | v2di __builtin_ia32_vpcomneq (v2di, v2di); | |
23030 | v16qi __builtin_ia32_vpcomneub (v16qi, v16qi); | |
23031 | v4si __builtin_ia32_vpcomneud (v4si, v4si); | |
23032 | v2di __builtin_ia32_vpcomneuq (v2di, v2di); | |
23033 | v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi); | |
23034 | v8hi __builtin_ia32_vpcomnew (v8hi, v8hi); | |
23035 | v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi); | |
23036 | v4si __builtin_ia32_vpcomtrued (v4si, v4si); | |
23037 | v2di __builtin_ia32_vpcomtrueq (v2di, v2di); | |
23038 | v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi); | |
23039 | v4si __builtin_ia32_vpcomtrueud (v4si, v4si); | |
23040 | v2di __builtin_ia32_vpcomtrueuq (v2di, v2di); | |
23041 | v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi); | |
23042 | v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi); | |
23043 | v4si __builtin_ia32_vphaddbd (v16qi); | |
23044 | v2di __builtin_ia32_vphaddbq (v16qi); | |
23045 | v8hi __builtin_ia32_vphaddbw (v16qi); | |
23046 | v2di __builtin_ia32_vphadddq (v4si); | |
23047 | v4si __builtin_ia32_vphaddubd (v16qi); | |
23048 | v2di __builtin_ia32_vphaddubq (v16qi); | |
23049 | v8hi __builtin_ia32_vphaddubw (v16qi); | |
23050 | v2di __builtin_ia32_vphaddudq (v4si); | |
23051 | v4si __builtin_ia32_vphadduwd (v8hi); | |
23052 | v2di __builtin_ia32_vphadduwq (v8hi); | |
23053 | v4si __builtin_ia32_vphaddwd (v8hi); | |
23054 | v2di __builtin_ia32_vphaddwq (v8hi); | |
23055 | v8hi __builtin_ia32_vphsubbw (v16qi); | |
23056 | v2di __builtin_ia32_vphsubdq (v4si); | |
23057 | v4si __builtin_ia32_vphsubwd (v8hi); | |
23058 | v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si); | |
23059 | v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di); | |
23060 | v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di); | |
23061 | v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si); | |
23062 | v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di); | |
23063 | v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di); | |
23064 | v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si); | |
23065 | v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi); | |
23066 | v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si); | |
23067 | v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi); | |
23068 | v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si); | |
23069 | v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si); | |
23070 | v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi); | |
23071 | v16qi __builtin_ia32_vprotb (v16qi, v16qi); | |
23072 | v4si __builtin_ia32_vprotd (v4si, v4si); | |
23073 | v2di __builtin_ia32_vprotq (v2di, v2di); | |
23074 | v8hi __builtin_ia32_vprotw (v8hi, v8hi); | |
23075 | v16qi __builtin_ia32_vpshab (v16qi, v16qi); | |
23076 | v4si __builtin_ia32_vpshad (v4si, v4si); | |
23077 | v2di __builtin_ia32_vpshaq (v2di, v2di); | |
23078 | v8hi __builtin_ia32_vpshaw (v8hi, v8hi); | |
23079 | v16qi __builtin_ia32_vpshlb (v16qi, v16qi); | |
23080 | v4si __builtin_ia32_vpshld (v4si, v4si); | |
23081 | v2di __builtin_ia32_vpshlq (v2di, v2di); | |
23082 | v8hi __builtin_ia32_vpshlw (v8hi, v8hi); | |
23083 | @end smallexample | |
23084 | ||
23085 | The following built-in functions are available when @option{-mfma4} is used. | |
23086 | All of them generate the machine instruction that is part of the name. | |
23087 | ||
23088 | @smallexample | |
23089 | v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df); | |
23090 | v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf); | |
23091 | v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df); | |
23092 | v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf); | |
23093 | v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df); | |
23094 | v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf); | |
23095 | v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df); | |
23096 | v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf); | |
23097 | v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df); | |
23098 | v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf); | |
23099 | v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df); | |
23100 | v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf); | |
23101 | v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df); | |
23102 | v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf); | |
23103 | v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df); | |
23104 | v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf); | |
23105 | v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df); | |
23106 | v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf); | |
23107 | v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df); | |
23108 | v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf); | |
23109 | v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df); | |
23110 | v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf); | |
23111 | v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df); | |
23112 | v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf); | |
23113 | v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df); | |
23114 | v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf); | |
23115 | v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df); | |
23116 | v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf); | |
23117 | v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df); | |
23118 | v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf); | |
23119 | v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df); | |
23120 | v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf); | |
23121 | ||
23122 | @end smallexample | |
23123 | ||
23124 | The following built-in functions are available when @option{-mlwp} is used. | |
23125 | ||
23126 | @smallexample | |
23127 | void __builtin_ia32_llwpcb16 (void *); | |
23128 | void __builtin_ia32_llwpcb32 (void *); | |
23129 | void __builtin_ia32_llwpcb64 (void *); | |
23130 | void * __builtin_ia32_llwpcb16 (void); | |
23131 | void * __builtin_ia32_llwpcb32 (void); | |
23132 | void * __builtin_ia32_llwpcb64 (void); | |
23133 | void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short); | |
23134 | void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int); | |
23135 | void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int); | |
23136 | unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short); | |
23137 | unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int); | |
23138 | unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int); | |
23139 | @end smallexample | |
23140 | ||
23141 | The following built-in functions are available when @option{-mbmi} is used. | |
23142 | All of them generate the machine instruction that is part of the name. | |
23143 | @smallexample | |
23144 | unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); | |
23145 | unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); | |
23146 | @end smallexample | |
23147 | ||
23148 | The following built-in functions are available when @option{-mbmi2} is used. | |
23149 | All of them generate the machine instruction that is part of the name. | |
23150 | @smallexample | |
23151 | unsigned int _bzhi_u32 (unsigned int, unsigned int); | |
23152 | unsigned int _pdep_u32 (unsigned int, unsigned int); | |
23153 | unsigned int _pext_u32 (unsigned int, unsigned int); | |
23154 | unsigned long long _bzhi_u64 (unsigned long long, unsigned long long); | |
23155 | unsigned long long _pdep_u64 (unsigned long long, unsigned long long); | |
23156 | unsigned long long _pext_u64 (unsigned long long, unsigned long long); | |
23157 | @end smallexample | |
23158 | ||
23159 | The following built-in functions are available when @option{-mlzcnt} is used. | |
23160 | All of them generate the machine instruction that is part of the name. | |
23161 | @smallexample | |
23162 | unsigned short __builtin_ia32_lzcnt_u16(unsigned short); | |
23163 | unsigned int __builtin_ia32_lzcnt_u32(unsigned int); | |
23164 | unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); | |
23165 | @end smallexample | |
23166 | ||
23167 | The following built-in functions are available when @option{-mfxsr} is used. | |
23168 | All of them generate the machine instruction that is part of the name. | |
23169 | @smallexample | |
23170 | void __builtin_ia32_fxsave (void *); | |
23171 | void __builtin_ia32_fxrstor (void *); | |
23172 | void __builtin_ia32_fxsave64 (void *); | |
23173 | void __builtin_ia32_fxrstor64 (void *); | |
23174 | @end smallexample | |
23175 | ||
23176 | The following built-in functions are available when @option{-mxsave} is used. | |
23177 | All of them generate the machine instruction that is part of the name. | |
23178 | @smallexample | |
23179 | void __builtin_ia32_xsave (void *, long long); | |
23180 | void __builtin_ia32_xrstor (void *, long long); | |
23181 | void __builtin_ia32_xsave64 (void *, long long); | |
23182 | void __builtin_ia32_xrstor64 (void *, long long); | |
23183 | @end smallexample | |
23184 | ||
23185 | The following built-in functions are available when @option{-mxsaveopt} is used. | |
23186 | All of them generate the machine instruction that is part of the name. | |
23187 | @smallexample | |
23188 | void __builtin_ia32_xsaveopt (void *, long long); | |
23189 | void __builtin_ia32_xsaveopt64 (void *, long long); | |
23190 | @end smallexample | |
23191 | ||
23192 | The following built-in functions are available when @option{-mtbm} is used. | |
23193 | Both of them generate the immediate form of the bextr machine instruction. | |
23194 | @smallexample | |
23195 | unsigned int __builtin_ia32_bextri_u32 (unsigned int, | |
23196 | const unsigned int); | |
23197 | unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, | |
23198 | const unsigned long long); | |
23199 | @end smallexample | |
23200 | ||
23201 | ||
23202 | The following built-in functions are available when @option{-m3dnow} is used. | |
23203 | All of them generate the machine instruction that is part of the name. | |
23204 | ||
23205 | @smallexample | |
23206 | void __builtin_ia32_femms (void); | |
23207 | v8qi __builtin_ia32_pavgusb (v8qi, v8qi); | |
23208 | v2si __builtin_ia32_pf2id (v2sf); | |
23209 | v2sf __builtin_ia32_pfacc (v2sf, v2sf); | |
23210 | v2sf __builtin_ia32_pfadd (v2sf, v2sf); | |
23211 | v2si __builtin_ia32_pfcmpeq (v2sf, v2sf); | |
23212 | v2si __builtin_ia32_pfcmpge (v2sf, v2sf); | |
23213 | v2si __builtin_ia32_pfcmpgt (v2sf, v2sf); | |
23214 | v2sf __builtin_ia32_pfmax (v2sf, v2sf); | |
23215 | v2sf __builtin_ia32_pfmin (v2sf, v2sf); | |
23216 | v2sf __builtin_ia32_pfmul (v2sf, v2sf); | |
23217 | v2sf __builtin_ia32_pfrcp (v2sf); | |
23218 | v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf); | |
23219 | v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf); | |
23220 | v2sf __builtin_ia32_pfrsqrt (v2sf); | |
23221 | v2sf __builtin_ia32_pfsub (v2sf, v2sf); | |
23222 | v2sf __builtin_ia32_pfsubr (v2sf, v2sf); | |
23223 | v2sf __builtin_ia32_pi2fd (v2si); | |
23224 | v4hi __builtin_ia32_pmulhrw (v4hi, v4hi); | |
23225 | @end smallexample | |
23226 | ||
23227 | The following built-in functions are available when @option{-m3dnowa} is used. | |
23228 | All of them generate the machine instruction that is part of the name. | |
23229 | ||
23230 | @smallexample | |
23231 | v2si __builtin_ia32_pf2iw (v2sf); | |
23232 | v2sf __builtin_ia32_pfnacc (v2sf, v2sf); | |
23233 | v2sf __builtin_ia32_pfpnacc (v2sf, v2sf); | |
23234 | v2sf __builtin_ia32_pi2fw (v2si); | |
23235 | v2sf __builtin_ia32_pswapdsf (v2sf); | |
23236 | v2si __builtin_ia32_pswapdsi (v2si); | |
23237 | @end smallexample | |
23238 | ||
23239 | The following built-in functions are available when @option{-mrtm} is used | |
23240 | They are used for restricted transactional memory. These are the internal | |
23241 | low level functions. Normally the functions in | |
23242 | @ref{x86 transactional memory intrinsics} should be used instead. | |
23243 | ||
23244 | @smallexample | |
23245 | int __builtin_ia32_xbegin (); | |
23246 | void __builtin_ia32_xend (); | |
23247 | void __builtin_ia32_xabort (status); | |
23248 | int __builtin_ia32_xtest (); | |
23249 | @end smallexample | |
23250 | ||
23251 | The following built-in functions are available when @option{-mmwaitx} is used. | |
23252 | All of them generate the machine instruction that is part of the name. | |
23253 | @smallexample | |
23254 | void __builtin_ia32_monitorx (void *, unsigned int, unsigned int); | |
23255 | void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int); | |
23256 | @end smallexample | |
23257 | ||
23258 | The following built-in functions are available when @option{-mclzero} is used. | |
23259 | All of them generate the machine instruction that is part of the name. | |
23260 | @smallexample | |
23261 | void __builtin_i32_clzero (void *); | |
23262 | @end smallexample | |
23263 | ||
23264 | The following built-in functions are available when @option{-mpku} is used. | |
23265 | They generate reads and writes to PKRU. | |
23266 | @smallexample | |
23267 | void __builtin_ia32_wrpkru (unsigned int); | |
23268 | unsigned int __builtin_ia32_rdpkru (); | |
23269 | @end smallexample | |
23270 | ||
23271 | The following built-in functions are available when | |
23272 | @option{-mshstk} option is used. They support shadow stack | |
23273 | machine instructions from Intel Control-flow Enforcement Technology (CET). | |
23274 | Each built-in function generates the machine instruction that is part | |
23275 | of the function's name. These are the internal low-level functions. | |
23276 | Normally the functions in @ref{x86 control-flow protection intrinsics} | |
23277 | should be used instead. | |
23278 | ||
23279 | @smallexample | |
23280 | unsigned int __builtin_ia32_rdsspd (void); | |
23281 | unsigned long long __builtin_ia32_rdsspq (void); | |
23282 | void __builtin_ia32_incsspd (unsigned int); | |
23283 | void __builtin_ia32_incsspq (unsigned long long); | |
23284 | void __builtin_ia32_saveprevssp(void); | |
23285 | void __builtin_ia32_rstorssp(void *); | |
23286 | void __builtin_ia32_wrssd(unsigned int, void *); | |
23287 | void __builtin_ia32_wrssq(unsigned long long, void *); | |
23288 | void __builtin_ia32_wrussd(unsigned int, void *); | |
23289 | void __builtin_ia32_wrussq(unsigned long long, void *); | |
23290 | void __builtin_ia32_setssbsy(void); | |
23291 | void __builtin_ia32_clrssbsy(void *); | |
23292 | @end smallexample | |
23293 | ||
23294 | @node x86 transactional memory intrinsics | |
23295 | @subsection x86 Transactional Memory Intrinsics | |
23296 | ||
23297 | These hardware transactional memory intrinsics for x86 allow you to use | |
23298 | memory transactions with RTM (Restricted Transactional Memory). | |
23299 | This support is enabled with the @option{-mrtm} option. | |
23300 | For using HLE (Hardware Lock Elision) see | |
23301 | @ref{x86 specific memory model extensions for transactional memory} instead. | |
23302 | ||
23303 | A memory transaction commits all changes to memory in an atomic way, | |
23304 | as visible to other threads. If the transaction fails it is rolled back | |
23305 | and all side effects discarded. | |
23306 | ||
23307 | Generally there is no guarantee that a memory transaction ever succeeds | |
23308 | and suitable fallback code always needs to be supplied. | |
23309 | ||
23310 | @deftypefn {RTM Function} {unsigned} _xbegin () | |
23311 | Start a RTM (Restricted Transactional Memory) transaction. | |
23312 | Returns @code{_XBEGIN_STARTED} when the transaction | |
23313 | started successfully (note this is not 0, so the constant has to be | |
23314 | explicitly tested). | |
23315 | ||
23316 | If the transaction aborts, all side effects | |
23317 | are undone and an abort code encoded as a bit mask is returned. | |
23318 | The following macros are defined: | |
23319 | ||
f25efe50 | 23320 | @defmac{_XABORT_EXPLICIT} |
d77de738 ML |
23321 | Transaction was explicitly aborted with @code{_xabort}. The parameter passed |
23322 | to @code{_xabort} is available with @code{_XABORT_CODE(status)}. | |
f25efe50 AA |
23323 | @end defmac |
23324 | ||
23325 | @defmac{_XABORT_RETRY} | |
d77de738 | 23326 | Transaction retry is possible. |
f25efe50 AA |
23327 | @end defmac |
23328 | ||
23329 | @defmac{_XABORT_CONFLICT} | |
d77de738 | 23330 | Transaction abort due to a memory conflict with another thread. |
f25efe50 AA |
23331 | @end defmac |
23332 | ||
23333 | @defmac{_XABORT_CAPACITY} | |
d77de738 | 23334 | Transaction abort due to the transaction using too much memory. |
f25efe50 AA |
23335 | @end defmac |
23336 | ||
23337 | @defmac{_XABORT_DEBUG} | |
d77de738 | 23338 | Transaction abort due to a debug trap. |
f25efe50 AA |
23339 | @end defmac |
23340 | ||
23341 | @defmac{_XABORT_NESTED} | |
d77de738 | 23342 | Transaction abort in an inner nested transaction. |
f25efe50 | 23343 | @end defmac |
d77de738 ML |
23344 | |
23345 | There is no guarantee | |
23346 | any transaction ever succeeds, so there always needs to be a valid | |
23347 | fallback path. | |
23348 | @end deftypefn | |
23349 | ||
23350 | @deftypefn {RTM Function} {void} _xend () | |
23351 | Commit the current transaction. When no transaction is active this faults. | |
23352 | All memory side effects of the transaction become visible | |
23353 | to other threads in an atomic manner. | |
23354 | @end deftypefn | |
23355 | ||
23356 | @deftypefn {RTM Function} {int} _xtest () | |
23357 | Return a nonzero value if a transaction is currently active, otherwise 0. | |
23358 | @end deftypefn | |
23359 | ||
23360 | @deftypefn {RTM Function} {void} _xabort (status) | |
23361 | Abort the current transaction. When no transaction is active this is a no-op. | |
23362 | The @var{status} is an 8-bit constant; its value is encoded in the return | |
23363 | value from @code{_xbegin}. | |
23364 | @end deftypefn | |
23365 | ||
23366 | Here is an example showing handling for @code{_XABORT_RETRY} | |
23367 | and a fallback path for other failures: | |
23368 | ||
23369 | @smallexample | |
23370 | #include <immintrin.h> | |
23371 | ||
23372 | int n_tries, max_tries; | |
23373 | unsigned status = _XABORT_EXPLICIT; | |
23374 | ... | |
23375 | ||
23376 | for (n_tries = 0; n_tries < max_tries; n_tries++) | |
23377 | @{ | |
23378 | status = _xbegin (); | |
23379 | if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY)) | |
23380 | break; | |
23381 | @} | |
23382 | if (status == _XBEGIN_STARTED) | |
23383 | @{ | |
23384 | ... transaction code... | |
23385 | _xend (); | |
23386 | @} | |
23387 | else | |
23388 | @{ | |
23389 | ... non-transactional fallback path... | |
23390 | @} | |
23391 | @end smallexample | |
23392 | ||
23393 | @noindent | |
23394 | Note that, in most cases, the transactional and non-transactional code | |
23395 | must synchronize together to ensure consistency. | |
23396 | ||
23397 | @node x86 control-flow protection intrinsics | |
23398 | @subsection x86 Control-Flow Protection Intrinsics | |
23399 | ||
23400 | @deftypefn {CET Function} {ret_type} _get_ssp (void) | |
23401 | Get the current value of shadow stack pointer if shadow stack support | |
23402 | from Intel CET is enabled in the hardware or @code{0} otherwise. | |
23403 | The @code{ret_type} is @code{unsigned long long} for 64-bit targets | |
23404 | and @code{unsigned int} for 32-bit targets. | |
23405 | @end deftypefn | |
23406 | ||
23407 | @deftypefn {CET Function} void _inc_ssp (unsigned int) | |
23408 | Increment the current shadow stack pointer by the size specified by the | |
23409 | function argument. The argument is masked to a byte value for security | |
23410 | reasons, so to increment by more than 255 bytes you must call the function | |
23411 | multiple times. | |
23412 | @end deftypefn | |
23413 | ||
23414 | The shadow stack unwind code looks like: | |
23415 | ||
23416 | @smallexample | |
23417 | #include <immintrin.h> | |
23418 | ||
23419 | /* Unwind the shadow stack for EH. */ | |
23420 | #define _Unwind_Frames_Extra(x) \ | |
23421 | do \ | |
23422 | @{ \ | |
23423 | _Unwind_Word ssp = _get_ssp (); \ | |
23424 | if (ssp != 0) \ | |
23425 | @{ \ | |
23426 | _Unwind_Word tmp = (x); \ | |
23427 | while (tmp > 255) \ | |
23428 | @{ \ | |
23429 | _inc_ssp (tmp); \ | |
23430 | tmp -= 255; \ | |
23431 | @} \ | |
23432 | _inc_ssp (tmp); \ | |
23433 | @} \ | |
23434 | @} \ | |
23435 | while (0) | |
23436 | @end smallexample | |
23437 | ||
23438 | @noindent | |
23439 | This code runs unconditionally on all 64-bit processors. For 32-bit | |
23440 | processors the code runs on those that support multi-byte NOP instructions. | |
23441 | ||
23442 | @node Target Format Checks | |
23443 | @section Format Checks Specific to Particular Target Machines | |
23444 | ||
23445 | For some target machines, GCC supports additional options to the | |
23446 | format attribute | |
23447 | (@pxref{Function Attributes,,Declaring Attributes of Functions}). | |
23448 | ||
23449 | @menu | |
23450 | * Solaris Format Checks:: | |
23451 | * Darwin Format Checks:: | |
23452 | @end menu | |
23453 | ||
23454 | @node Solaris Format Checks | |
23455 | @subsection Solaris Format Checks | |
23456 | ||
23457 | Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format | |
23458 | check. @code{cmn_err} accepts a subset of the standard @code{printf} | |
23459 | conversions, and the two-argument @code{%b} conversion for displaying | |
23460 | bit-fields. See the Solaris man page for @code{cmn_err} for more information. | |
23461 | ||
23462 | @node Darwin Format Checks | |
23463 | @subsection Darwin Format Checks | |
23464 | ||
23465 | In addition to the full set of format archetypes (attribute format style | |
23466 | arguments such as @code{printf}, @code{scanf}, @code{strftime}, and | |
23467 | @code{strfmon}), Darwin targets also support the @code{CFString} (or | |
23468 | @code{__CFString__}) archetype in the @code{format} attribute. | |
23469 | Declarations with this archetype are parsed for correct syntax | |
23470 | and argument types. However, parsing of the format string itself and | |
23471 | validating arguments against it in calls to such functions is currently | |
23472 | not performed. | |
23473 | ||
23474 | Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may | |
23475 | also be used as format arguments. Note that the relevant headers are only likely to be | |
23476 | available on Darwin (OSX) installations. On such installations, the XCode and system | |
23477 | documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and | |
23478 | associated functions. | |
23479 | ||
23480 | @node Pragmas | |
23481 | @section Pragmas Accepted by GCC | |
23482 | @cindex pragmas | |
23483 | @cindex @code{#pragma} | |
23484 | ||
23485 | GCC supports several types of pragmas, primarily in order to compile | |
23486 | code originally written for other compilers. Note that in general | |
23487 | we do not recommend the use of pragmas; @xref{Function Attributes}, | |
23488 | for further explanation. | |
23489 | ||
23490 | The GNU C preprocessor recognizes several pragmas in addition to the | |
23491 | compiler pragmas documented here. Refer to the CPP manual for more | |
23492 | information. | |
23493 | ||
23494 | @menu | |
23495 | * AArch64 Pragmas:: | |
23496 | * ARM Pragmas:: | |
23497 | * M32C Pragmas:: | |
d77de738 ML |
23498 | * PRU Pragmas:: |
23499 | * RS/6000 and PowerPC Pragmas:: | |
23500 | * S/390 Pragmas:: | |
23501 | * Darwin Pragmas:: | |
23502 | * Solaris Pragmas:: | |
23503 | * Symbol-Renaming Pragmas:: | |
23504 | * Structure-Layout Pragmas:: | |
23505 | * Weak Pragmas:: | |
23506 | * Diagnostic Pragmas:: | |
23507 | * Visibility Pragmas:: | |
23508 | * Push/Pop Macro Pragmas:: | |
23509 | * Function Specific Option Pragmas:: | |
23510 | * Loop-Specific Pragmas:: | |
23511 | @end menu | |
23512 | ||
23513 | @node AArch64 Pragmas | |
23514 | @subsection AArch64 Pragmas | |
23515 | ||
23516 | The pragmas defined by the AArch64 target correspond to the AArch64 | |
23517 | target function attributes. They can be specified as below: | |
23518 | @smallexample | |
23519 | #pragma GCC target("string") | |
23520 | @end smallexample | |
23521 | ||
23522 | where @code{@var{string}} can be any string accepted as an AArch64 target | |
23523 | attribute. @xref{AArch64 Function Attributes}, for more details | |
23524 | on the permissible values of @code{string}. | |
23525 | ||
23526 | @node ARM Pragmas | |
23527 | @subsection ARM Pragmas | |
23528 | ||
23529 | The ARM target defines pragmas for controlling the default addition of | |
23530 | @code{long_call} and @code{short_call} attributes to functions. | |
23531 | @xref{Function Attributes}, for information about the effects of these | |
23532 | attributes. | |
23533 | ||
23534 | @table @code | |
d77de738 | 23535 | @cindex pragma, long_calls |
f25efe50 | 23536 | @item long_calls |
d77de738 ML |
23537 | Set all subsequent functions to have the @code{long_call} attribute. |
23538 | ||
d77de738 | 23539 | @cindex pragma, no_long_calls |
f25efe50 | 23540 | @item no_long_calls |
d77de738 ML |
23541 | Set all subsequent functions to have the @code{short_call} attribute. |
23542 | ||
d77de738 | 23543 | @cindex pragma, long_calls_off |
f25efe50 | 23544 | @item long_calls_off |
d77de738 ML |
23545 | Do not affect the @code{long_call} or @code{short_call} attributes of |
23546 | subsequent functions. | |
23547 | @end table | |
23548 | ||
23549 | @node M32C Pragmas | |
23550 | @subsection M32C Pragmas | |
23551 | ||
23552 | @table @code | |
d77de738 | 23553 | @cindex pragma, memregs |
f25efe50 | 23554 | @item GCC memregs @var{number} |
d77de738 ML |
23555 | Overrides the command-line option @code{-memregs=} for the current |
23556 | file. Use with care! This pragma must be before any function in the | |
23557 | file, and mixing different memregs values in different objects may | |
23558 | make them incompatible. This pragma is useful when a | |
23559 | performance-critical function uses a memreg for temporary values, | |
23560 | as it may allow you to reduce the number of memregs used. | |
23561 | ||
d77de738 | 23562 | @cindex pragma, address |
f25efe50 | 23563 | @item ADDRESS @var{name} @var{address} |
d77de738 ML |
23564 | For any declared symbols matching @var{name}, this does three things |
23565 | to that symbol: it forces the symbol to be located at the given | |
23566 | address (a number), it forces the symbol to be volatile, and it | |
23567 | changes the symbol's scope to be static. This pragma exists for | |
23568 | compatibility with other compilers, but note that the common | |
23569 | @code{1234H} numeric syntax is not supported (use @code{0x1234} | |
23570 | instead). Example: | |
23571 | ||
23572 | @smallexample | |
23573 | #pragma ADDRESS port3 0x103 | |
23574 | char port3; | |
23575 | @end smallexample | |
23576 | ||
23577 | @end table | |
23578 | ||
d77de738 ML |
23579 | @node PRU Pragmas |
23580 | @subsection PRU Pragmas | |
23581 | ||
23582 | @table @code | |
23583 | ||
d77de738 | 23584 | @cindex pragma, ctable_entry |
f25efe50 | 23585 | @item ctable_entry @var{index} @var{constant_address} |
d77de738 ML |
23586 | Specifies that the PRU CTABLE entry given by @var{index} has the value |
23587 | @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions | |
23588 | when the load/store address is known and can be addressed with some CTABLE | |
23589 | entry. For example: | |
23590 | ||
23591 | @smallexample | |
23592 | /* will compile to "sbco Rx, 2, 0x10, 4" */ | |
23593 | #pragma ctable_entry 2 0x4802a000 | |
23594 | *(unsigned int *)0x4802a010 = val; | |
23595 | @end smallexample | |
23596 | ||
23597 | @end table | |
23598 | ||
23599 | @node RS/6000 and PowerPC Pragmas | |
23600 | @subsection RS/6000 and PowerPC Pragmas | |
23601 | ||
23602 | The RS/6000 and PowerPC targets define one pragma for controlling | |
23603 | whether or not the @code{longcall} attribute is added to function | |
23604 | declarations by default. This pragma overrides the @option{-mlongcall} | |
23605 | option, but not the @code{longcall} and @code{shortcall} attributes. | |
23606 | @xref{RS/6000 and PowerPC Options}, for more information about when long | |
23607 | calls are and are not necessary. | |
23608 | ||
23609 | @table @code | |
d77de738 | 23610 | @cindex pragma, longcall |
f25efe50 | 23611 | @item longcall (1) |
d77de738 ML |
23612 | Apply the @code{longcall} attribute to all subsequent function |
23613 | declarations. | |
23614 | ||
23615 | @item longcall (0) | |
23616 | Do not apply the @code{longcall} attribute to subsequent function | |
23617 | declarations. | |
23618 | @end table | |
23619 | ||
23620 | @c Describe h8300 pragmas here. | |
23621 | @c Describe sh pragmas here. | |
23622 | @c Describe v850 pragmas here. | |
23623 | ||
23624 | @node S/390 Pragmas | |
23625 | @subsection S/390 Pragmas | |
23626 | ||
23627 | The pragmas defined by the S/390 target correspond to the S/390 | |
23628 | target function attributes and some the additional options: | |
23629 | ||
23630 | @table @samp | |
23631 | @item zvector | |
23632 | @itemx no-zvector | |
23633 | @end table | |
23634 | ||
23635 | Note that options of the pragma, unlike options of the target | |
23636 | attribute, do change the value of preprocessor macros like | |
23637 | @code{__VEC__}. They can be specified as below: | |
23638 | ||
23639 | @smallexample | |
23640 | #pragma GCC target("string[,string]...") | |
23641 | #pragma GCC target("string"[,"string"]...) | |
23642 | @end smallexample | |
23643 | ||
23644 | @node Darwin Pragmas | |
23645 | @subsection Darwin Pragmas | |
23646 | ||
23647 | The following pragmas are available for all architectures running the | |
23648 | Darwin operating system. These are useful for compatibility with other | |
23649 | Mac OS compilers. | |
23650 | ||
23651 | @table @code | |
d77de738 | 23652 | @cindex pragma, mark |
f25efe50 | 23653 | @item mark @var{tokens}@dots{} |
d77de738 ML |
23654 | This pragma is accepted, but has no effect. |
23655 | ||
d77de738 | 23656 | @cindex pragma, options align |
f25efe50 | 23657 | @item options align=@var{alignment} |
d77de738 ML |
23658 | This pragma sets the alignment of fields in structures. The values of |
23659 | @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or | |
23660 | @code{power}, to emulate PowerPC alignment. Uses of this pragma nest | |
23661 | properly; to restore the previous setting, use @code{reset} for the | |
23662 | @var{alignment}. | |
23663 | ||
d77de738 | 23664 | @cindex pragma, segment |
f25efe50 | 23665 | @item segment @var{tokens}@dots{} |
d77de738 ML |
23666 | This pragma is accepted, but has no effect. |
23667 | ||
d77de738 | 23668 | @cindex pragma, unused |
f25efe50 | 23669 | @item unused (@var{var} [, @var{var}]@dots{}) |
d77de738 ML |
23670 | This pragma declares variables to be possibly unused. GCC does not |
23671 | produce warnings for the listed variables. The effect is similar to | |
23672 | that of the @code{unused} attribute, except that this pragma may appear | |
23673 | anywhere within the variables' scopes. | |
23674 | @end table | |
23675 | ||
23676 | @node Solaris Pragmas | |
23677 | @subsection Solaris Pragmas | |
23678 | ||
23679 | The Solaris target supports @code{#pragma redefine_extname} | |
23680 | (@pxref{Symbol-Renaming Pragmas}). It also supports additional | |
23681 | @code{#pragma} directives for compatibility with the system compiler. | |
23682 | ||
23683 | @table @code | |
d77de738 | 23684 | @cindex pragma, align |
f25efe50 | 23685 | @item align @var{alignment} (@var{variable} [, @var{variable}]...) |
d77de738 ML |
23686 | |
23687 | Increase the minimum alignment of each @var{variable} to @var{alignment}. | |
23688 | This is the same as GCC's @code{aligned} attribute @pxref{Variable | |
23689 | Attributes}). Macro expansion occurs on the arguments to this pragma | |
23690 | when compiling C and Objective-C@. It does not currently occur when | |
23691 | compiling C++, but this is a bug which may be fixed in a future | |
23692 | release. | |
23693 | ||
d77de738 | 23694 | @cindex pragma, fini |
f25efe50 | 23695 | @item fini (@var{function} [, @var{function}]...) |
d77de738 ML |
23696 | |
23697 | This pragma causes each listed @var{function} to be called after | |
23698 | main, or during shared module unloading, by adding a call to the | |
23699 | @code{.fini} section. | |
23700 | ||
d77de738 | 23701 | @cindex pragma, init |
f25efe50 | 23702 | @item init (@var{function} [, @var{function}]...) |
d77de738 ML |
23703 | |
23704 | This pragma causes each listed @var{function} to be called during | |
23705 | initialization (before @code{main}) or during shared module loading, by | |
23706 | adding a call to the @code{.init} section. | |
23707 | ||
23708 | @end table | |
23709 | ||
23710 | @node Symbol-Renaming Pragmas | |
23711 | @subsection Symbol-Renaming Pragmas | |
23712 | ||
23713 | GCC supports a @code{#pragma} directive that changes the name used in | |
23714 | assembly for a given declaration. While this pragma is supported on all | |
23715 | platforms, it is intended primarily to provide compatibility with the | |
23716 | Solaris system headers. This effect can also be achieved using the asm | |
23717 | labels extension (@pxref{Asm Labels}). | |
23718 | ||
23719 | @table @code | |
d77de738 | 23720 | @cindex pragma, redefine_extname |
f25efe50 | 23721 | @item redefine_extname @var{oldname} @var{newname} |
d77de738 ML |
23722 | |
23723 | This pragma gives the C function @var{oldname} the assembly symbol | |
23724 | @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} | |
23725 | is defined if this pragma is available (currently on all platforms). | |
23726 | @end table | |
23727 | ||
23728 | This pragma and the @code{asm} labels extension interact in a complicated | |
23729 | manner. Here are some corner cases you may want to be aware of: | |
23730 | ||
23731 | @enumerate | |
23732 | @item This pragma silently applies only to declarations with external | |
23733 | linkage. The @code{asm} label feature does not have this restriction. | |
23734 | ||
23735 | @item In C++, this pragma silently applies only to declarations with | |
23736 | ``C'' linkage. Again, @code{asm} labels do not have this restriction. | |
23737 | ||
23738 | @item If either of the ways of changing the assembly name of a | |
23739 | declaration are applied to a declaration whose assembly name has | |
23740 | already been determined (either by a previous use of one of these | |
23741 | features, or because the compiler needed the assembly name in order to | |
23742 | generate code), and the new name is different, a warning issues and | |
23743 | the name does not change. | |
23744 | ||
23745 | @item The @var{oldname} used by @code{#pragma redefine_extname} is | |
23746 | always the C-language name. | |
23747 | @end enumerate | |
23748 | ||
23749 | @node Structure-Layout Pragmas | |
23750 | @subsection Structure-Layout Pragmas | |
23751 | ||
23752 | For compatibility with Microsoft Windows compilers, GCC supports a | |
23753 | set of @code{#pragma} directives that change the maximum alignment of | |
23754 | members of structures (other than zero-width bit-fields), unions, and | |
23755 | classes subsequently defined. The @var{n} value below always is required | |
23756 | to be a small power of two and specifies the new alignment in bytes. | |
23757 | ||
23758 | @enumerate | |
23759 | @item @code{#pragma pack(@var{n})} simply sets the new alignment. | |
23760 | @item @code{#pragma pack()} sets the alignment to the one that was in | |
23761 | effect when compilation started (see also command-line option | |
23762 | @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). | |
23763 | @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment | |
23764 | setting on an internal stack and then optionally sets the new alignment. | |
23765 | @item @code{#pragma pack(pop)} restores the alignment setting to the one | |
23766 | saved at the top of the internal stack (and removes that stack entry). | |
23767 | Note that @code{#pragma pack([@var{n}])} does not influence this internal | |
23768 | stack; thus it is possible to have @code{#pragma pack(push)} followed by | |
23769 | multiple @code{#pragma pack(@var{n})} instances and finalized by a single | |
23770 | @code{#pragma pack(pop)}. | |
23771 | @end enumerate | |
23772 | ||
23773 | Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} | |
23774 | directive which lays out structures and unions subsequently defined as the | |
23775 | documented @code{__attribute__ ((ms_struct))}. | |
23776 | ||
23777 | @enumerate | |
23778 | @item @code{#pragma ms_struct on} turns on the Microsoft layout. | |
23779 | @item @code{#pragma ms_struct off} turns off the Microsoft layout. | |
23780 | @item @code{#pragma ms_struct reset} goes back to the default layout. | |
23781 | @end enumerate | |
23782 | ||
23783 | Most targets also support the @code{#pragma scalar_storage_order} directive | |
23784 | which lays out structures and unions subsequently defined as the documented | |
23785 | @code{__attribute__ ((scalar_storage_order))}. | |
23786 | ||
23787 | @enumerate | |
23788 | @item @code{#pragma scalar_storage_order big-endian} sets the storage order | |
23789 | of the scalar fields to big-endian. | |
23790 | @item @code{#pragma scalar_storage_order little-endian} sets the storage order | |
23791 | of the scalar fields to little-endian. | |
23792 | @item @code{#pragma scalar_storage_order default} goes back to the endianness | |
23793 | that was in effect when compilation started (see also command-line option | |
23794 | @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). | |
23795 | @end enumerate | |
23796 | ||
23797 | @node Weak Pragmas | |
23798 | @subsection Weak Pragmas | |
23799 | ||
23800 | For compatibility with SVR4, GCC supports a set of @code{#pragma} | |
23801 | directives for declaring symbols to be weak, and defining weak | |
23802 | aliases. | |
23803 | ||
23804 | @table @code | |
d77de738 | 23805 | @cindex pragma, weak |
f33d7a88 | 23806 | @item #pragma weak @var{symbol} |
d77de738 ML |
23807 | This pragma declares @var{symbol} to be weak, as if the declaration |
23808 | had the attribute of the same name. The pragma may appear before | |
23809 | or after the declaration of @var{symbol}. It is not an error for | |
23810 | @var{symbol} to never be defined at all. | |
23811 | ||
23812 | @item #pragma weak @var{symbol1} = @var{symbol2} | |
23813 | This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. | |
23814 | It is an error if @var{symbol2} is not defined in the current | |
23815 | translation unit. | |
23816 | @end table | |
23817 | ||
23818 | @node Diagnostic Pragmas | |
23819 | @subsection Diagnostic Pragmas | |
23820 | ||
23821 | GCC allows the user to selectively enable or disable certain types of | |
23822 | diagnostics, and change the kind of the diagnostic. For example, a | |
23823 | project's policy might require that all sources compile with | |
23824 | @option{-Werror} but certain files might have exceptions allowing | |
23825 | specific types of warnings. Or, a project might selectively enable | |
23826 | diagnostics and treat them as errors depending on which preprocessor | |
23827 | macros are defined. | |
23828 | ||
23829 | @table @code | |
d77de738 | 23830 | @cindex pragma, diagnostic |
f25efe50 | 23831 | @item #pragma GCC diagnostic @var{kind} @var{option} |
d77de738 ML |
23832 | |
23833 | Modifies the disposition of a diagnostic. Note that not all | |
23834 | diagnostics are modifiable; at the moment only warnings (normally | |
23835 | controlled by @samp{-W@dots{}}) can be controlled, and not all of them. | |
23836 | Use @option{-fdiagnostics-show-option} to determine which diagnostics | |
23837 | are controllable and which option controls them. | |
23838 | ||
23839 | @var{kind} is @samp{error} to treat this diagnostic as an error, | |
23840 | @samp{warning} to treat it like a warning (even if @option{-Werror} is | |
23841 | in effect), or @samp{ignored} if the diagnostic is to be ignored. | |
23842 | @var{option} is a double quoted string that matches the command-line | |
23843 | option. | |
23844 | ||
23845 | @smallexample | |
23846 | #pragma GCC diagnostic warning "-Wformat" | |
23847 | #pragma GCC diagnostic error "-Wformat" | |
23848 | #pragma GCC diagnostic ignored "-Wformat" | |
23849 | @end smallexample | |
23850 | ||
23851 | Note that these pragmas override any command-line options. GCC keeps | |
23852 | track of the location of each pragma, and issues diagnostics according | |
23853 | to the state as of that point in the source file. Thus, pragmas occurring | |
23854 | after a line do not affect diagnostics caused by that line. | |
23855 | ||
23856 | @item #pragma GCC diagnostic push | |
23857 | @itemx #pragma GCC diagnostic pop | |
23858 | ||
23859 | Causes GCC to remember the state of the diagnostics as of each | |
23860 | @code{push}, and restore to that point at each @code{pop}. If a | |
23861 | @code{pop} has no matching @code{push}, the command-line options are | |
23862 | restored. | |
23863 | ||
23864 | @smallexample | |
23865 | #pragma GCC diagnostic error "-Wuninitialized" | |
23866 | foo(a); /* error is given for this one */ | |
23867 | #pragma GCC diagnostic push | |
23868 | #pragma GCC diagnostic ignored "-Wuninitialized" | |
23869 | foo(b); /* no diagnostic for this one */ | |
23870 | #pragma GCC diagnostic pop | |
23871 | foo(c); /* error is given for this one */ | |
23872 | #pragma GCC diagnostic pop | |
23873 | foo(d); /* depends on command-line options */ | |
23874 | @end smallexample | |
23875 | ||
23876 | @item #pragma GCC diagnostic ignored_attributes | |
23877 | ||
23878 | Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress | |
23879 | warnings about unknown scoped attributes (in C++11 and C2X). For example, | |
23880 | @code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables | |
23881 | warning about the following declaration: | |
23882 | ||
23883 | @smallexample | |
23884 | [[vendor::attr]] void f(); | |
23885 | @end smallexample | |
23886 | ||
23887 | whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents | |
23888 | warning about both of these declarations: | |
23889 | ||
23890 | @smallexample | |
23891 | [[vendor::safe]] void f(); | |
23892 | [[vendor::unsafe]] void f2(); | |
23893 | @end smallexample | |
23894 | ||
23895 | @end table | |
23896 | ||
23897 | GCC also offers a simple mechanism for printing messages during | |
23898 | compilation. | |
23899 | ||
23900 | @table @code | |
d77de738 | 23901 | @cindex pragma, diagnostic |
f25efe50 | 23902 | @item #pragma message @var{string} |
d77de738 ML |
23903 | |
23904 | Prints @var{string} as a compiler message on compilation. The message | |
23905 | is informational only, and is neither a compilation warning nor an | |
23906 | error. Newlines can be included in the string by using the @samp{\n} | |
23907 | escape sequence. | |
23908 | ||
23909 | @smallexample | |
23910 | #pragma message "Compiling " __FILE__ "..." | |
23911 | @end smallexample | |
23912 | ||
23913 | @var{string} may be parenthesized, and is printed with location | |
23914 | information. For example, | |
23915 | ||
23916 | @smallexample | |
23917 | #define DO_PRAGMA(x) _Pragma (#x) | |
23918 | #define TODO(x) DO_PRAGMA(message ("TODO - " #x)) | |
23919 | ||
23920 | TODO(Remember to fix this) | |
23921 | @end smallexample | |
23922 | ||
23923 | @noindent | |
23924 | prints @samp{/tmp/file.c:4: note: #pragma message: | |
23925 | TODO - Remember to fix this}. | |
23926 | ||
d77de738 | 23927 | @cindex pragma, diagnostic |
f25efe50 | 23928 | @item #pragma GCC error @var{message} |
d77de738 ML |
23929 | Generates an error message. This pragma @emph{is} considered to |
23930 | indicate an error in the compilation, and it will be treated as such. | |
23931 | ||
23932 | Newlines can be included in the string by using the @samp{\n} | |
23933 | escape sequence. They will be displayed as newlines even if the | |
23934 | @option{-fmessage-length} option is set to zero. | |
23935 | ||
23936 | The error is only generated if the pragma is present in the code after | |
23937 | pre-processing has been completed. It does not matter however if the | |
23938 | code containing the pragma is unreachable: | |
23939 | ||
23940 | @smallexample | |
23941 | #if 0 | |
23942 | #pragma GCC error "this error is not seen" | |
23943 | #endif | |
23944 | void foo (void) | |
23945 | @{ | |
23946 | return; | |
23947 | #pragma GCC error "this error is seen" | |
23948 | @} | |
23949 | @end smallexample | |
23950 | ||
d77de738 | 23951 | @cindex pragma, diagnostic |
f25efe50 | 23952 | @item #pragma GCC warning @var{message} |
d77de738 ML |
23953 | This is just like @samp{pragma GCC error} except that a warning |
23954 | message is issued instead of an error message. Unless | |
23955 | @option{-Werror} is in effect, in which case this pragma will generate | |
23956 | an error as well. | |
23957 | ||
23958 | @end table | |
23959 | ||
23960 | @node Visibility Pragmas | |
23961 | @subsection Visibility Pragmas | |
23962 | ||
23963 | @table @code | |
f25efe50 | 23964 | @cindex pragma, visibility |
d77de738 ML |
23965 | @item #pragma GCC visibility push(@var{visibility}) |
23966 | @itemx #pragma GCC visibility pop | |
d77de738 ML |
23967 | |
23968 | This pragma allows the user to set the visibility for multiple | |
23969 | declarations without having to give each a visibility attribute | |
23970 | (@pxref{Function Attributes}). | |
23971 | ||
23972 | In C++, @samp{#pragma GCC visibility} affects only namespace-scope | |
23973 | declarations. Class members and template specializations are not | |
23974 | affected; if you want to override the visibility for a particular | |
23975 | member or instantiation, you must use an attribute. | |
23976 | ||
23977 | @end table | |
23978 | ||
23979 | ||
23980 | @node Push/Pop Macro Pragmas | |
23981 | @subsection Push/Pop Macro Pragmas | |
23982 | ||
23983 | For compatibility with Microsoft Windows compilers, GCC supports | |
23984 | @samp{#pragma push_macro(@var{"macro_name"})} | |
23985 | and @samp{#pragma pop_macro(@var{"macro_name"})}. | |
23986 | ||
23987 | @table @code | |
d77de738 | 23988 | @cindex pragma, push_macro |
f25efe50 | 23989 | @item #pragma push_macro(@var{"macro_name"}) |
d77de738 ML |
23990 | This pragma saves the value of the macro named as @var{macro_name} to |
23991 | the top of the stack for this macro. | |
23992 | ||
d77de738 | 23993 | @cindex pragma, pop_macro |
f25efe50 | 23994 | @item #pragma pop_macro(@var{"macro_name"}) |
d77de738 ML |
23995 | This pragma sets the value of the macro named as @var{macro_name} to |
23996 | the value on top of the stack for this macro. If the stack for | |
23997 | @var{macro_name} is empty, the value of the macro remains unchanged. | |
23998 | @end table | |
23999 | ||
24000 | For example: | |
24001 | ||
24002 | @smallexample | |
24003 | #define X 1 | |
24004 | #pragma push_macro("X") | |
24005 | #undef X | |
24006 | #define X -1 | |
24007 | #pragma pop_macro("X") | |
24008 | int x [X]; | |
24009 | @end smallexample | |
24010 | ||
24011 | @noindent | |
24012 | In this example, the definition of X as 1 is saved by @code{#pragma | |
24013 | push_macro} and restored by @code{#pragma pop_macro}. | |
24014 | ||
24015 | @node Function Specific Option Pragmas | |
24016 | @subsection Function Specific Option Pragmas | |
24017 | ||
24018 | @table @code | |
d77de738 | 24019 | @cindex pragma GCC target |
f25efe50 | 24020 | @item #pragma GCC target (@var{string}, @dots{}) |
d77de738 ML |
24021 | |
24022 | This pragma allows you to set target-specific options for functions | |
24023 | defined later in the source file. One or more strings can be | |
24024 | specified. Each function that is defined after this point is treated | |
24025 | as if it had been declared with one @code{target(}@var{string}@code{)} | |
24026 | attribute for each @var{string} argument. The parentheses around | |
24027 | the strings in the pragma are optional. @xref{Function Attributes}, | |
24028 | for more information about the @code{target} attribute and the attribute | |
24029 | syntax. | |
24030 | ||
24031 | The @code{#pragma GCC target} pragma is presently implemented for | |
24032 | x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. | |
24033 | ||
d77de738 | 24034 | @cindex pragma GCC optimize |
f25efe50 | 24035 | @item #pragma GCC optimize (@var{string}, @dots{}) |
d77de738 ML |
24036 | |
24037 | This pragma allows you to set global optimization options for functions | |
24038 | defined later in the source file. One or more strings can be | |
24039 | specified. Each function that is defined after this point is treated | |
24040 | as if it had been declared with one @code{optimize(}@var{string}@code{)} | |
24041 | attribute for each @var{string} argument. The parentheses around | |
24042 | the strings in the pragma are optional. @xref{Function Attributes}, | |
24043 | for more information about the @code{optimize} attribute and the attribute | |
24044 | syntax. | |
24045 | ||
d77de738 ML |
24046 | @cindex pragma GCC push_options |
24047 | @cindex pragma GCC pop_options | |
f25efe50 AA |
24048 | @item #pragma GCC push_options |
24049 | @itemx #pragma GCC pop_options | |
d77de738 ML |
24050 | |
24051 | These pragmas maintain a stack of the current target and optimization | |
24052 | options. It is intended for include files where you temporarily want | |
24053 | to switch to using a different @samp{#pragma GCC target} or | |
24054 | @samp{#pragma GCC optimize} and then to pop back to the previous | |
24055 | options. | |
24056 | ||
d77de738 | 24057 | @cindex pragma GCC reset_options |
f25efe50 | 24058 | @item #pragma GCC reset_options |
d77de738 ML |
24059 | |
24060 | This pragma clears the current @code{#pragma GCC target} and | |
24061 | @code{#pragma GCC optimize} to use the default switches as specified | |
24062 | on the command line. | |
24063 | ||
24064 | @end table | |
24065 | ||
24066 | @node Loop-Specific Pragmas | |
24067 | @subsection Loop-Specific Pragmas | |
24068 | ||
24069 | @table @code | |
d77de738 | 24070 | @cindex pragma GCC ivdep |
f25efe50 | 24071 | @item #pragma GCC ivdep |
d77de738 ML |
24072 | |
24073 | With this pragma, the programmer asserts that there are no loop-carried | |
24074 | dependencies which would prevent consecutive iterations of | |
24075 | the following loop from executing concurrently with SIMD | |
24076 | (single instruction multiple data) instructions. | |
24077 | ||
24078 | For example, the compiler can only unconditionally vectorize the following | |
24079 | loop with the pragma: | |
24080 | ||
24081 | @smallexample | |
24082 | void foo (int n, int *a, int *b, int *c) | |
24083 | @{ | |
24084 | int i, j; | |
24085 | #pragma GCC ivdep | |
24086 | for (i = 0; i < n; ++i) | |
24087 | a[i] = b[i] + c[i]; | |
24088 | @} | |
24089 | @end smallexample | |
24090 | ||
24091 | @noindent | |
24092 | In this example, using the @code{restrict} qualifier had the same | |
24093 | effect. In the following example, that would not be possible. Assume | |
24094 | @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows | |
24095 | that it can unconditionally vectorize the following loop: | |
24096 | ||
24097 | @smallexample | |
24098 | void ignore_vec_dep (int *a, int k, int c, int m) | |
24099 | @{ | |
24100 | #pragma GCC ivdep | |
24101 | for (int i = 0; i < m; i++) | |
24102 | a[i] = a[i + k] * c; | |
24103 | @} | |
24104 | @end smallexample | |
24105 | ||
d77de738 | 24106 | @cindex pragma GCC unroll @var{n} |
f25efe50 | 24107 | @item #pragma GCC unroll @var{n} |
d77de738 ML |
24108 | |
24109 | You can use this pragma to control how many times a loop should be unrolled. | |
24110 | It must be placed immediately before a @code{for}, @code{while} or @code{do} | |
24111 | loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. | |
24112 | @var{n} is an integer constant expression specifying the unrolling factor. | |
24113 | The values of @math{0} and @math{1} block any unrolling of the loop. | |
24114 | ||
24115 | @end table | |
24116 | ||
24117 | @node Unnamed Fields | |
24118 | @section Unnamed Structure and Union Fields | |
24119 | @cindex @code{struct} | |
24120 | @cindex @code{union} | |
24121 | ||
24122 | As permitted by ISO C11 and for compatibility with other compilers, | |
24123 | GCC allows you to define | |
24124 | a structure or union that contains, as fields, structures and unions | |
24125 | without names. For example: | |
24126 | ||
24127 | @smallexample | |
24128 | struct @{ | |
24129 | int a; | |
24130 | union @{ | |
24131 | int b; | |
24132 | float c; | |
24133 | @}; | |
24134 | int d; | |
24135 | @} foo; | |
24136 | @end smallexample | |
24137 | ||
24138 | @noindent | |
24139 | In this example, you are able to access members of the unnamed | |
24140 | union with code like @samp{foo.b}. Note that only unnamed structs and | |
24141 | unions are allowed, you may not have, for example, an unnamed | |
24142 | @code{int}. | |
24143 | ||
24144 | You must never create such structures that cause ambiguous field definitions. | |
24145 | For example, in this structure: | |
24146 | ||
24147 | @smallexample | |
24148 | struct @{ | |
24149 | int a; | |
24150 | struct @{ | |
24151 | int a; | |
24152 | @}; | |
24153 | @} foo; | |
24154 | @end smallexample | |
24155 | ||
24156 | @noindent | |
24157 | it is ambiguous which @code{a} is being referred to with @samp{foo.a}. | |
24158 | The compiler gives errors for such constructs. | |
24159 | ||
24160 | @opindex fms-extensions | |
24161 | Unless @option{-fms-extensions} is used, the unnamed field must be a | |
24162 | structure or union definition without a tag (for example, @samp{struct | |
24163 | @{ int a; @};}). If @option{-fms-extensions} is used, the field may | |
24164 | also be a definition with a tag such as @samp{struct foo @{ int a; | |
24165 | @};}, a reference to a previously defined structure or union such as | |
24166 | @samp{struct foo;}, or a reference to a @code{typedef} name for a | |
24167 | previously defined structure or union type. | |
24168 | ||
24169 | @opindex fplan9-extensions | |
24170 | The option @option{-fplan9-extensions} enables | |
24171 | @option{-fms-extensions} as well as two other extensions. First, a | |
24172 | pointer to a structure is automatically converted to a pointer to an | |
24173 | anonymous field for assignments and function calls. For example: | |
24174 | ||
24175 | @smallexample | |
24176 | struct s1 @{ int a; @}; | |
24177 | struct s2 @{ struct s1; @}; | |
24178 | extern void f1 (struct s1 *); | |
24179 | void f2 (struct s2 *p) @{ f1 (p); @} | |
24180 | @end smallexample | |
24181 | ||
24182 | @noindent | |
24183 | In the call to @code{f1} inside @code{f2}, the pointer @code{p} is | |
24184 | converted into a pointer to the anonymous field. | |
24185 | ||
24186 | Second, when the type of an anonymous field is a @code{typedef} for a | |
24187 | @code{struct} or @code{union}, code may refer to the field using the | |
24188 | name of the @code{typedef}. | |
24189 | ||
24190 | @smallexample | |
24191 | typedef struct @{ int a; @} s1; | |
24192 | struct s2 @{ s1; @}; | |
24193 | s1 f1 (struct s2 *p) @{ return p->s1; @} | |
24194 | @end smallexample | |
24195 | ||
24196 | These usages are only permitted when they are not ambiguous. | |
24197 | ||
24198 | @node Thread-Local | |
24199 | @section Thread-Local Storage | |
24200 | @cindex Thread-Local Storage | |
24201 | @cindex @acronym{TLS} | |
24202 | @cindex @code{__thread} | |
24203 | ||
24204 | Thread-local storage (@acronym{TLS}) is a mechanism by which variables | |
24205 | are allocated such that there is one instance of the variable per extant | |
24206 | thread. The runtime model GCC uses to implement this originates | |
24207 | in the IA-64 processor-specific ABI, but has since been migrated | |
24208 | to other processors as well. It requires significant support from | |
24209 | the linker (@command{ld}), dynamic linker (@command{ld.so}), and | |
24210 | system libraries (@file{libc.so} and @file{libpthread.so}), so it | |
24211 | is not available everywhere. | |
24212 | ||
24213 | At the user level, the extension is visible with a new storage | |
24214 | class keyword: @code{__thread}. For example: | |
24215 | ||
24216 | @smallexample | |
24217 | __thread int i; | |
24218 | extern __thread struct state s; | |
24219 | static __thread char *p; | |
24220 | @end smallexample | |
24221 | ||
24222 | The @code{__thread} specifier may be used alone, with the @code{extern} | |
24223 | or @code{static} specifiers, but with no other storage class specifier. | |
24224 | When used with @code{extern} or @code{static}, @code{__thread} must appear | |
24225 | immediately after the other storage class specifier. | |
24226 | ||
24227 | The @code{__thread} specifier may be applied to any global, file-scoped | |
24228 | static, function-scoped static, or static data member of a class. It may | |
24229 | not be applied to block-scoped automatic or non-static data member. | |
24230 | ||
24231 | When the address-of operator is applied to a thread-local variable, it is | |
24232 | evaluated at run time and returns the address of the current thread's | |
24233 | instance of that variable. An address so obtained may be used by any | |
24234 | thread. When a thread terminates, any pointers to thread-local variables | |
24235 | in that thread become invalid. | |
24236 | ||
24237 | No static initialization may refer to the address of a thread-local variable. | |
24238 | ||
24239 | In C++, if an initializer is present for a thread-local variable, it must | |
24240 | be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ | |
24241 | standard. | |
24242 | ||
24243 | See @uref{https://www.akkadia.org/drepper/tls.pdf, | |
24244 | ELF Handling For Thread-Local Storage} for a detailed explanation of | |
24245 | the four thread-local storage addressing models, and how the runtime | |
24246 | is expected to function. | |
24247 | ||
24248 | @menu | |
24249 | * C99 Thread-Local Edits:: | |
24250 | * C++98 Thread-Local Edits:: | |
24251 | @end menu | |
24252 | ||
24253 | @node C99 Thread-Local Edits | |
24254 | @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage | |
24255 | ||
24256 | The following are a set of changes to ISO/IEC 9899:1999 (aka C99) | |
24257 | that document the exact semantics of the language extension. | |
24258 | ||
24259 | @itemize @bullet | |
24260 | @item | |
24261 | @cite{5.1.2 Execution environments} | |
24262 | ||
24263 | Add new text after paragraph 1 | |
24264 | ||
24265 | @quotation | |
24266 | Within either execution environment, a @dfn{thread} is a flow of | |
24267 | control within a program. It is implementation defined whether | |
24268 | or not there may be more than one thread associated with a program. | |
24269 | It is implementation defined how threads beyond the first are | |
24270 | created, the name and type of the function called at thread | |
24271 | startup, and how threads may be terminated. However, objects | |
24272 | with thread storage duration shall be initialized before thread | |
24273 | startup. | |
24274 | @end quotation | |
24275 | ||
24276 | @item | |
24277 | @cite{6.2.4 Storage durations of objects} | |
24278 | ||
24279 | Add new text before paragraph 3 | |
24280 | ||
24281 | @quotation | |
24282 | An object whose identifier is declared with the storage-class | |
24283 | specifier @w{@code{__thread}} has @dfn{thread storage duration}. | |
24284 | Its lifetime is the entire execution of the thread, and its | |
24285 | stored value is initialized only once, prior to thread startup. | |
24286 | @end quotation | |
24287 | ||
24288 | @item | |
24289 | @cite{6.4.1 Keywords} | |
24290 | ||
24291 | Add @code{__thread}. | |
24292 | ||
24293 | @item | |
24294 | @cite{6.7.1 Storage-class specifiers} | |
24295 | ||
24296 | Add @code{__thread} to the list of storage class specifiers in | |
24297 | paragraph 1. | |
24298 | ||
24299 | Change paragraph 2 to | |
24300 | ||
24301 | @quotation | |
24302 | With the exception of @code{__thread}, at most one storage-class | |
24303 | specifier may be given [@dots{}]. The @code{__thread} specifier may | |
24304 | be used alone, or immediately following @code{extern} or | |
24305 | @code{static}. | |
24306 | @end quotation | |
24307 | ||
24308 | Add new text after paragraph 6 | |
24309 | ||
24310 | @quotation | |
24311 | The declaration of an identifier for a variable that has | |
24312 | block scope that specifies @code{__thread} shall also | |
24313 | specify either @code{extern} or @code{static}. | |
24314 | ||
24315 | The @code{__thread} specifier shall be used only with | |
24316 | variables. | |
24317 | @end quotation | |
24318 | @end itemize | |
24319 | ||
24320 | @node C++98 Thread-Local Edits | |
24321 | @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage | |
24322 | ||
24323 | The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) | |
24324 | that document the exact semantics of the language extension. | |
24325 | ||
24326 | @itemize @bullet | |
24327 | @item | |
24328 | @b{[intro.execution]} | |
24329 | ||
24330 | New text after paragraph 4 | |
24331 | ||
24332 | @quotation | |
24333 | A @dfn{thread} is a flow of control within the abstract machine. | |
24334 | It is implementation defined whether or not there may be more than | |
24335 | one thread. | |
24336 | @end quotation | |
24337 | ||
24338 | New text after paragraph 7 | |
24339 | ||
24340 | @quotation | |
24341 | It is unspecified whether additional action must be taken to | |
24342 | ensure when and whether side effects are visible to other threads. | |
24343 | @end quotation | |
24344 | ||
24345 | @item | |
24346 | @b{[lex.key]} | |
24347 | ||
24348 | Add @code{__thread}. | |
24349 | ||
24350 | @item | |
24351 | @b{[basic.start.main]} | |
24352 | ||
24353 | Add after paragraph 5 | |
24354 | ||
24355 | @quotation | |
24356 | The thread that begins execution at the @code{main} function is called | |
24357 | the @dfn{main thread}. It is implementation defined how functions | |
24358 | beginning threads other than the main thread are designated or typed. | |
24359 | A function so designated, as well as the @code{main} function, is called | |
24360 | a @dfn{thread startup function}. It is implementation defined what | |
24361 | happens if a thread startup function returns. It is implementation | |
24362 | defined what happens to other threads when any thread calls @code{exit}. | |
24363 | @end quotation | |
24364 | ||
24365 | @item | |
24366 | @b{[basic.start.init]} | |
24367 | ||
24368 | Add after paragraph 4 | |
24369 | ||
24370 | @quotation | |
24371 | The storage for an object of thread storage duration shall be | |
24372 | statically initialized before the first statement of the thread startup | |
24373 | function. An object of thread storage duration shall not require | |
24374 | dynamic initialization. | |
24375 | @end quotation | |
24376 | ||
24377 | @item | |
24378 | @b{[basic.start.term]} | |
24379 | ||
24380 | Add after paragraph 3 | |
24381 | ||
24382 | @quotation | |
24383 | The type of an object with thread storage duration shall not have a | |
24384 | non-trivial destructor, nor shall it be an array type whose elements | |
24385 | (directly or indirectly) have non-trivial destructors. | |
24386 | @end quotation | |
24387 | ||
24388 | @item | |
24389 | @b{[basic.stc]} | |
24390 | ||
24391 | Add ``thread storage duration'' to the list in paragraph 1. | |
24392 | ||
24393 | Change paragraph 2 | |
24394 | ||
24395 | @quotation | |
24396 | Thread, static, and automatic storage durations are associated with | |
24397 | objects introduced by declarations [@dots{}]. | |
24398 | @end quotation | |
24399 | ||
24400 | Add @code{__thread} to the list of specifiers in paragraph 3. | |
24401 | ||
24402 | @item | |
24403 | @b{[basic.stc.thread]} | |
24404 | ||
24405 | New section before @b{[basic.stc.static]} | |
24406 | ||
24407 | @quotation | |
24408 | The keyword @code{__thread} applied to a non-local object gives the | |
24409 | object thread storage duration. | |
24410 | ||
24411 | A local variable or class data member declared both @code{static} | |
24412 | and @code{__thread} gives the variable or member thread storage | |
24413 | duration. | |
24414 | @end quotation | |
24415 | ||
24416 | @item | |
24417 | @b{[basic.stc.static]} | |
24418 | ||
24419 | Change paragraph 1 | |
24420 | ||
24421 | @quotation | |
24422 | All objects that have neither thread storage duration, dynamic | |
24423 | storage duration nor are local [@dots{}]. | |
24424 | @end quotation | |
24425 | ||
24426 | @item | |
24427 | @b{[dcl.stc]} | |
24428 | ||
24429 | Add @code{__thread} to the list in paragraph 1. | |
24430 | ||
24431 | Change paragraph 1 | |
24432 | ||
24433 | @quotation | |
24434 | With the exception of @code{__thread}, at most one | |
24435 | @var{storage-class-specifier} shall appear in a given | |
24436 | @var{decl-specifier-seq}. The @code{__thread} specifier may | |
24437 | be used alone, or immediately following the @code{extern} or | |
24438 | @code{static} specifiers. [@dots{}] | |
24439 | @end quotation | |
24440 | ||
24441 | Add after paragraph 5 | |
24442 | ||
24443 | @quotation | |
24444 | The @code{__thread} specifier can be applied only to the names of objects | |
24445 | and to anonymous unions. | |
24446 | @end quotation | |
24447 | ||
24448 | @item | |
24449 | @b{[class.mem]} | |
24450 | ||
24451 | Add after paragraph 6 | |
24452 | ||
24453 | @quotation | |
24454 | Non-@code{static} members shall not be @code{__thread}. | |
24455 | @end quotation | |
24456 | @end itemize | |
24457 | ||
24458 | @node Binary constants | |
24459 | @section Binary Constants using the @samp{0b} Prefix | |
24460 | @cindex Binary constants using the @samp{0b} prefix | |
24461 | ||
24462 | Integer constants can be written as binary constants, consisting of a | |
24463 | sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or | |
24464 | @samp{0B}. This is particularly useful in environments that operate a | |
24465 | lot on the bit level (like microcontrollers). | |
24466 | ||
24467 | The following statements are identical: | |
24468 | ||
24469 | @smallexample | |
24470 | i = 42; | |
24471 | i = 0x2a; | |
24472 | i = 052; | |
24473 | i = 0b101010; | |
24474 | @end smallexample | |
24475 | ||
24476 | The type of these constants follows the same rules as for octal or | |
24477 | hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} | |
24478 | can be applied. | |
24479 | ||
24480 | @node C++ Extensions | |
24481 | @chapter Extensions to the C++ Language | |
24482 | @cindex extensions, C++ language | |
24483 | @cindex C++ language extensions | |
24484 | ||
24485 | The GNU compiler provides these extensions to the C++ language (and you | |
24486 | can also use most of the C language extensions in your C++ programs). If you | |
24487 | want to write code that checks whether these features are available, you can | |
24488 | test for the GNU compiler the same way as for C programs: check for a | |
24489 | predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to | |
24490 | test specifically for GNU C++ (@pxref{Common Predefined Macros,, | |
24491 | Predefined Macros,cpp,The GNU C Preprocessor}). | |
24492 | ||
24493 | @menu | |
24494 | * C++ Volatiles:: What constitutes an access to a volatile object. | |
24495 | * Restricted Pointers:: C99 restricted pointers and references. | |
24496 | * Vague Linkage:: Where G++ puts inlines, vtables and such. | |
24497 | * C++ Interface:: You can use a single C++ header file for both | |
24498 | declarations and definitions. | |
24499 | * Template Instantiation:: Methods for ensuring that exactly one copy of | |
24500 | each needed template instantiation is emitted. | |
24501 | * Bound member functions:: You can extract a function pointer to the | |
24502 | method denoted by a @samp{->*} or @samp{.*} expression. | |
24503 | * C++ Attributes:: Variable, function, and type attributes for C++ only. | |
24504 | * Function Multiversioning:: Declaring multiple function versions. | |
24505 | * Type Traits:: Compiler support for type traits. | |
24506 | * C++ Concepts:: Improved support for generic programming. | |
24507 | * Deprecated Features:: Things will disappear from G++. | |
24508 | * Backwards Compatibility:: Compatibilities with earlier definitions of C++. | |
24509 | @end menu | |
24510 | ||
24511 | @node C++ Volatiles | |
24512 | @section When is a Volatile C++ Object Accessed? | |
24513 | @cindex accessing volatiles | |
24514 | @cindex volatile read | |
24515 | @cindex volatile write | |
24516 | @cindex volatile access | |
24517 | ||
24518 | The C++ standard differs from the C standard in its treatment of | |
24519 | volatile objects. It fails to specify what constitutes a volatile | |
24520 | access, except to say that C++ should behave in a similar manner to C | |
24521 | with respect to volatiles, where possible. However, the different | |
24522 | lvalueness of expressions between C and C++ complicate the behavior. | |
24523 | G++ behaves the same as GCC for volatile access, @xref{C | |
24524 | Extensions,,Volatiles}, for a description of GCC's behavior. | |
24525 | ||
24526 | The C and C++ language specifications differ when an object is | |
24527 | accessed in a void context: | |
24528 | ||
24529 | @smallexample | |
24530 | volatile int *src = @var{somevalue}; | |
24531 | *src; | |
24532 | @end smallexample | |
24533 | ||
24534 | The C++ standard specifies that such expressions do not undergo lvalue | |
24535 | to rvalue conversion, and that the type of the dereferenced object may | |
24536 | be incomplete. The C++ standard does not specify explicitly that it | |
24537 | is lvalue to rvalue conversion that is responsible for causing an | |
24538 | access. There is reason to believe that it is, because otherwise | |
24539 | certain simple expressions become undefined. However, because it | |
24540 | would surprise most programmers, G++ treats dereferencing a pointer to | |
24541 | volatile object of complete type as GCC would do for an equivalent | |
24542 | type in C@. When the object has incomplete type, G++ issues a | |
24543 | warning; if you wish to force an error, you must force a conversion to | |
24544 | rvalue with, for instance, a static cast. | |
24545 | ||
24546 | When using a reference to volatile, G++ does not treat equivalent | |
24547 | expressions as accesses to volatiles, but instead issues a warning that | |
24548 | no volatile is accessed. The rationale for this is that otherwise it | |
24549 | becomes difficult to determine where volatile access occur, and not | |
24550 | possible to ignore the return value from functions returning volatile | |
24551 | references. Again, if you wish to force a read, cast the reference to | |
24552 | an rvalue. | |
24553 | ||
24554 | G++ implements the same behavior as GCC does when assigning to a | |
24555 | volatile object---there is no reread of the assigned-to object, the | |
24556 | assigned rvalue is reused. Note that in C++ assignment expressions | |
24557 | are lvalues, and if used as an lvalue, the volatile object is | |
24558 | referred to. For instance, @var{vref} refers to @var{vobj}, as | |
24559 | expected, in the following example: | |
24560 | ||
24561 | @smallexample | |
24562 | volatile int vobj; | |
24563 | volatile int &vref = vobj = @var{something}; | |
24564 | @end smallexample | |
24565 | ||
24566 | @node Restricted Pointers | |
24567 | @section Restricting Pointer Aliasing | |
24568 | @cindex restricted pointers | |
24569 | @cindex restricted references | |
24570 | @cindex restricted this pointer | |
24571 | ||
24572 | As with the C front end, G++ understands the C99 feature of restricted pointers, | |
24573 | specified with the @code{__restrict__}, or @code{__restrict} type | |
24574 | qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} | |
24575 | language flag, @code{restrict} is not a keyword in C++. | |
24576 | ||
24577 | In addition to allowing restricted pointers, you can specify restricted | |
24578 | references, which indicate that the reference is not aliased in the local | |
24579 | context. | |
24580 | ||
24581 | @smallexample | |
24582 | void fn (int *__restrict__ rptr, int &__restrict__ rref) | |
24583 | @{ | |
24584 | /* @r{@dots{}} */ | |
24585 | @} | |
24586 | @end smallexample | |
24587 | ||
24588 | @noindent | |
24589 | In the body of @code{fn}, @var{rptr} points to an unaliased integer and | |
24590 | @var{rref} refers to a (different) unaliased integer. | |
24591 | ||
24592 | You may also specify whether a member function's @var{this} pointer is | |
24593 | unaliased by using @code{__restrict__} as a member function qualifier. | |
24594 | ||
24595 | @smallexample | |
24596 | void T::fn () __restrict__ | |
24597 | @{ | |
24598 | /* @r{@dots{}} */ | |
24599 | @} | |
24600 | @end smallexample | |
24601 | ||
24602 | @noindent | |
24603 | Within the body of @code{T::fn}, @var{this} has the effective | |
24604 | definition @code{T *__restrict__ const this}. Notice that the | |
24605 | interpretation of a @code{__restrict__} member function qualifier is | |
24606 | different to that of @code{const} or @code{volatile} qualifier, in that it | |
24607 | is applied to the pointer rather than the object. This is consistent with | |
24608 | other compilers that implement restricted pointers. | |
24609 | ||
24610 | As with all outermost parameter qualifiers, @code{__restrict__} is | |
24611 | ignored in function definition matching. This means you only need to | |
24612 | specify @code{__restrict__} in a function definition, rather than | |
24613 | in a function prototype as well. | |
24614 | ||
24615 | @node Vague Linkage | |
24616 | @section Vague Linkage | |
24617 | @cindex vague linkage | |
24618 | ||
24619 | There are several constructs in C++ that require space in the object | |
24620 | file but are not clearly tied to a single translation unit. We say that | |
24621 | these constructs have ``vague linkage''. Typically such constructs are | |
24622 | emitted wherever they are needed, though sometimes we can be more | |
24623 | clever. | |
24624 | ||
24625 | @table @asis | |
24626 | @item Inline Functions | |
24627 | Inline functions are typically defined in a header file which can be | |
24628 | included in many different compilations. Hopefully they can usually be | |
24629 | inlined, but sometimes an out-of-line copy is necessary, if the address | |
24630 | of the function is taken or if inlining fails. In general, we emit an | |
24631 | out-of-line copy in all translation units where one is needed. As an | |
24632 | exception, we only emit inline virtual functions with the vtable, since | |
24633 | it always requires a copy. | |
24634 | ||
24635 | Local static variables and string constants used in an inline function | |
24636 | are also considered to have vague linkage, since they must be shared | |
24637 | between all inlined and out-of-line instances of the function. | |
24638 | ||
d77de738 | 24639 | @cindex vtable |
f25efe50 | 24640 | @item VTables |
d77de738 ML |
24641 | C++ virtual functions are implemented in most compilers using a lookup |
24642 | table, known as a vtable. The vtable contains pointers to the virtual | |
24643 | functions provided by a class, and each object of the class contains a | |
24644 | pointer to its vtable (or vtables, in some multiple-inheritance | |
24645 | situations). If the class declares any non-inline, non-pure virtual | |
24646 | functions, the first one is chosen as the ``key method'' for the class, | |
24647 | and the vtable is only emitted in the translation unit where the key | |
24648 | method is defined. | |
24649 | ||
24650 | @emph{Note:} If the chosen key method is later defined as inline, the | |
24651 | vtable is still emitted in every translation unit that defines it. | |
24652 | Make sure that any inline virtuals are declared inline in the class | |
24653 | body, even if they are not defined there. | |
24654 | ||
d77de738 ML |
24655 | @cindex @code{type_info} |
24656 | @cindex RTTI | |
f25efe50 | 24657 | @item @code{type_info} objects |
d77de738 ML |
24658 | C++ requires information about types to be written out in order to |
24659 | implement @samp{dynamic_cast}, @samp{typeid} and exception handling. | |
24660 | For polymorphic classes (classes with virtual functions), the @samp{type_info} | |
24661 | object is written out along with the vtable so that @samp{dynamic_cast} | |
24662 | can determine the dynamic type of a class object at run time. For all | |
24663 | other types, we write out the @samp{type_info} object when it is used: when | |
24664 | applying @samp{typeid} to an expression, throwing an object, or | |
24665 | referring to a type in a catch clause or exception specification. | |
24666 | ||
24667 | @item Template Instantiations | |
24668 | Most everything in this section also applies to template instantiations, | |
24669 | but there are other options as well. | |
24670 | @xref{Template Instantiation,,Where's the Template?}. | |
24671 | ||
24672 | @end table | |
24673 | ||
24674 | When used with GNU ld version 2.8 or later on an ELF system such as | |
24675 | GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of | |
24676 | these constructs will be discarded at link time. This is known as | |
24677 | COMDAT support. | |
24678 | ||
24679 | On targets that don't support COMDAT, but do support weak symbols, GCC | |
24680 | uses them. This way one copy overrides all the others, but | |
24681 | the unused copies still take up space in the executable. | |
24682 | ||
24683 | For targets that do not support either COMDAT or weak symbols, | |
24684 | most entities with vague linkage are emitted as local symbols to | |
24685 | avoid duplicate definition errors from the linker. This does not happen | |
24686 | for local statics in inlines, however, as having multiple copies | |
24687 | almost certainly breaks things. | |
24688 | ||
24689 | @xref{C++ Interface,,Declarations and Definitions in One Header}, for | |
24690 | another way to control placement of these constructs. | |
24691 | ||
24692 | @node C++ Interface | |
24693 | @section C++ Interface and Implementation Pragmas | |
24694 | ||
24695 | @cindex interface and implementation headers, C++ | |
24696 | @cindex C++ interface and implementation headers | |
24697 | @cindex pragmas, interface and implementation | |
24698 | ||
24699 | @code{#pragma interface} and @code{#pragma implementation} provide the | |
24700 | user with a way of explicitly directing the compiler to emit entities | |
24701 | with vague linkage (and debugging information) in a particular | |
24702 | translation unit. | |
24703 | ||
24704 | @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2 | |
24705 | by COMDAT support and the ``key method'' heuristic | |
24706 | mentioned in @ref{Vague Linkage}. Using them can actually cause your | |
24707 | program to grow due to unnecessary out-of-line copies of inline | |
24708 | functions. | |
24709 | ||
24710 | @table @code | |
f25efe50 | 24711 | @kindex #pragma interface |
d77de738 ML |
24712 | @item #pragma interface |
24713 | @itemx #pragma interface "@var{subdir}/@var{objects}.h" | |
d77de738 ML |
24714 | Use this directive in @emph{header files} that define object classes, to save |
24715 | space in most of the object files that use those classes. Normally, | |
24716 | local copies of certain information (backup copies of inline member | |
24717 | functions, debugging information, and the internal tables that implement | |
24718 | virtual functions) must be kept in each object file that includes class | |
24719 | definitions. You can use this pragma to avoid such duplication. When a | |
24720 | header file containing @samp{#pragma interface} is included in a | |
24721 | compilation, this auxiliary information is not generated (unless | |
24722 | the main input source file itself uses @samp{#pragma implementation}). | |
24723 | Instead, the object files contain references to be resolved at link | |
24724 | time. | |
24725 | ||
24726 | The second form of this directive is useful for the case where you have | |
24727 | multiple headers with the same name in different directories. If you | |
24728 | use this form, you must specify the same string to @samp{#pragma | |
24729 | implementation}. | |
24730 | ||
f25efe50 | 24731 | @kindex #pragma implementation |
d77de738 ML |
24732 | @item #pragma implementation |
24733 | @itemx #pragma implementation "@var{objects}.h" | |
d77de738 ML |
24734 | Use this pragma in a @emph{main input file}, when you want full output from |
24735 | included header files to be generated (and made globally visible). The | |
24736 | included header file, in turn, should use @samp{#pragma interface}. | |
24737 | Backup copies of inline member functions, debugging information, and the | |
24738 | internal tables used to implement virtual functions are all generated in | |
24739 | implementation files. | |
24740 | ||
24741 | @cindex implied @code{#pragma implementation} | |
24742 | @cindex @code{#pragma implementation}, implied | |
24743 | @cindex naming convention, implementation headers | |
24744 | If you use @samp{#pragma implementation} with no argument, it applies to | |
24745 | an include file with the same basename@footnote{A file's @dfn{basename} | |
24746 | is the name stripped of all leading path information and of trailing | |
24747 | suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source | |
24748 | file. For example, in @file{allclass.cc}, giving just | |
24749 | @samp{#pragma implementation} | |
24750 | by itself is equivalent to @samp{#pragma implementation "allclass.h"}. | |
24751 | ||
24752 | Use the string argument if you want a single implementation file to | |
24753 | include code from multiple header files. (You must also use | |
24754 | @samp{#include} to include the header file; @samp{#pragma | |
24755 | implementation} only specifies how to use the file---it doesn't actually | |
24756 | include it.) | |
24757 | ||
24758 | There is no way to split up the contents of a single header file into | |
24759 | multiple implementation files. | |
24760 | @end table | |
24761 | ||
24762 | @cindex inlining and C++ pragmas | |
24763 | @cindex C++ pragmas, effect on inlining | |
24764 | @cindex pragmas in C++, effect on inlining | |
24765 | @samp{#pragma implementation} and @samp{#pragma interface} also have an | |
24766 | effect on function inlining. | |
24767 | ||
24768 | If you define a class in a header file marked with @samp{#pragma | |
24769 | interface}, the effect on an inline function defined in that class is | |
24770 | similar to an explicit @code{extern} declaration---the compiler emits | |
24771 | no code at all to define an independent version of the function. Its | |
24772 | definition is used only for inlining with its callers. | |
24773 | ||
24774 | @opindex fno-implement-inlines | |
24775 | Conversely, when you include the same header file in a main source file | |
24776 | that declares it as @samp{#pragma implementation}, the compiler emits | |
24777 | code for the function itself; this defines a version of the function | |
24778 | that can be found via pointers (or by callers compiled without | |
24779 | inlining). If all calls to the function can be inlined, you can avoid | |
24780 | emitting the function by compiling with @option{-fno-implement-inlines}. | |
24781 | If any calls are not inlined, you will get linker errors. | |
24782 | ||
24783 | @node Template Instantiation | |
24784 | @section Where's the Template? | |
24785 | @cindex template instantiation | |
24786 | ||
24787 | C++ templates were the first language feature to require more | |
24788 | intelligence from the environment than was traditionally found on a UNIX | |
24789 | system. Somehow the compiler and linker have to make sure that each | |
24790 | template instance occurs exactly once in the executable if it is needed, | |
24791 | and not at all otherwise. There are two basic approaches to this | |
24792 | problem, which are referred to as the Borland model and the Cfront model. | |
24793 | ||
24794 | @table @asis | |
24795 | @item Borland model | |
24796 | Borland C++ solved the template instantiation problem by adding the code | |
24797 | equivalent of common blocks to their linker; the compiler emits template | |
24798 | instances in each translation unit that uses them, and the linker | |
24799 | collapses them together. The advantage of this model is that the linker | |
24800 | only has to consider the object files themselves; there is no external | |
24801 | complexity to worry about. The disadvantage is that compilation time | |
24802 | is increased because the template code is being compiled repeatedly. | |
24803 | Code written for this model tends to include definitions of all | |
24804 | templates in the header file, since they must be seen to be | |
24805 | instantiated. | |
24806 | ||
24807 | @item Cfront model | |
24808 | The AT&T C++ translator, Cfront, solved the template instantiation | |
24809 | problem by creating the notion of a template repository, an | |
24810 | automatically maintained place where template instances are stored. A | |
24811 | more modern version of the repository works as follows: As individual | |
24812 | object files are built, the compiler places any template definitions and | |
24813 | instantiations encountered in the repository. At link time, the link | |
24814 | wrapper adds in the objects in the repository and compiles any needed | |
24815 | instances that were not previously emitted. The advantages of this | |
24816 | model are more optimal compilation speed and the ability to use the | |
24817 | system linker; to implement the Borland model a compiler vendor also | |
24818 | needs to replace the linker. The disadvantages are vastly increased | |
24819 | complexity, and thus potential for error; for some code this can be | |
24820 | just as transparent, but in practice it can been very difficult to build | |
24821 | multiple programs in one directory and one program in multiple | |
24822 | directories. Code written for this model tends to separate definitions | |
24823 | of non-inline member templates into a separate file, which should be | |
24824 | compiled separately. | |
24825 | @end table | |
24826 | ||
24827 | G++ implements the Borland model on targets where the linker supports it, | |
24828 | including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows. | |
24829 | Otherwise G++ implements neither automatic model. | |
24830 | ||
24831 | You have the following options for dealing with template instantiations: | |
24832 | ||
24833 | @enumerate | |
24834 | @item | |
24835 | Do nothing. Code written for the Borland model works fine, but | |
24836 | each translation unit contains instances of each of the templates it | |
24837 | uses. The duplicate instances will be discarded by the linker, but in | |
24838 | a large program, this can lead to an unacceptable amount of code | |
24839 | duplication in object files or shared libraries. | |
24840 | ||
24841 | Duplicate instances of a template can be avoided by defining an explicit | |
24842 | instantiation in one object file, and preventing the compiler from doing | |
24843 | implicit instantiations in any other object files by using an explicit | |
24844 | instantiation declaration, using the @code{extern template} syntax: | |
24845 | ||
24846 | @smallexample | |
24847 | extern template int max (int, int); | |
24848 | @end smallexample | |
24849 | ||
24850 | This syntax is defined in the C++ 2011 standard, but has been supported by | |
24851 | G++ and other compilers since well before 2011. | |
24852 | ||
24853 | Explicit instantiations can be used for the largest or most frequently | |
24854 | duplicated instances, without having to know exactly which other instances | |
24855 | are used in the rest of the program. You can scatter the explicit | |
24856 | instantiations throughout your program, perhaps putting them in the | |
24857 | translation units where the instances are used or the translation units | |
24858 | that define the templates themselves; you can put all of the explicit | |
24859 | instantiations you need into one big file; or you can create small files | |
24860 | like | |
24861 | ||
24862 | @smallexample | |
24863 | #include "Foo.h" | |
24864 | #include "Foo.cc" | |
24865 | ||
24866 | template class Foo<int>; | |
24867 | template ostream& operator << | |
24868 | (ostream&, const Foo<int>&); | |
24869 | @end smallexample | |
24870 | ||
24871 | @noindent | |
24872 | for each of the instances you need, and create a template instantiation | |
24873 | library from those. | |
24874 | ||
24875 | This is the simplest option, but also offers flexibility and | |
24876 | fine-grained control when necessary. It is also the most portable | |
24877 | alternative and programs using this approach will work with most modern | |
24878 | compilers. | |
24879 | ||
24880 | @item | |
24881 | @opindex fno-implicit-templates | |
24882 | Compile your code with @option{-fno-implicit-templates} to disable the | |
24883 | implicit generation of template instances, and explicitly instantiate | |
24884 | all the ones you use. This approach requires more knowledge of exactly | |
24885 | which instances you need than do the others, but it's less | |
24886 | mysterious and allows greater control if you want to ensure that only | |
24887 | the intended instances are used. | |
24888 | ||
24889 | If you are using Cfront-model code, you can probably get away with not | |
24890 | using @option{-fno-implicit-templates} when compiling files that don't | |
24891 | @samp{#include} the member template definitions. | |
24892 | ||
24893 | If you use one big file to do the instantiations, you may want to | |
24894 | compile it without @option{-fno-implicit-templates} so you get all of the | |
24895 | instances required by your explicit instantiations (but not by any | |
24896 | other files) without having to specify them as well. | |
24897 | ||
24898 | In addition to forward declaration of explicit instantiations | |
24899 | (with @code{extern}), G++ has extended the template instantiation | |
24900 | syntax to support instantiation of the compiler support data for a | |
24901 | template class (i.e.@: the vtable) without instantiating any of its | |
24902 | members (with @code{inline}), and instantiation of only the static data | |
24903 | members of a template class, without the support data or member | |
24904 | functions (with @code{static}): | |
24905 | ||
24906 | @smallexample | |
24907 | inline template class Foo<int>; | |
24908 | static template class Foo<int>; | |
24909 | @end smallexample | |
24910 | @end enumerate | |
24911 | ||
24912 | @node Bound member functions | |
24913 | @section Extracting the Function Pointer from a Bound Pointer to Member Function | |
24914 | @cindex pmf | |
24915 | @cindex pointer to member function | |
24916 | @cindex bound pointer to member function | |
24917 | ||
24918 | In C++, pointer to member functions (PMFs) are implemented using a wide | |
24919 | pointer of sorts to handle all the possible call mechanisms; the PMF | |
24920 | needs to store information about how to adjust the @samp{this} pointer, | |
24921 | and if the function pointed to is virtual, where to find the vtable, and | |
24922 | where in the vtable to look for the member function. If you are using | |
24923 | PMFs in an inner loop, you should really reconsider that decision. If | |
24924 | that is not an option, you can extract the pointer to the function that | |
24925 | would be called for a given object/PMF pair and call it directly inside | |
24926 | the inner loop, to save a bit of time. | |
24927 | ||
24928 | Note that you still pay the penalty for the call through a | |
24929 | function pointer; on most modern architectures, such a call defeats the | |
24930 | branch prediction features of the CPU@. This is also true of normal | |
24931 | virtual function calls. | |
24932 | ||
24933 | The syntax for this extension is | |
24934 | ||
24935 | @smallexample | |
24936 | extern A a; | |
24937 | extern int (A::*fp)(); | |
24938 | typedef int (*fptr)(A *); | |
24939 | ||
24940 | fptr p = (fptr)(a.*fp); | |
24941 | @end smallexample | |
24942 | ||
24943 | For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), | |
24944 | no object is needed to obtain the address of the function. They can be | |
24945 | converted to function pointers directly: | |
24946 | ||
24947 | @smallexample | |
24948 | fptr p1 = (fptr)(&A::foo); | |
24949 | @end smallexample | |
24950 | ||
24951 | @opindex Wno-pmf-conversions | |
24952 | You must specify @option{-Wno-pmf-conversions} to use this extension. | |
24953 | ||
24954 | @node C++ Attributes | |
24955 | @section C++-Specific Variable, Function, and Type Attributes | |
24956 | ||
24957 | Some attributes only make sense for C++ programs. | |
24958 | ||
24959 | @table @code | |
d77de738 ML |
24960 | @cindex @code{abi_tag} function attribute |
24961 | @cindex @code{abi_tag} variable attribute | |
24962 | @cindex @code{abi_tag} type attribute | |
f25efe50 | 24963 | @item abi_tag ("@var{tag}", ...) |
d77de738 ML |
24964 | The @code{abi_tag} attribute can be applied to a function, variable, or class |
24965 | declaration. It modifies the mangled name of the entity to | |
24966 | incorporate the tag name, in order to distinguish the function or | |
24967 | class from an earlier version with a different ABI; perhaps the class | |
24968 | has changed size, or the function has a different return type that is | |
24969 | not encoded in the mangled name. | |
24970 | ||
24971 | The attribute can also be applied to an inline namespace, but does not | |
24972 | affect the mangled name of the namespace; in this case it is only used | |
24973 | for @option{-Wabi-tag} warnings and automatic tagging of functions and | |
24974 | variables. Tagging inline namespaces is generally preferable to | |
24975 | tagging individual declarations, but the latter is sometimes | |
24976 | necessary, such as when only certain members of a class need to be | |
24977 | tagged. | |
24978 | ||
24979 | The argument can be a list of strings of arbitrary length. The | |
24980 | strings are sorted on output, so the order of the list is | |
24981 | unimportant. | |
24982 | ||
24983 | A redeclaration of an entity must not add new ABI tags, | |
24984 | since doing so would change the mangled name. | |
24985 | ||
24986 | The ABI tags apply to a name, so all instantiations and | |
24987 | specializations of a template have the same tags. The attribute will | |
24988 | be ignored if applied to an explicit specialization or instantiation. | |
24989 | ||
24990 | The @option{-Wabi-tag} flag enables a warning about a class which does | |
24991 | not have all the ABI tags used by its subobjects and virtual functions; for users with code | |
24992 | that needs to coexist with an earlier ABI, using this option can help | |
24993 | to find all affected types that need to be tagged. | |
24994 | ||
24995 | When a type involving an ABI tag is used as the type of a variable or | |
24996 | return type of a function where that tag is not already present in the | |
24997 | signature of the function, the tag is automatically applied to the | |
24998 | variable or function. @option{-Wabi-tag} also warns about this | |
24999 | situation; this warning can be avoided by explicitly tagging the | |
25000 | variable or function or moving it into a tagged inline namespace. | |
25001 | ||
d77de738 | 25002 | @cindex @code{init_priority} variable attribute |
f25efe50 | 25003 | @item init_priority (@var{priority}) |
d77de738 ML |
25004 | |
25005 | In Standard C++, objects defined at namespace scope are guaranteed to be | |
25006 | initialized in an order in strict accordance with that of their definitions | |
25007 | @emph{in a given translation unit}. No guarantee is made for initializations | |
25008 | across translation units. However, GNU C++ allows users to control the | |
25009 | order of initialization of objects defined at namespace scope with the | |
25010 | @code{init_priority} attribute by specifying a relative @var{priority}, | |
25011 | a constant integral expression currently bounded between 101 and 65535 | |
25012 | inclusive. Lower numbers indicate a higher priority. | |
25013 | ||
25014 | In the following example, @code{A} would normally be created before | |
25015 | @code{B}, but the @code{init_priority} attribute reverses that order: | |
25016 | ||
25017 | @smallexample | |
25018 | Some_Class A __attribute__ ((init_priority (2000))); | |
25019 | Some_Class B __attribute__ ((init_priority (543))); | |
25020 | @end smallexample | |
25021 | ||
25022 | @noindent | |
25023 | Note that the particular values of @var{priority} do not matter; only their | |
25024 | relative ordering. | |
25025 | ||
d77de738 | 25026 | @cindex @code{warn_unused} type attribute |
f25efe50 | 25027 | @item warn_unused |
d77de738 ML |
25028 | |
25029 | For C++ types with non-trivial constructors and/or destructors it is | |
25030 | impossible for the compiler to determine whether a variable of this | |
25031 | type is truly unused if it is not referenced. This type attribute | |
25032 | informs the compiler that variables of this type should be warned | |
25033 | about if they appear to be unused, just like variables of fundamental | |
25034 | types. | |
25035 | ||
25036 | This attribute is appropriate for types which just represent a value, | |
25037 | such as @code{std::string}; it is not appropriate for types which | |
25038 | control a resource, such as @code{std::lock_guard}. | |
25039 | ||
25040 | This attribute is also accepted in C, but it is unnecessary because C | |
25041 | does not have constructors or destructors. | |
25042 | ||
25043 | @end table | |
25044 | ||
25045 | @node Function Multiversioning | |
25046 | @section Function Multiversioning | |
25047 | @cindex function versions | |
25048 | ||
25049 | With the GNU C++ front end, for x86 targets, you may specify multiple | |
25050 | versions of a function, where each function is specialized for a | |
25051 | specific target feature. At runtime, the appropriate version of the | |
25052 | function is automatically executed depending on the characteristics of | |
25053 | the execution platform. Here is an example. | |
25054 | ||
25055 | @smallexample | |
25056 | __attribute__ ((target ("default"))) | |
25057 | int foo () | |
25058 | @{ | |
25059 | // The default version of foo. | |
25060 | return 0; | |
25061 | @} | |
25062 | ||
25063 | __attribute__ ((target ("sse4.2"))) | |
25064 | int foo () | |
25065 | @{ | |
25066 | // foo version for SSE4.2 | |
25067 | return 1; | |
25068 | @} | |
25069 | ||
25070 | __attribute__ ((target ("arch=atom"))) | |
25071 | int foo () | |
25072 | @{ | |
25073 | // foo version for the Intel ATOM processor | |
25074 | return 2; | |
25075 | @} | |
25076 | ||
25077 | __attribute__ ((target ("arch=amdfam10"))) | |
25078 | int foo () | |
25079 | @{ | |
25080 | // foo version for the AMD Family 0x10 processors. | |
25081 | return 3; | |
25082 | @} | |
25083 | ||
25084 | int main () | |
25085 | @{ | |
25086 | int (*p)() = &foo; | |
25087 | assert ((*p) () == foo ()); | |
25088 | return 0; | |
25089 | @} | |
25090 | @end smallexample | |
25091 | ||
25092 | In the above example, four versions of function foo are created. The | |
25093 | first version of foo with the target attribute "default" is the default | |
25094 | version. This version gets executed when no other target specific | |
25095 | version qualifies for execution on a particular platform. A new version | |
25096 | of foo is created by using the same function signature but with a | |
25097 | different target string. Function foo is called or a pointer to it is | |
25098 | taken just like a regular function. GCC takes care of doing the | |
25099 | dispatching to call the right version at runtime. Refer to the | |
25100 | @uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on | |
25101 | Function Multiversioning} for more details. | |
25102 | ||
25103 | @node Type Traits | |
25104 | @section Type Traits | |
25105 | ||
25106 | The C++ front end implements syntactic extensions that allow | |
25107 | compile-time determination of | |
25108 | various characteristics of a type (or of a | |
25109 | pair of types). | |
25110 | ||
f25efe50 AA |
25111 | @defbuiltin{bool __has_nothrow_assign (@var{type})} |
25112 | If @var{type} is @code{const}-qualified or is a reference type then | |
d77de738 | 25113 | the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)} |
f25efe50 | 25114 | is @code{true} then the trait is @code{true}, else if @var{type} is |
d77de738 ML |
25115 | a cv-qualified class or union type with copy assignment operators that are |
25116 | known not to throw an exception then the trait is @code{true}, else it is | |
25117 | @code{false}. | |
f25efe50 | 25118 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 25119 | @code{void}, or an array of unknown bound. |
f25efe50 | 25120 | @enddefbuiltin |
d77de738 | 25121 | |
f25efe50 | 25122 | @defbuiltin{bool __has_nothrow_copy (@var{type})} |
d77de738 | 25123 | If @code{__has_trivial_copy (type)} is @code{true} then the trait is |
f25efe50 | 25124 | @code{true}, else if @var{type} is a cv-qualified class or union type |
d77de738 ML |
25125 | with copy constructors that are known not to throw an exception then |
25126 | the trait is @code{true}, else it is @code{false}. | |
f25efe50 | 25127 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 25128 | @code{void}, or an array of unknown bound. |
f25efe50 | 25129 | @enddefbuiltin |
d77de738 | 25130 | |
f25efe50 | 25131 | @defbuiltin{bool __has_nothrow_constructor (@var{type})} |
d77de738 | 25132 | If @code{__has_trivial_constructor (type)} is @code{true} then the trait |
f25efe50 | 25133 | is @code{true}, else if @var{type} is a cv class or union type (or array |
d77de738 ML |
25134 | thereof) with a default constructor that is known not to throw an |
25135 | exception then the trait is @code{true}, else it is @code{false}. | |
f25efe50 | 25136 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 25137 | @code{void}, or an array of unknown bound. |
f25efe50 | 25138 | @enddefbuiltin |
d77de738 | 25139 | |
f25efe50 AA |
25140 | @defbuiltin{bool __has_trivial_assign (@var{type})} |
25141 | If @var{type} is @code{const}- qualified or is a reference type then | |
d77de738 | 25142 | the trait is @code{false}. Otherwise if @code{__is_trivial (type)} is |
f25efe50 | 25143 | @code{true} then the trait is @code{true}, else if @var{type} is |
d77de738 ML |
25144 | a cv-qualified class or union type with a trivial copy assignment |
25145 | ([class.copy]) then the trait is @code{true}, else it is @code{false}. | |
f25efe50 | 25146 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 25147 | @code{void}, or an array of unknown bound. |
f25efe50 | 25148 | @enddefbuiltin |
d77de738 | 25149 | |
f25efe50 AA |
25150 | @defbuiltin{bool __has_trivial_copy (@var{type})} |
25151 | If @code{__is_trivial (type)} is @code{true} or @var{type} is a reference | |
25152 | type then the trait is @code{true}, else if @var{type} is a cv class | |
d77de738 | 25153 | or union type with a trivial copy constructor ([class.copy]) then the trait |
f25efe50 | 25154 | is @code{true}, else it is @code{false}. Requires: @var{type} shall be |
d77de738 ML |
25155 | a complete type, (possibly cv-qualified) @code{void}, or an array of unknown |
25156 | bound. | |
f25efe50 | 25157 | @enddefbuiltin |
d77de738 | 25158 | |
f25efe50 | 25159 | @defbuiltin{bool __has_trivial_constructor (@var{type})} |
d77de738 | 25160 | If @code{__is_trivial (type)} is @code{true} then the trait is @code{true}, |
f25efe50 | 25161 | else if @var{type} is a cv-qualified class or union type (or array thereof) |
d77de738 ML |
25162 | with a trivial default constructor ([class.ctor]) then the trait is @code{true}, |
25163 | else it is @code{false}. | |
f25efe50 | 25164 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 25165 | @code{void}, or an array of unknown bound. |
f25efe50 | 25166 | @enddefbuiltin |
d77de738 | 25167 | |
f25efe50 AA |
25168 | @defbuiltin{bool __has_trivial_destructor (@var{type})} |
25169 | If @code{__is_trivial (type)} is @code{true} or @var{type} is a reference type | |
25170 | then the trait is @code{true}, else if @var{type} is a cv class or union | |
d77de738 ML |
25171 | type (or array thereof) with a trivial destructor ([class.dtor]) then |
25172 | the trait is @code{true}, else it is @code{false}. | |
f25efe50 | 25173 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 25174 | @code{void}, or an array of unknown bound. |
f25efe50 | 25175 | @enddefbuiltin |
d77de738 | 25176 | |
f25efe50 AA |
25177 | @defbuiltin{bool __has_virtual_destructor (@var{type})} |
25178 | If @var{type} is a class type with a virtual destructor | |
d77de738 | 25179 | ([class.dtor]) then the trait is @code{true}, else it is @code{false}. |
f25efe50 AA |
25180 | Requires: If @var{type} is a non-union class type, it shall be a complete type. |
25181 | @enddefbuiltin | |
d77de738 | 25182 | |
f25efe50 AA |
25183 | @defbuiltin{bool __is_abstract (@var{type})} |
25184 | If @var{type} is an abstract class ([class.abstract]) then the trait | |
d77de738 | 25185 | is @code{true}, else it is @code{false}. |
f25efe50 AA |
25186 | Requires: If @var{type} is a non-union class type, it shall be a complete type. |
25187 | @enddefbuiltin | |
d77de738 | 25188 | |
f25efe50 AA |
25189 | @defbuiltin{bool __is_aggregate (@var{type})} |
25190 | If @var{type} is an aggregate type ([dcl.init.aggr]) the trait is | |
d77de738 | 25191 | @code{true}, else it is @code{false}. |
f25efe50 AA |
25192 | Requires: If @var{type} is a class type, it shall be a complete type. |
25193 | @enddefbuiltin | |
d77de738 | 25194 | |
f25efe50 AA |
25195 | @defbuiltin{bool __is_base_of (@var{base_type}, @var{derived_type})} |
25196 | If @var{base_type} is a base class of @var{derived_type} | |
d77de738 | 25197 | ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}. |
f25efe50 AA |
25198 | Top-level cv-qualifications of @var{base_type} and |
25199 | @var{derived_type} are ignored. For the purposes of this trait, a | |
d77de738 ML |
25200 | class type is considered is own base. |
25201 | Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)} | |
f25efe50 AA |
25202 | are @code{true} and @var{base_type} and @var{derived_type} are not the same |
25203 | type (disregarding cv-qualifiers), @var{derived_type} shall be a complete | |
d77de738 | 25204 | type. A diagnostic is produced if this requirement is not met. |
f25efe50 | 25205 | @enddefbuiltin |
d77de738 | 25206 | |
f25efe50 AA |
25207 | @defbuiltin{bool __is_class (@var{type})} |
25208 | If @var{type} is a cv-qualified class type, and not a union type | |
d77de738 | 25209 | ([basic.compound]) the trait is @code{true}, else it is @code{false}. |
f25efe50 | 25210 | @enddefbuiltin |
d77de738 | 25211 | |
30556bf8 | 25212 | @c FIXME Commented out for GCC 13, discuss user interface for GCC 14. |
f25efe50 | 25213 | @c @defbuiltin{bool __is_deducible (@var{template}, @var{type})} |
30556bf8 JM |
25214 | @c If template arguments for @code{template} can be deduced from |
25215 | @c @code{type} or obtained from default template arguments. | |
f25efe50 | 25216 | @c @enddefbuiltin |
148cbb15 | 25217 | |
f25efe50 | 25218 | @defbuiltin{bool __is_empty (@var{type})} |
d77de738 | 25219 | If @code{__is_class (type)} is @code{false} then the trait is @code{false}. |
f25efe50 | 25220 | Otherwise @var{type} is considered empty if and only if: @var{type} |
d77de738 | 25221 | has no non-static data members, or all non-static data members, if |
f25efe50 AA |
25222 | any, are bit-fields of length 0, and @var{type} has no virtual |
25223 | members, and @var{type} has no virtual base classes, and @var{type} | |
25224 | has no base classes @var{base_type} for which | |
d77de738 | 25225 | @code{__is_empty (base_type)} is @code{false}. |
f25efe50 AA |
25226 | Requires: If @var{type} is a non-union class type, it shall be a complete type. |
25227 | @enddefbuiltin | |
d77de738 | 25228 | |
f25efe50 AA |
25229 | @defbuiltin{bool __is_enum (@var{type})} |
25230 | If @var{type} is a cv enumeration type ([basic.compound]) the trait is | |
d77de738 | 25231 | @code{true}, else it is @code{false}. |
f25efe50 | 25232 | @enddefbuiltin |
d77de738 | 25233 | |
f25efe50 AA |
25234 | @defbuiltin{bool __is_final (@var{type})} |
25235 | If @var{type} is a class or union type marked @code{final}, then the trait | |
d77de738 | 25236 | is @code{true}, else it is @code{false}. |
f25efe50 AA |
25237 | Requires: If @var{type} is a class type, it shall be a complete type. |
25238 | @enddefbuiltin | |
d77de738 | 25239 | |
f25efe50 AA |
25240 | @defbuiltin{bool __is_literal_type (@var{type})} |
25241 | If @var{type} is a literal type ([basic.types]) the trait is | |
d77de738 | 25242 | @code{true}, else it is @code{false}. |
f25efe50 | 25243 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 25244 | @code{void}, or an array of unknown bound. |
f25efe50 | 25245 | @enddefbuiltin |
d77de738 | 25246 | |
f25efe50 AA |
25247 | @defbuiltin{bool __is_pod (@var{type})} |
25248 | If @var{type} is a cv POD type ([basic.types]) then the trait is @code{true}, | |
d77de738 | 25249 | else it is @code{false}. |
f25efe50 | 25250 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 25251 | @code{void}, or an array of unknown bound. |
f25efe50 | 25252 | @enddefbuiltin |
d77de738 | 25253 | |
f25efe50 AA |
25254 | @defbuiltin{bool __is_polymorphic (@var{type})} |
25255 | If @var{type} is a polymorphic class ([class.virtual]) then the trait | |
d77de738 | 25256 | is @code{true}, else it is @code{false}. |
f25efe50 AA |
25257 | Requires: If @var{type} is a non-union class type, it shall be a complete type. |
25258 | @enddefbuiltin | |
d77de738 | 25259 | |
f25efe50 AA |
25260 | @defbuiltin{bool __is_standard_layout (@var{type})} |
25261 | If @var{type} is a standard-layout type ([basic.types]) the trait is | |
d77de738 | 25262 | @code{true}, else it is @code{false}. |
f25efe50 | 25263 | Requires: @var{type} shall be a complete type, an array of complete types, |
d77de738 | 25264 | or (possibly cv-qualified) @code{void}. |
f25efe50 | 25265 | @enddefbuiltin |
d77de738 | 25266 | |
f25efe50 AA |
25267 | @defbuiltin{bool __is_trivial (@var{type})} |
25268 | If @var{type} is a trivial type ([basic.types]) the trait is | |
d77de738 | 25269 | @code{true}, else it is @code{false}. |
f25efe50 | 25270 | Requires: @var{type} shall be a complete type, an array of complete types, |
d77de738 | 25271 | or (possibly cv-qualified) @code{void}. |
f25efe50 | 25272 | @enddefbuiltin |
d77de738 | 25273 | |
f25efe50 AA |
25274 | @defbuiltin{bool __is_union (@var{type})} |
25275 | If @var{type} is a cv union type ([basic.compound]) the trait is | |
d77de738 | 25276 | @code{true}, else it is @code{false}. |
f25efe50 | 25277 | @enddefbuiltin |
d77de738 | 25278 | |
f25efe50 AA |
25279 | @defbuiltin{bool __underlying_type (@var{type})} |
25280 | The underlying type of @var{type}. | |
25281 | Requires: @var{type} shall be an enumeration type ([dcl.enum]). | |
25282 | @enddefbuiltin | |
d77de738 | 25283 | |
f25efe50 | 25284 | @defbuiltin{bool __integer_pack (@var{length})} |
d77de738 ML |
25285 | When used as the pattern of a pack expansion within a template |
25286 | definition, expands to a template argument pack containing integers | |
f25efe50 AA |
25287 | from @code{0} to @code{@var{length}-1}. This is provided for |
25288 | efficient implementation of @code{std::make_integer_sequence}. | |
25289 | @enddefbuiltin | |
d77de738 ML |
25290 | |
25291 | ||
25292 | @node C++ Concepts | |
25293 | @section C++ Concepts | |
25294 | ||
25295 | C++ concepts provide much-improved support for generic programming. In | |
25296 | particular, they allow the specification of constraints on template arguments. | |
25297 | The constraints are used to extend the usual overloading and partial | |
25298 | specialization capabilities of the language, allowing generic data structures | |
25299 | and algorithms to be ``refined'' based on their properties rather than their | |
25300 | type names. | |
25301 | ||
25302 | The following keywords are reserved for concepts. | |
25303 | ||
25304 | @table @code | |
f25efe50 | 25305 | @kindex assumes |
d77de738 ML |
25306 | @item assumes |
25307 | States an expression as an assumption, and if possible, verifies that the | |
25308 | assumption is valid. For example, @code{assume(n > 0)}. | |
25309 | ||
f25efe50 | 25310 | @kindex axiom |
d77de738 ML |
25311 | @item axiom |
25312 | Introduces an axiom definition. Axioms introduce requirements on values. | |
25313 | ||
f25efe50 | 25314 | @kindex axiom |
d77de738 ML |
25315 | @item forall |
25316 | Introduces a universally quantified object in an axiom. For example, | |
25317 | @code{forall (int n) n + 0 == n}). | |
25318 | ||
f25efe50 | 25319 | @kindex axiom |
d77de738 ML |
25320 | @item concept |
25321 | Introduces a concept definition. Concepts are sets of syntactic and semantic | |
25322 | requirements on types and their values. | |
25323 | ||
f25efe50 | 25324 | @kindex requires |
d77de738 ML |
25325 | @item requires |
25326 | Introduces constraints on template arguments or requirements for a member | |
25327 | function of a class template. | |
d77de738 ML |
25328 | @end table |
25329 | ||
25330 | The front end also exposes a number of internal mechanism that can be used | |
25331 | to simplify the writing of type traits. Note that some of these traits are | |
25332 | likely to be removed in the future. | |
25333 | ||
f25efe50 AA |
25334 | @defbuiltin{bool __is_same (@var{type1}, @var{type2})} |
25335 | A binary type trait: @code{true} whenever the @var{type1} and | |
25336 | @var{type2} refer to the same type. | |
25337 | @enddefbuiltin | |
d77de738 ML |
25338 | |
25339 | ||
25340 | @node Deprecated Features | |
25341 | @section Deprecated Features | |
25342 | ||
25343 | In the past, the GNU C++ compiler was extended to experiment with new | |
25344 | features, at a time when the C++ language was still evolving. Now that | |
25345 | the C++ standard is complete, some of those features are superseded by | |
25346 | superior alternatives. Using the old features might cause a warning in | |
25347 | some cases that the feature will be dropped in the future. In other | |
25348 | cases, the feature might be gone already. | |
25349 | ||
25350 | G++ allows a virtual function returning @samp{void *} to be overridden | |
25351 | by one returning a different pointer type. This extension to the | |
25352 | covariant return type rules is now deprecated and will be removed from a | |
25353 | future version. | |
25354 | ||
25355 | The use of default arguments in function pointers, function typedefs | |
25356 | and other places where they are not permitted by the standard is | |
25357 | deprecated and will be removed from a future version of G++. | |
25358 | ||
25359 | G++ allows floating-point literals to appear in integral constant expressions, | |
25360 | e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} } | |
25361 | This extension is deprecated and will be removed from a future version. | |
25362 | ||
25363 | G++ allows static data members of const floating-point type to be declared | |
25364 | with an initializer in a class definition. The standard only allows | |
25365 | initializers for static members of const integral types and const | |
25366 | enumeration types so this extension has been deprecated and will be removed | |
25367 | from a future version. | |
25368 | ||
25369 | G++ allows attributes to follow a parenthesized direct initializer, | |
25370 | e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension | |
25371 | has been ignored since G++ 3.3 and is deprecated. | |
25372 | ||
25373 | G++ allows anonymous structs and unions to have members that are not | |
25374 | public non-static data members (i.e.@: fields). These extensions are | |
25375 | deprecated. | |
25376 | ||
25377 | @node Backwards Compatibility | |
25378 | @section Backwards Compatibility | |
25379 | @cindex Backwards Compatibility | |
25380 | @cindex ARM [Annotated C++ Reference Manual] | |
25381 | ||
25382 | Now that there is a definitive ISO standard C++, G++ has a specification | |
25383 | to adhere to. The C++ language evolved over time, and features that | |
25384 | used to be acceptable in previous drafts of the standard, such as the ARM | |
25385 | [Annotated C++ Reference Manual], are no longer accepted. In order to allow | |
25386 | compilation of C++ written to such drafts, G++ contains some backwards | |
25387 | compatibilities. @emph{All such backwards compatibility features are | |
25388 | liable to disappear in future versions of G++.} They should be considered | |
25389 | deprecated. @xref{Deprecated Features}. | |
25390 | ||
25391 | @table @code | |
25392 | ||
25393 | @item Implicit C language | |
25394 | Old C system header files did not contain an @code{extern "C" @{@dots{}@}} | |
25395 | scope to set the language. On such systems, all system header files are | |
25396 | implicitly scoped inside a C language scope. Such headers must | |
25397 | correctly prototype function argument types, there is no leeway for | |
25398 | @code{()} to indicate an unspecified set of arguments. | |
25399 | ||
25400 | @end table | |
25401 | ||
25402 | @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd | |
25403 | @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr |