]>
Commit | Line | Data |
---|---|---|
a945c346 | 1 | @c Copyright (C) 1988-2024 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. | |
f0a90c7d | 80 | * Stack Scrubbing:: Stack scrubbing internal interfaces. |
d77de738 ML |
81 | * Vector Extensions:: Using vector instructions through built-in functions. |
82 | * Offsetof:: Special syntax for implementing @code{offsetof}. | |
83 | * __sync Builtins:: Legacy built-in functions for atomic memory access. | |
84 | * __atomic Builtins:: Atomic built-in functions with memory model. | |
85 | * Integer Overflow Builtins:: Built-in functions to perform arithmetics and | |
86 | arithmetic overflow checking. | |
87 | * x86 specific memory model extensions for transactional memory:: x86 memory models. | |
88 | * Object Size Checking:: Built-in functions for limited buffer overflow | |
89 | checking. | |
90 | * Other Builtins:: Other built-in functions. | |
91 | * Target Builtins:: Built-in functions specific to particular targets. | |
92 | * Target Format Checks:: Format checks specific to particular targets. | |
93 | * Pragmas:: Pragmas accepted by GCC. | |
94 | * Unnamed Fields:: Unnamed struct/union fields within structs/unions. | |
95 | * Thread-Local:: Per-thread variables. | |
96 | * Binary constants:: Binary constants using the @samp{0b} prefix. | |
97 | @end menu | |
98 | ||
99 | @node Statement Exprs | |
100 | @section Statements and Declarations in Expressions | |
101 | @cindex statements inside expressions | |
102 | @cindex declarations inside expressions | |
103 | @cindex expressions containing statements | |
104 | @cindex macros, statements in expressions | |
105 | ||
106 | @c the above section title wrapped and causes an underfull hbox.. i | |
107 | @c changed it from "within" to "in". --mew 4feb93 | |
108 | A compound statement enclosed in parentheses may appear as an expression | |
109 | in GNU C@. This allows you to use loops, switches, and local variables | |
110 | within an expression. | |
111 | ||
112 | Recall that a compound statement is a sequence of statements surrounded | |
113 | by braces; in this construct, parentheses go around the braces. For | |
114 | example: | |
115 | ||
116 | @smallexample | |
117 | (@{ int y = foo (); int z; | |
118 | if (y > 0) z = y; | |
119 | else z = - y; | |
120 | z; @}) | |
121 | @end smallexample | |
122 | ||
123 | @noindent | |
124 | is a valid (though slightly more complex than necessary) expression | |
125 | for the absolute value of @code{foo ()}. | |
126 | ||
127 | The last thing in the compound statement should be an expression | |
128 | followed by a semicolon; the value of this subexpression serves as the | |
129 | value of the entire construct. (If you use some other kind of statement | |
130 | last within the braces, the construct has type @code{void}, and thus | |
131 | effectively no value.) | |
132 | ||
133 | This feature is especially useful in making macro definitions ``safe'' (so | |
134 | that they evaluate each operand exactly once). For example, the | |
135 | ``maximum'' function is commonly defined as a macro in standard C as | |
136 | follows: | |
137 | ||
138 | @smallexample | |
139 | #define max(a,b) ((a) > (b) ? (a) : (b)) | |
140 | @end smallexample | |
141 | ||
142 | @noindent | |
143 | @cindex side effects, macro argument | |
144 | But this definition computes either @var{a} or @var{b} twice, with bad | |
145 | results if the operand has side effects. In GNU C, if you know the | |
146 | type of the operands (here taken as @code{int}), you can avoid this | |
147 | problem by defining the macro as follows: | |
148 | ||
149 | @smallexample | |
150 | #define maxint(a,b) \ | |
151 | (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) | |
152 | @end smallexample | |
153 | ||
154 | Note that introducing variable declarations (as we do in @code{maxint}) can | |
155 | cause variable shadowing, so while this example using the @code{max} macro | |
156 | produces correct results: | |
157 | @smallexample | |
158 | int _a = 1, _b = 2, c; | |
159 | c = max (_a, _b); | |
160 | @end smallexample | |
161 | @noindent | |
162 | this example using maxint will not: | |
163 | @smallexample | |
164 | int _a = 1, _b = 2, c; | |
165 | c = maxint (_a, _b); | |
166 | @end smallexample | |
167 | ||
168 | This problem may for instance occur when we use this pattern recursively, like | |
169 | so: | |
170 | ||
171 | @smallexample | |
172 | #define maxint3(a, b, c) \ | |
173 | (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @}) | |
174 | @end smallexample | |
175 | ||
176 | Embedded statements are not allowed in constant expressions, such as | |
177 | the value of an enumeration constant, the width of a bit-field, or | |
178 | the initial value of a static variable. | |
179 | ||
180 | If you don't know the type of the operand, you can still do this, but you | |
181 | must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}). | |
182 | ||
183 | In G++, the result value of a statement expression undergoes array and | |
184 | function pointer decay, and is returned by value to the enclosing | |
185 | expression. For instance, if @code{A} is a class, then | |
186 | ||
187 | @smallexample | |
188 | A a; | |
189 | ||
190 | (@{a;@}).Foo () | |
191 | @end smallexample | |
192 | ||
193 | @noindent | |
194 | constructs a temporary @code{A} object to hold the result of the | |
195 | statement expression, and that is used to invoke @code{Foo}. | |
196 | Therefore the @code{this} pointer observed by @code{Foo} is not the | |
197 | address of @code{a}. | |
198 | ||
199 | In a statement expression, any temporaries created within a statement | |
200 | are destroyed at that statement's end. This makes statement | |
201 | expressions inside macros slightly different from function calls. In | |
202 | the latter case temporaries introduced during argument evaluation are | |
203 | destroyed at the end of the statement that includes the function | |
204 | call. In the statement expression case they are destroyed during | |
205 | the statement expression. For instance, | |
206 | ||
207 | @smallexample | |
208 | #define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) | |
209 | template<typename T> T function(T a) @{ T b = a; return b + 3; @} | |
210 | ||
211 | void foo () | |
212 | @{ | |
213 | macro (X ()); | |
214 | function (X ()); | |
215 | @} | |
216 | @end smallexample | |
217 | ||
218 | @noindent | |
219 | has different places where temporaries are destroyed. For the | |
220 | @code{macro} case, the temporary @code{X} is destroyed just after | |
221 | the initialization of @code{b}. In the @code{function} case that | |
222 | temporary is destroyed when the function returns. | |
223 | ||
224 | These considerations mean that it is probably a bad idea to use | |
225 | statement expressions of this form in header files that are designed to | |
226 | work with C++. (Note that some versions of the GNU C Library contained | |
227 | header files using statement expressions that lead to precisely this | |
228 | bug.) | |
229 | ||
230 | Jumping into a statement expression with @code{goto} or using a | |
231 | @code{switch} statement outside the statement expression with a | |
232 | @code{case} or @code{default} label inside the statement expression is | |
233 | not permitted. Jumping into a statement expression with a computed | |
234 | @code{goto} (@pxref{Labels as Values}) has undefined behavior. | |
235 | Jumping out of a statement expression is permitted, but if the | |
236 | statement expression is part of a larger expression then it is | |
237 | unspecified which other subexpressions of that expression have been | |
238 | evaluated except where the language definition requires certain | |
239 | subexpressions to be evaluated before or after the statement | |
240 | expression. A @code{break} or @code{continue} statement inside of | |
241 | a statement expression used in @code{while}, @code{do} or @code{for} | |
242 | loop or @code{switch} statement condition | |
243 | or @code{for} statement init or increment expressions jumps to an | |
244 | outer loop or @code{switch} statement if any (otherwise it is an error), | |
245 | rather than to the loop or @code{switch} statement in whose condition | |
246 | or init or increment expression it appears. | |
247 | In any case, as with a function call, the evaluation of a | |
248 | statement expression is not interleaved with the evaluation of other | |
249 | parts of the containing expression. For example, | |
250 | ||
251 | @smallexample | |
252 | foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); | |
253 | @end smallexample | |
254 | ||
255 | @noindent | |
256 | calls @code{foo} and @code{bar1} and does not call @code{baz} but | |
257 | may or may not call @code{bar2}. If @code{bar2} is called, it is | |
258 | called after @code{foo} and before @code{bar1}. | |
259 | ||
260 | @node Local Labels | |
261 | @section Locally Declared Labels | |
262 | @cindex local labels | |
263 | @cindex macros, local labels | |
264 | ||
265 | GCC allows you to declare @dfn{local labels} in any nested block | |
266 | scope. A local label is just like an ordinary label, but you can | |
267 | only reference it (with a @code{goto} statement, or by taking its | |
268 | address) within the block in which it is declared. | |
269 | ||
270 | A local label declaration looks like this: | |
271 | ||
272 | @smallexample | |
273 | __label__ @var{label}; | |
274 | @end smallexample | |
275 | ||
276 | @noindent | |
277 | or | |
278 | ||
279 | @smallexample | |
280 | __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; | |
281 | @end smallexample | |
282 | ||
283 | Local label declarations must come at the beginning of the block, | |
284 | before any ordinary declarations or statements. | |
285 | ||
286 | The label declaration defines the label @emph{name}, but does not define | |
287 | the label itself. You must do this in the usual way, with | |
288 | @code{@var{label}:}, within the statements of the statement expression. | |
289 | ||
290 | The local label feature is useful for complex macros. If a macro | |
291 | contains nested loops, a @code{goto} can be useful for breaking out of | |
292 | them. However, an ordinary label whose scope is the whole function | |
293 | cannot be used: if the macro can be expanded several times in one | |
294 | function, the label is multiply defined in that function. A | |
295 | local label avoids this problem. For example: | |
296 | ||
297 | @smallexample | |
298 | #define SEARCH(value, array, target) \ | |
299 | do @{ \ | |
300 | __label__ found; \ | |
301 | typeof (target) _SEARCH_target = (target); \ | |
302 | typeof (*(array)) *_SEARCH_array = (array); \ | |
303 | int i, j; \ | |
304 | int value; \ | |
305 | for (i = 0; i < max; i++) \ | |
306 | for (j = 0; j < max; j++) \ | |
307 | if (_SEARCH_array[i][j] == _SEARCH_target) \ | |
308 | @{ (value) = i; goto found; @} \ | |
309 | (value) = -1; \ | |
310 | found:; \ | |
311 | @} while (0) | |
312 | @end smallexample | |
313 | ||
314 | This could also be written using a statement expression: | |
315 | ||
316 | @smallexample | |
317 | #define SEARCH(array, target) \ | |
318 | (@{ \ | |
319 | __label__ found; \ | |
320 | typeof (target) _SEARCH_target = (target); \ | |
321 | typeof (*(array)) *_SEARCH_array = (array); \ | |
322 | int i, j; \ | |
323 | int value; \ | |
324 | for (i = 0; i < max; i++) \ | |
325 | for (j = 0; j < max; j++) \ | |
326 | if (_SEARCH_array[i][j] == _SEARCH_target) \ | |
327 | @{ value = i; goto found; @} \ | |
328 | value = -1; \ | |
329 | found: \ | |
330 | value; \ | |
331 | @}) | |
332 | @end smallexample | |
333 | ||
334 | Local label declarations also make the labels they declare visible to | |
335 | nested functions, if there are any. @xref{Nested Functions}, for details. | |
336 | ||
337 | @node Labels as Values | |
338 | @section Labels as Values | |
339 | @cindex labels as values | |
340 | @cindex computed gotos | |
341 | @cindex goto with computed label | |
342 | @cindex address of a label | |
343 | ||
344 | You can get the address of a label defined in the current function | |
345 | (or a containing function) with the unary operator @samp{&&}. The | |
346 | value has type @code{void *}. This value is a constant and can be used | |
347 | wherever a constant of that type is valid. For example: | |
348 | ||
349 | @smallexample | |
350 | void *ptr; | |
351 | /* @r{@dots{}} */ | |
352 | ptr = &&foo; | |
353 | @end smallexample | |
354 | ||
355 | To use these values, you need to be able to jump to one. This is done | |
356 | with the computed goto statement@footnote{The analogous feature in | |
357 | Fortran is called an assigned goto, but that name seems inappropriate in | |
358 | C, where one can do more than simply store label addresses in label | |
359 | variables.}, @code{goto *@var{exp};}. For example, | |
360 | ||
361 | @smallexample | |
362 | goto *ptr; | |
363 | @end smallexample | |
364 | ||
365 | @noindent | |
366 | Any expression of type @code{void *} is allowed. | |
367 | ||
368 | One way of using these constants is in initializing a static array that | |
369 | serves as a jump table: | |
370 | ||
371 | @smallexample | |
372 | static void *array[] = @{ &&foo, &&bar, &&hack @}; | |
373 | @end smallexample | |
374 | ||
375 | @noindent | |
376 | Then you can select a label with indexing, like this: | |
377 | ||
378 | @smallexample | |
379 | goto *array[i]; | |
380 | @end smallexample | |
381 | ||
382 | @noindent | |
383 | Note that this does not check whether the subscript is in bounds---array | |
384 | indexing in C never does that. | |
385 | ||
386 | Such an array of label values serves a purpose much like that of the | |
387 | @code{switch} statement. The @code{switch} statement is cleaner, so | |
388 | use that rather than an array unless the problem does not fit a | |
389 | @code{switch} statement very well. | |
390 | ||
391 | Another use of label values is in an interpreter for threaded code. | |
392 | The labels within the interpreter function can be stored in the | |
393 | threaded code for super-fast dispatching. | |
394 | ||
395 | You may not use this mechanism to jump to code in a different function. | |
396 | If you do that, totally unpredictable things happen. The best way to | |
397 | avoid this is to store the label address only in automatic variables and | |
398 | never pass it as an argument. | |
399 | ||
400 | An alternate way to write the above example is | |
401 | ||
402 | @smallexample | |
403 | static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, | |
404 | &&hack - &&foo @}; | |
405 | goto *(&&foo + array[i]); | |
406 | @end smallexample | |
407 | ||
408 | @noindent | |
409 | This is more friendly to code living in shared libraries, as it reduces | |
410 | the number of dynamic relocations that are needed, and by consequence, | |
411 | allows the data to be read-only. | |
412 | This alternative with label differences is not supported for the AVR target, | |
413 | please use the first approach for AVR programs. | |
414 | ||
415 | The @code{&&foo} expressions for the same label might have different | |
416 | values if the containing function is inlined or cloned. If a program | |
417 | relies on them being always the same, | |
418 | @code{__attribute__((__noinline__,__noclone__))} should be used to | |
419 | prevent inlining and cloning. If @code{&&foo} is used in a static | |
420 | variable initializer, inlining and cloning is forbidden. | |
421 | ||
4d9e0f3f JM |
422 | Unlike a normal goto, in GNU C++ a computed goto will not call |
423 | destructors for objects that go out of scope. | |
424 | ||
d77de738 ML |
425 | @node Nested Functions |
426 | @section Nested Functions | |
427 | @cindex nested functions | |
428 | @cindex downward funargs | |
429 | @cindex thunks | |
430 | ||
431 | A @dfn{nested function} is a function defined inside another function. | |
432 | Nested functions are supported as an extension in GNU C, but are not | |
433 | supported by GNU C++. | |
434 | ||
435 | The nested function's name is local to the block where it is defined. | |
436 | For example, here we define a nested function named @code{square}, and | |
437 | call it twice: | |
438 | ||
439 | @smallexample | |
440 | @group | |
441 | foo (double a, double b) | |
442 | @{ | |
443 | double square (double z) @{ return z * z; @} | |
444 | ||
445 | return square (a) + square (b); | |
446 | @} | |
447 | @end group | |
448 | @end smallexample | |
449 | ||
450 | The nested function can access all the variables of the containing | |
451 | function that are visible at the point of its definition. This is | |
452 | called @dfn{lexical scoping}. For example, here we show a nested | |
453 | function which uses an inherited variable named @code{offset}: | |
454 | ||
455 | @smallexample | |
456 | @group | |
457 | bar (int *array, int offset, int size) | |
458 | @{ | |
459 | int access (int *array, int index) | |
460 | @{ return array[index + offset]; @} | |
461 | int i; | |
462 | /* @r{@dots{}} */ | |
463 | for (i = 0; i < size; i++) | |
464 | /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ | |
465 | @} | |
466 | @end group | |
467 | @end smallexample | |
468 | ||
469 | Nested function definitions are permitted within functions in the places | |
470 | where variable definitions are allowed; that is, in any block, mixed | |
471 | with the other declarations and statements in the block. | |
472 | ||
473 | It is possible to call the nested function from outside the scope of its | |
474 | name by storing its address or passing the address to another function: | |
475 | ||
476 | @smallexample | |
477 | hack (int *array, int size) | |
478 | @{ | |
479 | void store (int index, int value) | |
480 | @{ array[index] = value; @} | |
481 | ||
482 | intermediate (store, size); | |
483 | @} | |
484 | @end smallexample | |
485 | ||
486 | Here, the function @code{intermediate} receives the address of | |
487 | @code{store} as an argument. If @code{intermediate} calls @code{store}, | |
488 | the arguments given to @code{store} are used to store into @code{array}. | |
489 | But this technique works only so long as the containing function | |
490 | (@code{hack}, in this example) does not exit. | |
491 | ||
492 | If you try to call the nested function through its address after the | |
493 | containing function exits, all hell breaks loose. If you try | |
494 | to call it after a containing scope level exits, and if it refers | |
495 | to some of the variables that are no longer in scope, you may be lucky, | |
496 | but it's not wise to take the risk. If, however, the nested function | |
497 | does not refer to anything that has gone out of scope, you should be | |
498 | safe. | |
499 | ||
500 | GCC implements taking the address of a nested function using a technique | |
501 | called @dfn{trampolines}. This technique was described in | |
502 | @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX | |
503 | C++ Conference Proceedings, October 17-21, 1988). | |
504 | ||
505 | A nested function can jump to a label inherited from a containing | |
506 | function, provided the label is explicitly declared in the containing | |
507 | function (@pxref{Local Labels}). Such a jump returns instantly to the | |
508 | containing function, exiting the nested function that did the | |
509 | @code{goto} and any intermediate functions as well. Here is an example: | |
510 | ||
511 | @smallexample | |
512 | @group | |
513 | bar (int *array, int offset, int size) | |
514 | @{ | |
515 | __label__ failure; | |
516 | int access (int *array, int index) | |
517 | @{ | |
518 | if (index > size) | |
519 | goto failure; | |
520 | return array[index + offset]; | |
521 | @} | |
522 | int i; | |
523 | /* @r{@dots{}} */ | |
524 | for (i = 0; i < size; i++) | |
525 | /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ | |
526 | /* @r{@dots{}} */ | |
527 | return 0; | |
528 | ||
529 | /* @r{Control comes here from @code{access} | |
530 | if it detects an error.} */ | |
531 | failure: | |
532 | return -1; | |
533 | @} | |
534 | @end group | |
535 | @end smallexample | |
536 | ||
537 | A nested function always has no linkage. Declaring one with | |
538 | @code{extern} or @code{static} is erroneous. If you need to declare the nested function | |
539 | before its definition, use @code{auto} (which is otherwise meaningless | |
540 | for function declarations). | |
541 | ||
542 | @smallexample | |
543 | bar (int *array, int offset, int size) | |
544 | @{ | |
545 | __label__ failure; | |
546 | auto int access (int *, int); | |
547 | /* @r{@dots{}} */ | |
548 | int access (int *array, int index) | |
549 | @{ | |
550 | if (index > size) | |
551 | goto failure; | |
552 | return array[index + offset]; | |
553 | @} | |
554 | /* @r{@dots{}} */ | |
555 | @} | |
556 | @end smallexample | |
557 | ||
558 | @node Nonlocal Gotos | |
559 | @section Nonlocal Gotos | |
560 | @cindex nonlocal gotos | |
561 | ||
562 | GCC provides the built-in functions @code{__builtin_setjmp} and | |
563 | @code{__builtin_longjmp} which are similar to, but not interchangeable | |
564 | with, the C library functions @code{setjmp} and @code{longjmp}. | |
565 | The built-in versions are used internally by GCC's libraries | |
566 | to implement exception handling on some targets. You should use the | |
567 | standard C library functions declared in @code{<setjmp.h>} in user code | |
568 | instead of the builtins. | |
569 | ||
570 | The built-in versions of these functions use GCC's normal | |
571 | mechanisms to save and restore registers using the stack on function | |
572 | entry and exit. The jump buffer argument @var{buf} holds only the | |
573 | information needed to restore the stack frame, rather than the entire | |
574 | set of saved register values. | |
575 | ||
576 | An important caveat is that GCC arranges to save and restore only | |
577 | those registers known to the specific architecture variant being | |
578 | compiled for. This can make @code{__builtin_setjmp} and | |
579 | @code{__builtin_longjmp} more efficient than their library | |
580 | counterparts in some cases, but it can also cause incorrect and | |
581 | mysterious behavior when mixing with code that uses the full register | |
582 | set. | |
583 | ||
584 | You should declare the jump buffer argument @var{buf} to the | |
585 | built-in functions as: | |
586 | ||
587 | @smallexample | |
588 | #include <stdint.h> | |
589 | intptr_t @var{buf}[5]; | |
590 | @end smallexample | |
591 | ||
f25efe50 | 592 | @defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})} |
d77de738 ML |
593 | This function saves the current stack context in @var{buf}. |
594 | @code{__builtin_setjmp} returns 0 when returning directly, | |
595 | and 1 when returning from @code{__builtin_longjmp} using the same | |
596 | @var{buf}. | |
f25efe50 | 597 | @enddefbuiltin |
d77de738 | 598 | |
f25efe50 | 599 | @defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})} |
d77de738 ML |
600 | This function restores the stack context in @var{buf}, |
601 | saved by a previous call to @code{__builtin_setjmp}. After | |
602 | @code{__builtin_longjmp} is finished, the program resumes execution as | |
603 | if the matching @code{__builtin_setjmp} returns the value @var{val}, | |
604 | which must be 1. | |
605 | ||
606 | Because @code{__builtin_longjmp} depends on the function return | |
607 | mechanism to restore the stack context, it cannot be called | |
608 | from the same function calling @code{__builtin_setjmp} to | |
609 | initialize @var{buf}. It can only be called from a function called | |
610 | (directly or indirectly) from the function calling @code{__builtin_setjmp}. | |
f25efe50 | 611 | @enddefbuiltin |
d77de738 ML |
612 | |
613 | @node Constructing Calls | |
614 | @section Constructing Function Calls | |
615 | @cindex constructing calls | |
616 | @cindex forwarding calls | |
617 | ||
618 | Using the built-in functions described below, you can record | |
619 | the arguments a function received, and call another function | |
620 | with the same arguments, without knowing the number or types | |
621 | of the arguments. | |
622 | ||
623 | You can also record the return value of that function call, | |
624 | and later return that value, without knowing what data type | |
625 | the function tried to return (as long as your caller expects | |
626 | that data type). | |
627 | ||
628 | However, these built-in functions may interact badly with some | |
629 | sophisticated features or other extensions of the language. It | |
630 | is, therefore, not recommended to use them outside very simple | |
631 | functions acting as mere forwarders for their arguments. | |
632 | ||
f25efe50 | 633 | @defbuiltin{{void *} __builtin_apply_args ()} |
d77de738 ML |
634 | This built-in function returns a pointer to data |
635 | describing how to perform a call with the same arguments as are passed | |
636 | to the current function. | |
637 | ||
638 | The function saves the arg pointer register, structure value address, | |
639 | and all registers that might be used to pass arguments to a function | |
640 | into a block of memory allocated on the stack. Then it returns the | |
641 | address of that block. | |
f25efe50 | 642 | @enddefbuiltin |
d77de738 | 643 | |
f25efe50 | 644 | @defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})} |
d77de738 ML |
645 | This built-in function invokes @var{function} |
646 | with a copy of the parameters described by @var{arguments} | |
647 | and @var{size}. | |
648 | ||
649 | The value of @var{arguments} should be the value returned by | |
650 | @code{__builtin_apply_args}. The argument @var{size} specifies the size | |
651 | of the stack argument data, in bytes. | |
652 | ||
653 | This function returns a pointer to data describing | |
654 | how to return whatever value is returned by @var{function}. The data | |
655 | is saved in a block of memory allocated on the stack. | |
656 | ||
657 | It is not always simple to compute the proper value for @var{size}. The | |
658 | value is used by @code{__builtin_apply} to compute the amount of data | |
659 | that should be pushed on the stack and copied from the incoming argument | |
660 | area. | |
f25efe50 | 661 | @enddefbuiltin |
d77de738 | 662 | |
f25efe50 | 663 | @defbuiltin{{void} __builtin_return (void *@var{result})} |
d77de738 ML |
664 | This built-in function returns the value described by @var{result} from |
665 | the containing function. You should specify, for @var{result}, a value | |
666 | returned by @code{__builtin_apply}. | |
f25efe50 | 667 | @enddefbuiltin |
d77de738 | 668 | |
f25efe50 | 669 | @defbuiltin{{} __builtin_va_arg_pack ()} |
d77de738 ML |
670 | This built-in function represents all anonymous arguments of an inline |
671 | function. It can be used only in inline functions that are always | |
672 | inlined, never compiled as a separate function, such as those using | |
673 | @code{__attribute__ ((__always_inline__))} or | |
674 | @code{__attribute__ ((__gnu_inline__))} extern inline functions. | |
675 | It must be only passed as last argument to some other function | |
676 | with variable arguments. This is useful for writing small wrapper | |
677 | inlines for variable argument functions, when using preprocessor | |
678 | macros is undesirable. For example: | |
679 | @smallexample | |
680 | extern int myprintf (FILE *f, const char *format, ...); | |
681 | extern inline __attribute__ ((__gnu_inline__)) int | |
682 | myprintf (FILE *f, const char *format, ...) | |
683 | @{ | |
684 | int r = fprintf (f, "myprintf: "); | |
685 | if (r < 0) | |
686 | return r; | |
687 | int s = fprintf (f, format, __builtin_va_arg_pack ()); | |
688 | if (s < 0) | |
689 | return s; | |
690 | return r + s; | |
691 | @} | |
692 | @end smallexample | |
f25efe50 | 693 | @enddefbuiltin |
d77de738 | 694 | |
f25efe50 | 695 | @defbuiltin{int __builtin_va_arg_pack_len ()} |
d77de738 ML |
696 | This built-in function returns the number of anonymous arguments of |
697 | an inline function. It can be used only in inline functions that | |
698 | are always inlined, never compiled as a separate function, such | |
699 | as those using @code{__attribute__ ((__always_inline__))} or | |
700 | @code{__attribute__ ((__gnu_inline__))} extern inline functions. | |
701 | For example following does link- or run-time checking of open | |
702 | arguments for optimized code: | |
703 | @smallexample | |
704 | #ifdef __OPTIMIZE__ | |
705 | extern inline __attribute__((__gnu_inline__)) int | |
706 | myopen (const char *path, int oflag, ...) | |
707 | @{ | |
708 | if (__builtin_va_arg_pack_len () > 1) | |
709 | warn_open_too_many_arguments (); | |
710 | ||
711 | if (__builtin_constant_p (oflag)) | |
712 | @{ | |
713 | if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) | |
714 | @{ | |
715 | warn_open_missing_mode (); | |
716 | return __open_2 (path, oflag); | |
717 | @} | |
718 | return open (path, oflag, __builtin_va_arg_pack ()); | |
719 | @} | |
720 | ||
721 | if (__builtin_va_arg_pack_len () < 1) | |
722 | return __open_2 (path, oflag); | |
723 | ||
724 | return open (path, oflag, __builtin_va_arg_pack ()); | |
725 | @} | |
726 | #endif | |
727 | @end smallexample | |
f25efe50 | 728 | @enddefbuiltin |
d77de738 ML |
729 | |
730 | @node Typeof | |
731 | @section Referring to a Type with @code{typeof} | |
732 | @findex typeof | |
733 | @findex sizeof | |
734 | @cindex macros, types of arguments | |
735 | ||
736 | Another way to refer to the type of an expression is with @code{typeof}. | |
737 | The syntax of using of this keyword looks like @code{sizeof}, but the | |
738 | construct acts semantically like a type name defined with @code{typedef}. | |
739 | ||
740 | There are two ways of writing the argument to @code{typeof}: with an | |
741 | expression or with a type. Here is an example with an expression: | |
742 | ||
743 | @smallexample | |
744 | typeof (x[0](1)) | |
745 | @end smallexample | |
746 | ||
747 | @noindent | |
748 | This assumes that @code{x} is an array of pointers to functions; | |
749 | the type described is that of the values of the functions. | |
750 | ||
751 | Here is an example with a typename as the argument: | |
752 | ||
753 | @smallexample | |
754 | typeof (int *) | |
755 | @end smallexample | |
756 | ||
757 | @noindent | |
758 | Here the type described is that of pointers to @code{int}. | |
759 | ||
760 | If you are writing a header file that must work when included in ISO C | |
761 | programs, write @code{__typeof__} instead of @code{typeof}. | |
762 | @xref{Alternate Keywords}. | |
763 | ||
764 | A @code{typeof} construct can be used anywhere a typedef name can be | |
765 | used. For example, you can use it in a declaration, in a cast, or inside | |
766 | of @code{sizeof} or @code{typeof}. | |
767 | ||
768 | The operand of @code{typeof} is evaluated for its side effects if and | |
769 | only if it is an expression of variably modified type or the name of | |
770 | such a type. | |
771 | ||
772 | @code{typeof} is often useful in conjunction with | |
773 | statement expressions (@pxref{Statement Exprs}). | |
774 | Here is how the two together can | |
775 | be used to define a safe ``maximum'' macro which operates on any | |
776 | arithmetic type and evaluates each of its arguments exactly once: | |
777 | ||
778 | @smallexample | |
779 | #define max(a,b) \ | |
780 | (@{ typeof (a) _a = (a); \ | |
781 | typeof (b) _b = (b); \ | |
782 | _a > _b ? _a : _b; @}) | |
783 | @end smallexample | |
784 | ||
785 | @cindex underscores in variables in macros | |
786 | @cindex @samp{_} in variables in macros | |
787 | @cindex local variables in macros | |
788 | @cindex variables, local, in macros | |
789 | @cindex macros, local variables in | |
790 | ||
791 | The reason for using names that start with underscores for the local | |
792 | variables is to avoid conflicts with variable names that occur within the | |
793 | expressions that are substituted for @code{a} and @code{b}. Eventually we | |
794 | hope to design a new form of declaration syntax that allows you to declare | |
795 | variables whose scopes start only after their initializers; this will be a | |
796 | more reliable way to prevent such conflicts. | |
797 | ||
798 | @noindent | |
799 | Some more examples of the use of @code{typeof}: | |
800 | ||
801 | @itemize @bullet | |
802 | @item | |
803 | This declares @code{y} with the type of what @code{x} points to. | |
804 | ||
805 | @smallexample | |
806 | typeof (*x) y; | |
807 | @end smallexample | |
808 | ||
809 | @item | |
810 | This declares @code{y} as an array of such values. | |
811 | ||
812 | @smallexample | |
813 | typeof (*x) y[4]; | |
814 | @end smallexample | |
815 | ||
816 | @item | |
817 | This declares @code{y} as an array of pointers to characters: | |
818 | ||
819 | @smallexample | |
820 | typeof (typeof (char *)[4]) y; | |
821 | @end smallexample | |
822 | ||
823 | @noindent | |
824 | It is equivalent to the following traditional C declaration: | |
825 | ||
826 | @smallexample | |
827 | char *y[4]; | |
828 | @end smallexample | |
829 | ||
830 | To see the meaning of the declaration using @code{typeof}, and why it | |
831 | might be a useful way to write, rewrite it with these macros: | |
832 | ||
833 | @smallexample | |
834 | #define pointer(T) typeof(T *) | |
835 | #define array(T, N) typeof(T [N]) | |
836 | @end smallexample | |
837 | ||
838 | @noindent | |
839 | Now the declaration can be rewritten this way: | |
840 | ||
841 | @smallexample | |
842 | array (pointer (char), 4) y; | |
843 | @end smallexample | |
844 | ||
845 | @noindent | |
846 | Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 | |
847 | pointers to @code{char}. | |
848 | @end itemize | |
849 | ||
094a609c | 850 | The ISO C23 operator @code{typeof_unqual} is available in ISO C23 mode |
607d9d50 JJ |
851 | and its result is the non-atomic unqualified version of what @code{typeof} |
852 | operator returns. Alternate spelling @code{__typeof_unqual__} is | |
853 | available in all C modes and provides non-atomic unqualified version of | |
854 | what @code{__typeof__} operator returns. | |
855 | @xref{Alternate Keywords}. | |
856 | ||
790fef14 | 857 | @cindex @code{__auto_type} in GNU C |
d77de738 ML |
858 | In GNU C, but not GNU C++, you may also declare the type of a variable |
859 | as @code{__auto_type}. In that case, the declaration must declare | |
860 | only one variable, whose declarator must just be an identifier, the | |
861 | declaration must be initialized, and the type of the variable is | |
862 | determined by the initializer; the name of the variable is not in | |
863 | scope until after the initializer. (In C++, you should use C++11 | |
864 | @code{auto} for this purpose.) Using @code{__auto_type}, the | |
865 | ``maximum'' macro above could be written as: | |
866 | ||
867 | @smallexample | |
868 | #define max(a,b) \ | |
869 | (@{ __auto_type _a = (a); \ | |
870 | __auto_type _b = (b); \ | |
871 | _a > _b ? _a : _b; @}) | |
872 | @end smallexample | |
873 | ||
874 | Using @code{__auto_type} instead of @code{typeof} has two advantages: | |
875 | ||
876 | @itemize @bullet | |
877 | @item Each argument to the macro appears only once in the expansion of | |
878 | the macro. This prevents the size of the macro expansion growing | |
879 | exponentially when calls to such macros are nested inside arguments of | |
880 | such macros. | |
881 | ||
882 | @item If the argument to the macro has variably modified type, it is | |
883 | evaluated only once when using @code{__auto_type}, but twice if | |
884 | @code{typeof} is used. | |
885 | @end itemize | |
886 | ||
887 | @node Conditionals | |
888 | @section Conditionals with Omitted Operands | |
889 | @cindex conditional expressions, extensions | |
890 | @cindex omitted middle-operands | |
891 | @cindex middle-operands, omitted | |
892 | @cindex extensions, @code{?:} | |
893 | @cindex @code{?:} extensions | |
894 | ||
895 | The middle operand in a conditional expression may be omitted. Then | |
896 | if the first operand is nonzero, its value is the value of the conditional | |
897 | expression. | |
898 | ||
899 | Therefore, the expression | |
900 | ||
901 | @smallexample | |
902 | x ? : y | |
903 | @end smallexample | |
904 | ||
905 | @noindent | |
906 | has the value of @code{x} if that is nonzero; otherwise, the value of | |
907 | @code{y}. | |
908 | ||
909 | This example is perfectly equivalent to | |
910 | ||
911 | @smallexample | |
912 | x ? x : y | |
913 | @end smallexample | |
914 | ||
915 | @cindex side effect in @code{?:} | |
916 | @cindex @code{?:} side effect | |
917 | @noindent | |
918 | In this simple case, the ability to omit the middle operand is not | |
919 | especially useful. When it becomes useful is when the first operand does, | |
920 | or may (if it is a macro argument), contain a side effect. Then repeating | |
921 | the operand in the middle would perform the side effect twice. Omitting | |
922 | the middle operand uses the value already computed without the undesirable | |
923 | effects of recomputing it. | |
924 | ||
925 | @node __int128 | |
926 | @section 128-bit Integers | |
927 | @cindex @code{__int128} data types | |
928 | ||
929 | As an extension the integer scalar type @code{__int128} is supported for | |
930 | targets which have an integer mode wide enough to hold 128 bits. | |
931 | Simply write @code{__int128} for a signed 128-bit integer, or | |
932 | @code{unsigned __int128} for an unsigned 128-bit integer. There is no | |
933 | support in GCC for expressing an integer constant of type @code{__int128} | |
934 | for targets with @code{long long} integer less than 128 bits wide. | |
935 | ||
936 | @node Long Long | |
937 | @section Double-Word Integers | |
938 | @cindex @code{long long} data types | |
939 | @cindex double-word arithmetic | |
940 | @cindex multiprecision arithmetic | |
941 | @cindex @code{LL} integer suffix | |
942 | @cindex @code{ULL} integer suffix | |
943 | ||
944 | ISO C99 and ISO C++11 support data types for integers that are at least | |
945 | 64 bits wide, and as an extension GCC supports them in C90 and C++98 modes. | |
946 | Simply write @code{long long int} for a signed integer, or | |
947 | @code{unsigned long long int} for an unsigned integer. To make an | |
948 | integer constant of type @code{long long int}, add the suffix @samp{LL} | |
949 | to the integer. To make an integer constant of type @code{unsigned long | |
950 | long int}, add the suffix @samp{ULL} to the integer. | |
951 | ||
952 | You can use these types in arithmetic like any other integer types. | |
953 | Addition, subtraction, and bitwise boolean operations on these types | |
954 | are open-coded on all types of machines. Multiplication is open-coded | |
955 | if the machine supports a fullword-to-doubleword widening multiply | |
956 | instruction. Division and shifts are open-coded only on machines that | |
957 | provide special support. The operations that are not open-coded use | |
958 | special library routines that come with GCC@. | |
959 | ||
960 | There may be pitfalls when you use @code{long long} types for function | |
961 | arguments without function prototypes. If a function | |
962 | expects type @code{int} for its argument, and you pass a value of type | |
963 | @code{long long int}, confusion results because the caller and the | |
964 | subroutine disagree about the number of bytes for the argument. | |
965 | Likewise, if the function expects @code{long long int} and you pass | |
966 | @code{int}. The best way to avoid such problems is to use prototypes. | |
967 | ||
968 | @node Complex | |
969 | @section Complex Numbers | |
970 | @cindex complex numbers | |
971 | @cindex @code{_Complex} keyword | |
972 | @cindex @code{__complex__} keyword | |
973 | ||
974 | ISO C99 supports complex floating data types, and as an extension GCC | |
975 | supports them in C90 mode and in C++. GCC also supports complex integer data | |
976 | types which are not part of ISO C99. You can declare complex types | |
977 | using the keyword @code{_Complex}. As an extension, the older GNU | |
978 | keyword @code{__complex__} is also supported. | |
979 | ||
980 | For example, @samp{_Complex double x;} declares @code{x} as a | |
981 | variable whose real part and imaginary part are both of type | |
982 | @code{double}. @samp{_Complex short int y;} declares @code{y} to | |
983 | have real and imaginary parts of type @code{short int}; this is not | |
984 | likely to be useful, but it shows that the set of complex types is | |
985 | complete. | |
986 | ||
987 | To write a constant with a complex data type, use the suffix @samp{i} or | |
988 | @samp{j} (either one; they are equivalent). For example, @code{2.5fi} | |
989 | has type @code{_Complex float} and @code{3i} has type | |
990 | @code{_Complex int}. Such a constant always has a pure imaginary | |
991 | value, but you can form any complex value you like by adding one to a | |
992 | real constant. This is a GNU extension; if you have an ISO C99 | |
993 | conforming C library (such as the GNU C Library), and want to construct complex | |
994 | constants of floating type, you should include @code{<complex.h>} and | |
995 | use the macros @code{I} or @code{_Complex_I} instead. | |
996 | ||
997 | The ISO C++14 library also defines the @samp{i} suffix, so C++14 code | |
998 | that includes the @samp{<complex>} header cannot use @samp{i} for the | |
999 | GNU extension. The @samp{j} suffix still has the GNU meaning. | |
1000 | ||
1001 | GCC can handle both implicit and explicit casts between the @code{_Complex} | |
1002 | types and other @code{_Complex} types as casting both the real and imaginary | |
1003 | parts to the scalar type. | |
1004 | GCC can handle implicit and explicit casts from a scalar type to a @code{_Complex} | |
1005 | type and where the imaginary part will be considered zero. | |
1006 | The C front-end can handle implicit and explicit casts from a @code{_Complex} type | |
1007 | to a scalar type where the imaginary part will be ignored. In C++ code, this cast | |
1008 | is considered illformed and G++ will error out. | |
1009 | ||
1010 | GCC provides a built-in function @code{__builtin_complex} will can be used to | |
1011 | construct a complex value. | |
1012 | ||
1013 | @cindex @code{__real__} keyword | |
1014 | @cindex @code{__imag__} keyword | |
1015 | ||
1016 | GCC has a few extensions which can be used to extract the real | |
1017 | and the imaginary part of the complex-valued expression. Note | |
1018 | these expressions are lvalues if the @var{exp} is an lvalue. | |
1019 | These expressions operands have the type of a complex type | |
1020 | which might get prompoted to a complex type from a scalar type. | |
1021 | E.g. @code{__real__ (int)@var{x}} is the same as casting to | |
1022 | @code{_Complex int} before @code{__real__} is done. | |
1023 | ||
1024 | @multitable @columnfractions .4 .6 | |
1025 | @headitem Expression @tab Description | |
1026 | @item @code{__real__ @var{exp}} | |
1027 | @tab Extract the real part of @var{exp}. | |
1028 | @item @code{__imag__ @var{exp}} | |
1029 | @tab Extract the imaginary part of @var{exp}. | |
1030 | @end multitable | |
1031 | ||
1032 | For values of floating point, you should use the ISO C99 | |
1033 | functions, declared in @code{<complex.h>} and also provided as | |
1034 | built-in functions by GCC@. | |
1035 | ||
1036 | @multitable @columnfractions .4 .2 .2 .2 | |
1037 | @headitem Expression @tab float @tab double @tab long double | |
1038 | @item @code{__real__ @var{exp}} | |
1039 | @tab @code{crealf} @tab @code{creal} @tab @code{creall} | |
1040 | @item @code{__imag__ @var{exp}} | |
1041 | @tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl} | |
1042 | @end multitable | |
1043 | ||
1044 | @cindex complex conjugation | |
1045 | The operator @samp{~} performs complex conjugation when used on a value | |
1046 | with a complex type. This is a GNU extension; for values of | |
1047 | floating type, you should use the ISO C99 functions @code{conjf}, | |
1048 | @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also | |
1049 | provided as built-in functions by GCC@. Note unlike the @code{__real__} | |
1050 | and @code{__imag__} operators, this operator will not do an implicit cast | |
1051 | to the complex type because the @samp{~} is already a normal operator. | |
1052 | ||
1053 | GCC can allocate complex automatic variables in a noncontiguous | |
1054 | fashion; it's even possible for the real part to be in a register while | |
1055 | the imaginary part is on the stack (or vice versa). Only the DWARF | |
1056 | debug info format can represent this, so use of DWARF is recommended. | |
1057 | If you are using the stabs debug info format, GCC describes a noncontiguous | |
1058 | complex variable as if it were two separate variables of noncomplex type. | |
1059 | If the variable's actual name is @code{foo}, the two fictitious | |
1060 | variables are named @code{foo$real} and @code{foo$imag}. You can | |
1061 | examine and set these two fictitious variables with your debugger. | |
1062 | ||
f25efe50 | 1063 | @defbuiltin{@var{type} __builtin_complex (@var{real}, @var{imag})} |
d77de738 ML |
1064 | |
1065 | The built-in function @code{__builtin_complex} is provided for use in | |
1066 | implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and | |
1067 | @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a | |
1068 | real binary floating-point type, and the result has the corresponding | |
1069 | complex type with real and imaginary parts @var{real} and @var{imag}. | |
1070 | Unlike @samp{@var{real} + I * @var{imag}}, this works even when | |
1071 | infinities, NaNs and negative zeros are involved. | |
1072 | ||
f25efe50 | 1073 | @enddefbuiltin |
d77de738 ML |
1074 | |
1075 | @node Floating Types | |
1076 | @section Additional Floating Types | |
1077 | @cindex additional floating types | |
1078 | @cindex @code{_Float@var{n}} data types | |
1079 | @cindex @code{_Float@var{n}x} data types | |
1080 | @cindex @code{__float80} data type | |
1081 | @cindex @code{__float128} data type | |
1082 | @cindex @code{__ibm128} data type | |
1083 | @cindex @code{w} floating point suffix | |
1084 | @cindex @code{q} floating point suffix | |
1085 | @cindex @code{W} floating point suffix | |
1086 | @cindex @code{Q} floating point suffix | |
1087 | ||
1088 | ISO/IEC TS 18661-3:2015 defines C support for additional floating | |
1089 | types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports | |
1090 | these type names; the set of types supported depends on the target | |
145da6a8 | 1091 | architecture. |
d77de738 ML |
1092 | Constants with these types use suffixes @code{f@var{n}} or |
1093 | @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type | |
1094 | names can be used together with @code{_Complex} to declare complex | |
1095 | types. | |
1096 | ||
1097 | As an extension, GNU C and GNU C++ support additional floating | |
1098 | types, which are not supported by all targets. | |
1099 | @itemize @bullet | |
4e2d53c9 | 1100 | @item @code{__float128} is available on i386, x86_64, IA-64, LoongArch |
1101 | and hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable | |
d77de738 | 1102 | the vector scalar (VSX) instruction set. @code{__float128} supports |
4e2d53c9 | 1103 | the 128-bit floating type. On i386, x86_64, PowerPC, LoongArch and IA-64, |
d77de738 ML |
1104 | other than HP-UX, @code{__float128} is an alias for @code{_Float128}. |
1105 | On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long | |
1106 | double}. | |
1107 | ||
1108 | @item @code{__float80} is available on the i386, x86_64, and IA-64 | |
1109 | targets, and supports the 80-bit (@code{XFmode}) floating type. It is | |
1110 | an alias for the type name @code{_Float64x} on these targets. | |
1111 | ||
1112 | @item @code{__ibm128} is available on PowerPC targets, and provides | |
1113 | access to the IBM extended double format which is the current format | |
1114 | used for @code{long double}. When @code{long double} transitions to | |
1115 | @code{__float128} on PowerPC in the future, @code{__ibm128} will remain | |
1116 | for use in conversions between the two types. | |
1117 | @end itemize | |
1118 | ||
1119 | Support for these additional types includes the arithmetic operators: | |
1120 | add, subtract, multiply, divide; unary arithmetic operators; | |
1121 | relational operators; equality operators; and conversions to and from | |
1122 | integer and other floating types. Use a suffix @samp{w} or @samp{W} | |
1123 | in a literal constant of type @code{__float80} or type | |
1124 | @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{__float128}. | |
1125 | ||
1126 | In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128} | |
1127 | on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is | |
1128 | expected in future versions of GCC that @code{_Float128} and @code{__float128} | |
1129 | will be enabled automatically. | |
1130 | ||
1131 | The @code{_Float128} type is supported on all systems where | |
1132 | @code{__float128} is supported or where @code{long double} has the | |
1133 | IEEE binary128 format. The @code{_Float64x} type is supported on all | |
1134 | systems where @code{__float128} is supported. The @code{_Float32} | |
1135 | type is supported on all systems supporting IEEE binary32; the | |
1136 | @code{_Float64} and @code{_Float32x} types are supported on all systems | |
1137 | supporting IEEE binary64. The @code{_Float16} type is supported on AArch64 | |
1138 | systems by default, on ARM systems when the IEEE format for 16-bit | |
1139 | floating-point types is selected with @option{-mfp16-format=ieee} and, | |
1140 | for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently | |
1141 | support @code{_Float128x} on any systems. | |
1142 | ||
1143 | On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex | |
1144 | types using the corresponding internal complex type, @code{XCmode} for | |
1145 | @code{__float80} type and @code{TCmode} for @code{__float128} type: | |
1146 | ||
1147 | @smallexample | |
1148 | typedef _Complex float __attribute__((mode(TC))) _Complex128; | |
1149 | typedef _Complex float __attribute__((mode(XC))) _Complex80; | |
1150 | @end smallexample | |
1151 | ||
1152 | On the PowerPC Linux VSX targets, you can declare complex types using | |
1153 | the corresponding internal complex type, @code{KCmode} for | |
1154 | @code{__float128} type and @code{ICmode} for @code{__ibm128} type: | |
1155 | ||
1156 | @smallexample | |
1157 | typedef _Complex float __attribute__((mode(KC))) _Complex_float128; | |
1158 | typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128; | |
1159 | @end smallexample | |
1160 | ||
1161 | @node Half-Precision | |
1162 | @section Half-Precision Floating Point | |
1163 | @cindex half-precision floating point | |
1164 | @cindex @code{__fp16} data type | |
1165 | @cindex @code{__Float16} data type | |
1166 | ||
1167 | On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating | |
1168 | point via the @code{__fp16} type defined in the ARM C Language Extensions. | |
1169 | On ARM systems, you must enable this type explicitly with the | |
1170 | @option{-mfp16-format} command-line option in order to use it. | |
1171 | On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit) | |
1172 | floating point via the @code{_Float16} type. For C++, x86 provides a builtin | |
1173 | type named @code{_Float16} which contains same data format as C. | |
1174 | ||
1175 | ARM targets support two incompatible representations for half-precision | |
1176 | floating-point values. You must choose one of the representations and | |
1177 | use it consistently in your program. | |
1178 | ||
1179 | Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. | |
1180 | This format can represent normalized values in the range of @math{2^{-14}} to 65504. | |
1181 | There are 11 bits of significand precision, approximately 3 | |
1182 | decimal digits. | |
1183 | ||
1184 | Specifying @option{-mfp16-format=alternative} selects the ARM | |
1185 | alternative format. This representation is similar to the IEEE | |
1186 | format, but does not support infinities or NaNs. Instead, the range | |
1187 | of exponents is extended, so that this format can represent normalized | |
1188 | values in the range of @math{2^{-14}} to 131008. | |
1189 | ||
1190 | The GCC port for AArch64 only supports the IEEE 754-2008 format, and does | |
1191 | not require use of the @option{-mfp16-format} command-line option. | |
1192 | ||
1193 | The @code{__fp16} type may only be used as an argument to intrinsics defined | |
1194 | in @code{<arm_fp16.h>}, or as a storage format. For purposes of | |
1195 | arithmetic and other operations, @code{__fp16} values in C or C++ | |
1196 | expressions are automatically promoted to @code{float}. | |
1197 | ||
1198 | The ARM target provides hardware support for conversions between | |
1199 | @code{__fp16} and @code{float} values | |
1200 | as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides | |
1201 | hardware support for conversions between @code{__fp16} and @code{double} | |
1202 | values. GCC generates code using these hardware instructions if you | |
1203 | compile with options to select an FPU that provides them; | |
1204 | for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, | |
1205 | in addition to the @option{-mfp16-format} option to select | |
1206 | a half-precision format. | |
1207 | ||
1208 | Language-level support for the @code{__fp16} data type is | |
1209 | independent of whether GCC generates code using hardware floating-point | |
1210 | instructions. In cases where hardware support is not specified, GCC | |
1211 | implements conversions between @code{__fp16} and other types as library | |
1212 | calls. | |
1213 | ||
1214 | It is recommended that portable code use the @code{_Float16} type defined | |
1215 | by ISO/IEC TS 18661-3:2015. @xref{Floating Types}. | |
1216 | ||
1217 | On x86 targets with SSE2 enabled, without @option{-mavx512fp16}, | |
1218 | all operations will be emulated by software emulation and the @code{float} | |
1219 | instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the | |
1220 | intermediate result of the operation as 32-bit precision. This may lead to | |
1221 | inconsistent behavior between software emulation and AVX512-FP16 instructions. | |
1222 | Using @option{-fexcess-precision=16} will force round back after each operation. | |
1223 | ||
1224 | Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of | |
1225 | software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round | |
1226 | after each operation. The same is true with @option{-fexcess-precision=standard} | |
1227 | and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse}, | |
1228 | @option{-fexcess-precision=standard} alone does the same thing as before, | |
1229 | It is useful for code that does not have @code{_Float16} and runs on the x87 | |
1230 | FPU. | |
1231 | ||
1232 | @node Decimal Float | |
1233 | @section Decimal Floating Types | |
1234 | @cindex decimal floating types | |
1235 | @cindex @code{_Decimal32} data type | |
1236 | @cindex @code{_Decimal64} data type | |
1237 | @cindex @code{_Decimal128} data type | |
1238 | @cindex @code{df} integer suffix | |
1239 | @cindex @code{dd} integer suffix | |
1240 | @cindex @code{dl} integer suffix | |
1241 | @cindex @code{DF} integer suffix | |
1242 | @cindex @code{DD} integer suffix | |
1243 | @cindex @code{DL} integer suffix | |
1244 | ||
1245 | As an extension, GNU C supports decimal floating types as | |
1246 | defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal | |
1247 | floating types in GCC will evolve as the draft technical report changes. | |
1248 | Calling conventions for any target might also change. Not all targets | |
1249 | support decimal floating types. | |
1250 | ||
1251 | The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and | |
1252 | @code{_Decimal128}. They use a radix of ten, unlike the floating types | |
1253 | @code{float}, @code{double}, and @code{long double} whose radix is not | |
1254 | specified by the C standard but is usually two. | |
1255 | ||
1256 | Support for decimal floating types includes the arithmetic operators | |
1257 | add, subtract, multiply, divide; unary arithmetic operators; | |
1258 | relational operators; equality operators; and conversions to and from | |
1259 | integer and other floating types. Use a suffix @samp{df} or | |
1260 | @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} | |
1261 | or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for | |
1262 | @code{_Decimal128}. | |
1263 | ||
1264 | GCC support of decimal float as specified by the draft technical report | |
1265 | is incomplete: | |
1266 | ||
1267 | @itemize @bullet | |
1268 | @item | |
1269 | When the value of a decimal floating type cannot be represented in the | |
1270 | integer type to which it is being converted, the result is undefined | |
1271 | rather than the result value specified by the draft technical report. | |
1272 | ||
1273 | @item | |
1274 | GCC does not provide the C library functionality associated with | |
1275 | @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and | |
1276 | @file{wchar.h}, which must come from a separate C library implementation. | |
1277 | Because of this the GNU C compiler does not define macro | |
1278 | @code{__STDC_DEC_FP__} to indicate that the implementation conforms to | |
1279 | the technical report. | |
1280 | @end itemize | |
1281 | ||
1282 | Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} | |
1283 | are supported by the DWARF debug information format. | |
1284 | ||
1285 | @node Hex Floats | |
1286 | @section Hex Floats | |
1287 | @cindex hex floats | |
1288 | ||
1289 | ISO C99 and ISO C++17 support floating-point numbers written not only in | |
1290 | the usual decimal notation, such as @code{1.55e1}, but also numbers such as | |
1291 | @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC | |
1292 | supports this in C90 mode (except in some cases when strictly | |
1293 | conforming) and in C++98, C++11 and C++14 modes. In that format the | |
1294 | @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are | |
1295 | mandatory. The exponent is a decimal number that indicates the power of | |
1296 | 2 by which the significant part is multiplied. Thus @samp{0x1.f} is | |
1297 | @tex | |
1298 | $1 {15\over16}$, | |
1299 | @end tex | |
1300 | @ifnottex | |
1301 | 1 15/16, | |
1302 | @end ifnottex | |
1303 | @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} | |
1304 | is the same as @code{1.55e1}. | |
1305 | ||
1306 | Unlike for floating-point numbers in the decimal notation the exponent | |
1307 | is always required in the hexadecimal notation. Otherwise the compiler | |
1308 | would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This | |
1309 | could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the | |
1310 | extension for floating-point constants of type @code{float}. | |
1311 | ||
1312 | @node Fixed-Point | |
1313 | @section Fixed-Point Types | |
1314 | @cindex fixed-point types | |
1315 | @cindex @code{_Fract} data type | |
1316 | @cindex @code{_Accum} data type | |
1317 | @cindex @code{_Sat} data type | |
1318 | @cindex @code{hr} fixed-suffix | |
1319 | @cindex @code{r} fixed-suffix | |
1320 | @cindex @code{lr} fixed-suffix | |
1321 | @cindex @code{llr} fixed-suffix | |
1322 | @cindex @code{uhr} fixed-suffix | |
1323 | @cindex @code{ur} fixed-suffix | |
1324 | @cindex @code{ulr} fixed-suffix | |
1325 | @cindex @code{ullr} fixed-suffix | |
1326 | @cindex @code{hk} fixed-suffix | |
1327 | @cindex @code{k} fixed-suffix | |
1328 | @cindex @code{lk} fixed-suffix | |
1329 | @cindex @code{llk} fixed-suffix | |
1330 | @cindex @code{uhk} fixed-suffix | |
1331 | @cindex @code{uk} fixed-suffix | |
1332 | @cindex @code{ulk} fixed-suffix | |
1333 | @cindex @code{ullk} fixed-suffix | |
1334 | @cindex @code{HR} fixed-suffix | |
1335 | @cindex @code{R} fixed-suffix | |
1336 | @cindex @code{LR} fixed-suffix | |
1337 | @cindex @code{LLR} fixed-suffix | |
1338 | @cindex @code{UHR} fixed-suffix | |
1339 | @cindex @code{UR} fixed-suffix | |
1340 | @cindex @code{ULR} fixed-suffix | |
1341 | @cindex @code{ULLR} fixed-suffix | |
1342 | @cindex @code{HK} fixed-suffix | |
1343 | @cindex @code{K} fixed-suffix | |
1344 | @cindex @code{LK} fixed-suffix | |
1345 | @cindex @code{LLK} fixed-suffix | |
1346 | @cindex @code{UHK} fixed-suffix | |
1347 | @cindex @code{UK} fixed-suffix | |
1348 | @cindex @code{ULK} fixed-suffix | |
1349 | @cindex @code{ULLK} fixed-suffix | |
1350 | ||
1351 | As an extension, GNU C supports fixed-point types as | |
1352 | defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point | |
1353 | types in GCC will evolve as the draft technical report changes. | |
1354 | Calling conventions for any target might also change. Not all targets | |
1355 | support fixed-point types. | |
1356 | ||
1357 | The fixed-point types are | |
1358 | @code{short _Fract}, | |
1359 | @code{_Fract}, | |
1360 | @code{long _Fract}, | |
1361 | @code{long long _Fract}, | |
1362 | @code{unsigned short _Fract}, | |
1363 | @code{unsigned _Fract}, | |
1364 | @code{unsigned long _Fract}, | |
1365 | @code{unsigned long long _Fract}, | |
1366 | @code{_Sat short _Fract}, | |
1367 | @code{_Sat _Fract}, | |
1368 | @code{_Sat long _Fract}, | |
1369 | @code{_Sat long long _Fract}, | |
1370 | @code{_Sat unsigned short _Fract}, | |
1371 | @code{_Sat unsigned _Fract}, | |
1372 | @code{_Sat unsigned long _Fract}, | |
1373 | @code{_Sat unsigned long long _Fract}, | |
1374 | @code{short _Accum}, | |
1375 | @code{_Accum}, | |
1376 | @code{long _Accum}, | |
1377 | @code{long long _Accum}, | |
1378 | @code{unsigned short _Accum}, | |
1379 | @code{unsigned _Accum}, | |
1380 | @code{unsigned long _Accum}, | |
1381 | @code{unsigned long long _Accum}, | |
1382 | @code{_Sat short _Accum}, | |
1383 | @code{_Sat _Accum}, | |
1384 | @code{_Sat long _Accum}, | |
1385 | @code{_Sat long long _Accum}, | |
1386 | @code{_Sat unsigned short _Accum}, | |
1387 | @code{_Sat unsigned _Accum}, | |
1388 | @code{_Sat unsigned long _Accum}, | |
1389 | @code{_Sat unsigned long long _Accum}. | |
1390 | ||
1391 | Fixed-point data values contain fractional and optional integral parts. | |
1392 | The format of fixed-point data varies and depends on the target machine. | |
1393 | ||
1394 | Support for fixed-point types includes: | |
1395 | @itemize @bullet | |
1396 | @item | |
1397 | prefix and postfix increment and decrement operators (@code{++}, @code{--}) | |
1398 | @item | |
1399 | unary arithmetic operators (@code{+}, @code{-}, @code{!}) | |
1400 | @item | |
1401 | binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) | |
1402 | @item | |
1403 | binary shift operators (@code{<<}, @code{>>}) | |
1404 | @item | |
1405 | relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) | |
1406 | @item | |
1407 | equality operators (@code{==}, @code{!=}) | |
1408 | @item | |
1409 | assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, | |
1410 | @code{<<=}, @code{>>=}) | |
1411 | @item | |
1412 | conversions to and from integer, floating-point, or fixed-point types | |
1413 | @end itemize | |
1414 | ||
1415 | Use a suffix in a fixed-point literal constant: | |
1416 | @itemize | |
1417 | @item @samp{hr} or @samp{HR} for @code{short _Fract} and | |
1418 | @code{_Sat short _Fract} | |
1419 | @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} | |
1420 | @item @samp{lr} or @samp{LR} for @code{long _Fract} and | |
1421 | @code{_Sat long _Fract} | |
1422 | @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and | |
1423 | @code{_Sat long long _Fract} | |
1424 | @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and | |
1425 | @code{_Sat unsigned short _Fract} | |
1426 | @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and | |
1427 | @code{_Sat unsigned _Fract} | |
1428 | @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and | |
1429 | @code{_Sat unsigned long _Fract} | |
1430 | @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} | |
1431 | and @code{_Sat unsigned long long _Fract} | |
1432 | @item @samp{hk} or @samp{HK} for @code{short _Accum} and | |
1433 | @code{_Sat short _Accum} | |
1434 | @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} | |
1435 | @item @samp{lk} or @samp{LK} for @code{long _Accum} and | |
1436 | @code{_Sat long _Accum} | |
1437 | @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and | |
1438 | @code{_Sat long long _Accum} | |
1439 | @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and | |
1440 | @code{_Sat unsigned short _Accum} | |
1441 | @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and | |
1442 | @code{_Sat unsigned _Accum} | |
1443 | @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and | |
1444 | @code{_Sat unsigned long _Accum} | |
1445 | @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} | |
1446 | and @code{_Sat unsigned long long _Accum} | |
1447 | @end itemize | |
1448 | ||
1449 | GCC support of fixed-point types as specified by the draft technical report | |
1450 | is incomplete: | |
1451 | ||
1452 | @itemize @bullet | |
1453 | @item | |
1454 | Pragmas to control overflow and rounding behaviors are not implemented. | |
1455 | @end itemize | |
1456 | ||
1457 | Fixed-point types are supported by the DWARF debug information format. | |
1458 | ||
1459 | @node Named Address Spaces | |
1460 | @section Named Address Spaces | |
1461 | @cindex Named Address Spaces | |
1462 | ||
1463 | As an extension, GNU C supports named address spaces as | |
1464 | defined in the N1275 draft of ISO/IEC DTR 18037. Support for named | |
1465 | address spaces in GCC will evolve as the draft technical report | |
1466 | changes. Calling conventions for any target might also change. At | |
1467 | present, only the AVR, M32C, PRU, RL78, and x86 targets support | |
1468 | address spaces other than the generic address space. | |
1469 | ||
1470 | Address space identifiers may be used exactly like any other C type | |
1471 | qualifier (e.g., @code{const} or @code{volatile}). See the N1275 | |
1472 | document for more details. | |
1473 | ||
1474 | @anchor{AVR Named Address Spaces} | |
1475 | @subsection AVR Named Address Spaces | |
1476 | ||
1477 | On the AVR target, there are several address spaces that can be used | |
1478 | in order to put read-only data into the flash memory and access that | |
1479 | data by means of the special instructions @code{LPM} or @code{ELPM} | |
1480 | needed to read from flash. | |
1481 | ||
1482 | Devices belonging to @code{avrtiny} and @code{avrxmega3} can access | |
1483 | flash memory by means of @code{LD*} instructions because the flash | |
1484 | memory is mapped into the RAM address space. There is @emph{no need} | |
1485 | for language extensions like @code{__flash} or attribute | |
1486 | @ref{AVR Variable Attributes,,@code{progmem}}. | |
1487 | The default linker description files for these devices cater for that | |
1488 | feature and @code{.rodata} stays in flash: The compiler just generates | |
1489 | @code{LD*} instructions, and the linker script adds core specific | |
1490 | offsets to all @code{.rodata} symbols: @code{0x4000} in the case of | |
1491 | @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}. | |
1492 | See @ref{AVR Options} for a list of respective devices. | |
1493 | ||
1494 | For devices not in @code{avrtiny} or @code{avrxmega3}, | |
1495 | any data including read-only data is located in RAM (the generic | |
1496 | address space) because flash memory is not visible in the RAM address | |
1497 | space. In order to locate read-only data in flash memory @emph{and} | |
1498 | to generate the right instructions to access this data without | |
1499 | using (inline) assembler code, special address spaces are needed. | |
1500 | ||
1501 | @table @code | |
d77de738 | 1502 | @cindex @code{__flash} AVR Named Address Spaces |
f33d7a88 | 1503 | @item __flash |
d77de738 ML |
1504 | The @code{__flash} qualifier locates data in the |
1505 | @code{.progmem.data} section. Data is read using the @code{LPM} | |
1506 | instruction. Pointers to this address space are 16 bits wide. | |
1507 | ||
d77de738 ML |
1508 | @cindex @code{__flash1} AVR Named Address Spaces |
1509 | @cindex @code{__flash2} AVR Named Address Spaces | |
1510 | @cindex @code{__flash3} AVR Named Address Spaces | |
1511 | @cindex @code{__flash4} AVR Named Address Spaces | |
1512 | @cindex @code{__flash5} AVR Named Address Spaces | |
f33d7a88 AA |
1513 | @item __flash1 |
1514 | @itemx __flash2 | |
1515 | @itemx __flash3 | |
1516 | @itemx __flash4 | |
1517 | @itemx __flash5 | |
d77de738 ML |
1518 | These are 16-bit address spaces locating data in section |
1519 | @code{.progmem@var{N}.data} where @var{N} refers to | |
1520 | address space @code{__flash@var{N}}. | |
1521 | The compiler sets the @code{RAMPZ} segment register appropriately | |
1522 | before reading data by means of the @code{ELPM} instruction. | |
1523 | ||
d77de738 | 1524 | @cindex @code{__memx} AVR Named Address Spaces |
f33d7a88 | 1525 | @item __memx |
d77de738 ML |
1526 | This is a 24-bit address space that linearizes flash and RAM: |
1527 | If the high bit of the address is set, data is read from | |
1528 | RAM using the lower two bytes as RAM address. | |
1529 | If the high bit of the address is clear, data is read from flash | |
1530 | with @code{RAMPZ} set according to the high byte of the address. | |
1531 | @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. | |
1532 | ||
1533 | Objects in this address space are located in @code{.progmemx.data}. | |
1534 | @end table | |
1535 | ||
1536 | @b{Example} | |
1537 | ||
1538 | @smallexample | |
1539 | char my_read (const __flash char ** p) | |
1540 | @{ | |
1541 | /* p is a pointer to RAM that points to a pointer to flash. | |
1542 | The first indirection of p reads that flash pointer | |
1543 | from RAM and the second indirection reads a char from this | |
1544 | flash address. */ | |
1545 | ||
1546 | return **p; | |
1547 | @} | |
1548 | ||
1549 | /* Locate array[] in flash memory */ | |
1550 | const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; | |
1551 | ||
1552 | int i = 1; | |
1553 | ||
1554 | int main (void) | |
1555 | @{ | |
1556 | /* Return 17 by reading from flash memory */ | |
1557 | return array[array[i]]; | |
1558 | @} | |
1559 | @end smallexample | |
1560 | ||
1561 | @noindent | |
1562 | For each named address space supported by avr-gcc there is an equally | |
1563 | named but uppercase built-in macro defined. | |
1564 | The purpose is to facilitate testing if respective address space | |
1565 | support is available or not: | |
1566 | ||
1567 | @smallexample | |
1568 | #ifdef __FLASH | |
1569 | const __flash int var = 1; | |
1570 | ||
1571 | int read_var (void) | |
1572 | @{ | |
1573 | return var; | |
1574 | @} | |
1575 | #else | |
1576 | #include <avr/pgmspace.h> /* From AVR-LibC */ | |
1577 | ||
1578 | const int var PROGMEM = 1; | |
1579 | ||
1580 | int read_var (void) | |
1581 | @{ | |
1582 | return (int) pgm_read_word (&var); | |
1583 | @} | |
1584 | #endif /* __FLASH */ | |
1585 | @end smallexample | |
1586 | ||
1587 | @noindent | |
1588 | Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} | |
1589 | locates data in flash but | |
1590 | accesses to these data read from generic address space, i.e.@: | |
1591 | from RAM, | |
1592 | so that you need special accessors like @code{pgm_read_byte} | |
38bce6ff | 1593 | from @w{@uref{https://www.nongnu.org/avr-libc/user-manual/,AVR-LibC}} |
d77de738 ML |
1594 | together with attribute @code{progmem}. |
1595 | ||
1596 | @noindent | |
1597 | @b{Limitations and caveats} | |
1598 | ||
1599 | @itemize | |
1600 | @item | |
1601 | Reading across the 64@tie{}KiB section boundary of | |
1602 | the @code{__flash} or @code{__flash@var{N}} address spaces | |
1603 | shows undefined behavior. The only address space that | |
1604 | supports reading across the 64@tie{}KiB flash segment boundaries is | |
1605 | @code{__memx}. | |
1606 | ||
1607 | @item | |
1608 | If you use one of the @code{__flash@var{N}} address spaces | |
1609 | you must arrange your linker script to locate the | |
1610 | @code{.progmem@var{N}.data} sections according to your needs. | |
1611 | ||
1612 | @item | |
1613 | Any data or pointers to the non-generic address spaces must | |
1614 | be qualified as @code{const}, i.e.@: as read-only data. | |
1615 | This still applies if the data in one of these address | |
1616 | spaces like software version number or calibration lookup table are intended to | |
1617 | be changed after load time by, say, a boot loader. In this case | |
1618 | the right qualification is @code{const} @code{volatile} so that the compiler | |
1619 | must not optimize away known values or insert them | |
1620 | as immediates into operands of instructions. | |
1621 | ||
1622 | @item | |
1623 | The following code initializes a variable @code{pfoo} | |
1624 | located in static storage with a 24-bit address: | |
1625 | @smallexample | |
1626 | extern const __memx char foo; | |
1627 | const __memx void *pfoo = &foo; | |
1628 | @end smallexample | |
1629 | ||
1630 | @item | |
1631 | On the reduced Tiny devices like ATtiny40, no address spaces are supported. | |
1632 | Just use vanilla C / C++ code without overhead as outlined above. | |
1633 | Attribute @code{progmem} is supported but works differently, | |
1634 | see @ref{AVR Variable Attributes}. | |
1635 | ||
1636 | @end itemize | |
1637 | ||
1638 | @subsection M32C Named Address Spaces | |
1639 | @cindex @code{__far} M32C Named Address Spaces | |
1640 | ||
1641 | On the M32C target, with the R8C and M16C CPU variants, variables | |
1642 | qualified with @code{__far} are accessed using 32-bit addresses in | |
1643 | order to access memory beyond the first 64@tie{}Ki bytes. If | |
1644 | @code{__far} is used with the M32CM or M32C CPU variants, it has no | |
1645 | effect. | |
1646 | ||
1647 | @subsection PRU Named Address Spaces | |
1648 | @cindex @code{__regio_symbol} PRU Named Address Spaces | |
1649 | ||
1650 | On the PRU target, variables qualified with @code{__regio_symbol} are | |
1651 | aliases used to access the special I/O CPU registers. They must be | |
1652 | declared as @code{extern} because such variables will not be allocated in | |
1653 | any data memory. They must also be marked as @code{volatile}, and can | |
1654 | only be 32-bit integer types. The only names those variables can have | |
1655 | are @code{__R30} and @code{__R31}, representing respectively the | |
1656 | @code{R30} and @code{R31} special I/O CPU registers. Hence the following | |
1657 | example is the only valid usage of @code{__regio_symbol}: | |
1658 | ||
1659 | @smallexample | |
1660 | extern volatile __regio_symbol uint32_t __R30; | |
1661 | extern volatile __regio_symbol uint32_t __R31; | |
1662 | @end smallexample | |
1663 | ||
1664 | @subsection RL78 Named Address Spaces | |
1665 | @cindex @code{__far} RL78 Named Address Spaces | |
1666 | ||
1667 | On the RL78 target, variables qualified with @code{__far} are accessed | |
1668 | with 32-bit pointers (20-bit addresses) rather than the default 16-bit | |
1669 | addresses. Non-far variables are assumed to appear in the topmost | |
1670 | 64@tie{}KiB of the address space. | |
1671 | ||
1672 | @subsection x86 Named Address Spaces | |
1673 | @cindex x86 named address spaces | |
1674 | ||
1675 | On the x86 target, variables may be declared as being relative | |
1676 | to the @code{%fs} or @code{%gs} segments. | |
1677 | ||
1678 | @table @code | |
d77de738 ML |
1679 | @cindex @code{__seg_fs} x86 named address space |
1680 | @cindex @code{__seg_gs} x86 named address space | |
f33d7a88 AA |
1681 | @item __seg_fs |
1682 | @itemx __seg_gs | |
d77de738 ML |
1683 | The object is accessed with the respective segment override prefix. |
1684 | ||
1685 | The respective segment base must be set via some method specific to | |
1686 | the operating system. Rather than require an expensive system call | |
1687 | to retrieve the segment base, these address spaces are not considered | |
1688 | to be subspaces of the generic (flat) address space. This means that | |
1689 | explicit casts are required to convert pointers between these address | |
1690 | spaces and the generic address space. In practice the application | |
1691 | should cast to @code{uintptr_t} and apply the segment base offset | |
1692 | that it installed previously. | |
1693 | ||
1694 | The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are | |
1695 | defined when these address spaces are supported. | |
1696 | @end table | |
1697 | ||
1698 | @node Zero Length | |
1699 | @section Arrays of Length Zero | |
1700 | @cindex arrays of length zero | |
1701 | @cindex zero-length arrays | |
1702 | @cindex length-zero arrays | |
1703 | @cindex flexible array members | |
1704 | ||
1705 | Declaring zero-length arrays is allowed in GNU C as an extension. | |
1706 | A zero-length array can be useful as the last element of a structure | |
1707 | that is really a header for a variable-length object: | |
1708 | ||
1709 | @smallexample | |
1710 | struct line @{ | |
1711 | int length; | |
1712 | char contents[0]; | |
1713 | @}; | |
1714 | ||
1715 | struct line *thisline = (struct line *) | |
1716 | malloc (sizeof (struct line) + this_length); | |
1717 | thisline->length = this_length; | |
1718 | @end smallexample | |
1719 | ||
429c72eb JW |
1720 | In this example, @code{thisline->contents} is an array of @code{char} that |
1721 | can hold up to @code{thisline->length} bytes. | |
1722 | ||
d77de738 ML |
1723 | Although the size of a zero-length array is zero, an array member of |
1724 | this kind may increase the size of the enclosing type as a result of tail | |
1725 | padding. The offset of a zero-length array member from the beginning | |
1726 | of the enclosing structure is the same as the offset of an array with | |
1727 | one or more elements of the same type. The alignment of a zero-length | |
1728 | array is the same as the alignment of its elements. | |
1729 | ||
1730 | Declaring zero-length arrays in other contexts, including as interior | |
1731 | members of structure objects or as non-member objects, is discouraged. | |
1732 | Accessing elements of zero-length arrays declared in such contexts is | |
1733 | undefined and may be diagnosed. | |
1734 | ||
1735 | In the absence of the zero-length array extension, in ISO C90 | |
1736 | the @code{contents} array in the example above would typically be declared | |
1737 | to have a single element. Unlike a zero-length array which only contributes | |
1738 | to the size of the enclosing structure for the purposes of alignment, | |
1739 | a one-element array always occupies at least as much space as a single | |
1740 | object of the type. Although using one-element arrays this way is | |
1741 | discouraged, GCC handles accesses to trailing one-element array members | |
1742 | analogously to zero-length arrays. | |
1743 | ||
1744 | The preferred mechanism to declare variable-length types like | |
1745 | @code{struct line} above is the ISO C99 @dfn{flexible array member}, | |
1746 | with slightly different syntax and semantics: | |
1747 | ||
1748 | @itemize @bullet | |
1749 | @item | |
1750 | Flexible array members are written as @code{contents[]} without | |
1751 | the @code{0}. | |
1752 | ||
1753 | @item | |
1754 | Flexible array members have incomplete type, and so the @code{sizeof} | |
1755 | operator may not be applied. As a quirk of the original implementation | |
1756 | of zero-length arrays, @code{sizeof} evaluates to zero. | |
1757 | ||
1758 | @item | |
1759 | Flexible array members may only appear as the last member of a | |
1760 | @code{struct} that is otherwise non-empty. | |
1761 | ||
1762 | @item | |
1763 | A structure containing a flexible array member, or a union containing | |
1764 | such a structure (possibly recursively), may not be a member of a | |
1765 | structure or an element of an array. (However, these uses are | |
070a6bf0 QZ |
1766 | permitted by GCC as extensions, see details below.) |
1767 | @end itemize | |
1768 | ||
1769 | The GCC extension accepts a structure containing an ISO C99 @dfn{flexible array | |
1770 | member}, or a union containing such a structure (possibly recursively) | |
1771 | to be a member of a structure. | |
1772 | ||
1773 | There are two situations: | |
1774 | ||
1775 | @itemize @bullet | |
1776 | @item | |
1777 | A structure containing a C99 flexible array member, or a union containing | |
1778 | such a structure, is the last field of another structure, for example: | |
1779 | ||
1780 | @smallexample | |
1781 | struct flex @{ int length; char data[]; @}; | |
1782 | union union_flex @{ int others; struct flex f; @}; | |
1783 | ||
1784 | struct out_flex_struct @{ int m; struct flex flex_data; @}; | |
1785 | struct out_flex_union @{ int n; union union_flex flex_data; @}; | |
1786 | @end smallexample | |
1787 | ||
1788 | In the above, both @code{out_flex_struct.flex_data.data[]} and | |
1789 | @code{out_flex_union.flex_data.f.data[]} are considered as flexible arrays too. | |
1790 | ||
1791 | @item | |
1792 | A structure containing a C99 flexible array member, or a union containing | |
1793 | such a structure, is not the last field of another structure, for example: | |
1794 | ||
1795 | @smallexample | |
1796 | struct flex @{ int length; char data[]; @}; | |
1797 | ||
1798 | struct mid_flex @{ int m; struct flex flex_data; int n; @}; | |
1799 | @end smallexample | |
1800 | ||
1801 | In the above, accessing a member of the array @code{mid_flex.flex_data.data[]} | |
1802 | might have undefined behavior. Compilers do not handle such a case | |
1803 | consistently. Any code relying on this case should be modified to ensure | |
1804 | that flexible array members only end up at the ends of structures. | |
1805 | ||
1806 | Please use the warning option @option{-Wflex-array-member-not-at-end} to | |
1807 | identify all such cases in the source code and modify them. This extension | |
1808 | is now deprecated. | |
d77de738 ML |
1809 | @end itemize |
1810 | ||
1811 | Non-empty initialization of zero-length | |
1812 | arrays is treated like any case where there are more initializer | |
1813 | elements than the array holds, in that a suitable warning about ``excess | |
1814 | elements in array'' is given, and the excess elements (all of them, in | |
1815 | this case) are ignored. | |
1816 | ||
1817 | GCC allows static initialization of flexible array members. | |
1818 | This is equivalent to defining a new structure containing the original | |
1819 | structure followed by an array of sufficient size to contain the data. | |
1820 | E.g.@: in the following, @code{f1} is constructed as if it were declared | |
1821 | like @code{f2}. | |
1822 | ||
1823 | @smallexample | |
1824 | struct f1 @{ | |
1825 | int x; int y[]; | |
1826 | @} f1 = @{ 1, @{ 2, 3, 4 @} @}; | |
1827 | ||
1828 | struct f2 @{ | |
1829 | struct f1 f1; int data[3]; | |
1830 | @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; | |
1831 | @end smallexample | |
1832 | ||
1833 | @noindent | |
1834 | The convenience of this extension is that @code{f1} has the desired | |
1835 | type, eliminating the need to consistently refer to @code{f2.f1}. | |
1836 | ||
1837 | This has symmetry with normal static arrays, in that an array of | |
1838 | unknown size is also written with @code{[]}. | |
1839 | ||
1840 | Of course, this extension only makes sense if the extra data comes at | |
1841 | the end of a top-level object, as otherwise we would be overwriting | |
1842 | data at subsequent offsets. To avoid undue complication and confusion | |
1843 | with initialization of deeply nested arrays, we simply disallow any | |
1844 | non-empty initialization except when the structure is the top-level | |
1845 | object. For example: | |
1846 | ||
1847 | @smallexample | |
1848 | struct foo @{ int x; int y[]; @}; | |
1849 | struct bar @{ struct foo z; @}; | |
1850 | ||
1851 | struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} | |
1852 | struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} | |
1853 | struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} | |
1854 | struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} | |
1855 | @end smallexample | |
1856 | ||
1857 | @node Empty Structures | |
1858 | @section Structures with No Members | |
1859 | @cindex empty structures | |
1860 | @cindex zero-size structures | |
1861 | ||
1862 | GCC permits a C structure to have no members: | |
1863 | ||
1864 | @smallexample | |
1865 | struct empty @{ | |
1866 | @}; | |
1867 | @end smallexample | |
1868 | ||
1869 | The structure has size zero. In C++, empty structures are part | |
1870 | of the language. G++ treats empty structures as if they had a single | |
1871 | member of type @code{char}. | |
1872 | ||
1873 | @node Variable Length | |
1874 | @section Arrays of Variable Length | |
1875 | @cindex variable-length arrays | |
1876 | @cindex arrays of variable length | |
1877 | @cindex VLAs | |
1878 | ||
1879 | Variable-length automatic arrays are allowed in ISO C99, and as an | |
1880 | extension GCC accepts them in C90 mode and in C++. These arrays are | |
1881 | declared like any other automatic arrays, but with a length that is not | |
1882 | a constant expression. The storage is allocated at the point of | |
1883 | declaration and deallocated when the block scope containing the declaration | |
1884 | exits. For | |
1885 | example: | |
1886 | ||
1887 | @smallexample | |
1888 | FILE * | |
1889 | concat_fopen (char *s1, char *s2, char *mode) | |
1890 | @{ | |
1891 | char str[strlen (s1) + strlen (s2) + 1]; | |
1892 | strcpy (str, s1); | |
1893 | strcat (str, s2); | |
1894 | return fopen (str, mode); | |
1895 | @} | |
1896 | @end smallexample | |
1897 | ||
1898 | @cindex scope of a variable length array | |
1899 | @cindex variable-length array scope | |
1900 | @cindex deallocating variable length arrays | |
1901 | Jumping or breaking out of the scope of the array name deallocates the | |
1902 | storage. Jumping into the scope is not allowed; you get an error | |
1903 | message for it. | |
1904 | ||
1905 | @cindex variable-length array in a structure | |
1906 | As an extension, GCC accepts variable-length arrays as a member of | |
1907 | a structure or a union. For example: | |
1908 | ||
1909 | @smallexample | |
1910 | void | |
1911 | foo (int n) | |
1912 | @{ | |
1913 | struct S @{ int x[n]; @}; | |
1914 | @} | |
1915 | @end smallexample | |
1916 | ||
1917 | @cindex @code{alloca} vs variable-length arrays | |
1918 | You can use the function @code{alloca} to get an effect much like | |
1919 | variable-length arrays. The function @code{alloca} is available in | |
1920 | many other C implementations (but not in all). On the other hand, | |
1921 | variable-length arrays are more elegant. | |
1922 | ||
1923 | There are other differences between these two methods. Space allocated | |
1924 | with @code{alloca} exists until the containing @emph{function} returns. | |
1925 | The space for a variable-length array is deallocated as soon as the array | |
1926 | name's scope ends, unless you also use @code{alloca} in this scope. | |
1927 | ||
1928 | You can also use variable-length arrays as arguments to functions: | |
1929 | ||
1930 | @smallexample | |
1931 | struct entry | |
1932 | tester (int len, char data[len][len]) | |
1933 | @{ | |
1934 | /* @r{@dots{}} */ | |
1935 | @} | |
1936 | @end smallexample | |
1937 | ||
1938 | The length of an array is computed once when the storage is allocated | |
1939 | and is remembered for the scope of the array in case you access it with | |
1940 | @code{sizeof}. | |
1941 | ||
1942 | If you want to pass the array first and the length afterward, you can | |
1943 | use a forward declaration in the parameter list---another GNU extension. | |
1944 | ||
1945 | @smallexample | |
1946 | struct entry | |
1947 | tester (int len; char data[len][len], int len) | |
1948 | @{ | |
1949 | /* @r{@dots{}} */ | |
1950 | @} | |
1951 | @end smallexample | |
1952 | ||
1953 | @cindex parameter forward declaration | |
1954 | The @samp{int len} before the semicolon is a @dfn{parameter forward | |
1955 | declaration}, and it serves the purpose of making the name @code{len} | |
1956 | known when the declaration of @code{data} is parsed. | |
1957 | ||
1958 | You can write any number of such parameter forward declarations in the | |
1959 | parameter list. They can be separated by commas or semicolons, but the | |
1960 | last one must end with a semicolon, which is followed by the ``real'' | |
1961 | parameter declarations. Each forward declaration must match a ``real'' | |
1962 | declaration in parameter name and data type. ISO C99 does not support | |
1963 | parameter forward declarations. | |
1964 | ||
1965 | @node Variadic Macros | |
1966 | @section Macros with a Variable Number of Arguments. | |
1967 | @cindex variable number of arguments | |
1968 | @cindex macro with variable arguments | |
1969 | @cindex rest argument (in macro) | |
1970 | @cindex variadic macros | |
1971 | ||
1972 | In the ISO C standard of 1999, a macro can be declared to accept a | |
1973 | variable number of arguments much as a function can. The syntax for | |
1974 | defining the macro is similar to that of a function. Here is an | |
1975 | example: | |
1976 | ||
1977 | @smallexample | |
1978 | #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) | |
1979 | @end smallexample | |
1980 | ||
1981 | @noindent | |
1982 | Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of | |
1983 | such a macro, it represents the zero or more tokens until the closing | |
1984 | parenthesis that ends the invocation, including any commas. This set of | |
1985 | tokens replaces the identifier @code{__VA_ARGS__} in the macro body | |
1986 | wherever it appears. See the CPP manual for more information. | |
1987 | ||
1988 | GCC has long supported variadic macros, and used a different syntax that | |
1989 | allowed you to give a name to the variable arguments just like any other | |
1990 | argument. Here is an example: | |
1991 | ||
1992 | @smallexample | |
1993 | #define debug(format, args...) fprintf (stderr, format, args) | |
1994 | @end smallexample | |
1995 | ||
1996 | @noindent | |
1997 | This is in all ways equivalent to the ISO C example above, but arguably | |
1998 | more readable and descriptive. | |
1999 | ||
2000 | GNU CPP has two further variadic macro extensions, and permits them to | |
2001 | be used with either of the above forms of macro definition. | |
2002 | ||
2003 | In standard C, you are not allowed to leave the variable argument out | |
2004 | entirely; but you are allowed to pass an empty argument. For example, | |
2005 | this invocation is invalid in ISO C, because there is no comma after | |
2006 | the string: | |
2007 | ||
2008 | @smallexample | |
2009 | debug ("A message") | |
2010 | @end smallexample | |
2011 | ||
2012 | GNU CPP permits you to completely omit the variable arguments in this | |
2013 | way. In the above examples, the compiler would complain, though since | |
2014 | the expansion of the macro still has the extra comma after the format | |
2015 | string. | |
2016 | ||
2017 | To help solve this problem, CPP behaves specially for variable arguments | |
2018 | used with the token paste operator, @samp{##}. If instead you write | |
2019 | ||
2020 | @smallexample | |
2021 | #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) | |
2022 | @end smallexample | |
2023 | ||
2024 | @noindent | |
2025 | and if the variable arguments are omitted or empty, the @samp{##} | |
2026 | operator causes the preprocessor to remove the comma before it. If you | |
2027 | do provide some variable arguments in your macro invocation, GNU CPP | |
2028 | does not complain about the paste operation and instead places the | |
2029 | variable arguments after the comma. Just like any other pasted macro | |
2030 | argument, these arguments are not macro expanded. | |
2031 | ||
2032 | @node Escaped Newlines | |
2033 | @section Slightly Looser Rules for Escaped Newlines | |
2034 | @cindex escaped newlines | |
2035 | @cindex newlines (escaped) | |
2036 | ||
2037 | The preprocessor treatment of escaped newlines is more relaxed | |
2038 | than that specified by the C90 standard, which requires the newline | |
2039 | to immediately follow a backslash. | |
2040 | GCC's implementation allows whitespace in the form | |
2041 | of spaces, horizontal and vertical tabs, and form feeds between the | |
2042 | backslash and the subsequent newline. The preprocessor issues a | |
2043 | warning, but treats it as a valid escaped newline and combines the two | |
2044 | lines to form a single logical line. This works within comments and | |
2045 | tokens, as well as between tokens. Comments are @emph{not} treated as | |
2046 | whitespace for the purposes of this relaxation, since they have not | |
2047 | yet been replaced with spaces. | |
2048 | ||
2049 | @node Subscripting | |
2050 | @section Non-Lvalue Arrays May Have Subscripts | |
2051 | @cindex subscripting | |
2052 | @cindex arrays, non-lvalue | |
2053 | ||
2054 | @cindex subscripting and function values | |
2055 | In ISO C99, arrays that are not lvalues still decay to pointers, and | |
2056 | may be subscripted, although they may not be modified or used after | |
2057 | the next sequence point and the unary @samp{&} operator may not be | |
2058 | applied to them. As an extension, GNU C allows such arrays to be | |
2059 | subscripted in C90 mode, though otherwise they do not decay to | |
2060 | pointers outside C99 mode. For example, | |
2061 | this is valid in GNU C though not valid in C90: | |
2062 | ||
2063 | @smallexample | |
2064 | @group | |
2065 | struct foo @{int a[4];@}; | |
2066 | ||
2067 | struct foo f(); | |
2068 | ||
2069 | bar (int index) | |
2070 | @{ | |
2071 | return f().a[index]; | |
2072 | @} | |
2073 | @end group | |
2074 | @end smallexample | |
2075 | ||
2076 | @node Pointer Arith | |
2077 | @section Arithmetic on @code{void}- and Function-Pointers | |
2078 | @cindex void pointers, arithmetic | |
2079 | @cindex void, size of pointer to | |
2080 | @cindex function pointers, arithmetic | |
2081 | @cindex function, size of pointer to | |
2082 | ||
2083 | In GNU C, addition and subtraction operations are supported on pointers to | |
2084 | @code{void} and on pointers to functions. This is done by treating the | |
2085 | size of a @code{void} or of a function as 1. | |
2086 | ||
2087 | A consequence of this is that @code{sizeof} is also allowed on @code{void} | |
2088 | and on function types, and returns 1. | |
2089 | ||
2090 | @opindex Wpointer-arith | |
2091 | The option @option{-Wpointer-arith} requests a warning if these extensions | |
2092 | are used. | |
2093 | ||
2094 | @node Variadic Pointer Args | |
2095 | @section Pointer Arguments in Variadic Functions | |
2096 | @cindex pointer arguments in variadic functions | |
2097 | @cindex variadic functions, pointer arguments | |
2098 | ||
2099 | Standard C requires that pointer types used with @code{va_arg} in | |
2100 | functions with variable argument lists either must be compatible with | |
2101 | that of the actual argument, or that one type must be a pointer to | |
2102 | @code{void} and the other a pointer to a character type. GNU C | |
2103 | implements the POSIX XSI extension that additionally permits the use | |
2104 | of @code{va_arg} with a pointer type to receive arguments of any other | |
2105 | pointer type. | |
2106 | ||
2107 | In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used | |
2108 | to consume an argument of any pointer type. | |
2109 | ||
2110 | @node Pointers to Arrays | |
2111 | @section Pointers to Arrays with Qualifiers Work as Expected | |
2112 | @cindex pointers to arrays | |
2113 | @cindex const qualifier | |
2114 | ||
2115 | In GNU C, pointers to arrays with qualifiers work similar to pointers | |
2116 | to other qualified types. For example, a value of type @code{int (*)[5]} | |
2117 | can be used to initialize a variable of type @code{const int (*)[5]}. | |
2118 | These types are incompatible in ISO C because the @code{const} qualifier | |
2119 | is formally attached to the element type of the array and not the | |
2120 | array itself. | |
2121 | ||
2122 | @smallexample | |
2123 | extern void | |
2124 | transpose (int N, int M, double out[M][N], const double in[N][M]); | |
2125 | double x[3][2]; | |
2126 | double y[2][3]; | |
2127 | @r{@dots{}} | |
2128 | transpose(3, 2, y, x); | |
2129 | @end smallexample | |
2130 | ||
2131 | @node Initializers | |
2132 | @section Non-Constant Initializers | |
2133 | @cindex initializers, non-constant | |
2134 | @cindex non-constant initializers | |
2135 | ||
2136 | As in standard C++ and ISO C99, the elements of an aggregate initializer for an | |
2137 | automatic variable are not required to be constant expressions in GNU C@. | |
2138 | Here is an example of an initializer with run-time varying elements: | |
2139 | ||
2140 | @smallexample | |
2141 | foo (float f, float g) | |
2142 | @{ | |
2143 | float beat_freqs[2] = @{ f-g, f+g @}; | |
2144 | /* @r{@dots{}} */ | |
2145 | @} | |
2146 | @end smallexample | |
2147 | ||
2148 | @node Compound Literals | |
2149 | @section Compound Literals | |
2150 | @cindex constructor expressions | |
2151 | @cindex initializations in expressions | |
2152 | @cindex structures, constructor expression | |
2153 | @cindex expressions, constructor | |
2154 | @cindex compound literals | |
2155 | @c The GNU C name for what C99 calls compound literals was "constructor expressions". | |
2156 | ||
2157 | A compound literal looks like a cast of a brace-enclosed aggregate | |
2158 | initializer list. Its value is an object of the type specified in | |
2159 | the cast, containing the elements specified in the initializer. | |
2160 | Unlike the result of a cast, a compound literal is an lvalue. ISO | |
2161 | C99 and later support compound literals. As an extension, GCC | |
2162 | supports compound literals also in C90 mode and in C++, although | |
2163 | as explained below, the C++ semantics are somewhat different. | |
2164 | ||
2165 | Usually, the specified type of a compound literal is a structure. Assume | |
2166 | that @code{struct foo} and @code{structure} are declared as shown: | |
2167 | ||
2168 | @smallexample | |
2169 | struct foo @{int a; char b[2];@} structure; | |
2170 | @end smallexample | |
2171 | ||
2172 | @noindent | |
2173 | Here is an example of constructing a @code{struct foo} with a compound literal: | |
2174 | ||
2175 | @smallexample | |
2176 | structure = ((struct foo) @{x + y, 'a', 0@}); | |
2177 | @end smallexample | |
2178 | ||
2179 | @noindent | |
2180 | This is equivalent to writing the following: | |
2181 | ||
2182 | @smallexample | |
2183 | @{ | |
2184 | struct foo temp = @{x + y, 'a', 0@}; | |
2185 | structure = temp; | |
2186 | @} | |
2187 | @end smallexample | |
2188 | ||
2189 | You can also construct an array, though this is dangerous in C++, as | |
2190 | explained below. If all the elements of the compound literal are | |
2191 | (made up of) simple constant expressions suitable for use in | |
2192 | initializers of objects of static storage duration, then the compound | |
2193 | literal can be coerced to a pointer to its first element and used in | |
2194 | such an initializer, as shown here: | |
2195 | ||
2196 | @smallexample | |
2197 | char **foo = (char *[]) @{ "x", "y", "z" @}; | |
2198 | @end smallexample | |
2199 | ||
2200 | Compound literals for scalar types and union types are also allowed. In | |
2201 | the following example the variable @code{i} is initialized to the value | |
2202 | @code{2}, the result of incrementing the unnamed object created by | |
2203 | the compound literal. | |
2204 | ||
2205 | @smallexample | |
2206 | int i = ++(int) @{ 1 @}; | |
2207 | @end smallexample | |
2208 | ||
2209 | As a GNU extension, GCC allows initialization of objects with static storage | |
2210 | duration by compound literals (which is not possible in ISO C99 because | |
2211 | the initializer is not a constant). | |
2212 | It is handled as if the object were initialized only with the brace-enclosed | |
2213 | list if the types of the compound literal and the object match. | |
2214 | The elements of the compound literal must be constant. | |
2215 | If the object being initialized has array type of unknown size, the size is | |
2216 | determined by the size of the compound literal. | |
2217 | ||
2218 | @smallexample | |
2219 | static struct foo x = (struct foo) @{1, 'a', 'b'@}; | |
2220 | static int y[] = (int []) @{1, 2, 3@}; | |
2221 | static int z[] = (int [3]) @{1@}; | |
2222 | @end smallexample | |
2223 | ||
2224 | @noindent | |
2225 | The above lines are equivalent to the following: | |
2226 | @smallexample | |
2227 | static struct foo x = @{1, 'a', 'b'@}; | |
2228 | static int y[] = @{1, 2, 3@}; | |
2229 | static int z[] = @{1, 0, 0@}; | |
2230 | @end smallexample | |
2231 | ||
2232 | In C, a compound literal designates an unnamed object with static or | |
2233 | automatic storage duration. In C++, a compound literal designates a | |
2234 | temporary object that only lives until the end of its full-expression. | |
2235 | As a result, well-defined C code that takes the address of a subobject | |
2236 | of a compound literal can be undefined in C++, so G++ rejects | |
2237 | the conversion of a temporary array to a pointer. For instance, if | |
2238 | the array compound literal example above appeared inside a function, | |
2239 | any subsequent use of @code{foo} in C++ would have undefined behavior | |
2240 | because the lifetime of the array ends after the declaration of @code{foo}. | |
2241 | ||
2242 | As an optimization, G++ sometimes gives array compound literals longer | |
2243 | lifetimes: when the array either appears outside a function or has | |
2244 | a @code{const}-qualified type. If @code{foo} and its initializer had | |
2245 | elements of type @code{char *const} rather than @code{char *}, or if | |
2246 | @code{foo} were a global variable, the array would have static storage | |
2247 | duration. But it is probably safest just to avoid the use of array | |
2248 | compound literals in C++ code. | |
2249 | ||
2250 | @node Designated Inits | |
2251 | @section Designated Initializers | |
2252 | @cindex initializers with labeled elements | |
2253 | @cindex labeled elements in initializers | |
2254 | @cindex case labels in initializers | |
2255 | @cindex designated initializers | |
2256 | ||
2257 | Standard C90 requires the elements of an initializer to appear in a fixed | |
2258 | order, the same as the order of the elements in the array or structure | |
2259 | being initialized. | |
2260 | ||
2261 | In ISO C99 you can give the elements in any order, specifying the array | |
2262 | indices or structure field names they apply to, and GNU C allows this as | |
2263 | an extension in C90 mode as well. This extension is not | |
2264 | implemented in GNU C++. | |
2265 | ||
2266 | To specify an array index, write | |
2267 | @samp{[@var{index}] =} before the element value. For example, | |
2268 | ||
2269 | @smallexample | |
2270 | int a[6] = @{ [4] = 29, [2] = 15 @}; | |
2271 | @end smallexample | |
2272 | ||
2273 | @noindent | |
2274 | is equivalent to | |
2275 | ||
2276 | @smallexample | |
2277 | int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; | |
2278 | @end smallexample | |
2279 | ||
2280 | @noindent | |
2281 | The index values must be constant expressions, even if the array being | |
2282 | initialized is automatic. | |
2283 | ||
2284 | An alternative syntax for this that has been obsolete since GCC 2.5 but | |
2285 | GCC still accepts is to write @samp{[@var{index}]} before the element | |
2286 | value, with no @samp{=}. | |
2287 | ||
2288 | To initialize a range of elements to the same value, write | |
2289 | @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU | |
2290 | extension. For example, | |
2291 | ||
2292 | @smallexample | |
2293 | int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; | |
2294 | @end smallexample | |
2295 | ||
2296 | @noindent | |
2297 | If the value in it has side effects, the side effects happen only once, | |
2298 | not for each initialized field by the range initializer. | |
2299 | ||
2300 | @noindent | |
2301 | Note that the length of the array is the highest value specified | |
2302 | plus one. | |
2303 | ||
2304 | In a structure initializer, specify the name of a field to initialize | |
2305 | with @samp{.@var{fieldname} =} before the element value. For example, | |
2306 | given the following structure, | |
2307 | ||
2308 | @smallexample | |
2309 | struct point @{ int x, y; @}; | |
2310 | @end smallexample | |
2311 | ||
2312 | @noindent | |
2313 | the following initialization | |
2314 | ||
2315 | @smallexample | |
2316 | struct point p = @{ .y = yvalue, .x = xvalue @}; | |
2317 | @end smallexample | |
2318 | ||
2319 | @noindent | |
2320 | is equivalent to | |
2321 | ||
2322 | @smallexample | |
2323 | struct point p = @{ xvalue, yvalue @}; | |
2324 | @end smallexample | |
2325 | ||
2326 | Another syntax that has the same meaning, obsolete since GCC 2.5, is | |
2327 | @samp{@var{fieldname}:}, as shown here: | |
2328 | ||
2329 | @smallexample | |
2330 | struct point p = @{ y: yvalue, x: xvalue @}; | |
2331 | @end smallexample | |
2332 | ||
2333 | Omitted fields are implicitly initialized the same as for objects | |
2334 | that have static storage duration. | |
2335 | ||
2336 | @cindex designators | |
2337 | The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a | |
2338 | @dfn{designator}. You can also use a designator (or the obsolete colon | |
2339 | syntax) when initializing a union, to specify which element of the union | |
2340 | should be used. For example, | |
2341 | ||
2342 | @smallexample | |
2343 | union foo @{ int i; double d; @}; | |
2344 | ||
2345 | union foo f = @{ .d = 4 @}; | |
2346 | @end smallexample | |
2347 | ||
2348 | @noindent | |
2349 | converts 4 to a @code{double} to store it in the union using | |
2350 | the second element. By contrast, casting 4 to type @code{union foo} | |
2351 | stores it into the union as the integer @code{i}, since it is | |
2352 | an integer. @xref{Cast to Union}. | |
2353 | ||
2354 | You can combine this technique of naming elements with ordinary C | |
2355 | initialization of successive elements. Each initializer element that | |
2356 | does not have a designator applies to the next consecutive element of the | |
2357 | array or structure. For example, | |
2358 | ||
2359 | @smallexample | |
2360 | int a[6] = @{ [1] = v1, v2, [4] = v4 @}; | |
2361 | @end smallexample | |
2362 | ||
2363 | @noindent | |
2364 | is equivalent to | |
2365 | ||
2366 | @smallexample | |
2367 | int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; | |
2368 | @end smallexample | |
2369 | ||
2370 | Labeling the elements of an array initializer is especially useful | |
2371 | when the indices are characters or belong to an @code{enum} type. | |
2372 | For example: | |
2373 | ||
2374 | @smallexample | |
2375 | int whitespace[256] | |
2376 | = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, | |
2377 | ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; | |
2378 | @end smallexample | |
2379 | ||
2380 | @cindex designator lists | |
2381 | You can also write a series of @samp{.@var{fieldname}} and | |
2382 | @samp{[@var{index}]} designators before an @samp{=} to specify a | |
2383 | nested subobject to initialize; the list is taken relative to the | |
2384 | subobject corresponding to the closest surrounding brace pair. For | |
2385 | example, with the @samp{struct point} declaration above: | |
2386 | ||
2387 | @smallexample | |
2388 | struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; | |
2389 | @end smallexample | |
2390 | ||
2391 | If the same field is initialized multiple times, or overlapping | |
2392 | fields of a union are initialized, the value from the last | |
2393 | initialization is used. When a field of a union is itself a structure, | |
2394 | the entire structure from the last field initialized is used. If any previous | |
2395 | initializer has side effect, it is unspecified whether the side effect | |
2396 | happens or not. Currently, GCC discards the side-effecting | |
2397 | initializer expressions and issues a warning. | |
2398 | ||
2399 | @node Case Ranges | |
2400 | @section Case Ranges | |
2401 | @cindex case ranges | |
2402 | @cindex ranges in case statements | |
2403 | ||
2404 | You can specify a range of consecutive values in a single @code{case} label, | |
2405 | like this: | |
2406 | ||
2407 | @smallexample | |
2408 | case @var{low} ... @var{high}: | |
2409 | @end smallexample | |
2410 | ||
2411 | @noindent | |
2412 | This has the same effect as the proper number of individual @code{case} | |
2413 | labels, one for each integer value from @var{low} to @var{high}, inclusive. | |
2414 | ||
2415 | This feature is especially useful for ranges of ASCII character codes: | |
2416 | ||
2417 | @smallexample | |
2418 | case 'A' ... 'Z': | |
2419 | @end smallexample | |
2420 | ||
2421 | @strong{Be careful:} Write spaces around the @code{...}, for otherwise | |
2422 | it may be parsed wrong when you use it with integer values. For example, | |
2423 | write this: | |
2424 | ||
2425 | @smallexample | |
2426 | case 1 ... 5: | |
2427 | @end smallexample | |
2428 | ||
2429 | @noindent | |
2430 | rather than this: | |
2431 | ||
2432 | @smallexample | |
2433 | case 1...5: | |
2434 | @end smallexample | |
2435 | ||
2436 | @node Cast to Union | |
2437 | @section Cast to a Union Type | |
2438 | @cindex cast to a union | |
2439 | @cindex union, casting to a | |
2440 | ||
2441 | A cast to a union type is a C extension not available in C++. It looks | |
2442 | just like ordinary casts with the constraint that the type specified is | |
2443 | a union type. You can specify the type either with the @code{union} | |
2444 | keyword or with a @code{typedef} name that refers to a union. The result | |
2445 | of a cast to a union is a temporary rvalue of the union type with a member | |
2446 | whose type matches that of the operand initialized to the value of | |
2447 | the operand. The effect of a cast to a union is similar to a compound | |
2448 | literal except that it yields an rvalue like standard casts do. | |
2449 | @xref{Compound Literals}. | |
2450 | ||
2451 | Expressions that may be cast to the union type are those whose type matches | |
2452 | at least one of the members of the union. Thus, given the following union | |
2453 | and variables: | |
2454 | ||
2455 | @smallexample | |
2456 | union foo @{ int i; double d; @}; | |
2457 | int x; | |
2458 | double y; | |
2459 | union foo z; | |
2460 | @end smallexample | |
2461 | ||
2462 | @noindent | |
2463 | both @code{x} and @code{y} can be cast to type @code{union foo} and | |
2464 | the following assignments | |
2465 | @smallexample | |
2466 | z = (union foo) x; | |
2467 | z = (union foo) y; | |
2468 | @end smallexample | |
2469 | are shorthand equivalents of these | |
2470 | @smallexample | |
2471 | z = (union foo) @{ .i = x @}; | |
2472 | z = (union foo) @{ .d = y @}; | |
2473 | @end smallexample | |
2474 | ||
2475 | However, @code{(union foo) FLT_MAX;} is not a valid cast because the union | |
2476 | has no member of type @code{float}. | |
2477 | ||
2478 | Using the cast as the right-hand side of an assignment to a variable of | |
2479 | union type is equivalent to storing in a member of the union with | |
2480 | the same type | |
2481 | ||
2482 | @smallexample | |
2483 | union foo u; | |
2484 | /* @r{@dots{}} */ | |
2485 | u = (union foo) x @equiv{} u.i = x | |
2486 | u = (union foo) y @equiv{} u.d = y | |
2487 | @end smallexample | |
2488 | ||
2489 | You can also use the union cast as a function argument: | |
2490 | ||
2491 | @smallexample | |
2492 | void hack (union foo); | |
2493 | /* @r{@dots{}} */ | |
2494 | hack ((union foo) x); | |
2495 | @end smallexample | |
2496 | ||
2497 | @node Mixed Labels and Declarations | |
2498 | @section Mixed Declarations, Labels and Code | |
2499 | @cindex mixed declarations and code | |
2500 | @cindex declarations, mixed with code | |
2501 | @cindex code, mixed with declarations | |
2502 | ||
2503 | ISO C99 and ISO C++ allow declarations and code to be freely mixed | |
094a609c | 2504 | within compound statements. ISO C23 allows labels to be |
d77de738 ML |
2505 | placed before declarations and at the end of a compound statement. |
2506 | As an extension, GNU C also allows all this in C90 mode. For example, | |
2507 | you could do: | |
2508 | ||
2509 | @smallexample | |
2510 | int i; | |
2511 | /* @r{@dots{}} */ | |
2512 | i++; | |
2513 | int j = i + 2; | |
2514 | @end smallexample | |
2515 | ||
2516 | Each identifier is visible from where it is declared until the end of | |
2517 | the enclosing block. | |
2518 | ||
2519 | @node Function Attributes | |
2520 | @section Declaring Attributes of Functions | |
2521 | @cindex function attributes | |
2522 | @cindex declaring attributes of functions | |
2523 | @cindex @code{volatile} applied to function | |
2524 | @cindex @code{const} applied to function | |
2525 | ||
2526 | In GNU C and C++, you can use function attributes to specify certain | |
2527 | function properties that may help the compiler optimize calls or | |
2528 | check code more carefully for correctness. For example, you | |
2529 | can use attributes to specify that a function never returns | |
2530 | (@code{noreturn}), returns a value depending only on the values of | |
2531 | its arguments (@code{const}), or has @code{printf}-style arguments | |
2532 | (@code{format}). | |
2533 | ||
2534 | You can also use attributes to control memory placement, code | |
2535 | generation options or call/return conventions within the function | |
2536 | being annotated. Many of these attributes are target-specific. For | |
2537 | example, many targets support attributes for defining interrupt | |
2538 | handler functions, which typically must follow special register usage | |
2539 | and return conventions. Such attributes are described in the subsection | |
2540 | for each target. However, a considerable number of attributes are | |
2541 | supported by most, if not all targets. Those are described in | |
2542 | the @ref{Common Function Attributes} section. | |
2543 | ||
837a12a2 SL |
2544 | GCC provides two different ways to specify attributes: the traditional |
2545 | GNU syntax using @samp{__attribute__ ((...))} annotations, and the | |
2546 | newer standard C and C++ syntax using @samp{[[...]]} with the | |
2547 | @samp{gnu::} prefix on attribute names. Note that the exact rules for | |
2548 | placement of attributes in your source code are different depending on | |
2549 | which syntax you use. @xref{Attribute Syntax}, for details. | |
2550 | ||
2551 | Compatible attribute specifications on distinct declarations | |
d77de738 ML |
2552 | of the same function are merged. An attribute specification that is not |
2553 | compatible with attributes already applied to a declaration of the same | |
2554 | function is ignored with a warning. | |
2555 | ||
2556 | Some function attributes take one or more arguments that refer to | |
2557 | the function's parameters by their positions within the function parameter | |
2558 | list. Such attribute arguments are referred to as @dfn{positional arguments}. | |
2559 | Unless specified otherwise, positional arguments that specify properties | |
2560 | of parameters with pointer types can also specify the same properties of | |
2561 | the implicit C++ @code{this} argument in non-static member functions, and | |
2562 | of parameters of reference to a pointer type. For ordinary functions, | |
2563 | position one refers to the first parameter on the list. In C++ non-static | |
2564 | member functions, position one refers to the implicit @code{this} pointer. | |
2565 | The same restrictions and effects apply to function attributes used with | |
2566 | ordinary functions or C++ member functions. | |
2567 | ||
2568 | GCC also supports attributes on | |
2569 | variable declarations (@pxref{Variable Attributes}), | |
2570 | labels (@pxref{Label Attributes}), | |
2571 | enumerators (@pxref{Enumerator Attributes}), | |
2572 | statements (@pxref{Statement Attributes}), | |
2573 | types (@pxref{Type Attributes}), | |
2574 | and on field declarations (for @code{tainted_args}). | |
2575 | ||
2576 | There is some overlap between the purposes of attributes and pragmas | |
2577 | (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been | |
2578 | found convenient to use @code{__attribute__} to achieve a natural | |
2579 | attachment of attributes to their corresponding declarations, whereas | |
2580 | @code{#pragma} is of use for compatibility with other compilers | |
2581 | or constructs that do not naturally form part of the grammar. | |
2582 | ||
2583 | In addition to the attributes documented here, | |
2584 | GCC plugins may provide their own attributes. | |
2585 | ||
2586 | @menu | |
2587 | * Common Function Attributes:: | |
2588 | * AArch64 Function Attributes:: | |
2589 | * AMD GCN Function Attributes:: | |
2590 | * ARC Function Attributes:: | |
2591 | * ARM Function Attributes:: | |
2592 | * AVR Function Attributes:: | |
2593 | * Blackfin Function Attributes:: | |
2594 | * BPF Function Attributes:: | |
2595 | * C-SKY Function Attributes:: | |
2596 | * Epiphany Function Attributes:: | |
2597 | * H8/300 Function Attributes:: | |
2598 | * IA-64 Function Attributes:: | |
2599 | * M32C Function Attributes:: | |
2600 | * M32R/D Function Attributes:: | |
2601 | * m68k Function Attributes:: | |
2602 | * MCORE Function Attributes:: | |
d77de738 ML |
2603 | * MicroBlaze Function Attributes:: |
2604 | * Microsoft Windows Function Attributes:: | |
2605 | * MIPS Function Attributes:: | |
2606 | * MSP430 Function Attributes:: | |
2607 | * NDS32 Function Attributes:: | |
2608 | * Nios II Function Attributes:: | |
2609 | * Nvidia PTX Function Attributes:: | |
2610 | * PowerPC Function Attributes:: | |
2611 | * RISC-V Function Attributes:: | |
2612 | * RL78 Function Attributes:: | |
2613 | * RX Function Attributes:: | |
2614 | * S/390 Function Attributes:: | |
2615 | * SH Function Attributes:: | |
2616 | * Symbian OS Function Attributes:: | |
2617 | * V850 Function Attributes:: | |
2618 | * Visium Function Attributes:: | |
2619 | * x86 Function Attributes:: | |
2620 | * Xstormy16 Function Attributes:: | |
2621 | @end menu | |
2622 | ||
2623 | @node Common Function Attributes | |
2624 | @subsection Common Function Attributes | |
2625 | ||
2626 | The following attributes are supported on most targets. | |
2627 | ||
2628 | @table @code | |
2629 | @c Keep this table alphabetized by attribute name. Treat _ as space. | |
2630 | ||
0aad1da6 | 2631 | @cindex @code{access} function attribute |
d77de738 ML |
2632 | @item access (@var{access-mode}, @var{ref-index}) |
2633 | @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index}) | |
2634 | ||
2635 | The @code{access} attribute enables the detection of invalid or unsafe | |
2636 | accesses by functions to which they apply or their callers, as well as | |
2637 | write-only accesses to objects that are never read from. Such accesses | |
2638 | may be diagnosed by warnings such as @option{-Wstringop-overflow}, | |
2639 | @option{-Wuninitialized}, @option{-Wunused}, and others. | |
2640 | ||
2641 | The @code{access} attribute specifies that a function to whose by-reference | |
2642 | arguments the attribute applies accesses the referenced object according to | |
2643 | @var{access-mode}. The @var{access-mode} argument is required and must be | |
2644 | one of four names: @code{read_only}, @code{read_write}, @code{write_only}, | |
2645 | or @code{none}. The remaining two are positional arguments. | |
2646 | ||
2647 | The required @var{ref-index} positional argument denotes a function | |
2648 | argument of pointer (or in C++, reference) type that is subject to | |
2649 | the access. The same pointer argument can be referenced by at most one | |
2650 | distinct @code{access} attribute. | |
2651 | ||
2652 | The optional @var{size-index} positional argument denotes a function | |
2653 | argument of integer type that specifies the maximum size of the access. | |
2654 | The size is the number of elements of the type referenced by @var{ref-index}, | |
2655 | or the number of bytes when the pointer type is @code{void*}. When no | |
2656 | @var{size-index} argument is specified, the pointer argument must be either | |
2657 | null or point to a space that is suitably aligned and large for at least one | |
2658 | object of the referenced type (this implies that a past-the-end pointer is | |
2659 | not a valid argument). The actual size of the access may be less but it | |
2660 | must not be more. | |
2661 | ||
2662 | The @code{read_only} access mode specifies that the pointer to which it | |
2663 | applies is used to read the referenced object but not write to it. Unless | |
2664 | the argument specifying the size of the access denoted by @var{size-index} | |
2665 | is zero, the referenced object must be initialized. The mode implies | |
2666 | a stronger guarantee than the @code{const} qualifier which, when cast away | |
2667 | from a pointer, does not prevent the pointed-to object from being modified. | |
2668 | Examples of the use of the @code{read_only} access mode is the argument to | |
2669 | the @code{puts} function, or the second and third arguments to | |
2670 | the @code{memcpy} function. | |
2671 | ||
2672 | @smallexample | |
4ace81b6 SL |
2673 | __attribute__ ((access (read_only, 1))) |
2674 | int puts (const char*); | |
2675 | ||
2676 | __attribute__ ((access (read_only, 2, 3))) | |
2677 | void* memcpy (void*, const void*, size_t); | |
d77de738 ML |
2678 | @end smallexample |
2679 | ||
2680 | The @code{read_write} access mode applies to arguments of pointer types | |
2681 | without the @code{const} qualifier. It specifies that the pointer to which | |
2682 | it applies is used to both read and write the referenced object. Unless | |
2683 | the argument specifying the size of the access denoted by @var{size-index} | |
2684 | is zero, the object referenced by the pointer must be initialized. An example | |
2685 | of the use of the @code{read_write} access mode is the first argument to | |
2686 | the @code{strcat} function. | |
2687 | ||
2688 | @smallexample | |
4ace81b6 SL |
2689 | __attribute__ ((access (read_write, 1), access (read_only, 2))) |
2690 | char* strcat (char*, const char*); | |
d77de738 ML |
2691 | @end smallexample |
2692 | ||
2693 | The @code{write_only} access mode applies to arguments of pointer types | |
2694 | without the @code{const} qualifier. It specifies that the pointer to which | |
2695 | it applies is used to write to the referenced object but not read from it. | |
2696 | The object referenced by the pointer need not be initialized. An example | |
2697 | of the use of the @code{write_only} access mode is the first argument to | |
2698 | the @code{strcpy} function, or the first two arguments to the @code{fgets} | |
2699 | function. | |
2700 | ||
2701 | @smallexample | |
4ace81b6 SL |
2702 | __attribute__ ((access (write_only, 1), access (read_only, 2))) |
2703 | char* strcpy (char*, const char*); | |
2704 | ||
2705 | __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) | |
2706 | int fgets (char*, int, FILE*); | |
d77de738 ML |
2707 | @end smallexample |
2708 | ||
2709 | The access mode @code{none} specifies that the pointer to which it applies | |
2710 | is not used to access the referenced object at all. Unless the pointer is | |
2711 | null the pointed-to object must exist and have at least the size as denoted | |
2712 | by the @var{size-index} argument. When the optional @var{size-index} | |
2713 | argument is omitted for an argument of @code{void*} type the actual pointer | |
2714 | agument is ignored. The referenced object need not be initialized. | |
2715 | The mode is intended to be used as a means to help validate the expected | |
2716 | object size, for example in functions that call @code{__builtin_object_size}. | |
2717 | @xref{Object Size Checking}. | |
2718 | ||
2719 | Note that the @code{access} attribute merely specifies how an object | |
2720 | referenced by the pointer argument can be accessed; it does not imply that | |
2721 | an access @strong{will} happen. Also, the @code{access} attribute does not | |
2722 | imply the attribute @code{nonnull}; it may be appropriate to add both attributes | |
2723 | at the declaration of a function that unconditionally manipulates a buffer via | |
2724 | a pointer argument. See the @code{nonnull} attribute for more information and | |
2725 | caveats. | |
2726 | ||
d77de738 | 2727 | @cindex @code{alias} function attribute |
f33d7a88 | 2728 | @item alias ("@var{target}") |
d77de738 ML |
2729 | The @code{alias} attribute causes the declaration to be emitted as an alias |
2730 | for another symbol, which must have been previously declared with the same | |
2731 | type, and for variables, also the same size and alignment. Declaring an alias | |
2732 | with a different type than the target is undefined and may be diagnosed. As | |
2733 | an example, the following declarations: | |
2734 | ||
2735 | @smallexample | |
2736 | void __f () @{ /* @r{Do something.} */; @} | |
2737 | void f () __attribute__ ((weak, alias ("__f"))); | |
2738 | @end smallexample | |
2739 | ||
2740 | @noindent | |
2741 | define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name | |
2742 | for the target must be used. It is an error if @samp{__f} is not defined in | |
2743 | the same translation unit. | |
2744 | ||
2745 | This attribute requires assembler and object file support, | |
2746 | and may not be available on all targets. | |
2747 | ||
f33d7a88 | 2748 | @cindex @code{aligned} function attribute |
d77de738 ML |
2749 | @item aligned |
2750 | @itemx aligned (@var{alignment}) | |
d77de738 ML |
2751 | The @code{aligned} attribute specifies a minimum alignment for |
2752 | the first instruction of the function, measured in bytes. When specified, | |
2753 | @var{alignment} must be an integer constant power of 2. Specifying no | |
2754 | @var{alignment} argument implies the ideal alignment for the target. | |
2755 | The @code{__alignof__} operator can be used to determine what that is | |
2756 | (@pxref{Alignment}). The attribute has no effect when a definition for | |
2757 | the function is not provided in the same translation unit. | |
2758 | ||
2759 | The attribute cannot be used to decrease the alignment of a function | |
2760 | previously declared with a more restrictive alignment; only to increase | |
2761 | it. Attempts to do otherwise are diagnosed. Some targets specify | |
2762 | a minimum default alignment for functions that is greater than 1. On | |
2763 | such targets, specifying a less restrictive alignment is silently ignored. | |
2764 | Using the attribute overrides the effect of the @option{-falign-functions} | |
2765 | (@pxref{Optimize Options}) option for this function. | |
2766 | ||
2767 | Note that the effectiveness of @code{aligned} attributes may be | |
2768 | limited by inherent limitations in the system linker | |
2769 | and/or object file format. On some systems, the | |
2770 | linker is only able to arrange for functions to be aligned up to a | |
2771 | certain maximum alignment. (For some linkers, the maximum supported | |
2772 | alignment may be very very small.) See your linker documentation for | |
2773 | further information. | |
2774 | ||
2775 | The @code{aligned} attribute can also be used for variables and fields | |
2776 | (@pxref{Variable Attributes}.) | |
2777 | ||
d77de738 | 2778 | @cindex @code{alloc_align} function attribute |
f33d7a88 | 2779 | @item alloc_align (@var{position}) |
d77de738 ML |
2780 | The @code{alloc_align} attribute may be applied to a function that |
2781 | returns a pointer and takes at least one argument of an integer or | |
2782 | enumerated type. | |
2783 | It indicates that the returned pointer is aligned on a boundary given | |
2784 | by the function argument at @var{position}. Meaningful alignments are | |
2785 | powers of 2 greater than one. GCC uses this information to improve | |
2786 | pointer alignment analysis. | |
2787 | ||
2788 | The function parameter denoting the allocated alignment is specified by | |
2789 | one constant integer argument whose number is the argument of the attribute. | |
2790 | Argument numbering starts at one. | |
2791 | ||
2792 | For instance, | |
2793 | ||
2794 | @smallexample | |
2795 | void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1))); | |
2796 | @end smallexample | |
2797 | ||
2798 | @noindent | |
2799 | declares that @code{my_memalign} returns memory with minimum alignment | |
2800 | given by parameter 1. | |
2801 | ||
f33d7a88 | 2802 | @cindex @code{alloc_size} function attribute |
d77de738 ML |
2803 | @item alloc_size (@var{position}) |
2804 | @itemx alloc_size (@var{position-1}, @var{position-2}) | |
d77de738 ML |
2805 | The @code{alloc_size} attribute may be applied to a function that |
2806 | returns a pointer and takes at least one argument of an integer or | |
2807 | enumerated type. | |
2808 | It indicates that the returned pointer points to memory whose size is | |
2809 | given by the function argument at @var{position-1}, or by the product | |
2810 | of the arguments at @var{position-1} and @var{position-2}. Meaningful | |
2811 | sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this | |
2812 | information to improve the results of @code{__builtin_object_size}. | |
2813 | ||
2814 | The function parameter(s) denoting the allocated size are specified by | |
2815 | one or two integer arguments supplied to the attribute. The allocated size | |
2816 | is either the value of the single function argument specified or the product | |
2817 | of the two function arguments specified. Argument numbering starts at | |
2818 | one for ordinary functions, and at two for C++ non-static member functions. | |
2819 | ||
2820 | For instance, | |
2821 | ||
2822 | @smallexample | |
2823 | void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2))); | |
2824 | void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2))); | |
2825 | @end smallexample | |
2826 | ||
2827 | @noindent | |
2828 | declares that @code{my_calloc} returns memory of the size given by | |
2829 | the product of parameter 1 and 2 and that @code{my_realloc} returns memory | |
2830 | of the size given by parameter 2. | |
2831 | ||
d77de738 | 2832 | @cindex @code{always_inline} function attribute |
f33d7a88 | 2833 | @item always_inline |
d77de738 ML |
2834 | Generally, functions are not inlined unless optimization is specified. |
2835 | For functions declared inline, this attribute inlines the function | |
2836 | independent of any restrictions that otherwise apply to inlining. | |
2837 | Failure to inline such a function is diagnosed as an error. | |
2838 | Note that if such a function is called indirectly the compiler may | |
2839 | or may not inline it depending on optimization level and a failure | |
2840 | to inline an indirect call may or may not be diagnosed. | |
2841 | ||
d77de738 | 2842 | @cindex @code{artificial} function attribute |
f33d7a88 | 2843 | @item artificial |
d77de738 ML |
2844 | This attribute is useful for small inline wrappers that if possible |
2845 | should appear during debugging as a unit. Depending on the debug | |
2846 | info format it either means marking the function as artificial | |
2847 | or using the caller location for all instructions within the inlined | |
2848 | body. | |
2849 | ||
f33d7a88 | 2850 | @cindex @code{assume_aligned} function attribute |
d77de738 ML |
2851 | @item assume_aligned (@var{alignment}) |
2852 | @itemx assume_aligned (@var{alignment}, @var{offset}) | |
d77de738 ML |
2853 | The @code{assume_aligned} attribute may be applied to a function that |
2854 | returns a pointer. It indicates that the returned pointer is aligned | |
2855 | on a boundary given by @var{alignment}. If the attribute has two | |
2856 | arguments, the second argument is misalignment @var{offset}. Meaningful | |
2857 | values of @var{alignment} are powers of 2 greater than one. Meaningful | |
2858 | values of @var{offset} are greater than zero and less than @var{alignment}. | |
2859 | ||
2860 | For instance | |
2861 | ||
2862 | @smallexample | |
2863 | void* my_alloc1 (size_t) __attribute__((assume_aligned (16))); | |
2864 | void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8))); | |
2865 | @end smallexample | |
2866 | ||
2867 | @noindent | |
2868 | declares that @code{my_alloc1} returns 16-byte aligned pointers and | |
2869 | that @code{my_alloc2} returns a pointer whose value modulo 32 is equal | |
2870 | to 8. | |
2871 | ||
d77de738 | 2872 | @cindex @code{cold} function attribute |
f33d7a88 | 2873 | @item cold |
d77de738 ML |
2874 | The @code{cold} attribute on functions is used to inform the compiler that |
2875 | the function is unlikely to be executed. The function is optimized for | |
2876 | size rather than speed and on many targets it is placed into a special | |
2877 | subsection of the text section so all cold functions appear close together, | |
2878 | improving code locality of non-cold parts of program. The paths leading | |
2879 | to calls of cold functions within code are marked as unlikely by the branch | |
2880 | prediction mechanism. It is thus useful to mark functions used to handle | |
2881 | unlikely conditions, such as @code{perror}, as cold to improve optimization | |
4f52e61e JM |
2882 | of hot functions that do call marked functions in rare occasions. In C++, |
2883 | the @code{cold} attribute can be applied to types with the effect of being | |
2884 | propagated to member functions. See | |
2885 | @ref{C++ Attributes}. | |
d77de738 ML |
2886 | |
2887 | When profile feedback is available, via @option{-fprofile-use}, cold functions | |
2888 | are automatically detected and this attribute is ignored. | |
2889 | ||
d77de738 ML |
2890 | @cindex @code{const} function attribute |
2891 | @cindex functions that have no side effects | |
f33d7a88 | 2892 | @item const |
d77de738 ML |
2893 | Calls to functions whose return value is not affected by changes to |
2894 | the observable state of the program and that have no observable effects | |
2895 | on such state other than to return a value may lend themselves to | |
2896 | optimizations such as common subexpression elimination. Declaring such | |
2897 | functions with the @code{const} attribute allows GCC to avoid emitting | |
2898 | some calls in repeated invocations of the function with the same argument | |
2899 | values. | |
2900 | ||
2901 | For example, | |
2902 | ||
2903 | @smallexample | |
2904 | int square (int) __attribute__ ((const)); | |
2905 | @end smallexample | |
2906 | ||
2907 | @noindent | |
2908 | tells GCC that subsequent calls to function @code{square} with the same | |
2909 | argument value can be replaced by the result of the first call regardless | |
2910 | of the statements in between. | |
2911 | ||
2912 | The @code{const} attribute prohibits a function from reading objects | |
2913 | that affect its return value between successive invocations. However, | |
2914 | functions declared with the attribute can safely read objects that do | |
2915 | not change their return value, such as non-volatile constants. | |
2916 | ||
2917 | The @code{const} attribute imposes greater restrictions on a function's | |
2918 | definition than the similar @code{pure} attribute. Declaring the same | |
2919 | function with both the @code{const} and the @code{pure} attribute is | |
2920 | diagnosed. Because a const function cannot have any observable side | |
2921 | effects it does not make sense for it to return @code{void}. Declaring | |
2922 | such a function is diagnosed. | |
2923 | ||
2924 | @cindex pointer arguments | |
2925 | Note that a function that has pointer arguments and examines the data | |
2926 | pointed to must @emph{not} be declared @code{const} if the pointed-to | |
2927 | data might change between successive invocations of the function. In | |
2928 | general, since a function cannot distinguish data that might change | |
2929 | from data that cannot, const functions should never take pointer or, | |
2930 | in C++, reference arguments. Likewise, a function that calls a non-const | |
2931 | function usually must not be const itself. | |
2932 | ||
f33d7a88 AA |
2933 | @cindex @code{constructor} function attribute |
2934 | @cindex @code{destructor} function attribute | |
d77de738 ML |
2935 | @item constructor |
2936 | @itemx destructor | |
2937 | @itemx constructor (@var{priority}) | |
2938 | @itemx destructor (@var{priority}) | |
d77de738 ML |
2939 | The @code{constructor} attribute causes the function to be called |
2940 | automatically before execution enters @code{main ()}. Similarly, the | |
2941 | @code{destructor} attribute causes the function to be called | |
2942 | automatically after @code{main ()} completes or @code{exit ()} is | |
2943 | called. Functions with these attributes are useful for | |
2944 | initializing data that is used implicitly during the execution of | |
2945 | the program. | |
2946 | ||
2947 | On some targets the attributes also accept an integer argument to | |
2948 | specify a priority to control the order in which constructor and | |
2949 | destructor functions are run. A constructor | |
2950 | with a smaller priority number runs before a constructor with a larger | |
2951 | priority number; the opposite relationship holds for destructors. Note | |
2952 | that priorities 0-100 are reserved. So, if you have a constructor that | |
2953 | allocates a resource and a destructor that deallocates the same | |
2954 | resource, both functions typically have the same priority. The | |
2955 | priorities for constructor and destructor functions are the same as | |
2956 | those specified for namespace-scope C++ objects (@pxref{C++ Attributes}). | |
2957 | However, at present, the order in which constructors for C++ objects | |
2958 | with static storage duration and functions decorated with attribute | |
2959 | @code{constructor} are invoked is unspecified. In mixed declarations, | |
2960 | attribute @code{init_priority} can be used to impose a specific ordering. | |
2961 | ||
2962 | Using the argument forms of the @code{constructor} and @code{destructor} | |
2963 | attributes on targets where the feature is not supported is rejected with | |
2964 | an error. | |
2965 | ||
f33d7a88 | 2966 | @cindex @code{copy} function attribute |
d77de738 ML |
2967 | @item copy |
2968 | @itemx copy (@var{function}) | |
d77de738 ML |
2969 | The @code{copy} attribute applies the set of attributes with which |
2970 | @var{function} has been declared to the declaration of the function | |
2971 | to which the attribute is applied. The attribute is designed for | |
2972 | libraries that define aliases or function resolvers that are expected | |
2973 | to specify the same set of attributes as their targets. The @code{copy} | |
2974 | attribute can be used with functions, variables, or types. However, | |
2975 | the kind of symbol to which the attribute is applied (either function | |
2976 | or variable) must match the kind of symbol to which the argument refers. | |
2977 | The @code{copy} attribute copies only syntactic and semantic attributes | |
2978 | but not attributes that affect a symbol's linkage or visibility such as | |
2979 | @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} | |
2980 | and @code{target_clones} attribute are also not copied. | |
2981 | @xref{Common Type Attributes}. | |
2982 | @xref{Common Variable Attributes}. | |
2983 | ||
2984 | For example, the @var{StrongAlias} macro below makes use of the @code{alias} | |
2985 | and @code{copy} attributes to define an alias named @var{alloc} for function | |
2986 | @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and | |
2987 | @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has | |
2988 | the same type as the target function. As a result of the @code{copy} | |
2989 | attribute the alias also shares the same attributes as the target. | |
2990 | ||
2991 | @smallexample | |
2992 | #define StrongAlias(TargetFunc, AliasDecl) \ | |
2993 | extern __typeof__ (TargetFunc) AliasDecl \ | |
2994 | __attribute__ ((alias (#TargetFunc), copy (TargetFunc))); | |
2995 | ||
2996 | extern __attribute__ ((alloc_size (1), malloc, nothrow)) | |
2997 | void* allocate (size_t); | |
2998 | StrongAlias (allocate, alloc); | |
2999 | @end smallexample | |
3000 | ||
f33d7a88 | 3001 | @cindex @code{deprecated} function attribute |
d77de738 ML |
3002 | @item deprecated |
3003 | @itemx deprecated (@var{msg}) | |
d77de738 ML |
3004 | The @code{deprecated} attribute results in a warning if the function |
3005 | is used anywhere in the source file. This is useful when identifying | |
3006 | functions that are expected to be removed in a future version of a | |
3007 | program. The warning also includes the location of the declaration | |
3008 | of the deprecated function, to enable users to easily find further | |
3009 | information about why the function is deprecated, or what they should | |
3010 | do instead. Note that the warnings only occurs for uses: | |
3011 | ||
3012 | @smallexample | |
3013 | int old_fn () __attribute__ ((deprecated)); | |
3014 | int old_fn (); | |
3015 | int (*fn_ptr)() = old_fn; | |
3016 | @end smallexample | |
3017 | ||
3018 | @noindent | |
3019 | results in a warning on line 3 but not line 2. The optional @var{msg} | |
3020 | argument, which must be a string, is printed in the warning if | |
3021 | present. | |
3022 | ||
3023 | The @code{deprecated} attribute can also be used for variables and | |
3024 | types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) | |
3025 | ||
3026 | The message attached to the attribute is affected by the setting of | |
3027 | the @option{-fmessage-length} option. | |
3028 | ||
f33d7a88 | 3029 | @cindex @code{unavailable} function attribute |
d77de738 ML |
3030 | @item unavailable |
3031 | @itemx unavailable (@var{msg}) | |
d77de738 ML |
3032 | The @code{unavailable} attribute results in an error if the function |
3033 | is used anywhere in the source file. This is useful when identifying | |
3034 | functions that have been removed from a particular variation of an | |
3035 | interface. Other than emitting an error rather than a warning, the | |
3036 | @code{unavailable} attribute behaves in the same manner as | |
3037 | @code{deprecated}. | |
3038 | ||
3039 | The @code{unavailable} attribute can also be used for variables and | |
3040 | types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) | |
3041 | ||
d77de738 ML |
3042 | @cindex @code{error} function attribute |
3043 | @cindex @code{warning} function attribute | |
f33d7a88 AA |
3044 | @item error ("@var{message}") |
3045 | @itemx warning ("@var{message}") | |
d77de738 ML |
3046 | If the @code{error} or @code{warning} attribute |
3047 | is used on a function declaration and a call to such a function | |
3048 | is not eliminated through dead code elimination or other optimizations, | |
3049 | an error or warning (respectively) that includes @var{message} is diagnosed. | |
3050 | This is useful | |
3051 | for compile-time checking, especially together with @code{__builtin_constant_p} | |
3052 | and inline functions where checking the inline function arguments is not | |
3053 | possible through @code{extern char [(condition) ? 1 : -1];} tricks. | |
3054 | ||
3055 | While it is possible to leave the function undefined and thus invoke | |
3056 | a link failure (to define the function with | |
3057 | a message in @code{.gnu.warning*} section), | |
3058 | when using these attributes the problem is diagnosed | |
3059 | earlier and with exact location of the call even in presence of inline | |
3060 | functions or when not emitting debugging information. | |
551935d1 AO |
3061 | |
3062 | @cindex @code{expected_throw} function attribute | |
3063 | @item expected_throw | |
3064 | This attribute, attached to a function, tells the compiler the function | |
3065 | is more likely to raise or propagate an exception than to return, loop | |
3066 | forever, or terminate the program. | |
3067 | ||
3068 | This hint is mostly ignored by the compiler. The only effect is when | |
3069 | it's applied to @code{noreturn} functions and | |
3070 | @samp{-fharden-control-flow-redundancy} is enabled, and | |
3071 | @samp{-fhardcfr-check-noreturn-calls=not-always} is not overridden. | |
d77de738 | 3072 | |
d77de738 | 3073 | @cindex @code{externally_visible} function attribute |
f33d7a88 | 3074 | @item externally_visible |
d77de738 ML |
3075 | This attribute, attached to a global variable or function, nullifies |
3076 | the effect of the @option{-fwhole-program} command-line option, so the | |
3077 | object remains visible outside the current compilation unit. | |
3078 | ||
3079 | If @option{-fwhole-program} is used together with @option{-flto} and | |
3080 | @command{gold} is used as the linker plugin, | |
3081 | @code{externally_visible} attributes are automatically added to functions | |
3082 | (not variable yet due to a current @command{gold} issue) | |
3083 | that are accessed outside of LTO objects according to resolution file | |
3084 | produced by @command{gold}. | |
3085 | For other linkers that cannot generate resolution file, | |
3086 | explicit @code{externally_visible} attributes are still necessary. | |
3087 | ||
f33d7a88 | 3088 | @cindex @code{fd_arg} function attribute |
d77de738 ML |
3089 | @item fd_arg |
3090 | @itemx fd_arg (@var{N}) | |
d77de738 ML |
3091 | The @code{fd_arg} attribute may be applied to a function that takes an open |
3092 | file descriptor at referenced argument @var{N}. | |
3093 | ||
3094 | It indicates that the passed filedescriptor must not have been closed. | |
3095 | Therefore, when the analyzer is enabled with @option{-fanalyzer}, the | |
3096 | analyzer may emit a @option{-Wanalyzer-fd-use-after-close} diagnostic | |
3097 | if it detects a code path in which a function with this attribute is | |
3098 | called with a closed file descriptor. | |
3099 | ||
3100 | The attribute also indicates that the file descriptor must have been checked for | |
3101 | validity before usage. Therefore, analyzer may emit | |
3102 | @option{-Wanalyzer-fd-use-without-check} diagnostic if it detects a code path in | |
3103 | which a function with this attribute is called with a file descriptor that has | |
3104 | not been checked for validity. | |
3105 | ||
f33d7a88 | 3106 | @cindex @code{fd_arg_read} function attribute |
d77de738 ML |
3107 | @item fd_arg_read |
3108 | @itemx fd_arg_read (@var{N}) | |
d77de738 ML |
3109 | The @code{fd_arg_read} is identical to @code{fd_arg}, but with the additional |
3110 | requirement that it might read from the file descriptor, and thus, the file | |
3111 | descriptor must not have been opened as write-only. | |
3112 | ||
3113 | The analyzer may emit a @option{-Wanalyzer-access-mode-mismatch} | |
3114 | diagnostic if it detects a code path in which a function with this | |
3115 | attribute is called on a file descriptor opened with @code{O_WRONLY}. | |
3116 | ||
f33d7a88 | 3117 | @cindex @code{fd_arg_write} function attribute |
d77de738 ML |
3118 | @item fd_arg_write |
3119 | @itemx fd_arg_write (@var{N}) | |
d77de738 ML |
3120 | The @code{fd_arg_write} is identical to @code{fd_arg_read} except that the |
3121 | analyzer may emit a @option{-Wanalyzer-access-mode-mismatch} diagnostic if | |
3122 | it detects a code path in which a function with this attribute is called on a | |
3123 | file descriptor opened with @code{O_RDONLY}. | |
3124 | ||
d77de738 | 3125 | @cindex @code{flatten} function attribute |
f33d7a88 | 3126 | @item flatten |
d77de738 | 3127 | Generally, inlining into a function is limited. For a function marked with |
ffbd7c3d RB |
3128 | this attribute, every call inside this function is inlined including the |
3129 | calls such inlining introduces to the function (but not recursive calls | |
3130 | to the function itself), if possible. | |
d77de738 ML |
3131 | Functions declared with attribute @code{noinline} and similar are not |
3132 | inlined. Whether the function itself is considered for inlining depends | |
3133 | on its size and the current inlining parameters. | |
3134 | ||
d77de738 ML |
3135 | @cindex @code{format} function attribute |
3136 | @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments | |
3137 | @opindex Wformat | |
f33d7a88 | 3138 | @item format (@var{archetype}, @var{string-index}, @var{first-to-check}) |
d77de738 ML |
3139 | The @code{format} attribute specifies that a function takes @code{printf}, |
3140 | @code{scanf}, @code{strftime} or @code{strfmon} style arguments that | |
3141 | should be type-checked against a format string. For example, the | |
3142 | declaration: | |
3143 | ||
3144 | @smallexample | |
3145 | extern int | |
3146 | my_printf (void *my_object, const char *my_format, ...) | |
3147 | __attribute__ ((format (printf, 2, 3))); | |
3148 | @end smallexample | |
3149 | ||
3150 | @noindent | |
3151 | causes the compiler to check the arguments in calls to @code{my_printf} | |
3152 | for consistency with the @code{printf} style format string argument | |
3153 | @code{my_format}. | |
3154 | ||
3155 | The parameter @var{archetype} determines how the format string is | |
3156 | interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, | |
3157 | @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or | |
3158 | @code{strfmon}. (You can also use @code{__printf__}, | |
3159 | @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On | |
3160 | MinGW targets, @code{ms_printf}, @code{ms_scanf}, and | |
3161 | @code{ms_strftime} are also present. | |
3162 | @var{archetype} values such as @code{printf} refer to the formats accepted | |
3163 | by the system's C runtime library, | |
3164 | while values prefixed with @samp{gnu_} always refer | |
3165 | to the formats accepted by the GNU C Library. On Microsoft Windows | |
3166 | targets, values prefixed with @samp{ms_} refer to the formats accepted by the | |
3167 | @file{msvcrt.dll} library. | |
3168 | The parameter @var{string-index} | |
3169 | specifies which argument is the format string argument (starting | |
3170 | from 1), while @var{first-to-check} is the number of the first | |
3171 | argument to check against the format string. For functions | |
3172 | where the arguments are not available to be checked (such as | |
3173 | @code{vprintf}), specify the third parameter as zero. In this case the | |
3174 | compiler only checks the format string for consistency. For | |
3175 | @code{strftime} formats, the third parameter is required to be zero. | |
3176 | Since non-static C++ methods have an implicit @code{this} argument, the | |
3177 | arguments of such methods should be counted from two, not one, when | |
3178 | giving values for @var{string-index} and @var{first-to-check}. | |
3179 | ||
3180 | In the example above, the format string (@code{my_format}) is the second | |
3181 | argument of the function @code{my_print}, and the arguments to check | |
3182 | start with the third argument, so the correct parameters for the format | |
3183 | attribute are 2 and 3. | |
3184 | ||
3185 | @opindex ffreestanding | |
3186 | @opindex fno-builtin | |
3187 | The @code{format} attribute allows you to identify your own functions | |
3188 | that take format strings as arguments, so that GCC can check the | |
3189 | calls to these functions for errors. The compiler always (unless | |
3190 | @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats | |
3191 | for the standard library functions @code{printf}, @code{fprintf}, | |
3192 | @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, | |
3193 | @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such | |
3194 | warnings are requested (using @option{-Wformat}), so there is no need to | |
3195 | modify the header file @file{stdio.h}. In C99 mode, the functions | |
3196 | @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and | |
3197 | @code{vsscanf} are also checked. Except in strictly conforming C | |
3198 | standard modes, the X/Open function @code{strfmon} is also checked as | |
3199 | are @code{printf_unlocked} and @code{fprintf_unlocked}. | |
3200 | @xref{C Dialect Options,,Options Controlling C Dialect}. | |
3201 | ||
3202 | For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is | |
3203 | recognized in the same context. Declarations including these format attributes | |
3204 | are parsed for correct syntax, however the result of checking of such format | |
3205 | strings is not yet defined, and is not carried out by this version of the | |
3206 | compiler. | |
3207 | ||
3208 | The target may also provide additional types of format checks. | |
3209 | @xref{Target Format Checks,,Format Checks Specific to Particular | |
3210 | Target Machines}. | |
3211 | ||
d77de738 ML |
3212 | @cindex @code{format_arg} function attribute |
3213 | @opindex Wformat-nonliteral | |
f33d7a88 | 3214 | @item format_arg (@var{string-index}) |
d77de738 ML |
3215 | The @code{format_arg} attribute specifies that a function takes one or |
3216 | more format strings for a @code{printf}, @code{scanf}, @code{strftime} or | |
3217 | @code{strfmon} style function and modifies it (for example, to translate | |
3218 | it into another language), so the result can be passed to a | |
3219 | @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style | |
3220 | function (with the remaining arguments to the format function the same | |
3221 | as they would have been for the unmodified string). Multiple | |
3222 | @code{format_arg} attributes may be applied to the same function, each | |
3223 | designating a distinct parameter as a format string. For example, the | |
3224 | declaration: | |
3225 | ||
3226 | @smallexample | |
3227 | extern char * | |
3228 | my_dgettext (char *my_domain, const char *my_format) | |
3229 | __attribute__ ((format_arg (2))); | |
3230 | @end smallexample | |
3231 | ||
3232 | @noindent | |
3233 | causes the compiler to check the arguments in calls to a @code{printf}, | |
3234 | @code{scanf}, @code{strftime} or @code{strfmon} type function, whose | |
3235 | format string argument is a call to the @code{my_dgettext} function, for | |
3236 | consistency with the format string argument @code{my_format}. If the | |
3237 | @code{format_arg} attribute had not been specified, all the compiler | |
3238 | could tell in such calls to format functions would be that the format | |
3239 | string argument is not constant; this would generate a warning when | |
3240 | @option{-Wformat-nonliteral} is used, but the calls could not be checked | |
3241 | without the attribute. | |
3242 | ||
3243 | In calls to a function declared with more than one @code{format_arg} | |
3244 | attribute, each with a distinct argument value, the corresponding | |
3245 | actual function arguments are checked against all format strings | |
3246 | designated by the attributes. This capability is designed to support | |
3247 | the GNU @code{ngettext} family of functions. | |
3248 | ||
3249 | The parameter @var{string-index} specifies which argument is the format | |
3250 | string argument (starting from one). Since non-static C++ methods have | |
3251 | an implicit @code{this} argument, the arguments of such methods should | |
3252 | be counted from two. | |
3253 | ||
3254 | The @code{format_arg} attribute allows you to identify your own | |
3255 | functions that modify format strings, so that GCC can check the | |
3256 | calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} | |
3257 | type function whose operands are a call to one of your own function. | |
3258 | The compiler always treats @code{gettext}, @code{dgettext}, and | |
3259 | @code{dcgettext} in this manner except when strict ISO C support is | |
3260 | requested by @option{-ansi} or an appropriate @option{-std} option, or | |
3261 | @option{-ffreestanding} or @option{-fno-builtin} | |
3262 | is used. @xref{C Dialect Options,,Options | |
3263 | Controlling C Dialect}. | |
3264 | ||
3265 | For Objective-C dialects, the @code{format-arg} attribute may refer to an | |
3266 | @code{NSString} reference for compatibility with the @code{format} attribute | |
3267 | above. | |
3268 | ||
3269 | The target may also allow additional types in @code{format-arg} attributes. | |
3270 | @xref{Target Format Checks,,Format Checks Specific to Particular | |
3271 | Target Machines}. | |
3272 | ||
d77de738 | 3273 | @cindex @code{gnu_inline} function attribute |
f33d7a88 | 3274 | @item gnu_inline |
d77de738 ML |
3275 | This attribute should be used with a function that is also declared |
3276 | with the @code{inline} keyword. It directs GCC to treat the function | |
3277 | as if it were defined in gnu90 mode even when compiling in C99 or | |
3278 | gnu99 mode. | |
3279 | ||
3280 | If the function is declared @code{extern}, then this definition of the | |
3281 | function is used only for inlining. In no case is the function | |
3282 | compiled as a standalone function, not even if you take its address | |
3283 | explicitly. Such an address becomes an external reference, as if you | |
3284 | had only declared the function, and had not defined it. This has | |
3285 | almost the effect of a macro. The way to use this is to put a | |
3286 | function definition in a header file with this attribute, and put | |
3287 | another copy of the function, without @code{extern}, in a library | |
3288 | file. The definition in the header file causes most calls to the | |
3289 | function to be inlined. If any uses of the function remain, they | |
3290 | refer to the single copy in the library. Note that the two | |
3291 | definitions of the functions need not be precisely the same, although | |
3292 | if they do not have the same effect your program may behave oddly. | |
3293 | ||
3294 | In C, if the function is neither @code{extern} nor @code{static}, then | |
3295 | the function is compiled as a standalone function, as well as being | |
3296 | inlined where possible. | |
3297 | ||
3298 | This is how GCC traditionally handled functions declared | |
3299 | @code{inline}. Since ISO C99 specifies a different semantics for | |
3300 | @code{inline}, this function attribute is provided as a transition | |
3301 | measure and as a useful feature in its own right. This attribute is | |
3302 | available in GCC 4.1.3 and later. It is available if either of the | |
3303 | preprocessor macros @code{__GNUC_GNU_INLINE__} or | |
3304 | @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline | |
3305 | Function is As Fast As a Macro}. | |
3306 | ||
3307 | In C++, this attribute does not depend on @code{extern} in any way, | |
3308 | but it still requires the @code{inline} keyword to enable its special | |
3309 | behavior. | |
3310 | ||
d77de738 | 3311 | @cindex @code{hot} function attribute |
f33d7a88 | 3312 | @item hot |
d77de738 ML |
3313 | The @code{hot} attribute on a function is used to inform the compiler that |
3314 | the function is a hot spot of the compiled program. The function is | |
3315 | optimized more aggressively and on many targets it is placed into a special | |
3316 | subsection of the text section so all hot functions appear close together, | |
4f52e61e JM |
3317 | improving locality. In C++, the @code{hot} attribute can be applied to types |
3318 | with the effect of being propagated to member functions. See | |
3319 | @ref{C++ Attributes}. | |
d77de738 ML |
3320 | |
3321 | When profile feedback is available, via @option{-fprofile-use}, hot functions | |
3322 | are automatically detected and this attribute is ignored. | |
3323 | ||
d77de738 ML |
3324 | @cindex @code{ifunc} function attribute |
3325 | @cindex indirect functions | |
3326 | @cindex functions that are dynamically resolved | |
f33d7a88 | 3327 | @item ifunc ("@var{resolver}") |
d77de738 ML |
3328 | The @code{ifunc} attribute is used to mark a function as an indirect |
3329 | function using the STT_GNU_IFUNC symbol type extension to the ELF | |
3330 | standard. This allows the resolution of the symbol value to be | |
3331 | determined dynamically at load time, and an optimized version of the | |
3332 | routine to be selected for the particular processor or other system | |
3333 | characteristics determined then. To use this attribute, first define | |
3334 | the implementation functions available, and a resolver function that | |
3335 | returns a pointer to the selected implementation function. The | |
3336 | implementation functions' declarations must match the API of the | |
3337 | function being implemented. The resolver should be declared to | |
3338 | be a function taking no arguments and returning a pointer to | |
3339 | a function of the same type as the implementation. For example: | |
3340 | ||
3341 | @smallexample | |
3342 | void *my_memcpy (void *dst, const void *src, size_t len) | |
3343 | @{ | |
3344 | @dots{} | |
3345 | return dst; | |
3346 | @} | |
3347 | ||
3348 | static void * (*resolve_memcpy (void))(void *, const void *, size_t) | |
3349 | @{ | |
3350 | return my_memcpy; // we will just always select this routine | |
3351 | @} | |
3352 | @end smallexample | |
3353 | ||
3354 | @noindent | |
3355 | The exported header file declaring the function the user calls would | |
3356 | contain: | |
3357 | ||
3358 | @smallexample | |
3359 | extern void *memcpy (void *, const void *, size_t); | |
3360 | @end smallexample | |
3361 | ||
3362 | @noindent | |
3363 | allowing the user to call @code{memcpy} as a regular function, unaware of | |
3364 | the actual implementation. Finally, the indirect function needs to be | |
3365 | defined in the same translation unit as the resolver function: | |
3366 | ||
3367 | @smallexample | |
3368 | void *memcpy (void *, const void *, size_t) | |
3369 | __attribute__ ((ifunc ("resolve_memcpy"))); | |
3370 | @end smallexample | |
3371 | ||
3372 | In C++, the @code{ifunc} attribute takes a string that is the mangled name | |
3373 | of the resolver function. A C++ resolver for a non-static member function | |
3374 | of class @code{C} should be declared to return a pointer to a non-member | |
3375 | function taking pointer to @code{C} as the first argument, followed by | |
3376 | the same arguments as of the implementation function. G++ checks | |
3377 | the signatures of the two functions and issues | |
3378 | a @option{-Wattribute-alias} warning for mismatches. To suppress a warning | |
3379 | for the necessary cast from a pointer to the implementation member function | |
3380 | to the type of the corresponding non-member function use | |
3381 | the @option{-Wno-pmf-conversions} option. For example: | |
3382 | ||
3383 | @smallexample | |
3384 | class S | |
3385 | @{ | |
3386 | private: | |
3387 | int debug_impl (int); | |
3388 | int optimized_impl (int); | |
3389 | ||
3390 | typedef int Func (S*, int); | |
3391 | ||
3392 | static Func* resolver (); | |
3393 | public: | |
3394 | ||
3395 | int interface (int); | |
3396 | @}; | |
3397 | ||
3398 | int S::debug_impl (int) @{ /* @r{@dots{}} */ @} | |
3399 | int S::optimized_impl (int) @{ /* @r{@dots{}} */ @} | |
3400 | ||
3401 | S::Func* S::resolver () | |
3402 | @{ | |
3403 | int (S::*pimpl) (int) | |
3404 | = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl; | |
3405 | ||
3406 | // Cast triggers -Wno-pmf-conversions. | |
3407 | return reinterpret_cast<Func*>(pimpl); | |
3408 | @} | |
3409 | ||
3410 | int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv"))); | |
3411 | @end smallexample | |
3412 | ||
3413 | Indirect functions cannot be weak. Binutils version 2.20.1 or higher | |
3414 | and GNU C Library version 2.11.1 are required to use this feature. | |
3415 | ||
0aad1da6 AP |
3416 | @cindex @code{interrupt_handler} function attribute |
3417 | @cindex @code{interrupt} function attribute | |
d77de738 ML |
3418 | @item interrupt |
3419 | @itemx interrupt_handler | |
3420 | Many GCC back ends support attributes to indicate that a function is | |
3421 | an interrupt handler, which tells the compiler to generate function | |
3422 | entry and exit sequences that differ from those from regular | |
3423 | functions. The exact syntax and behavior are target-specific; | |
3424 | refer to the following subsections for details. | |
3425 | ||
d77de738 | 3426 | @cindex @code{leaf} function attribute |
f33d7a88 | 3427 | @item leaf |
d77de738 ML |
3428 | Calls to external functions with this attribute must return to the |
3429 | current compilation unit only by return or by exception handling. In | |
3430 | particular, a leaf function is not allowed to invoke callback functions | |
3431 | passed to it from the current compilation unit, directly call functions | |
3432 | exported by the unit, or @code{longjmp} into the unit. Leaf functions | |
3433 | might still call functions from other compilation units and thus they | |
3434 | are not necessarily leaf in the sense that they contain no function | |
3435 | calls at all. | |
3436 | ||
3437 | The attribute is intended for library functions to improve dataflow | |
3438 | analysis. The compiler takes the hint that any data not escaping the | |
3439 | current compilation unit cannot be used or modified by the leaf | |
3440 | function. For example, the @code{sin} function is a leaf function, but | |
3441 | @code{qsort} is not. | |
3442 | ||
3443 | Note that leaf functions might indirectly run a signal handler defined | |
3444 | in the current compilation unit that uses static variables. Similarly, | |
3445 | when lazy symbol resolution is in effect, leaf functions might invoke | |
3446 | indirect functions whose resolver function or implementation function is | |
3447 | defined in the current compilation unit and uses static variables. There | |
3448 | is no standard-compliant way to write such a signal handler, resolver | |
3449 | function, or implementation function, and the best that you can do is to | |
3450 | remove the @code{leaf} attribute or mark all such static variables | |
3451 | @code{volatile}. Lastly, for ELF-based systems that support symbol | |
3452 | interposition, care should be taken that functions defined in the | |
3453 | current compilation unit do not unexpectedly interpose other symbols | |
3454 | based on the defined standards mode and defined feature test macros; | |
3455 | otherwise an inadvertent callback would be added. | |
3456 | ||
3457 | The attribute has no effect on functions defined within the current | |
3458 | compilation unit. This is to allow easy merging of multiple compilation | |
3459 | units into one, for example, by using the link-time optimization. For | |
3460 | this reason the attribute is not allowed on types to annotate indirect | |
3461 | calls. | |
3462 | ||
f33d7a88 AA |
3463 | @cindex @code{malloc} function attribute |
3464 | @cindex functions that behave like malloc | |
d77de738 ML |
3465 | @item malloc |
3466 | @item malloc (@var{deallocator}) | |
3467 | @item malloc (@var{deallocator}, @var{ptr-index}) | |
d77de738 ML |
3468 | Attribute @code{malloc} indicates that a function is @code{malloc}-like, |
3469 | i.e., that the pointer @var{P} returned by the function cannot alias any | |
3470 | other pointer valid when the function returns, and moreover no | |
3471 | pointers to valid objects occur in any storage addressed by @var{P}. In | |
dfc5ea6b | 3472 | addition, GCC predicts that a function with the attribute returns |
d77de738 ML |
3473 | non-null in most cases. |
3474 | ||
3475 | Independently, the form of the attribute with one or two arguments | |
3476 | associates @code{deallocator} as a suitable deallocation function for | |
3477 | pointers returned from the @code{malloc}-like function. @var{ptr-index} | |
3478 | denotes the positional argument to which when the pointer is passed in | |
3479 | calls to @code{deallocator} has the effect of deallocating it. | |
3480 | ||
3481 | Using the attribute with no arguments is designed to improve optimization | |
3482 | by relying on the aliasing property it implies. Functions like @code{malloc} | |
3483 | and @code{calloc} have this property because they return a pointer to | |
3484 | uninitialized or zeroed-out, newly obtained storage. However, functions | |
3485 | like @code{realloc} do not have this property, as they may return pointers | |
3486 | to storage containing pointers to existing objects. Additionally, since | |
3487 | all such functions are assumed to return null only infrequently, callers | |
3488 | can be optimized based on that assumption. | |
3489 | ||
3490 | Associating a function with a @var{deallocator} helps detect calls to | |
3491 | mismatched allocation and deallocation functions and diagnose them under | |
3492 | the control of options such as @option{-Wmismatched-dealloc}. It also | |
3493 | makes it possible to diagnose attempts to deallocate objects that were not | |
3494 | allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate | |
3495 | that an allocation function both satisifies the nonaliasing property and | |
3496 | has a deallocator associated with it, both the plain form of the attribute | |
3497 | and the one with the @var{deallocator} argument must be used. The same | |
3498 | function can be both an allocator and a deallocator. Since inlining one | |
3499 | of the associated functions but not the other could result in apparent | |
3500 | mismatches, this form of attribute @code{malloc} is not accepted on inline | |
3501 | functions. For the same reason, using the attribute prevents both | |
3502 | the allocation and deallocation functions from being expanded inline. | |
3503 | ||
3504 | For example, besides stating that the functions return pointers that do | |
3505 | not alias any others, the following declarations make @code{fclose} | |
3506 | a suitable deallocator for pointers returned from all functions except | |
3507 | @code{popen}, and @code{pclose} as the only suitable deallocator for | |
3508 | pointers returned from @code{popen}. The deallocator functions must | |
3509 | be declared before they can be referenced in the attribute. | |
3510 | ||
3511 | @smallexample | |
3512 | int fclose (FILE*); | |
3513 | int pclose (FILE*); | |
3514 | ||
3515 | __attribute__ ((malloc, malloc (fclose, 1))) | |
3516 | FILE* fdopen (int, const char*); | |
3517 | __attribute__ ((malloc, malloc (fclose, 1))) | |
3518 | FILE* fopen (const char*, const char*); | |
3519 | __attribute__ ((malloc, malloc (fclose, 1))) | |
3520 | FILE* fmemopen(void *, size_t, const char *); | |
3521 | __attribute__ ((malloc, malloc (pclose, 1))) | |
3522 | FILE* popen (const char*, const char*); | |
3523 | __attribute__ ((malloc, malloc (fclose, 1))) | |
3524 | FILE* tmpfile (void); | |
3525 | @end smallexample | |
3526 | ||
3527 | The warnings guarded by @option{-fanalyzer} respect allocation and | |
3528 | deallocation pairs marked with the @code{malloc}. In particular: | |
3529 | ||
3530 | @itemize @bullet | |
3531 | ||
3532 | @item | |
4ace81b6 | 3533 | The analyzer emits a @option{-Wanalyzer-mismatching-deallocation} |
d77de738 ML |
3534 | diagnostic if there is an execution path in which the result of an |
3535 | allocation call is passed to a different deallocator. | |
3536 | ||
3537 | @item | |
4ace81b6 | 3538 | The analyzer emits a @option{-Wanalyzer-double-free} |
d77de738 ML |
3539 | diagnostic if there is an execution path in which a value is passed |
3540 | more than once to a deallocation call. | |
3541 | ||
3542 | @item | |
4ace81b6 SL |
3543 | The analyzer considers the possibility that an allocation function |
3544 | could fail and return null. If there are | |
d77de738 | 3545 | execution paths in which an unchecked result of an allocation call is |
4ace81b6 SL |
3546 | dereferenced or passed to a function requiring a non-null argument, |
3547 | it emits | |
3548 | @option{-Wanalyzer-possible-null-dereference} and | |
3549 | @option{-Wanalyzer-possible-null-argument} diagnostics. | |
d77de738 ML |
3550 | If the allocator always returns non-null, use |
3551 | @code{__attribute__ ((returns_nonnull))} to suppress these warnings. | |
3552 | For example: | |
3553 | @smallexample | |
3554 | char *xstrdup (const char *) | |
3555 | __attribute__((malloc (free), returns_nonnull)); | |
3556 | @end smallexample | |
3557 | ||
3558 | @item | |
4ace81b6 | 3559 | The analyzer emits a @option{-Wanalyzer-use-after-free} |
d77de738 ML |
3560 | diagnostic if there is an execution path in which the memory passed |
3561 | by pointer to a deallocation call is used after the deallocation. | |
3562 | ||
3563 | @item | |
4ace81b6 | 3564 | The analyzer emits a @option{-Wanalyzer-malloc-leak} diagnostic if |
d77de738 ML |
3565 | there is an execution path in which the result of an allocation call |
3566 | is leaked (without being passed to the deallocation function). | |
3567 | ||
3568 | @item | |
4ace81b6 | 3569 | The analyzer emits a @option{-Wanalyzer-free-of-non-heap} diagnostic |
d77de738 ML |
3570 | if a deallocation function is used on a global or on-stack variable. |
3571 | ||
3572 | @end itemize | |
3573 | ||
4ace81b6 | 3574 | The analyzer assumes that deallocators can gracefully handle the null |
d77de738 ML |
3575 | pointer. If this is not the case, the deallocator can be marked with |
3576 | @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit | |
3577 | a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths | |
4ace81b6 | 3578 | in which the deallocator is called with null. |
d77de738 | 3579 | |
d77de738 | 3580 | @cindex @code{no_icf} function attribute |
f33d7a88 | 3581 | @item no_icf |
d77de738 ML |
3582 | This function attribute prevents a functions from being merged with another |
3583 | semantically equivalent function. | |
3584 | ||
d77de738 ML |
3585 | @cindex @code{no_instrument_function} function attribute |
3586 | @opindex finstrument-functions | |
3587 | @opindex p | |
3588 | @opindex pg | |
f33d7a88 | 3589 | @item no_instrument_function |
d77de738 ML |
3590 | If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are |
3591 | given, profiling function calls are | |
3592 | generated at entry and exit of most user-compiled functions. | |
3593 | Functions with this attribute are not so instrumented. | |
3594 | ||
d77de738 | 3595 | @cindex @code{no_profile_instrument_function} function attribute |
f33d7a88 | 3596 | @item no_profile_instrument_function |
d77de738 ML |
3597 | The @code{no_profile_instrument_function} attribute on functions is used |
3598 | to inform the compiler that it should not process any profile feedback based | |
3599 | optimization code instrumentation. | |
3600 | ||
d77de738 | 3601 | @cindex @code{no_reorder} function attribute |
f33d7a88 | 3602 | @item no_reorder |
d77de738 ML |
3603 | Do not reorder functions or variables marked @code{no_reorder} |
3604 | against each other or top level assembler statements the executable. | |
3605 | The actual order in the program will depend on the linker command | |
3606 | line. Static variables marked like this are also not removed. | |
3607 | This has a similar effect | |
3608 | as the @option{-fno-toplevel-reorder} option, but only applies to the | |
3609 | marked symbols. | |
3610 | ||
d77de738 | 3611 | @cindex @code{no_sanitize} function attribute |
f33d7a88 | 3612 | @item no_sanitize ("@var{sanitize_option}") |
d77de738 ML |
3613 | The @code{no_sanitize} attribute on functions is used |
3614 | to inform the compiler that it should not do sanitization of any option | |
3615 | mentioned in @var{sanitize_option}. A list of values acceptable by | |
3616 | the @option{-fsanitize} option can be provided. | |
3617 | ||
3618 | @smallexample | |
3619 | void __attribute__ ((no_sanitize ("alignment", "object-size"))) | |
3620 | f () @{ /* @r{Do something.} */; @} | |
3621 | void __attribute__ ((no_sanitize ("alignment,object-size"))) | |
3622 | g () @{ /* @r{Do something.} */; @} | |
3623 | @end smallexample | |
3624 | ||
f33d7a88 | 3625 | @cindex @code{no_sanitize_address} function attribute |
d77de738 ML |
3626 | @item no_sanitize_address |
3627 | @itemx no_address_safety_analysis | |
d77de738 ML |
3628 | The @code{no_sanitize_address} attribute on functions is used |
3629 | to inform the compiler that it should not instrument memory accesses | |
3630 | in the function when compiling with the @option{-fsanitize=address} option. | |
3631 | The @code{no_address_safety_analysis} is a deprecated alias of the | |
3632 | @code{no_sanitize_address} attribute, new code should use | |
3633 | @code{no_sanitize_address}. | |
3634 | ||
d77de738 | 3635 | @cindex @code{no_sanitize_thread} function attribute |
f33d7a88 | 3636 | @item no_sanitize_thread |
d77de738 ML |
3637 | The @code{no_sanitize_thread} attribute on functions is used |
3638 | to inform the compiler that it should not instrument memory accesses | |
3639 | in the function when compiling with the @option{-fsanitize=thread} option. | |
3640 | ||
d77de738 | 3641 | @cindex @code{no_sanitize_undefined} function attribute |
f33d7a88 | 3642 | @item no_sanitize_undefined |
d77de738 ML |
3643 | The @code{no_sanitize_undefined} attribute on functions is used |
3644 | to inform the compiler that it should not check for undefined behavior | |
3645 | in the function when compiling with the @option{-fsanitize=undefined} option. | |
3646 | ||
d77de738 | 3647 | @cindex @code{no_sanitize_coverage} function attribute |
f33d7a88 | 3648 | @item no_sanitize_coverage |
d77de738 ML |
3649 | The @code{no_sanitize_coverage} attribute on functions is used |
3650 | to inform the compiler that it should not do coverage-guided | |
3651 | fuzzing code instrumentation (@option{-fsanitize-coverage}). | |
3652 | ||
d77de738 ML |
3653 | @cindex @code{no_split_stack} function attribute |
3654 | @opindex fsplit-stack | |
f33d7a88 | 3655 | @item no_split_stack |
d77de738 ML |
3656 | If @option{-fsplit-stack} is given, functions have a small |
3657 | prologue which decides whether to split the stack. Functions with the | |
3658 | @code{no_split_stack} attribute do not have that prologue, and thus | |
3659 | may run with only a small amount of stack space available. | |
3660 | ||
d77de738 | 3661 | @cindex @code{no_stack_limit} function attribute |
f33d7a88 | 3662 | @item no_stack_limit |
d77de738 ML |
3663 | This attribute locally overrides the @option{-fstack-limit-register} |
3664 | and @option{-fstack-limit-symbol} command-line options; it has the effect | |
3665 | of disabling stack limit checking in the function it applies to. | |
3666 | ||
d77de738 | 3667 | @cindex @code{noclone} function attribute |
f33d7a88 | 3668 | @item noclone |
d77de738 ML |
3669 | This function attribute prevents a function from being considered for |
3670 | cloning---a mechanism that produces specialized copies of functions | |
3671 | and which is (currently) performed by interprocedural constant | |
3672 | propagation. | |
3673 | ||
d77de738 | 3674 | @cindex @code{noinline} function attribute |
f33d7a88 | 3675 | @item noinline |
d77de738 ML |
3676 | This function attribute prevents a function from being considered for |
3677 | inlining. | |
3678 | @c Don't enumerate the optimizations by name here; we try to be | |
3679 | @c future-compatible with this mechanism. | |
3680 | If the function does not have side effects, there are optimizations | |
3681 | other than inlining that cause function calls to be optimized away, | |
3682 | although the function call is live. To keep such calls from being | |
3683 | optimized away, put | |
3684 | @smallexample | |
3685 | asm (""); | |
3686 | @end smallexample | |
3687 | ||
3688 | @noindent | |
3689 | (@pxref{Extended Asm}) in the called function, to serve as a special | |
3690 | side effect. | |
3691 | ||
d77de738 | 3692 | @cindex @code{noipa} function attribute |
f33d7a88 | 3693 | @item noipa |
d77de738 ML |
3694 | Disable interprocedural optimizations between the function with this |
3695 | attribute and its callers, as if the body of the function is not available | |
3696 | when optimizing callers and the callers are unavailable when optimizing | |
3697 | the body. This attribute implies @code{noinline}, @code{noclone} and | |
3698 | @code{no_icf} attributes. However, this attribute is not equivalent | |
3699 | to a combination of other attributes, because its purpose is to suppress | |
3700 | existing and future optimizations employing interprocedural analysis, | |
3701 | including those that do not have an attribute suitable for disabling | |
3702 | them individually. This attribute is supported mainly for the purpose | |
3703 | of testing the compiler. | |
3704 | ||
d77de738 ML |
3705 | @cindex @code{nonnull} function attribute |
3706 | @cindex functions with non-null pointer arguments | |
f33d7a88 AA |
3707 | @item nonnull |
3708 | @itemx nonnull (@var{arg-index}, @dots{}) | |
d77de738 ML |
3709 | The @code{nonnull} attribute may be applied to a function that takes at |
3710 | least one argument of a pointer type. It indicates that the referenced | |
3711 | arguments must be non-null pointers. For instance, the declaration: | |
3712 | ||
3713 | @smallexample | |
3714 | extern void * | |
3715 | my_memcpy (void *dest, const void *src, size_t len) | |
3716 | __attribute__((nonnull (1, 2))); | |
3717 | @end smallexample | |
3718 | ||
3719 | @noindent | |
3720 | informs the compiler that, in calls to @code{my_memcpy}, arguments | |
3721 | @var{dest} and @var{src} must be non-null. | |
3722 | ||
3723 | The attribute has an effect both on functions calls and function definitions. | |
3724 | ||
3725 | For function calls: | |
3726 | @itemize @bullet | |
3727 | @item If the compiler determines that a null pointer is | |
3728 | passed in an argument slot marked as non-null, and the | |
3729 | @option{-Wnonnull} option is enabled, a warning is issued. | |
3730 | @xref{Warning Options}. | |
3731 | @item The @option{-fisolate-erroneous-paths-attribute} option can be | |
3732 | specified to have GCC transform calls with null arguments to non-null | |
3733 | functions into traps. @xref{Optimize Options}. | |
3734 | @item The compiler may also perform optimizations based on the | |
3735 | knowledge that certain function arguments cannot be null. These | |
3736 | optimizations can be disabled by the | |
3737 | @option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}. | |
3738 | @end itemize | |
3739 | ||
3740 | For function definitions: | |
3741 | @itemize @bullet | |
3742 | @item If the compiler determines that a function parameter that is | |
3743 | marked with nonnull is compared with null, and | |
3744 | @option{-Wnonnull-compare} option is enabled, a warning is issued. | |
3745 | @xref{Warning Options}. | |
3746 | @item The compiler may also perform optimizations based on the | |
0e38aedc | 3747 | knowledge that @code{nonnull} parameters cannot be null. This can |
d77de738 ML |
3748 | currently not be disabled other than by removing the nonnull |
3749 | attribute. | |
3750 | @end itemize | |
3751 | ||
3752 | If no @var{arg-index} is given to the @code{nonnull} attribute, | |
3753 | all pointer arguments are marked as non-null. To illustrate, the | |
3754 | following declaration is equivalent to the previous example: | |
3755 | ||
3756 | @smallexample | |
3757 | extern void * | |
3758 | my_memcpy (void *dest, const void *src, size_t len) | |
3759 | __attribute__((nonnull)); | |
3760 | @end smallexample | |
3761 | ||
cd7dadcd DM |
3762 | @cindex @code{null_terminated_string_arg} function attribute |
3763 | @item null_terminated_string_arg | |
3764 | @itemx null_terminated_string_arg (@var{N}) | |
3765 | The @code{null_terminated_string_arg} attribute may be applied to a | |
3766 | function that takes a @code{char *} or @code{const char *} at | |
3767 | referenced argument @var{N}. | |
3768 | ||
3769 | It indicates that the passed argument must be a C-style null-terminated | |
3770 | string. Specifically, the presence of the attribute implies that, if | |
3771 | the pointer is non-null, the function may scan through the referenced | |
3772 | buffer looking for the first zero byte. | |
3773 | ||
3774 | In particular, when the analyzer is enabled (via @option{-fanalyzer}), | |
3775 | if the pointer is non-null, it will simulate scanning for the first | |
3776 | zero byte in the referenced buffer, and potentially emit | |
3777 | @option{-Wanalyzer-use-of-uninitialized-value} | |
3778 | or @option{-Wanalyzer-out-of-bounds} on improperly terminated buffers. | |
3779 | ||
3780 | For example, given the following: | |
3781 | ||
3782 | @smallexample | |
3783 | char *example_1 (const char *p) | |
3784 | __attribute__((null_terminated_string_arg (1))); | |
3785 | @end smallexample | |
3786 | ||
3787 | the analyzer will check that any non-null pointers passed to the function | |
3788 | are validly terminated. | |
3789 | ||
3790 | If the parameter must be non-null, it is appropriate to use both this | |
3791 | attribute and the attribute @code{nonnull}, such as in: | |
3792 | ||
3793 | @smallexample | |
3794 | extern char *example_2 (const char *p) | |
3795 | __attribute__((null_terminated_string_arg (1), | |
3796 | nonnull (1))); | |
3797 | @end smallexample | |
3798 | ||
3799 | See the @code{nonnull} attribute for more information and | |
3800 | caveats. | |
3801 | ||
3802 | If the pointer argument is also referred to by an @code{access} attribute on the | |
3803 | function with @var{access-mode} either @code{read_only} or @code{read_write} | |
3804 | and the latter attribute has the optional @var{size-index} argument | |
3805 | referring to a size argument, this expressses the maximum size of the access. | |
3806 | For example, given: | |
3807 | ||
3808 | @smallexample | |
3809 | extern char *example_fn (const char *p, size_t n) | |
3810 | __attribute__((null_terminated_string_arg (1), | |
3811 | access (read_only, 1, 2), | |
3812 | nonnull (1))); | |
3813 | @end smallexample | |
3814 | ||
3815 | the analyzer will require the first parameter to be non-null, and either | |
3816 | be validly null-terminated, or validly readable up to the size specified by | |
3817 | the second parameter. | |
3818 | ||
d77de738 | 3819 | @cindex @code{noplt} function attribute |
f33d7a88 | 3820 | @item noplt |
d77de738 ML |
3821 | The @code{noplt} attribute is the counterpart to option @option{-fno-plt}. |
3822 | Calls to functions marked with this attribute in position-independent code | |
3823 | do not use the PLT. | |
3824 | ||
3825 | @smallexample | |
3826 | @group | |
3827 | /* Externally defined function foo. */ | |
3828 | int foo () __attribute__ ((noplt)); | |
3829 | ||
3830 | int | |
3831 | main (/* @r{@dots{}} */) | |
3832 | @{ | |
3833 | /* @r{@dots{}} */ | |
3834 | foo (); | |
3835 | /* @r{@dots{}} */ | |
3836 | @} | |
3837 | @end group | |
3838 | @end smallexample | |
3839 | ||
3840 | The @code{noplt} attribute on function @code{foo} | |
3841 | tells the compiler to assume that | |
3842 | the function @code{foo} is externally defined and that the call to | |
3843 | @code{foo} must avoid the PLT | |
3844 | in position-independent code. | |
3845 | ||
3846 | In position-dependent code, a few targets also convert calls to | |
3847 | functions that are marked to not use the PLT to use the GOT instead. | |
3848 | ||
d77de738 ML |
3849 | @cindex @code{noreturn} function attribute |
3850 | @cindex functions that never return | |
f33d7a88 | 3851 | @item noreturn |
d77de738 ML |
3852 | A few standard library functions, such as @code{abort} and @code{exit}, |
3853 | cannot return. GCC knows this automatically. Some programs define | |
3854 | their own functions that never return. You can declare them | |
3855 | @code{noreturn} to tell the compiler this fact. For example, | |
3856 | ||
3857 | @smallexample | |
3858 | @group | |
3859 | void fatal () __attribute__ ((noreturn)); | |
3860 | ||
3861 | void | |
3862 | fatal (/* @r{@dots{}} */) | |
3863 | @{ | |
3864 | /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ | |
3865 | exit (1); | |
3866 | @} | |
3867 | @end group | |
3868 | @end smallexample | |
3869 | ||
3870 | The @code{noreturn} keyword tells the compiler to assume that | |
3871 | @code{fatal} cannot return. It can then optimize without regard to what | |
3872 | would happen if @code{fatal} ever did return. This makes slightly | |
3873 | better code. More importantly, it helps avoid spurious warnings of | |
3874 | uninitialized variables. | |
3875 | ||
3876 | The @code{noreturn} keyword does not affect the exceptional path when that | |
3877 | applies: a @code{noreturn}-marked function may still return to the caller | |
3878 | by throwing an exception or calling @code{longjmp}. | |
3879 | ||
3880 | In order to preserve backtraces, GCC will never turn calls to | |
3881 | @code{noreturn} functions into tail calls. | |
3882 | ||
3883 | Do not assume that registers saved by the calling function are | |
3884 | restored before calling the @code{noreturn} function. | |
3885 | ||
3886 | It does not make sense for a @code{noreturn} function to have a return | |
3887 | type other than @code{void}. | |
3888 | ||
d77de738 | 3889 | @cindex @code{nothrow} function attribute |
f33d7a88 | 3890 | @item nothrow |
d77de738 ML |
3891 | The @code{nothrow} attribute is used to inform the compiler that a |
3892 | function cannot throw an exception. For example, most functions in | |
3893 | the standard C library can be guaranteed not to throw an exception | |
3894 | with the notable exceptions of @code{qsort} and @code{bsearch} that | |
3895 | take function pointer arguments. | |
3896 | ||
f33d7a88 | 3897 | @cindex @code{optimize} function attribute |
d77de738 ML |
3898 | @item optimize (@var{level}, @dots{}) |
3899 | @item optimize (@var{string}, @dots{}) | |
d77de738 ML |
3900 | The @code{optimize} attribute is used to specify that a function is to |
3901 | be compiled with different optimization options than specified on the | |
3902 | command line. The optimize attribute arguments of a function behave | |
d4e8523b | 3903 | as if appended to the command-line. |
d77de738 ML |
3904 | |
3905 | Valid arguments are constant non-negative integers and | |
3906 | strings. Each numeric argument specifies an optimization @var{level}. | |
3907 | Each @var{string} argument consists of one or more comma-separated | |
3908 | substrings. Each substring that begins with the letter @code{O} refers | |
3909 | to an optimization option such as @option{-O0} or @option{-Os}. Other | |
3910 | substrings are taken as suffixes to the @code{-f} prefix jointly | |
3911 | forming the name of an optimization option. @xref{Optimize Options}. | |
3912 | ||
3913 | @samp{#pragma GCC optimize} can be used to set optimization options | |
3914 | for more than one function. @xref{Function Specific Option Pragmas}, | |
3915 | for details about the pragma. | |
3916 | ||
3917 | Providing multiple strings as arguments separated by commas to specify | |
3918 | multiple options is equivalent to separating the option suffixes with | |
3919 | a comma (@samp{,}) within a single string. Spaces are not permitted | |
3920 | within the strings. | |
3921 | ||
3922 | Not every optimization option that starts with the @var{-f} prefix | |
3923 | specified by the attribute necessarily has an effect on the function. | |
3924 | The @code{optimize} attribute should be used for debugging purposes only. | |
3925 | It is not suitable in production code. | |
3926 | ||
d77de738 ML |
3927 | @cindex @code{patchable_function_entry} function attribute |
3928 | @cindex extra NOP instructions at the function entry point | |
f33d7a88 | 3929 | @item patchable_function_entry |
d77de738 ML |
3930 | In case the target's text segment can be made writable at run time by |
3931 | any means, padding the function entry with a number of NOPs can be | |
3932 | used to provide a universal tool for instrumentation. | |
3933 | ||
3934 | The @code{patchable_function_entry} function attribute can be used to | |
3935 | change the number of NOPs to any desired value. The two-value syntax | |
3936 | is the same as for the command-line switch | |
3937 | @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with | |
3938 | the function entry point before the @var{M}th NOP instruction. | |
3939 | @var{M} defaults to 0 if omitted e.g.@: function entry point is before | |
3940 | the first NOP. | |
3941 | ||
3942 | If patchable function entries are enabled globally using the command-line | |
3943 | option @option{-fpatchable-function-entry=N,M}, then you must disable | |
3944 | instrumentation on all functions that are part of the instrumentation | |
3945 | framework with the attribute @code{patchable_function_entry (0)} | |
3946 | to prevent recursion. | |
3947 | ||
d77de738 ML |
3948 | @cindex @code{pure} function attribute |
3949 | @cindex functions that have no side effects | |
f33d7a88 | 3950 | @item pure |
d77de738 ML |
3951 | |
3952 | Calls to functions that have no observable effects on the state of | |
3953 | the program other than to return a value may lend themselves to optimizations | |
3954 | such as common subexpression elimination. Declaring such functions with | |
3955 | the @code{pure} attribute allows GCC to avoid emitting some calls in repeated | |
3956 | invocations of the function with the same argument values. | |
3957 | ||
3958 | The @code{pure} attribute prohibits a function from modifying the state | |
3959 | of the program that is observable by means other than inspecting | |
3960 | the function's return value. However, functions declared with the @code{pure} | |
3961 | attribute can safely read any non-volatile objects, and modify the value of | |
3962 | objects in a way that does not affect their return value or the observable | |
3963 | state of the program. | |
3964 | ||
3965 | For example, | |
3966 | ||
3967 | @smallexample | |
3968 | int hash (char *) __attribute__ ((pure)); | |
3969 | @end smallexample | |
3970 | ||
3971 | @noindent | |
3972 | tells GCC that subsequent calls to the function @code{hash} with the same | |
3973 | string can be replaced by the result of the first call provided the state | |
3974 | of the program observable by @code{hash}, including the contents of the array | |
3975 | itself, does not change in between. Even though @code{hash} takes a non-const | |
3976 | pointer argument it must not modify the array it points to, or any other object | |
3977 | whose value the rest of the program may depend on. However, the caller may | |
3978 | safely change the contents of the array between successive calls to | |
3979 | the function (doing so disables the optimization). The restriction also | |
3980 | applies to member objects referenced by the @code{this} pointer in C++ | |
3981 | non-static member functions. | |
3982 | ||
3983 | Some common examples of pure functions are @code{strlen} or @code{memcmp}. | |
3984 | Interesting non-pure functions are functions with infinite loops or those | |
3985 | depending on volatile memory or other system resource, that may change between | |
3986 | consecutive calls (such as the standard C @code{feof} function in | |
3987 | a multithreading environment). | |
3988 | ||
3989 | The @code{pure} attribute imposes similar but looser restrictions on | |
3990 | a function's definition than the @code{const} attribute: @code{pure} | |
3991 | allows the function to read any non-volatile memory, even if it changes | |
3992 | in between successive invocations of the function. Declaring the same | |
3993 | function with both the @code{pure} and the @code{const} attribute is | |
3994 | diagnosed. Because a pure function cannot have any observable side | |
3995 | effects it does not make sense for such a function to return @code{void}. | |
3996 | Declaring such a function is diagnosed. | |
3997 | ||
d77de738 | 3998 | @cindex @code{returns_nonnull} function attribute |
f33d7a88 | 3999 | @item returns_nonnull |
d77de738 ML |
4000 | The @code{returns_nonnull} attribute specifies that the function |
4001 | return value should be a non-null pointer. For instance, the declaration: | |
4002 | ||
4003 | @smallexample | |
4004 | extern void * | |
4005 | mymalloc (size_t len) __attribute__((returns_nonnull)); | |
4006 | @end smallexample | |
4007 | ||
4008 | @noindent | |
4009 | lets the compiler optimize callers based on the knowledge | |
4010 | that the return value will never be null. | |
4011 | ||
d77de738 ML |
4012 | @cindex @code{returns_twice} function attribute |
4013 | @cindex functions that return more than once | |
f33d7a88 | 4014 | @item returns_twice |
d77de738 ML |
4015 | The @code{returns_twice} attribute tells the compiler that a function may |
4016 | return more than one time. The compiler ensures that all registers | |
4017 | are dead before calling such a function and emits a warning about | |
4018 | the variables that may be clobbered after the second return from the | |
4019 | function. Examples of such functions are @code{setjmp} and @code{vfork}. | |
4020 | The @code{longjmp}-like counterpart of such function, if any, might need | |
4021 | to be marked with the @code{noreturn} attribute. | |
4022 | ||
d77de738 ML |
4023 | @cindex @code{section} function attribute |
4024 | @cindex functions in arbitrary sections | |
f33d7a88 | 4025 | @item section ("@var{section-name}") |
d77de738 ML |
4026 | Normally, the compiler places the code it generates in the @code{text} section. |
4027 | Sometimes, however, you need additional sections, or you need certain | |
4028 | particular functions to appear in special sections. The @code{section} | |
4029 | attribute specifies that a function lives in a particular section. | |
4030 | For example, the declaration: | |
4031 | ||
4032 | @smallexample | |
4033 | extern void foobar (void) __attribute__ ((section ("bar"))); | |
4034 | @end smallexample | |
4035 | ||
4036 | @noindent | |
4037 | puts the function @code{foobar} in the @code{bar} section. | |
4038 | ||
4039 | Some file formats do not support arbitrary sections so the @code{section} | |
4040 | attribute is not available on all platforms. | |
4041 | If you need to map the entire contents of a module to a particular | |
4042 | section, consider using the facilities of the linker instead. | |
4043 | ||
f33d7a88 | 4044 | @cindex @code{sentinel} function attribute |
d77de738 ML |
4045 | @item sentinel |
4046 | @itemx sentinel (@var{position}) | |
d77de738 ML |
4047 | This function attribute indicates that an argument in a call to the function |
4048 | is expected to be an explicit @code{NULL}. The attribute is only valid on | |
4049 | variadic functions. By default, the sentinel is expected to be the last | |
4050 | argument of the function call. If the optional @var{position} argument | |
4051 | is specified to the attribute, the sentinel must be located at | |
4052 | @var{position} counting backwards from the end of the argument list. | |
4053 | ||
4054 | @smallexample | |
4055 | __attribute__ ((sentinel)) | |
4056 | is equivalent to | |
4057 | __attribute__ ((sentinel(0))) | |
4058 | @end smallexample | |
4059 | ||
4060 | The attribute is automatically set with a position of 0 for the built-in | |
4061 | functions @code{execl} and @code{execlp}. The built-in function | |
4062 | @code{execle} has the attribute set with a position of 1. | |
4063 | ||
4064 | A valid @code{NULL} in this context is defined as zero with any object | |
4065 | pointer type. If your system defines the @code{NULL} macro with | |
4066 | an integer type then you need to add an explicit cast. During | |
4067 | installation GCC replaces the system @code{<stddef.h>} header with | |
4068 | a copy that redefines NULL appropriately. | |
4069 | ||
4070 | The warnings for missing or incorrect sentinels are enabled with | |
4071 | @option{-Wformat}. | |
4072 | ||
f33d7a88 | 4073 | @cindex @code{simd} function attribute |
d77de738 ML |
4074 | @item simd |
4075 | @itemx simd("@var{mask}") | |
d77de738 ML |
4076 | This attribute enables creation of one or more function versions that |
4077 | can process multiple arguments using SIMD instructions from a | |
4078 | single invocation. Specifying this attribute allows compiler to | |
4079 | assume that such versions are available at link time (provided | |
4080 | in the same or another translation unit). Generated versions are | |
4081 | target-dependent and described in the corresponding Vector ABI document. For | |
4082 | x86_64 target this document can be found | |
4083 | @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}. | |
4084 | ||
4085 | The optional argument @var{mask} may have the value | |
4086 | @code{notinbranch} or @code{inbranch}, | |
4087 | and instructs the compiler to generate non-masked or masked | |
4088 | clones correspondingly. By default, all clones are generated. | |
4089 | ||
4090 | If the attribute is specified and @code{#pragma omp declare simd} is | |
4091 | present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd} | |
4092 | switch is specified, then the attribute is ignored. | |
4093 | ||
d77de738 | 4094 | @cindex @code{stack_protect} function attribute |
f33d7a88 | 4095 | @item stack_protect |
d77de738 ML |
4096 | This attribute adds stack protection code to the function if |
4097 | flags @option{-fstack-protector}, @option{-fstack-protector-strong} | |
4098 | or @option{-fstack-protector-explicit} are set. | |
4099 | ||
d77de738 | 4100 | @cindex @code{no_stack_protector} function attribute |
f33d7a88 | 4101 | @item no_stack_protector |
d77de738 ML |
4102 | This attribute prevents stack protection code for the function. |
4103 | ||
d77de738 | 4104 | @cindex @code{target} function attribute |
f33d7a88 | 4105 | @item target (@var{string}, @dots{}) |
d77de738 ML |
4106 | Multiple target back ends implement the @code{target} attribute |
4107 | to specify that a function is to | |
4108 | be compiled with different target options than specified on the | |
4109 | command line. The original target command-line options are ignored. | |
4110 | One or more strings can be provided as arguments. | |
4111 | Each string consists of one or more comma-separated suffixes to | |
4112 | the @code{-m} prefix jointly forming the name of a machine-dependent | |
4113 | option. @xref{Submodel Options,,Machine-Dependent Options}. | |
4114 | ||
4115 | The @code{target} attribute can be used for instance to have a function | |
4116 | compiled with a different ISA (instruction set architecture) than the | |
4117 | default. @samp{#pragma GCC target} can be used to specify target-specific | |
4118 | options for more than one function. @xref{Function Specific Option Pragmas}, | |
4119 | for details about the pragma. | |
4120 | ||
4121 | For instance, on an x86, you could declare one function with the | |
4122 | @code{target("sse4.1,arch=core2")} attribute and another with | |
4123 | @code{target("sse4a,arch=amdfam10")}. This is equivalent to | |
4124 | compiling the first function with @option{-msse4.1} and | |
4125 | @option{-march=core2} options, and the second function with | |
4126 | @option{-msse4a} and @option{-march=amdfam10} options. It is up to you | |
4127 | to make sure that a function is only invoked on a machine that | |
4128 | supports the particular ISA it is compiled for (for example by using | |
4129 | @code{cpuid} on x86 to determine what feature bits and architecture | |
4130 | family are used). | |
4131 | ||
4132 | @smallexample | |
4133 | int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); | |
4134 | int sse3_func (void) __attribute__ ((__target__ ("sse3"))); | |
4135 | @end smallexample | |
4136 | ||
4137 | Providing multiple strings as arguments separated by commas to specify | |
4138 | multiple options is equivalent to separating the option suffixes with | |
4139 | a comma (@samp{,}) within a single string. Spaces are not permitted | |
4140 | within the strings. | |
4141 | ||
4142 | The options supported are specific to each target; refer to @ref{x86 | |
4143 | Function Attributes}, @ref{PowerPC Function Attributes}, | |
4144 | @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes}, | |
4145 | @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes} | |
4146 | for details. | |
4147 | ||
d77de738 | 4148 | @cindex @code{symver} function attribute |
f33d7a88 | 4149 | @item symver ("@var{name2}@@@var{nodename}") |
d77de738 ML |
4150 | On ELF targets this attribute creates a symbol version. The @var{name2} part |
4151 | of the parameter is the actual name of the symbol by which it will be | |
4152 | externally referenced. The @code{nodename} portion should be the name of a | |
4153 | node specified in the version script supplied to the linker when building a | |
4154 | shared library. Versioned symbol must be defined and must be exported with | |
4155 | default visibility. | |
4156 | ||
4157 | @smallexample | |
4158 | __attribute__ ((__symver__ ("foo@@VERS_1"))) int | |
4159 | foo_v1 (void) | |
4160 | @{ | |
4161 | @} | |
4162 | @end smallexample | |
4163 | ||
4164 | Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler | |
4165 | output. | |
4166 | ||
4167 | One can also define multiple version for a given symbol | |
4168 | (starting from binutils 2.35). | |
4169 | ||
4170 | @smallexample | |
4171 | __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3"))) | |
4172 | int symver_foo_v1 (void) | |
4173 | @{ | |
4174 | @} | |
4175 | @end smallexample | |
4176 | ||
4177 | This example creates a symbol name @code{symver_foo_v1} | |
4178 | which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}. | |
4179 | ||
4180 | If you have an older release of binutils, then symbol alias needs to | |
4181 | be used: | |
4182 | ||
4183 | @smallexample | |
4184 | __attribute__ ((__symver__ ("foo@@VERS_2"))) | |
4185 | int foo_v1 (void) | |
4186 | @{ | |
4187 | return 0; | |
4188 | @} | |
4189 | ||
4190 | __attribute__ ((__symver__ ("foo@@VERS_3"))) | |
4191 | __attribute__ ((alias ("foo_v1"))) | |
4192 | int symver_foo_v1 (void); | |
4193 | @end smallexample | |
4194 | ||
4195 | Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in | |
4196 | addition to creating a symbol version (as if | |
4197 | @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used | |
4198 | to resolve @var{name2} by the linker. | |
4199 | ||
d77de738 | 4200 | @cindex @code{tainted_args} function attribute |
f33d7a88 | 4201 | @item tainted_args |
d77de738 ML |
4202 | The @code{tainted_args} attribute is used to specify that a function is called |
4203 | in a way that requires sanitization of its arguments, such as a system | |
4204 | call in an operating system kernel. Such a function can be considered part | |
4205 | of the ``attack surface'' of the program. The attribute can be used both | |
4206 | on function declarations, and on field declarations containing function | |
4207 | pointers. In the latter case, any function used as an initializer of | |
4208 | such a callback field will be treated as being called with tainted | |
4209 | arguments. | |
4210 | ||
83b210d5 DM |
4211 | The analyzer will pay particular attention to such functions when |
4212 | @option{-fanalyzer} is supplied, potentially issuing warnings guarded by | |
d77de738 ML |
4213 | @option{-Wanalyzer-tainted-allocation-size}, |
4214 | @option{-Wanalyzer-tainted-array-index}, | |
4215 | @option{-Wanalyzer-tainted-divisor}, | |
4216 | @option{-Wanalyzer-tainted-offset}, | |
4217 | and @option{-Wanalyzer-tainted-size}. | |
4218 | ||
d77de738 | 4219 | @cindex @code{target_clones} function attribute |
f33d7a88 | 4220 | @item target_clones (@var{options}) |
d77de738 ML |
4221 | The @code{target_clones} attribute is used to specify that a function |
4222 | be cloned into multiple versions compiled with different target options | |
4223 | than specified on the command line. The supported options and restrictions | |
4224 | are the same as for @code{target} attribute. | |
4225 | ||
4226 | For instance, on an x86, you could compile a function with | |
4227 | @code{target_clones("sse4.1,avx")}. GCC creates two function clones, | |
4228 | one compiled with @option{-msse4.1} and another with @option{-mavx}. | |
4229 | ||
4230 | On a PowerPC, you can compile a function with | |
4231 | @code{target_clones("cpu=power9,default")}. GCC will create two | |
4232 | function clones, one compiled with @option{-mcpu=power9} and another | |
4233 | with the default options. GCC must be configured to use GLIBC 2.23 or | |
4234 | newer in order to use the @code{target_clones} attribute. | |
4235 | ||
4236 | It also creates a resolver function (see | |
4237 | the @code{ifunc} attribute above) that dynamically selects a clone | |
4238 | suitable for current architecture. The resolver is created only if there | |
4239 | is a usage of a function with @code{target_clones} attribute. | |
4240 | ||
4241 | Note that any subsequent call of a function without @code{target_clone} | |
4242 | from a @code{target_clone} caller will not lead to copying | |
4243 | (target clone) of the called function. | |
4244 | If you want to enforce such behaviour, | |
4245 | we recommend declaring the calling function with the @code{flatten} attribute? | |
4246 | ||
d77de738 | 4247 | @cindex @code{unused} function attribute |
f33d7a88 | 4248 | @item unused |
d77de738 ML |
4249 | This attribute, attached to a function, means that the function is meant |
4250 | to be possibly unused. GCC does not produce a warning for this | |
4251 | function. | |
4252 | ||
d77de738 | 4253 | @cindex @code{used} function attribute |
f33d7a88 | 4254 | @item used |
d77de738 ML |
4255 | This attribute, attached to a function, means that code must be emitted |
4256 | for the function even if it appears that the function is not referenced. | |
4257 | This is useful, for example, when the function is referenced only in | |
4258 | inline assembly. | |
4259 | ||
4260 | When applied to a member function of a C++ class template, the | |
4261 | attribute also means that the function is instantiated if the | |
4262 | class itself is instantiated. | |
4263 | ||
d77de738 | 4264 | @cindex @code{retain} function attribute |
f33d7a88 | 4265 | @item retain |
d77de738 ML |
4266 | For ELF targets that support the GNU or FreeBSD OSABIs, this attribute |
4267 | will save the function from linker garbage collection. To support | |
4268 | this behavior, functions that have not been placed in specific sections | |
4269 | (e.g. by the @code{section} attribute, or the @code{-ffunction-sections} | |
4270 | option), will be placed in new, unique sections. | |
4271 | ||
4272 | This additional functionality requires Binutils version 2.36 or later. | |
4273 | ||
d77de738 | 4274 | @cindex @code{visibility} function attribute |
f33d7a88 | 4275 | @item visibility ("@var{visibility_type}") |
d77de738 ML |
4276 | This attribute affects the linkage of the declaration to which it is attached. |
4277 | It can be applied to variables (@pxref{Common Variable Attributes}) and types | |
4278 | (@pxref{Common Type Attributes}) as well as functions. | |
4279 | ||
4280 | There are four supported @var{visibility_type} values: default, | |
4281 | hidden, protected or internal visibility. | |
4282 | ||
4283 | @smallexample | |
4284 | void __attribute__ ((visibility ("protected"))) | |
4285 | f () @{ /* @r{Do something.} */; @} | |
4286 | int i __attribute__ ((visibility ("hidden"))); | |
4287 | @end smallexample | |
4288 | ||
4289 | The possible values of @var{visibility_type} correspond to the | |
4290 | visibility settings in the ELF gABI. | |
4291 | ||
4292 | @table @code | |
4293 | @c keep this list of visibilities in alphabetical order. | |
4294 | ||
4295 | @item default | |
4296 | Default visibility is the normal case for the object file format. | |
4297 | This value is available for the visibility attribute to override other | |
4298 | options that may change the assumed visibility of entities. | |
4299 | ||
4300 | On ELF, default visibility means that the declaration is visible to other | |
4301 | modules and, in shared libraries, means that the declared entity may be | |
4302 | overridden. | |
4303 | ||
4304 | On Darwin, default visibility means that the declaration is visible to | |
4305 | other modules. | |
4306 | ||
4307 | Default visibility corresponds to ``external linkage'' in the language. | |
4308 | ||
4309 | @item hidden | |
4310 | Hidden visibility indicates that the entity declared has a new | |
4311 | form of linkage, which we call ``hidden linkage''. Two | |
4312 | declarations of an object with hidden linkage refer to the same object | |
4313 | if they are in the same shared object. | |
4314 | ||
4315 | @item internal | |
4316 | Internal visibility is like hidden visibility, but with additional | |
4317 | processor specific semantics. Unless otherwise specified by the | |
4318 | psABI, GCC defines internal visibility to mean that a function is | |
4319 | @emph{never} called from another module. Compare this with hidden | |
4320 | functions which, while they cannot be referenced directly by other | |
4321 | modules, can be referenced indirectly via function pointers. By | |
4322 | indicating that a function cannot be called from outside the module, | |
4323 | GCC may for instance omit the load of a PIC register since it is known | |
4324 | that the calling function loaded the correct value. | |
4325 | ||
4326 | @item protected | |
4327 | Protected visibility is like default visibility except that it | |
4328 | indicates that references within the defining module bind to the | |
4329 | definition in that module. That is, the declared entity cannot be | |
4330 | overridden by another module. | |
4331 | ||
4332 | @end table | |
4333 | ||
4334 | All visibilities are supported on many, but not all, ELF targets | |
4335 | (supported when the assembler supports the @samp{.visibility} | |
4336 | pseudo-op). Default visibility is supported everywhere. Hidden | |
4337 | visibility is supported on Darwin targets. | |
4338 | ||
4339 | The visibility attribute should be applied only to declarations that | |
4340 | would otherwise have external linkage. The attribute should be applied | |
4341 | consistently, so that the same entity should not be declared with | |
4342 | different settings of the attribute. | |
4343 | ||
4344 | In C++, the visibility attribute applies to types as well as functions | |
4345 | and objects, because in C++ types have linkage. A class must not have | |
4346 | greater visibility than its non-static data member types and bases, | |
4347 | and class members default to the visibility of their class. Also, a | |
4348 | declaration without explicit visibility is limited to the visibility | |
4349 | of its type. | |
4350 | ||
4351 | In C++, you can mark member functions and static member variables of a | |
4352 | class with the visibility attribute. This is useful if you know a | |
4353 | particular method or static member variable should only be used from | |
4354 | one shared object; then you can mark it hidden while the rest of the | |
4355 | class has default visibility. Care must be taken to avoid breaking | |
4356 | the One Definition Rule; for example, it is usually not useful to mark | |
4357 | an inline method as hidden without marking the whole class as hidden. | |
4358 | ||
4359 | A C++ namespace declaration can also have the visibility attribute. | |
4360 | ||
4361 | @smallexample | |
4362 | namespace nspace1 __attribute__ ((visibility ("protected"))) | |
4363 | @{ /* @r{Do something.} */; @} | |
4364 | @end smallexample | |
4365 | ||
4366 | This attribute applies only to the particular namespace body, not to | |
4367 | other definitions of the same namespace; it is equivalent to using | |
4368 | @samp{#pragma GCC visibility} before and after the namespace | |
4369 | definition (@pxref{Visibility Pragmas}). | |
4370 | ||
4371 | In C++, if a template argument has limited visibility, this | |
4372 | restriction is implicitly propagated to the template instantiation. | |
4373 | Otherwise, template instantiations and specializations default to the | |
4374 | visibility of their template. | |
4375 | ||
4376 | If both the template and enclosing class have explicit visibility, the | |
4377 | visibility from the template is used. | |
4378 | ||
d77de738 | 4379 | @cindex @code{warn_unused_result} function attribute |
f33d7a88 | 4380 | @item warn_unused_result |
d77de738 ML |
4381 | The @code{warn_unused_result} attribute causes a warning to be emitted |
4382 | if a caller of the function with this attribute does not use its | |
4383 | return value. This is useful for functions where not checking | |
4384 | the result is either a security problem or always a bug, such as | |
4385 | @code{realloc}. | |
4386 | ||
4387 | @smallexample | |
4388 | int fn () __attribute__ ((warn_unused_result)); | |
4389 | int foo () | |
4390 | @{ | |
4391 | if (fn () < 0) return -1; | |
4392 | fn (); | |
4393 | return 0; | |
4394 | @} | |
4395 | @end smallexample | |
4396 | ||
4397 | @noindent | |
4398 | results in warning on line 5. | |
4399 | ||
d77de738 | 4400 | @cindex @code{weak} function attribute |
f33d7a88 | 4401 | @item weak |
d77de738 ML |
4402 | The @code{weak} attribute causes a declaration of an external symbol |
4403 | to be emitted as a weak symbol rather than a global. This is primarily | |
4404 | useful in defining library functions that can be overridden in user code, | |
4405 | though it can also be used with non-function declarations. The overriding | |
4406 | symbol must have the same type as the weak symbol. In addition, if it | |
4407 | designates a variable it must also have the same size and alignment as | |
4408 | the weak symbol. Weak symbols are supported for ELF targets, and also | |
4409 | for a.out targets when using the GNU assembler and linker. | |
4410 | ||
f33d7a88 | 4411 | @cindex @code{weakref} function attribute |
d77de738 ML |
4412 | @item weakref |
4413 | @itemx weakref ("@var{target}") | |
d77de738 ML |
4414 | The @code{weakref} attribute marks a declaration as a weak reference. |
4415 | Without arguments, it should be accompanied by an @code{alias} attribute | |
4416 | naming the target symbol. Alternatively, @var{target} may be given as | |
4417 | an argument to @code{weakref} itself, naming the target definition of | |
4418 | the alias. The @var{target} must have the same type as the declaration. | |
4419 | In addition, if it designates a variable it must also have the same size | |
4420 | and alignment as the declaration. In either form of the declaration | |
4421 | @code{weakref} implicitly marks the declared symbol as @code{weak}. Without | |
4422 | a @var{target} given as an argument to @code{weakref} or to @code{alias}, | |
4423 | @code{weakref} is equivalent to @code{weak} (in that case the declaration | |
4424 | may be @code{extern}). | |
4425 | ||
4426 | @smallexample | |
4427 | /* Given the declaration: */ | |
4428 | extern int y (void); | |
4429 | ||
4430 | /* the following... */ | |
4431 | static int x (void) __attribute__ ((weakref ("y"))); | |
4432 | ||
4433 | /* is equivalent to... */ | |
4434 | static int x (void) __attribute__ ((weakref, alias ("y"))); | |
4435 | ||
4436 | /* or, alternatively, to... */ | |
4437 | static int x (void) __attribute__ ((weakref)); | |
4438 | static int x (void) __attribute__ ((alias ("y"))); | |
4439 | @end smallexample | |
4440 | ||
4441 | A weak reference is an alias that does not by itself require a | |
4442 | definition to be given for the target symbol. If the target symbol is | |
4443 | only referenced through weak references, then it becomes a @code{weak} | |
4444 | undefined symbol. If it is directly referenced, however, then such | |
4445 | strong references prevail, and a definition is required for the | |
4446 | symbol, not necessarily in the same translation unit. | |
4447 | ||
4448 | The effect is equivalent to moving all references to the alias to a | |
4449 | separate translation unit, renaming the alias to the aliased symbol, | |
4450 | declaring it as weak, compiling the two separate translation units and | |
4451 | performing a link with relocatable output (i.e.@: @code{ld -r}) on them. | |
4452 | ||
4453 | A declaration to which @code{weakref} is attached and that is associated | |
4454 | with a named @code{target} must be @code{static}. | |
4455 | ||
d77de738 | 4456 | @cindex @code{zero_call_used_regs} function attribute |
f33d7a88 | 4457 | @item zero_call_used_regs ("@var{choice}") |
d77de738 ML |
4458 | |
4459 | The @code{zero_call_used_regs} attribute causes the compiler to zero | |
4460 | a subset of all call-used registers@footnote{A ``call-used'' register | |
4461 | is a register whose contents can be changed by a function call; | |
4462 | therefore, a caller cannot assume that the register has the same contents | |
4463 | on return from the function as it had before calling the function. Such | |
4464 | registers are also called ``call-clobbered'', ``caller-saved'', or | |
4465 | ``volatile''.} at function return. | |
4466 | This is used to increase program security by either mitigating | |
4467 | Return-Oriented Programming (ROP) attacks or preventing information leakage | |
4468 | through registers. | |
4469 | ||
4470 | In order to satisfy users with different security needs and control the | |
4471 | run-time overhead at the same time, the @var{choice} parameter provides a | |
4472 | flexible way to choose the subset of the call-used registers to be zeroed. | |
83f69969 | 4473 | The four basic values of @var{choice} are: |
d77de738 ML |
4474 | |
4475 | @itemize @bullet | |
4476 | @item | |
4477 | @samp{skip} doesn't zero any call-used registers. | |
4478 | ||
4479 | @item | |
4480 | @samp{used} only zeros call-used registers that are used in the function. | |
4481 | A ``used'' register is one whose content has been set or referenced in | |
4482 | the function. | |
4483 | ||
4484 | @item | |
4485 | @samp{all} zeros all call-used registers. | |
83f69969 AO |
4486 | |
4487 | @item | |
4488 | @samp{leafy} behaves like @samp{used} in a leaf function, and like | |
4489 | @samp{all} in a nonleaf function. This makes for leaner zeroing in leaf | |
4490 | functions, where the set of used registers is known, and that may be | |
4491 | enough for some purposes of register zeroing. | |
d77de738 ML |
4492 | @end itemize |
4493 | ||
4494 | In addition to these three basic choices, it is possible to modify | |
83f69969 | 4495 | @samp{used}, @samp{all}, and @samp{leafy} as follows: |
d77de738 ML |
4496 | |
4497 | @itemize @bullet | |
4498 | @item | |
4499 | Adding @samp{-gpr} restricts the zeroing to general-purpose registers. | |
4500 | ||
4501 | @item | |
4502 | Adding @samp{-arg} restricts the zeroing to registers that can sometimes | |
4503 | be used to pass function arguments. This includes all argument registers | |
4504 | defined by the platform's calling conversion, regardless of whether the | |
4505 | function uses those registers for function arguments or not. | |
4506 | @end itemize | |
4507 | ||
4508 | The modifiers can be used individually or together. If they are used | |
4509 | together, they must appear in the order above. | |
4510 | ||
4511 | The full list of @var{choice}s is therefore: | |
4512 | ||
4513 | @table @code | |
4514 | @item skip | |
4515 | doesn't zero any call-used register. | |
4516 | ||
4517 | @item used | |
4518 | only zeros call-used registers that are used in the function. | |
4519 | ||
4520 | @item used-gpr | |
4521 | only zeros call-used general purpose registers that are used in the function. | |
4522 | ||
4523 | @item used-arg | |
4524 | only zeros call-used registers that are used in the function and pass arguments. | |
4525 | ||
4526 | @item used-gpr-arg | |
4527 | only zeros call-used general purpose registers that are used in the function | |
4528 | and pass arguments. | |
4529 | ||
4530 | @item all | |
4531 | zeros all call-used registers. | |
4532 | ||
4533 | @item all-gpr | |
4534 | zeros all call-used general purpose registers. | |
4535 | ||
4536 | @item all-arg | |
4537 | zeros all call-used registers that pass arguments. | |
4538 | ||
4539 | @item all-gpr-arg | |
4540 | zeros all call-used general purpose registers that pass | |
4541 | arguments. | |
83f69969 AO |
4542 | |
4543 | @item leafy | |
4544 | Same as @samp{used} in a leaf function, and same as @samp{all} in a | |
4545 | nonleaf function. | |
4546 | ||
4547 | @item leafy-gpr | |
4548 | Same as @samp{used-gpr} in a leaf function, and same as @samp{all-gpr} | |
4549 | in a nonleaf function. | |
4550 | ||
4551 | @item leafy-arg | |
4552 | Same as @samp{used-arg} in a leaf function, and same as @samp{all-arg} | |
4553 | in a nonleaf function. | |
4554 | ||
4555 | @item leafy-gpr-arg | |
4556 | Same as @samp{used-gpr-arg} in a leaf function, and same as | |
4557 | @samp{all-gpr-arg} in a nonleaf function. | |
4558 | ||
d77de738 ML |
4559 | @end table |
4560 | ||
4561 | Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg}, | |
83f69969 AO |
4562 | @samp{all-gpr-arg}, @samp{leafy-arg}, and @samp{leafy-gpr-arg} are |
4563 | mainly used for ROP mitigation. | |
d77de738 ML |
4564 | |
4565 | The default for the attribute is controlled by @option{-fzero-call-used-regs}. | |
4566 | @end table | |
4567 | ||
4568 | @c This is the end of the target-independent attribute table | |
4569 | ||
4570 | @node AArch64 Function Attributes | |
4571 | @subsection AArch64 Function Attributes | |
4572 | ||
4573 | The following target-specific function attributes are available for the | |
4574 | AArch64 target. For the most part, these options mirror the behavior of | |
4575 | similar command-line options (@pxref{AArch64 Options}), but on a | |
4576 | per-function basis. | |
4577 | ||
4578 | @table @code | |
d77de738 | 4579 | @cindex @code{general-regs-only} function attribute, AArch64 |
f33d7a88 | 4580 | @item general-regs-only |
d77de738 ML |
4581 | Indicates that no floating-point or Advanced SIMD registers should be |
4582 | used when generating code for this function. If the function explicitly | |
4583 | uses floating-point code, then the compiler gives an error. This is | |
4584 | the same behavior as that of the command-line option | |
4585 | @option{-mgeneral-regs-only}. | |
4586 | ||
d77de738 | 4587 | @cindex @code{fix-cortex-a53-835769} function attribute, AArch64 |
f33d7a88 | 4588 | @item fix-cortex-a53-835769 |
d77de738 ML |
4589 | Indicates that the workaround for the Cortex-A53 erratum 835769 should be |
4590 | applied to this function. To explicitly disable the workaround for this | |
4591 | function specify the negated form: @code{no-fix-cortex-a53-835769}. | |
4592 | This corresponds to the behavior of the command line options | |
4593 | @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}. | |
4594 | ||
d77de738 | 4595 | @cindex @code{cmodel=} function attribute, AArch64 |
f33d7a88 | 4596 | @item cmodel= |
d77de738 ML |
4597 | Indicates that code should be generated for a particular code model for |
4598 | this function. The behavior and permissible arguments are the same as | |
4599 | for the command line option @option{-mcmodel=}. | |
4600 | ||
f33d7a88 | 4601 | @cindex @code{strict-align} function attribute, AArch64 |
d77de738 ML |
4602 | @item strict-align |
4603 | @itemx no-strict-align | |
d77de738 ML |
4604 | @code{strict-align} indicates that the compiler should not assume that unaligned |
4605 | memory references are handled by the system. To allow the compiler to assume | |
4606 | that aligned memory references are handled by the system, the inverse attribute | |
4607 | @code{no-strict-align} can be specified. The behavior is same as for the | |
4608 | command-line option @option{-mstrict-align} and @option{-mno-strict-align}. | |
4609 | ||
d77de738 | 4610 | @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64 |
f33d7a88 | 4611 | @item omit-leaf-frame-pointer |
d77de738 ML |
4612 | Indicates that the frame pointer should be omitted for a leaf function call. |
4613 | To keep the frame pointer, the inverse attribute | |
4614 | @code{no-omit-leaf-frame-pointer} can be specified. These attributes have | |
4615 | the same behavior as the command-line options @option{-momit-leaf-frame-pointer} | |
4616 | and @option{-mno-omit-leaf-frame-pointer}. | |
4617 | ||
d77de738 | 4618 | @cindex @code{tls-dialect=} function attribute, AArch64 |
f33d7a88 | 4619 | @item tls-dialect= |
d77de738 ML |
4620 | Specifies the TLS dialect to use for this function. The behavior and |
4621 | permissible arguments are the same as for the command-line option | |
4622 | @option{-mtls-dialect=}. | |
4623 | ||
d77de738 | 4624 | @cindex @code{arch=} function attribute, AArch64 |
f33d7a88 | 4625 | @item arch= |
d77de738 ML |
4626 | Specifies the architecture version and architectural extensions to use |
4627 | for this function. The behavior and permissible arguments are the same as | |
4628 | for the @option{-march=} command-line option. | |
4629 | ||
d77de738 | 4630 | @cindex @code{tune=} function attribute, AArch64 |
f33d7a88 | 4631 | @item tune= |
d77de738 ML |
4632 | Specifies the core for which to tune the performance of this function. |
4633 | The behavior and permissible arguments are the same as for the @option{-mtune=} | |
4634 | command-line option. | |
4635 | ||
d77de738 | 4636 | @cindex @code{cpu=} function attribute, AArch64 |
f33d7a88 | 4637 | @item cpu= |
d77de738 ML |
4638 | Specifies the core for which to tune the performance of this function and also |
4639 | whose architectural features to use. The behavior and valid arguments are the | |
4640 | same as for the @option{-mcpu=} command-line option. | |
4641 | ||
d77de738 | 4642 | @cindex @code{sign-return-address} function attribute, AArch64 |
f33d7a88 | 4643 | @item sign-return-address |
d77de738 ML |
4644 | Select the function scope on which return address signing will be applied. The |
4645 | behavior and permissible arguments are the same as for the command-line option | |
4646 | @option{-msign-return-address=}. The default value is @code{none}. This | |
4647 | attribute is deprecated. The @code{branch-protection} attribute should | |
4648 | be used instead. | |
4649 | ||
d77de738 | 4650 | @cindex @code{branch-protection} function attribute, AArch64 |
f33d7a88 | 4651 | @item branch-protection |
d77de738 ML |
4652 | Select the function scope on which branch protection will be applied. The |
4653 | behavior and permissible arguments are the same as for the command-line option | |
4654 | @option{-mbranch-protection=}. The default value is @code{none}. | |
4655 | ||
d77de738 | 4656 | @cindex @code{outline-atomics} function attribute, AArch64 |
f33d7a88 | 4657 | @item outline-atomics |
d77de738 ML |
4658 | Enable or disable calls to out-of-line helpers to implement atomic operations. |
4659 | This corresponds to the behavior of the command line options | |
4660 | @option{-moutline-atomics} and @option{-mno-outline-atomics}. | |
4661 | ||
4662 | @end table | |
4663 | ||
4664 | The above target attributes can be specified as follows: | |
4665 | ||
4666 | @smallexample | |
4667 | __attribute__((target("@var{attr-string}"))) | |
4668 | int | |
4669 | f (int a) | |
4670 | @{ | |
4671 | return a + 5; | |
4672 | @} | |
4673 | @end smallexample | |
4674 | ||
4675 | where @code{@var{attr-string}} is one of the attribute strings specified above. | |
4676 | ||
4677 | Additionally, the architectural extension string may be specified on its | |
4678 | own. This can be used to turn on and off particular architectural extensions | |
4679 | without having to specify a particular architecture version or core. Example: | |
4680 | ||
4681 | @smallexample | |
4682 | __attribute__((target("+crc+nocrypto"))) | |
4683 | int | |
4684 | foo (int a) | |
4685 | @{ | |
4686 | return a + 5; | |
4687 | @} | |
4688 | @end smallexample | |
4689 | ||
4690 | In this example @code{target("+crc+nocrypto")} enables the @code{crc} | |
4691 | extension and disables the @code{crypto} extension for the function @code{foo} | |
4692 | without modifying an existing @option{-march=} or @option{-mcpu} option. | |
4693 | ||
4694 | Multiple target function attributes can be specified by separating them with | |
4695 | a comma. For example: | |
4696 | @smallexample | |
4697 | __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53"))) | |
4698 | int | |
4699 | foo (int a) | |
4700 | @{ | |
4701 | return a + 5; | |
4702 | @} | |
4703 | @end smallexample | |
4704 | ||
4705 | is valid and compiles function @code{foo} for ARMv8-A with @code{crc} | |
4706 | and @code{crypto} extensions and tunes it for @code{cortex-a53}. | |
4707 | ||
4708 | @subsubsection Inlining rules | |
4709 | Specifying target attributes on individual functions or performing link-time | |
4710 | optimization across translation units compiled with different target options | |
4711 | can affect function inlining rules: | |
4712 | ||
4713 | In particular, a caller function can inline a callee function only if the | |
4714 | architectural features available to the callee are a subset of the features | |
4715 | available to the caller. | |
4716 | For example: A function @code{foo} compiled with @option{-march=armv8-a+crc}, | |
4717 | or tagged with the equivalent @code{arch=armv8-a+crc} attribute, | |
4718 | can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc} | |
4719 | because the all the architectural features that function @code{bar} requires | |
4720 | are available to function @code{foo}. Conversely, function @code{bar} cannot | |
4721 | inline function @code{foo}. | |
4722 | ||
4723 | Additionally inlining a function compiled with @option{-mstrict-align} into a | |
4724 | function compiled without @code{-mstrict-align} is not allowed. | |
4725 | However, inlining a function compiled without @option{-mstrict-align} into a | |
4726 | function compiled with @option{-mstrict-align} is allowed. | |
4727 | ||
4728 | Note that CPU tuning options and attributes such as the @option{-mcpu=}, | |
4729 | @option{-mtune=} do not inhibit inlining unless the CPU specified by the | |
4730 | @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the | |
4731 | architectural feature rules specified above. | |
4732 | ||
4733 | @node AMD GCN Function Attributes | |
4734 | @subsection AMD GCN Function Attributes | |
4735 | ||
4736 | These function attributes are supported by the AMD GCN back end: | |
4737 | ||
4738 | @table @code | |
d77de738 | 4739 | @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN |
f33d7a88 | 4740 | @item amdgpu_hsa_kernel |
d77de738 ML |
4741 | This attribute indicates that the corresponding function should be compiled as |
4742 | a kernel function, that is an entry point that can be invoked from the host | |
4743 | via the HSA runtime library. By default functions are only callable only from | |
4744 | other GCN functions. | |
4745 | ||
4746 | This attribute is implicitly applied to any function named @code{main}, using | |
4747 | default parameters. | |
4748 | ||
4749 | Kernel functions may return an integer value, which will be written to a | |
4750 | conventional place within the HSA "kernargs" region. | |
4751 | ||
4752 | The attribute parameters configure what values are passed into the kernel | |
4753 | function by the GPU drivers, via the initial register state. Some values are | |
4754 | used by the compiler, and therefore forced on. Enabling other options may | |
4755 | break assumptions in the compiler and/or run-time libraries. | |
4756 | ||
4757 | @table @code | |
4758 | @item private_segment_buffer | |
4759 | Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to | |
4760 | locate the stack). | |
4761 | ||
4762 | @item dispatch_ptr | |
4763 | Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the | |
4764 | launch dimensions). | |
4765 | ||
4766 | @item queue_ptr | |
4767 | Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address | |
4768 | spaces). | |
4769 | ||
4770 | @item kernarg_segment_ptr | |
4771 | Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to | |
4772 | locate the kernel arguments, "kernargs"). | |
4773 | ||
4774 | @item dispatch_id | |
4775 | Set @code{enable_sgpr_dispatch_id} flag. | |
4776 | ||
4777 | @item flat_scratch_init | |
4778 | Set @code{enable_sgpr_flat_scratch_init} flag. | |
4779 | ||
4780 | @item private_segment_size | |
4781 | Set @code{enable_sgpr_private_segment_size} flag. | |
4782 | ||
4783 | @item grid_workgroup_count_X | |
4784 | Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to | |
4785 | use OpenACC/OpenMP). | |
4786 | ||
4787 | @item grid_workgroup_count_Y | |
4788 | Set @code{enable_sgpr_grid_workgroup_count_y} flag. | |
4789 | ||
4790 | @item grid_workgroup_count_Z | |
4791 | Set @code{enable_sgpr_grid_workgroup_count_z} flag. | |
4792 | ||
4793 | @item workgroup_id_X | |
4794 | Set @code{enable_sgpr_workgroup_id_x} flag. | |
4795 | ||
4796 | @item workgroup_id_Y | |
4797 | Set @code{enable_sgpr_workgroup_id_y} flag. | |
4798 | ||
4799 | @item workgroup_id_Z | |
4800 | Set @code{enable_sgpr_workgroup_id_z} flag. | |
4801 | ||
4802 | @item workgroup_info | |
4803 | Set @code{enable_sgpr_workgroup_info} flag. | |
4804 | ||
4805 | @item private_segment_wave_offset | |
4806 | Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on | |
4807 | (required to locate the stack). | |
4808 | ||
4809 | @item work_item_id_X | |
4810 | Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled). | |
4811 | ||
4812 | @item work_item_id_Y | |
4813 | Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable | |
4814 | vectorization.) | |
4815 | ||
4816 | @item work_item_id_Z | |
4817 | Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use | |
4818 | OpenACC/OpenMP). | |
4819 | ||
4820 | @end table | |
4821 | @end table | |
4822 | ||
4823 | @node ARC Function Attributes | |
4824 | @subsection ARC Function Attributes | |
4825 | ||
4826 | These function attributes are supported by the ARC back end: | |
4827 | ||
4828 | @table @code | |
d77de738 | 4829 | @cindex @code{interrupt} function attribute, ARC |
f33d7a88 | 4830 | @item interrupt |
d77de738 ML |
4831 | Use this attribute to indicate |
4832 | that the specified function is an interrupt handler. The compiler generates | |
4833 | function entry and exit sequences suitable for use in an interrupt handler | |
4834 | when this attribute is present. | |
4835 | ||
4836 | On the ARC, you must specify the kind of interrupt to be handled | |
4837 | in a parameter to the interrupt attribute like this: | |
4838 | ||
4839 | @smallexample | |
4840 | void f () __attribute__ ((interrupt ("ilink1"))); | |
4841 | @end smallexample | |
4842 | ||
4843 | Permissible values for this parameter are: @w{@code{ilink1}} and | |
4844 | @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and | |
4845 | @w{@code{firq}} for ARCv2 architecture. | |
4846 | ||
d77de738 ML |
4847 | @cindex @code{long_call} function attribute, ARC |
4848 | @cindex @code{medium_call} function attribute, ARC | |
4849 | @cindex @code{short_call} function attribute, ARC | |
4850 | @cindex indirect calls, ARC | |
f33d7a88 AA |
4851 | @item long_call |
4852 | @itemx medium_call | |
4853 | @itemx short_call | |
d77de738 ML |
4854 | These attributes specify how a particular function is called. |
4855 | These attributes override the | |
4856 | @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options}) | |
4857 | command-line switches and @code{#pragma long_calls} settings. | |
4858 | ||
4859 | For ARC, a function marked with the @code{long_call} attribute is | |
4860 | always called using register-indirect jump-and-link instructions, | |
4861 | thereby enabling the called function to be placed anywhere within the | |
4862 | 32-bit address space. A function marked with the @code{medium_call} | |
4863 | attribute will always be close enough to be called with an unconditional | |
4864 | branch-and-link instruction, which has a 25-bit offset from | |
4865 | the call site. A function marked with the @code{short_call} | |
4866 | attribute will always be close enough to be called with a conditional | |
4867 | branch-and-link instruction, which has a 21-bit offset from | |
4868 | the call site. | |
4869 | ||
d77de738 | 4870 | @cindex @code{jli_always} function attribute, ARC |
f33d7a88 | 4871 | @item jli_always |
d77de738 ML |
4872 | Forces a particular function to be called using @code{jli} |
4873 | instruction. The @code{jli} instruction makes use of a table stored | |
4874 | into @code{.jlitab} section, which holds the location of the functions | |
4875 | which are addressed using this instruction. | |
4876 | ||
d77de738 | 4877 | @cindex @code{jli_fixed} function attribute, ARC |
f33d7a88 | 4878 | @item jli_fixed |
d77de738 ML |
4879 | Identical like the above one, but the location of the function in the |
4880 | @code{jli} table is known and given as an attribute parameter. | |
4881 | ||
d77de738 | 4882 | @cindex @code{secure_call} function attribute, ARC |
f33d7a88 | 4883 | @item secure_call |
d77de738 ML |
4884 | This attribute allows one to mark secure-code functions that are |
4885 | callable from normal mode. The location of the secure call function | |
4886 | into the @code{sjli} table needs to be passed as argument. | |
4887 | ||
d77de738 | 4888 | @cindex @code{naked} function attribute, ARC |
f33d7a88 | 4889 | @item naked |
d77de738 ML |
4890 | This attribute allows the compiler to construct the requisite function |
4891 | declaration, while allowing the body of the function to be assembly | |
4892 | code. The specified function will not have prologue/epilogue | |
4893 | sequences generated by the compiler. Only basic @code{asm} statements | |
4894 | can safely be included in naked functions (@pxref{Basic Asm}). While | |
4895 | using extended @code{asm} or a mixture of basic @code{asm} and C code | |
4896 | may appear to work, they cannot be depended upon to work reliably and | |
4897 | are not supported. | |
4898 | ||
4899 | @end table | |
4900 | ||
4901 | @node ARM Function Attributes | |
4902 | @subsection ARM Function Attributes | |
4903 | ||
4904 | These function attributes are supported for ARM targets: | |
4905 | ||
4906 | @table @code | |
4907 | ||
d77de738 | 4908 | @cindex @code{general-regs-only} function attribute, ARM |
f33d7a88 | 4909 | @item general-regs-only |
d77de738 ML |
4910 | Indicates that no floating-point or Advanced SIMD registers should be |
4911 | used when generating code for this function. If the function explicitly | |
4912 | uses floating-point code, then the compiler gives an error. This is | |
4913 | the same behavior as that of the command-line option | |
4914 | @option{-mgeneral-regs-only}. | |
4915 | ||
d77de738 | 4916 | @cindex @code{interrupt} function attribute, ARM |
f33d7a88 | 4917 | @item interrupt |
d77de738 ML |
4918 | Use this attribute to indicate |
4919 | that the specified function is an interrupt handler. The compiler generates | |
4920 | function entry and exit sequences suitable for use in an interrupt handler | |
4921 | when this attribute is present. | |
4922 | ||
4923 | You can specify the kind of interrupt to be handled by | |
4924 | adding an optional parameter to the interrupt attribute like this: | |
4925 | ||
4926 | @smallexample | |
4927 | void f () __attribute__ ((interrupt ("IRQ"))); | |
4928 | @end smallexample | |
4929 | ||
4930 | @noindent | |
4931 | Permissible values for this parameter are: @code{IRQ}, @code{FIQ}, | |
4932 | @code{SWI}, @code{ABORT} and @code{UNDEF}. | |
4933 | ||
4934 | On ARMv7-M the interrupt type is ignored, and the attribute means the function | |
4935 | may be called with a word-aligned stack pointer. | |
4936 | ||
d77de738 | 4937 | @cindex @code{isr} function attribute, ARM |
f33d7a88 | 4938 | @item isr |
d77de738 ML |
4939 | Use this attribute on ARM to write Interrupt Service Routines. This is an |
4940 | alias to the @code{interrupt} attribute above. | |
4941 | ||
d77de738 ML |
4942 | @cindex @code{long_call} function attribute, ARM |
4943 | @cindex @code{short_call} function attribute, ARM | |
4944 | @cindex indirect calls, ARM | |
f33d7a88 AA |
4945 | @item long_call |
4946 | @itemx short_call | |
d77de738 ML |
4947 | These attributes specify how a particular function is called. |
4948 | These attributes override the | |
4949 | @option{-mlong-calls} (@pxref{ARM Options}) | |
4950 | command-line switch and @code{#pragma long_calls} settings. For ARM, the | |
4951 | @code{long_call} attribute indicates that the function might be far | |
4952 | away from the call site and require a different (more expensive) | |
4953 | calling sequence. The @code{short_call} attribute always places | |
4954 | the offset to the function from the call site into the @samp{BL} | |
4955 | instruction directly. | |
4956 | ||
d77de738 | 4957 | @cindex @code{naked} function attribute, ARM |
f33d7a88 | 4958 | @item naked |
d77de738 ML |
4959 | This attribute allows the compiler to construct the |
4960 | requisite function declaration, while allowing the body of the | |
4961 | function to be assembly code. The specified function will not have | |
4962 | prologue/epilogue sequences generated by the compiler. Only basic | |
4963 | @code{asm} statements can safely be included in naked functions | |
4964 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
4965 | basic @code{asm} and C code may appear to work, they cannot be | |
4966 | depended upon to work reliably and are not supported. | |
4967 | ||
d77de738 | 4968 | @cindex @code{pcs} function attribute, ARM |
f33d7a88 | 4969 | @item pcs |
d77de738 ML |
4970 | |
4971 | The @code{pcs} attribute can be used to control the calling convention | |
4972 | used for a function on ARM. The attribute takes an argument that specifies | |
4973 | the calling convention to use. | |
4974 | ||
4975 | When compiling using the AAPCS ABI (or a variant of it) then valid | |
4976 | values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In | |
4977 | order to use a variant other than @code{"aapcs"} then the compiler must | |
4978 | be permitted to use the appropriate co-processor registers (i.e., the | |
4979 | VFP registers must be available in order to use @code{"aapcs-vfp"}). | |
4980 | For example, | |
4981 | ||
4982 | @smallexample | |
4983 | /* Argument passed in r0, and result returned in r0+r1. */ | |
4984 | double f2d (float) __attribute__((pcs("aapcs"))); | |
4985 | @end smallexample | |
4986 | ||
4987 | Variadic functions always use the @code{"aapcs"} calling convention and | |
4988 | the compiler rejects attempts to specify an alternative. | |
4989 | ||
d77de738 | 4990 | @cindex @code{target} function attribute |
f33d7a88 | 4991 | @item target (@var{options}) |
d77de738 ML |
4992 | As discussed in @ref{Common Function Attributes}, this attribute |
4993 | allows specification of target-specific compilation options. | |
4994 | ||
4995 | On ARM, the following options are allowed: | |
4996 | ||
4997 | @table @samp | |
d77de738 | 4998 | @cindex @code{target("thumb")} function attribute, ARM |
f33d7a88 | 4999 | @item thumb |
d77de738 ML |
5000 | Force code generation in the Thumb (T16/T32) ISA, depending on the |
5001 | architecture level. | |
5002 | ||
d77de738 | 5003 | @cindex @code{target("arm")} function attribute, ARM |
f33d7a88 | 5004 | @item arm |
d77de738 ML |
5005 | Force code generation in the ARM (A32) ISA. |
5006 | ||
5007 | Functions from different modes can be inlined in the caller's mode. | |
5008 | ||
d77de738 | 5009 | @cindex @code{target("fpu=")} function attribute, ARM |
f33d7a88 | 5010 | @item fpu= |
d77de738 ML |
5011 | Specifies the fpu for which to tune the performance of this function. |
5012 | The behavior and permissible arguments are the same as for the @option{-mfpu=} | |
5013 | command-line option. | |
5014 | ||
d77de738 | 5015 | @cindex @code{arch=} function attribute, ARM |
f33d7a88 | 5016 | @item arch= |
d77de738 ML |
5017 | Specifies the architecture version and architectural extensions to use |
5018 | for this function. The behavior and permissible arguments are the same as | |
5019 | for the @option{-march=} command-line option. | |
5020 | ||
5021 | The above target attributes can be specified as follows: | |
5022 | ||
5023 | @smallexample | |
5024 | __attribute__((target("arch=armv8-a+crc"))) | |
5025 | int | |
5026 | f (int a) | |
5027 | @{ | |
5028 | return a + 5; | |
5029 | @} | |
5030 | @end smallexample | |
5031 | ||
5032 | Additionally, the architectural extension string may be specified on its | |
5033 | own. This can be used to turn on and off particular architectural extensions | |
5034 | without having to specify a particular architecture version or core. Example: | |
5035 | ||
5036 | @smallexample | |
5037 | __attribute__((target("+crc+nocrypto"))) | |
5038 | int | |
5039 | foo (int a) | |
5040 | @{ | |
5041 | return a + 5; | |
5042 | @} | |
5043 | @end smallexample | |
5044 | ||
5045 | In this example @code{target("+crc+nocrypto")} enables the @code{crc} | |
5046 | extension and disables the @code{crypto} extension for the function @code{foo} | |
5047 | without modifying an existing @option{-march=} or @option{-mcpu} option. | |
5048 | ||
5049 | @end table | |
5050 | ||
5051 | @end table | |
5052 | ||
5053 | @node AVR Function Attributes | |
5054 | @subsection AVR Function Attributes | |
5055 | ||
5056 | These function attributes are supported by the AVR back end: | |
5057 | ||
5058 | @table @code | |
d77de738 | 5059 | @cindex @code{interrupt} function attribute, AVR |
f33d7a88 | 5060 | @item interrupt |
d77de738 ML |
5061 | Use this attribute to indicate |
5062 | that the specified function is an interrupt handler. The compiler generates | |
5063 | function entry and exit sequences suitable for use in an interrupt handler | |
5064 | when this attribute is present. | |
5065 | ||
5066 | On the AVR, the hardware globally disables interrupts when an | |
5067 | interrupt is executed. The first instruction of an interrupt handler | |
5068 | declared with this attribute is a @code{SEI} instruction to | |
5069 | re-enable interrupts. See also the @code{signal} function attribute | |
5070 | that does not insert a @code{SEI} instruction. If both @code{signal} and | |
5071 | @code{interrupt} are specified for the same function, @code{signal} | |
5072 | is silently ignored. | |
5073 | ||
d77de738 | 5074 | @cindex @code{naked} function attribute, AVR |
f33d7a88 | 5075 | @item naked |
d77de738 ML |
5076 | This attribute allows the compiler to construct the |
5077 | requisite function declaration, while allowing the body of the | |
5078 | function to be assembly code. The specified function will not have | |
5079 | prologue/epilogue sequences generated by the compiler. Only basic | |
5080 | @code{asm} statements can safely be included in naked functions | |
5081 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5082 | basic @code{asm} and C code may appear to work, they cannot be | |
5083 | depended upon to work reliably and are not supported. | |
5084 | ||
d77de738 | 5085 | @cindex @code{no_gccisr} function attribute, AVR |
f33d7a88 | 5086 | @item no_gccisr |
d77de738 ML |
5087 | Do not use @code{__gcc_isr} pseudo instructions in a function with |
5088 | the @code{interrupt} or @code{signal} attribute aka. interrupt | |
5089 | service routine (ISR). | |
5090 | Use this attribute if the preamble of the ISR prologue should always read | |
5091 | @example | |
5092 | push __zero_reg__ | |
5093 | push __tmp_reg__ | |
5094 | in __tmp_reg__, __SREG__ | |
5095 | push __tmp_reg__ | |
5096 | clr __zero_reg__ | |
5097 | @end example | |
5098 | and accordingly for the postamble of the epilogue --- no matter whether | |
5099 | the mentioned registers are actually used in the ISR or not. | |
5100 | Situations where you might want to use this attribute include: | |
5101 | @itemize @bullet | |
5102 | @item | |
5103 | Code that (effectively) clobbers bits of @code{SREG} other than the | |
5104 | @code{I}-flag by writing to the memory location of @code{SREG}. | |
5105 | @item | |
5106 | Code that uses inline assembler to jump to a different function which | |
5107 | expects (parts of) the prologue code as outlined above to be present. | |
5108 | @end itemize | |
5109 | To disable @code{__gcc_isr} generation for the whole compilation unit, | |
5110 | there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}. | |
5111 | ||
d77de738 ML |
5112 | @cindex @code{OS_main} function attribute, AVR |
5113 | @cindex @code{OS_task} function attribute, AVR | |
f33d7a88 AA |
5114 | @item OS_main |
5115 | @itemx OS_task | |
d77de738 ML |
5116 | On AVR, functions with the @code{OS_main} or @code{OS_task} attribute |
5117 | do not save/restore any call-saved register in their prologue/epilogue. | |
5118 | ||
5119 | The @code{OS_main} attribute can be used when there @emph{is | |
5120 | guarantee} that interrupts are disabled at the time when the function | |
5121 | is entered. This saves resources when the stack pointer has to be | |
5122 | changed to set up a frame for local variables. | |
5123 | ||
5124 | The @code{OS_task} attribute can be used when there is @emph{no | |
5125 | guarantee} that interrupts are disabled at that time when the function | |
5126 | is entered like for, e@.g@. task functions in a multi-threading operating | |
5127 | system. In that case, changing the stack pointer register is | |
5128 | guarded by save/clear/restore of the global interrupt enable flag. | |
5129 | ||
5130 | The differences to the @code{naked} function attribute are: | |
5131 | @itemize @bullet | |
5132 | @item @code{naked} functions do not have a return instruction whereas | |
5133 | @code{OS_main} and @code{OS_task} functions have a @code{RET} or | |
5134 | @code{RETI} return instruction. | |
5135 | @item @code{naked} functions do not set up a frame for local variables | |
5136 | or a frame pointer whereas @code{OS_main} and @code{OS_task} do this | |
5137 | as needed. | |
5138 | @end itemize | |
5139 | ||
d77de738 | 5140 | @cindex @code{signal} function attribute, AVR |
f33d7a88 | 5141 | @item signal |
d77de738 ML |
5142 | Use this attribute on the AVR to indicate that the specified |
5143 | function is an interrupt handler. The compiler generates function | |
5144 | entry and exit sequences suitable for use in an interrupt handler when this | |
5145 | attribute is present. | |
5146 | ||
5147 | See also the @code{interrupt} function attribute. | |
5148 | ||
5149 | The AVR hardware globally disables interrupts when an interrupt is executed. | |
5150 | Interrupt handler functions defined with the @code{signal} attribute | |
5151 | do not re-enable interrupts. It is save to enable interrupts in a | |
5152 | @code{signal} handler. This ``save'' only applies to the code | |
5153 | generated by the compiler and not to the IRQ layout of the | |
5154 | application which is responsibility of the application. | |
5155 | ||
5156 | If both @code{signal} and @code{interrupt} are specified for the same | |
5157 | function, @code{signal} is silently ignored. | |
5158 | @end table | |
5159 | ||
5160 | @node Blackfin Function Attributes | |
5161 | @subsection Blackfin Function Attributes | |
5162 | ||
5163 | These function attributes are supported by the Blackfin back end: | |
5164 | ||
5165 | @table @code | |
5166 | ||
d77de738 ML |
5167 | @cindex @code{exception_handler} function attribute |
5168 | @cindex exception handler functions, Blackfin | |
f33d7a88 | 5169 | @item exception_handler |
d77de738 ML |
5170 | Use this attribute on the Blackfin to indicate that the specified function |
5171 | is an exception handler. The compiler generates function entry and | |
5172 | exit sequences suitable for use in an exception handler when this | |
5173 | attribute is present. | |
5174 | ||
d77de738 | 5175 | @cindex @code{interrupt_handler} function attribute, Blackfin |
f33d7a88 | 5176 | @item interrupt_handler |
d77de738 ML |
5177 | Use this attribute to |
5178 | indicate that the specified function is an interrupt handler. The compiler | |
5179 | generates function entry and exit sequences suitable for use in an | |
5180 | interrupt handler when this attribute is present. | |
5181 | ||
d77de738 ML |
5182 | @cindex @code{kspisusp} function attribute, Blackfin |
5183 | @cindex User stack pointer in interrupts on the Blackfin | |
f33d7a88 | 5184 | @item kspisusp |
d77de738 ML |
5185 | When used together with @code{interrupt_handler}, @code{exception_handler} |
5186 | or @code{nmi_handler}, code is generated to load the stack pointer | |
5187 | from the USP register in the function prologue. | |
5188 | ||
d77de738 | 5189 | @cindex @code{l1_text} function attribute, Blackfin |
f33d7a88 | 5190 | @item l1_text |
d77de738 ML |
5191 | This attribute specifies a function to be placed into L1 Instruction |
5192 | SRAM@. The function is put into a specific section named @code{.l1.text}. | |
5193 | With @option{-mfdpic}, function calls with a such function as the callee | |
5194 | or caller uses inlined PLT. | |
5195 | ||
d77de738 | 5196 | @cindex @code{l2} function attribute, Blackfin |
f33d7a88 | 5197 | @item l2 |
d77de738 ML |
5198 | This attribute specifies a function to be placed into L2 |
5199 | SRAM. The function is put into a specific section named | |
5200 | @code{.l2.text}. With @option{-mfdpic}, callers of such functions use | |
5201 | an inlined PLT. | |
5202 | ||
d77de738 ML |
5203 | @cindex indirect calls, Blackfin |
5204 | @cindex @code{longcall} function attribute, Blackfin | |
5205 | @cindex @code{shortcall} function attribute, Blackfin | |
f33d7a88 AA |
5206 | @item longcall |
5207 | @itemx shortcall | |
d77de738 ML |
5208 | The @code{longcall} attribute |
5209 | indicates that the function might be far away from the call site and | |
5210 | require a different (more expensive) calling sequence. The | |
5211 | @code{shortcall} attribute indicates that the function is always close | |
5212 | enough for the shorter calling sequence to be used. These attributes | |
5213 | override the @option{-mlongcall} switch. | |
5214 | ||
d77de738 ML |
5215 | @cindex @code{nesting} function attribute, Blackfin |
5216 | @cindex Allow nesting in an interrupt handler on the Blackfin processor | |
f33d7a88 | 5217 | @item nesting |
d77de738 ML |
5218 | Use this attribute together with @code{interrupt_handler}, |
5219 | @code{exception_handler} or @code{nmi_handler} to indicate that the function | |
5220 | entry code should enable nested interrupts or exceptions. | |
5221 | ||
d77de738 ML |
5222 | @cindex @code{nmi_handler} function attribute, Blackfin |
5223 | @cindex NMI handler functions on the Blackfin processor | |
f33d7a88 | 5224 | @item nmi_handler |
d77de738 ML |
5225 | Use this attribute on the Blackfin to indicate that the specified function |
5226 | is an NMI handler. The compiler generates function entry and | |
5227 | exit sequences suitable for use in an NMI handler when this | |
5228 | attribute is present. | |
5229 | ||
d77de738 ML |
5230 | @cindex @code{saveall} function attribute, Blackfin |
5231 | @cindex save all registers on the Blackfin | |
f33d7a88 | 5232 | @item saveall |
d77de738 ML |
5233 | Use this attribute to indicate that |
5234 | all registers except the stack pointer should be saved in the prologue | |
5235 | regardless of whether they are used or not. | |
5236 | @end table | |
5237 | ||
5238 | @node BPF Function Attributes | |
5239 | @subsection BPF Function Attributes | |
5240 | ||
5241 | These function attributes are supported by the BPF back end: | |
5242 | ||
5243 | @table @code | |
d77de738 | 5244 | @cindex @code{kernel helper}, function attribute, BPF |
f33d7a88 | 5245 | @item kernel_helper |
d77de738 ML |
5246 | use this attribute to indicate the specified function declaration is a |
5247 | kernel helper. The helper function is passed as an argument to the | |
5248 | attribute. Example: | |
5249 | ||
5250 | @smallexample | |
5251 | int bpf_probe_read (void *dst, int size, const void *unsafe_ptr) | |
5252 | __attribute__ ((kernel_helper (4))); | |
5253 | @end smallexample | |
b7c50f68 JM |
5254 | |
5255 | @cindex @code{naked} function attribute, BPF | |
5256 | @item naked | |
5257 | This attribute allows the compiler to construct the requisite function | |
5258 | declaration, while allowing the body of the function to be assembly | |
5259 | code. The specified function will not have prologue/epilogue | |
5260 | sequences generated by the compiler. Only basic @code{asm} statements | |
5261 | can safely be included in naked functions (@pxref{Basic Asm}). While | |
5262 | using extended @code{asm} or a mixture of basic @code{asm} and C code | |
5263 | may appear to work, they cannot be depended upon to work reliably and | |
5264 | are not supported. | |
d77de738 ML |
5265 | @end table |
5266 | ||
5267 | @node C-SKY Function Attributes | |
5268 | @subsection C-SKY Function Attributes | |
5269 | ||
5270 | These function attributes are supported by the C-SKY back end: | |
5271 | ||
5272 | @table @code | |
d77de738 ML |
5273 | @cindex @code{interrupt} function attribute, C-SKY |
5274 | @cindex @code{isr} function attribute, C-SKY | |
f33d7a88 AA |
5275 | @item interrupt |
5276 | @itemx isr | |
d77de738 ML |
5277 | Use these attributes to indicate that the specified function |
5278 | is an interrupt handler. | |
5279 | The compiler generates function entry and exit sequences suitable for | |
5280 | use in an interrupt handler when either of these attributes are present. | |
5281 | ||
5282 | Use of these options requires the @option{-mistack} command-line option | |
5283 | to enable support for the necessary interrupt stack instructions. They | |
5284 | are ignored with a warning otherwise. @xref{C-SKY Options}. | |
5285 | ||
d77de738 | 5286 | @cindex @code{naked} function attribute, C-SKY |
f33d7a88 | 5287 | @item naked |
d77de738 ML |
5288 | This attribute allows the compiler to construct the |
5289 | requisite function declaration, while allowing the body of the | |
5290 | function to be assembly code. The specified function will not have | |
5291 | prologue/epilogue sequences generated by the compiler. Only basic | |
5292 | @code{asm} statements can safely be included in naked functions | |
5293 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5294 | basic @code{asm} and C code may appear to work, they cannot be | |
5295 | depended upon to work reliably and are not supported. | |
5296 | @end table | |
5297 | ||
5298 | ||
5299 | @node Epiphany Function Attributes | |
5300 | @subsection Epiphany Function Attributes | |
5301 | ||
5302 | These function attributes are supported by the Epiphany back end: | |
5303 | ||
5304 | @table @code | |
d77de738 | 5305 | @cindex @code{disinterrupt} function attribute, Epiphany |
f33d7a88 | 5306 | @item disinterrupt |
d77de738 ML |
5307 | This attribute causes the compiler to emit |
5308 | instructions to disable interrupts for the duration of the given | |
5309 | function. | |
5310 | ||
d77de738 | 5311 | @cindex @code{forwarder_section} function attribute, Epiphany |
f33d7a88 | 5312 | @item forwarder_section |
d77de738 ML |
5313 | This attribute modifies the behavior of an interrupt handler. |
5314 | The interrupt handler may be in external memory which cannot be | |
5315 | reached by a branch instruction, so generate a local memory trampoline | |
5316 | to transfer control. The single parameter identifies the section where | |
5317 | the trampoline is placed. | |
5318 | ||
d77de738 | 5319 | @cindex @code{interrupt} function attribute, Epiphany |
f33d7a88 | 5320 | @item interrupt |
d77de738 ML |
5321 | Use this attribute to indicate |
5322 | that the specified function is an interrupt handler. The compiler generates | |
5323 | function entry and exit sequences suitable for use in an interrupt handler | |
5324 | when this attribute is present. It may also generate | |
5325 | a special section with code to initialize the interrupt vector table. | |
5326 | ||
5327 | On Epiphany targets one or more optional parameters can be added like this: | |
5328 | ||
5329 | @smallexample | |
5330 | void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); | |
5331 | @end smallexample | |
5332 | ||
5333 | Permissible values for these parameters are: @w{@code{reset}}, | |
5334 | @w{@code{software_exception}}, @w{@code{page_miss}}, | |
5335 | @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, | |
5336 | @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. | |
5337 | Multiple parameters indicate that multiple entries in the interrupt | |
5338 | vector table should be initialized for this function, i.e.@: for each | |
5339 | parameter @w{@var{name}}, a jump to the function is emitted in | |
5340 | the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted | |
5341 | entirely, in which case no interrupt vector table entry is provided. | |
5342 | ||
5343 | Note that interrupts are enabled inside the function | |
5344 | unless the @code{disinterrupt} attribute is also specified. | |
5345 | ||
5346 | The following examples are all valid uses of these attributes on | |
5347 | Epiphany targets: | |
5348 | @smallexample | |
5349 | void __attribute__ ((interrupt)) universal_handler (); | |
5350 | void __attribute__ ((interrupt ("dma1"))) dma1_handler (); | |
5351 | void __attribute__ ((interrupt ("dma0, dma1"))) | |
5352 | universal_dma_handler (); | |
5353 | void __attribute__ ((interrupt ("timer0"), disinterrupt)) | |
5354 | fast_timer_handler (); | |
5355 | void __attribute__ ((interrupt ("dma0, dma1"), | |
5356 | forwarder_section ("tramp"))) | |
5357 | external_dma_handler (); | |
5358 | @end smallexample | |
5359 | ||
d77de738 ML |
5360 | @cindex @code{long_call} function attribute, Epiphany |
5361 | @cindex @code{short_call} function attribute, Epiphany | |
5362 | @cindex indirect calls, Epiphany | |
f33d7a88 AA |
5363 | @item long_call |
5364 | @itemx short_call | |
d77de738 ML |
5365 | These attributes specify how a particular function is called. |
5366 | These attributes override the | |
5367 | @option{-mlong-calls} (@pxref{Adapteva Epiphany Options}) | |
5368 | command-line switch and @code{#pragma long_calls} settings. | |
5369 | @end table | |
5370 | ||
5371 | ||
5372 | @node H8/300 Function Attributes | |
5373 | @subsection H8/300 Function Attributes | |
5374 | ||
5375 | These function attributes are available for H8/300 targets: | |
5376 | ||
5377 | @table @code | |
d77de738 | 5378 | @cindex @code{function_vector} function attribute, H8/300 |
f33d7a88 | 5379 | @item function_vector |
d77de738 ML |
5380 | Use this attribute on the H8/300, H8/300H, and H8S to indicate |
5381 | that the specified function should be called through the function vector. | |
5382 | Calling a function through the function vector reduces code size; however, | |
5383 | the function vector has a limited size (maximum 128 entries on the H8/300 | |
5384 | and 64 entries on the H8/300H and H8S) | |
5385 | and shares space with the interrupt vector. | |
5386 | ||
d77de738 | 5387 | @cindex @code{interrupt_handler} function attribute, H8/300 |
f33d7a88 | 5388 | @item interrupt_handler |
d77de738 ML |
5389 | Use this attribute on the H8/300, H8/300H, and H8S to |
5390 | indicate that the specified function is an interrupt handler. The compiler | |
5391 | generates function entry and exit sequences suitable for use in an | |
5392 | interrupt handler when this attribute is present. | |
5393 | ||
d77de738 ML |
5394 | @cindex @code{saveall} function attribute, H8/300 |
5395 | @cindex save all registers on the H8/300, H8/300H, and H8S | |
f33d7a88 | 5396 | @item saveall |
d77de738 ML |
5397 | Use this attribute on the H8/300, H8/300H, and H8S to indicate that |
5398 | all registers except the stack pointer should be saved in the prologue | |
5399 | regardless of whether they are used or not. | |
5400 | @end table | |
5401 | ||
5402 | @node IA-64 Function Attributes | |
5403 | @subsection IA-64 Function Attributes | |
5404 | ||
5405 | These function attributes are supported on IA-64 targets: | |
5406 | ||
5407 | @table @code | |
d77de738 | 5408 | @cindex @code{syscall_linkage} function attribute, IA-64 |
f33d7a88 | 5409 | @item syscall_linkage |
d77de738 ML |
5410 | This attribute is used to modify the IA-64 calling convention by marking |
5411 | all input registers as live at all function exits. This makes it possible | |
5412 | to restart a system call after an interrupt without having to save/restore | |
5413 | the input registers. This also prevents kernel data from leaking into | |
5414 | application code. | |
5415 | ||
d77de738 | 5416 | @cindex @code{version_id} function attribute, IA-64 |
f33d7a88 | 5417 | @item version_id |
d77de738 ML |
5418 | This IA-64 HP-UX attribute, attached to a global variable or function, renames a |
5419 | symbol to contain a version string, thus allowing for function level | |
5420 | versioning. HP-UX system header files may use function level versioning | |
5421 | for some system calls. | |
5422 | ||
5423 | @smallexample | |
5424 | extern int foo () __attribute__((version_id ("20040821"))); | |
5425 | @end smallexample | |
5426 | ||
5427 | @noindent | |
5428 | Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}. | |
5429 | @end table | |
5430 | ||
5431 | @node M32C Function Attributes | |
5432 | @subsection M32C Function Attributes | |
5433 | ||
5434 | These function attributes are supported by the M32C back end: | |
5435 | ||
5436 | @table @code | |
d77de738 | 5437 | @cindex @code{bank_switch} function attribute, M32C |
f33d7a88 | 5438 | @item bank_switch |
d77de738 ML |
5439 | When added to an interrupt handler with the M32C port, causes the |
5440 | prologue and epilogue to use bank switching to preserve the registers | |
5441 | rather than saving them on the stack. | |
5442 | ||
d77de738 | 5443 | @cindex @code{fast_interrupt} function attribute, M32C |
f33d7a88 | 5444 | @item fast_interrupt |
d77de738 ML |
5445 | Use this attribute on the M32C port to indicate that the specified |
5446 | function is a fast interrupt handler. This is just like the | |
5447 | @code{interrupt} attribute, except that @code{freit} is used to return | |
5448 | instead of @code{reit}. | |
5449 | ||
d77de738 | 5450 | @cindex @code{function_vector} function attribute, M16C/M32C |
f33d7a88 | 5451 | @item function_vector |
d77de738 ML |
5452 | On M16C/M32C targets, the @code{function_vector} attribute declares a |
5453 | special page subroutine call function. Use of this attribute reduces | |
5454 | the code size by 2 bytes for each call generated to the | |
5455 | subroutine. The argument to the attribute is the vector number entry | |
5456 | from the special page vector table which contains the 16 low-order | |
5457 | bits of the subroutine's entry address. Each vector table has special | |
5458 | page number (18 to 255) that is used in @code{jsrs} instructions. | |
5459 | Jump addresses of the routines are generated by adding 0x0F0000 (in | |
5460 | case of M16C targets) or 0xFF0000 (in case of M32C targets), to the | |
5461 | 2-byte addresses set in the vector table. Therefore you need to ensure | |
5462 | that all the special page vector routines should get mapped within the | |
5463 | address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF | |
5464 | (for M32C). | |
5465 | ||
5466 | In the following example 2 bytes are saved for each call to | |
5467 | function @code{foo}. | |
5468 | ||
5469 | @smallexample | |
5470 | void foo (void) __attribute__((function_vector(0x18))); | |
5471 | void foo (void) | |
5472 | @{ | |
5473 | @} | |
5474 | ||
5475 | void bar (void) | |
5476 | @{ | |
5477 | foo(); | |
5478 | @} | |
5479 | @end smallexample | |
5480 | ||
5481 | If functions are defined in one file and are called in another file, | |
5482 | then be sure to write this declaration in both files. | |
5483 | ||
5484 | This attribute is ignored for R8C target. | |
5485 | ||
d77de738 | 5486 | @cindex @code{interrupt} function attribute, M32C |
f33d7a88 | 5487 | @item interrupt |
d77de738 ML |
5488 | Use this attribute to indicate |
5489 | that the specified function is an interrupt handler. The compiler generates | |
5490 | function entry and exit sequences suitable for use in an interrupt handler | |
5491 | when this attribute is present. | |
5492 | @end table | |
5493 | ||
5494 | @node M32R/D Function Attributes | |
5495 | @subsection M32R/D Function Attributes | |
5496 | ||
5497 | These function attributes are supported by the M32R/D back end: | |
5498 | ||
5499 | @table @code | |
d77de738 | 5500 | @cindex @code{interrupt} function attribute, M32R/D |
f33d7a88 | 5501 | @item interrupt |
d77de738 ML |
5502 | Use this attribute to indicate |
5503 | that the specified function is an interrupt handler. The compiler generates | |
5504 | function entry and exit sequences suitable for use in an interrupt handler | |
5505 | when this attribute is present. | |
5506 | ||
d77de738 ML |
5507 | @cindex @code{model} function attribute, M32R/D |
5508 | @cindex function addressability on the M32R/D | |
f33d7a88 | 5509 | @item model (@var{model-name}) |
d77de738 ML |
5510 | |
5511 | On the M32R/D, use this attribute to set the addressability of an | |
5512 | object, and of the code generated for a function. The identifier | |
5513 | @var{model-name} is one of @code{small}, @code{medium}, or | |
5514 | @code{large}, representing each of the code models. | |
5515 | ||
5516 | Small model objects live in the lower 16MB of memory (so that their | |
5517 | addresses can be loaded with the @code{ld24} instruction), and are | |
5518 | callable with the @code{bl} instruction. | |
5519 | ||
5520 | Medium model objects may live anywhere in the 32-bit address space (the | |
5521 | compiler generates @code{seth/add3} instructions to load their addresses), | |
5522 | and are callable with the @code{bl} instruction. | |
5523 | ||
5524 | Large model objects may live anywhere in the 32-bit address space (the | |
5525 | compiler generates @code{seth/add3} instructions to load their addresses), | |
5526 | and may not be reachable with the @code{bl} instruction (the compiler | |
5527 | generates the much slower @code{seth/add3/jl} instruction sequence). | |
5528 | @end table | |
5529 | ||
5530 | @node m68k Function Attributes | |
5531 | @subsection m68k Function Attributes | |
5532 | ||
5533 | These function attributes are supported by the m68k back end: | |
5534 | ||
5535 | @table @code | |
d77de738 ML |
5536 | @cindex @code{interrupt} function attribute, m68k |
5537 | @cindex @code{interrupt_handler} function attribute, m68k | |
f33d7a88 AA |
5538 | @item interrupt |
5539 | @itemx interrupt_handler | |
d77de738 ML |
5540 | Use this attribute to |
5541 | indicate that the specified function is an interrupt handler. The compiler | |
5542 | generates function entry and exit sequences suitable for use in an | |
5543 | interrupt handler when this attribute is present. Either name may be used. | |
5544 | ||
d77de738 | 5545 | @cindex @code{interrupt_thread} function attribute, fido |
f33d7a88 | 5546 | @item interrupt_thread |
d77de738 ML |
5547 | Use this attribute on fido, a subarchitecture of the m68k, to indicate |
5548 | that the specified function is an interrupt handler that is designed | |
5549 | to run as a thread. The compiler omits generate prologue/epilogue | |
5550 | sequences and replaces the return instruction with a @code{sleep} | |
5551 | instruction. This attribute is available only on fido. | |
5552 | @end table | |
5553 | ||
5554 | @node MCORE Function Attributes | |
5555 | @subsection MCORE Function Attributes | |
5556 | ||
5557 | These function attributes are supported by the MCORE back end: | |
5558 | ||
5559 | @table @code | |
d77de738 | 5560 | @cindex @code{naked} function attribute, MCORE |
f33d7a88 | 5561 | @item naked |
d77de738 ML |
5562 | This attribute allows the compiler to construct the |
5563 | requisite function declaration, while allowing the body of the | |
5564 | function to be assembly code. The specified function will not have | |
5565 | prologue/epilogue sequences generated by the compiler. Only basic | |
5566 | @code{asm} statements can safely be included in naked functions | |
5567 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5568 | basic @code{asm} and C code may appear to work, they cannot be | |
5569 | depended upon to work reliably and are not supported. | |
5570 | @end table | |
5571 | ||
d77de738 ML |
5572 | @node MicroBlaze Function Attributes |
5573 | @subsection MicroBlaze Function Attributes | |
5574 | ||
5575 | These function attributes are supported on MicroBlaze targets: | |
5576 | ||
5577 | @table @code | |
d77de738 | 5578 | @cindex @code{save_volatiles} function attribute, MicroBlaze |
f33d7a88 | 5579 | @item save_volatiles |
d77de738 ML |
5580 | Use this attribute to indicate that the function is |
5581 | an interrupt handler. All volatile registers (in addition to non-volatile | |
5582 | registers) are saved in the function prologue. If the function is a leaf | |
5583 | function, only volatiles used by the function are saved. A normal function | |
5584 | return is generated instead of a return from interrupt. | |
5585 | ||
d77de738 ML |
5586 | @cindex @code{break_handler} function attribute, MicroBlaze |
5587 | @cindex break handler functions | |
f33d7a88 | 5588 | @item break_handler |
d77de738 ML |
5589 | Use this attribute to indicate that |
5590 | the specified function is a break handler. The compiler generates function | |
5591 | entry and exit sequences suitable for use in an break handler when this | |
5592 | attribute is present. The return from @code{break_handler} is done through | |
5593 | the @code{rtbd} instead of @code{rtsd}. | |
5594 | ||
5595 | @smallexample | |
5596 | void f () __attribute__ ((break_handler)); | |
5597 | @end smallexample | |
5598 | ||
d77de738 ML |
5599 | @cindex @code{interrupt_handler} function attribute, MicroBlaze |
5600 | @cindex @code{fast_interrupt} function attribute, MicroBlaze | |
f33d7a88 AA |
5601 | @item interrupt_handler |
5602 | @itemx fast_interrupt | |
d77de738 ML |
5603 | These attributes indicate that the specified function is an interrupt |
5604 | handler. Use the @code{fast_interrupt} attribute to indicate handlers | |
5605 | used in low-latency interrupt mode, and @code{interrupt_handler} for | |
5606 | interrupts that do not use low-latency handlers. In both cases, GCC | |
5607 | emits appropriate prologue code and generates a return from the handler | |
5608 | using @code{rtid} instead of @code{rtsd}. | |
5609 | @end table | |
5610 | ||
5611 | @node Microsoft Windows Function Attributes | |
5612 | @subsection Microsoft Windows Function Attributes | |
5613 | ||
5614 | The following attributes are available on Microsoft Windows and Symbian OS | |
5615 | targets. | |
5616 | ||
5617 | @table @code | |
d77de738 ML |
5618 | @cindex @code{dllexport} function attribute |
5619 | @cindex @code{__declspec(dllexport)} | |
f33d7a88 | 5620 | @item dllexport |
d77de738 ML |
5621 | On Microsoft Windows targets and Symbian OS targets the |
5622 | @code{dllexport} attribute causes the compiler to provide a global | |
5623 | pointer to a pointer in a DLL, so that it can be referenced with the | |
5624 | @code{dllimport} attribute. On Microsoft Windows targets, the pointer | |
5625 | name is formed by combining @code{_imp__} and the function or variable | |
5626 | name. | |
5627 | ||
5628 | You can use @code{__declspec(dllexport)} as a synonym for | |
5629 | @code{__attribute__ ((dllexport))} for compatibility with other | |
5630 | compilers. | |
5631 | ||
5632 | On systems that support the @code{visibility} attribute, this | |
5633 | attribute also implies ``default'' visibility. It is an error to | |
5634 | explicitly specify any other visibility. | |
5635 | ||
5636 | GCC's default behavior is to emit all inline functions with the | |
5637 | @code{dllexport} attribute. Since this can cause object file-size bloat, | |
5638 | you can use @option{-fno-keep-inline-dllexport}, which tells GCC to | |
5639 | ignore the attribute for inlined functions unless the | |
5640 | @option{-fkeep-inline-functions} flag is used instead. | |
5641 | ||
5642 | The attribute is ignored for undefined symbols. | |
5643 | ||
5644 | When applied to C++ classes, the attribute marks defined non-inlined | |
5645 | member functions and static data members as exports. Static consts | |
5646 | initialized in-class are not marked unless they are also defined | |
5647 | out-of-class. | |
5648 | ||
5649 | For Microsoft Windows targets there are alternative methods for | |
5650 | including the symbol in the DLL's export table such as using a | |
5651 | @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using | |
5652 | the @option{--export-all} linker flag. | |
5653 | ||
d77de738 ML |
5654 | @cindex @code{dllimport} function attribute |
5655 | @cindex @code{__declspec(dllimport)} | |
f33d7a88 | 5656 | @item dllimport |
d77de738 ML |
5657 | On Microsoft Windows and Symbian OS targets, the @code{dllimport} |
5658 | attribute causes the compiler to reference a function or variable via | |
5659 | a global pointer to a pointer that is set up by the DLL exporting the | |
5660 | symbol. The attribute implies @code{extern}. On Microsoft Windows | |
5661 | targets, the pointer name is formed by combining @code{_imp__} and the | |
5662 | function or variable name. | |
5663 | ||
5664 | You can use @code{__declspec(dllimport)} as a synonym for | |
5665 | @code{__attribute__ ((dllimport))} for compatibility with other | |
5666 | compilers. | |
5667 | ||
5668 | On systems that support the @code{visibility} attribute, this | |
5669 | attribute also implies ``default'' visibility. It is an error to | |
5670 | explicitly specify any other visibility. | |
5671 | ||
5672 | Currently, the attribute is ignored for inlined functions. If the | |
5673 | attribute is applied to a symbol @emph{definition}, an error is reported. | |
5674 | If a symbol previously declared @code{dllimport} is later defined, the | |
5675 | attribute is ignored in subsequent references, and a warning is emitted. | |
5676 | The attribute is also overridden by a subsequent declaration as | |
5677 | @code{dllexport}. | |
5678 | ||
5679 | When applied to C++ classes, the attribute marks non-inlined | |
5680 | member functions and static data members as imports. However, the | |
5681 | attribute is ignored for virtual methods to allow creation of vtables | |
5682 | using thunks. | |
5683 | ||
5684 | On the SH Symbian OS target the @code{dllimport} attribute also has | |
5685 | another affect---it can cause the vtable and run-time type information | |
5686 | for a class to be exported. This happens when the class has a | |
5687 | dllimported constructor or a non-inline, non-pure virtual function | |
5688 | and, for either of those two conditions, the class also has an inline | |
5689 | constructor or destructor and has a key function that is defined in | |
5690 | the current translation unit. | |
5691 | ||
5692 | For Microsoft Windows targets the use of the @code{dllimport} | |
5693 | attribute on functions is not necessary, but provides a small | |
5694 | performance benefit by eliminating a thunk in the DLL@. The use of the | |
5695 | @code{dllimport} attribute on imported variables can be avoided by passing the | |
5696 | @option{--enable-auto-import} switch to the GNU linker. As with | |
5697 | functions, using the attribute for a variable eliminates a thunk in | |
5698 | the DLL@. | |
5699 | ||
5700 | One drawback to using this attribute is that a pointer to a | |
5701 | @emph{variable} marked as @code{dllimport} cannot be used as a constant | |
5702 | address. However, a pointer to a @emph{function} with the | |
5703 | @code{dllimport} attribute can be used as a constant initializer; in | |
5704 | this case, the address of a stub function in the import lib is | |
5705 | referenced. On Microsoft Windows targets, the attribute can be disabled | |
5706 | for functions by setting the @option{-mnop-fun-dllimport} flag. | |
5707 | @end table | |
5708 | ||
5709 | @node MIPS Function Attributes | |
5710 | @subsection MIPS Function Attributes | |
5711 | ||
5712 | These function attributes are supported by the MIPS back end: | |
5713 | ||
5714 | @table @code | |
d77de738 | 5715 | @cindex @code{interrupt} function attribute, MIPS |
f33d7a88 | 5716 | @item interrupt |
d77de738 ML |
5717 | Use this attribute to indicate that the specified function is an interrupt |
5718 | handler. The compiler generates function entry and exit sequences suitable | |
5719 | for use in an interrupt handler when this attribute is present. | |
5720 | An optional argument is supported for the interrupt attribute which allows | |
5721 | the interrupt mode to be described. By default GCC assumes the external | |
5722 | interrupt controller (EIC) mode is in use, this can be explicitly set using | |
5723 | @code{eic}. When interrupts are non-masked then the requested Interrupt | |
5724 | Priority Level (IPL) is copied to the current IPL which has the effect of only | |
5725 | enabling higher priority interrupts. To use vectored interrupt mode use | |
5726 | the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change | |
5727 | the behavior of the non-masked interrupt support and GCC will arrange to mask | |
5728 | all interrupts from sw0 up to and including the specified interrupt vector. | |
5729 | ||
5730 | You can use the following attributes to modify the behavior | |
5731 | of an interrupt handler: | |
5732 | @table @code | |
d77de738 | 5733 | @cindex @code{use_shadow_register_set} function attribute, MIPS |
f33d7a88 | 5734 | @item use_shadow_register_set |
d77de738 ML |
5735 | Assume that the handler uses a shadow register set, instead of |
5736 | the main general-purpose registers. An optional argument @code{intstack} is | |
5737 | supported to indicate that the shadow register set contains a valid stack | |
5738 | pointer. | |
5739 | ||
d77de738 | 5740 | @cindex @code{keep_interrupts_masked} function attribute, MIPS |
f33d7a88 | 5741 | @item keep_interrupts_masked |
d77de738 ML |
5742 | Keep interrupts masked for the whole function. Without this attribute, |
5743 | GCC tries to reenable interrupts for as much of the function as it can. | |
5744 | ||
d77de738 | 5745 | @cindex @code{use_debug_exception_return} function attribute, MIPS |
f33d7a88 | 5746 | @item use_debug_exception_return |
d77de738 ML |
5747 | Return using the @code{deret} instruction. Interrupt handlers that don't |
5748 | have this attribute return using @code{eret} instead. | |
5749 | @end table | |
5750 | ||
5751 | You can use any combination of these attributes, as shown below: | |
5752 | @smallexample | |
5753 | void __attribute__ ((interrupt)) v0 (); | |
5754 | void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); | |
5755 | void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); | |
5756 | void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); | |
5757 | void __attribute__ ((interrupt, use_shadow_register_set, | |
5758 | keep_interrupts_masked)) v4 (); | |
5759 | void __attribute__ ((interrupt, use_shadow_register_set, | |
5760 | use_debug_exception_return)) v5 (); | |
5761 | void __attribute__ ((interrupt, keep_interrupts_masked, | |
5762 | use_debug_exception_return)) v6 (); | |
5763 | void __attribute__ ((interrupt, use_shadow_register_set, | |
5764 | keep_interrupts_masked, | |
5765 | use_debug_exception_return)) v7 (); | |
5766 | void __attribute__ ((interrupt("eic"))) v8 (); | |
5767 | void __attribute__ ((interrupt("vector=hw3"))) v9 (); | |
5768 | @end smallexample | |
5769 | ||
d77de738 ML |
5770 | @cindex indirect calls, MIPS |
5771 | @cindex @code{long_call} function attribute, MIPS | |
5772 | @cindex @code{short_call} function attribute, MIPS | |
5773 | @cindex @code{near} function attribute, MIPS | |
5774 | @cindex @code{far} function attribute, MIPS | |
f33d7a88 AA |
5775 | @item long_call |
5776 | @itemx short_call | |
5777 | @itemx near | |
5778 | @itemx far | |
d77de738 ML |
5779 | These attributes specify how a particular function is called on MIPS@. |
5780 | The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) | |
5781 | command-line switch. The @code{long_call} and @code{far} attributes are | |
5782 | synonyms, and cause the compiler to always call | |
5783 | the function by first loading its address into a register, and then using | |
5784 | the contents of that register. The @code{short_call} and @code{near} | |
5785 | attributes are synonyms, and have the opposite | |
5786 | effect; they specify that non-PIC calls should be made using the more | |
5787 | efficient @code{jal} instruction. | |
5788 | ||
d77de738 ML |
5789 | @cindex @code{mips16} function attribute, MIPS |
5790 | @cindex @code{nomips16} function attribute, MIPS | |
f33d7a88 AA |
5791 | @item mips16 |
5792 | @itemx nomips16 | |
d77de738 ML |
5793 | |
5794 | On MIPS targets, you can use the @code{mips16} and @code{nomips16} | |
5795 | function attributes to locally select or turn off MIPS16 code generation. | |
5796 | A function with the @code{mips16} attribute is emitted as MIPS16 code, | |
5797 | while MIPS16 code generation is disabled for functions with the | |
5798 | @code{nomips16} attribute. These attributes override the | |
5799 | @option{-mips16} and @option{-mno-mips16} options on the command line | |
5800 | (@pxref{MIPS Options}). | |
5801 | ||
5802 | When compiling files containing mixed MIPS16 and non-MIPS16 code, the | |
5803 | preprocessor symbol @code{__mips16} reflects the setting on the command line, | |
5804 | not that within individual functions. Mixed MIPS16 and non-MIPS16 code | |
5805 | may interact badly with some GCC extensions such as @code{__builtin_apply} | |
5806 | (@pxref{Constructing Calls}). | |
5807 | ||
d77de738 ML |
5808 | @cindex @code{micromips} function attribute |
5809 | @cindex @code{nomicromips} function attribute | |
f33d7a88 AA |
5810 | @item micromips, MIPS |
5811 | @itemx nomicromips, MIPS | |
d77de738 ML |
5812 | |
5813 | On MIPS targets, you can use the @code{micromips} and @code{nomicromips} | |
5814 | function attributes to locally select or turn off microMIPS code generation. | |
5815 | A function with the @code{micromips} attribute is emitted as microMIPS code, | |
5816 | while microMIPS code generation is disabled for functions with the | |
5817 | @code{nomicromips} attribute. These attributes override the | |
5818 | @option{-mmicromips} and @option{-mno-micromips} options on the command line | |
5819 | (@pxref{MIPS Options}). | |
5820 | ||
5821 | When compiling files containing mixed microMIPS and non-microMIPS code, the | |
5822 | preprocessor symbol @code{__mips_micromips} reflects the setting on the | |
5823 | command line, | |
5824 | not that within individual functions. Mixed microMIPS and non-microMIPS code | |
5825 | may interact badly with some GCC extensions such as @code{__builtin_apply} | |
5826 | (@pxref{Constructing Calls}). | |
5827 | ||
d77de738 | 5828 | @cindex @code{nocompression} function attribute, MIPS |
f33d7a88 | 5829 | @item nocompression |
d77de738 ML |
5830 | On MIPS targets, you can use the @code{nocompression} function attribute |
5831 | to locally turn off MIPS16 and microMIPS code generation. This attribute | |
5832 | overrides the @option{-mips16} and @option{-mmicromips} options on the | |
5833 | command line (@pxref{MIPS Options}). | |
a3a45f0b | 5834 | |
a3a45f0b | 5835 | @cindex @code{use_hazard_barrier_return} function attribute, MIPS |
e54b01a1 | 5836 | @item use_hazard_barrier_return |
a3a45f0b JZ |
5837 | This function attribute instructs the compiler to generate a hazard barrier |
5838 | return that clears all execution and instruction hazards while returning, | |
5839 | instead of generating a normal return instruction. | |
65864221 SD |
5840 | |
5841 | @item code_readable | |
5842 | @cindex @code{code_readable} function attribute, MIPS | |
5843 | For MIPS targets that support PC-relative addressing modes, this attribute | |
5844 | can be used to control how an object is addressed. The attribute takes | |
5845 | a single optional argument: | |
5846 | ||
5847 | @table @samp | |
5848 | @item no | |
5849 | The function should not read the instruction stream as data. | |
5850 | @item yes | |
5851 | The function can read the instruction stream as data. | |
5852 | @item pcrel | |
5853 | The function can read the instruction stream in a pc-relative mode. | |
5854 | @end table | |
5855 | ||
5856 | If there is no argument supplied, the default of @code{"yes"} applies. | |
d77de738 ML |
5857 | @end table |
5858 | ||
5859 | @node MSP430 Function Attributes | |
5860 | @subsection MSP430 Function Attributes | |
5861 | ||
5862 | These function attributes are supported by the MSP430 back end: | |
5863 | ||
5864 | @table @code | |
d77de738 | 5865 | @cindex @code{critical} function attribute, MSP430 |
f33d7a88 | 5866 | @item critical |
d77de738 ML |
5867 | Critical functions disable interrupts upon entry and restore the |
5868 | previous interrupt state upon exit. Critical functions cannot also | |
5869 | have the @code{naked}, @code{reentrant} or @code{interrupt} attributes. | |
5870 | ||
5871 | The MSP430 hardware ensures that interrupts are disabled on entry to | |
5872 | @code{interrupt} functions, and restores the previous interrupt state | |
5873 | on exit. The @code{critical} attribute is therefore redundant on | |
5874 | @code{interrupt} functions. | |
5875 | ||
d77de738 | 5876 | @cindex @code{interrupt} function attribute, MSP430 |
f33d7a88 | 5877 | @item interrupt |
d77de738 ML |
5878 | Use this attribute to indicate |
5879 | that the specified function is an interrupt handler. The compiler generates | |
5880 | function entry and exit sequences suitable for use in an interrupt handler | |
5881 | when this attribute is present. | |
5882 | ||
5883 | You can provide an argument to the interrupt | |
5884 | attribute which specifies a name or number. If the argument is a | |
5885 | number it indicates the slot in the interrupt vector table (0 - 31) to | |
5886 | which this handler should be assigned. If the argument is a name it | |
5887 | is treated as a symbolic name for the vector slot. These names should | |
5888 | match up with appropriate entries in the linker script. By default | |
5889 | the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and | |
5890 | @code{reset} for vector 31 are recognized. | |
5891 | ||
d77de738 | 5892 | @cindex @code{naked} function attribute, MSP430 |
f33d7a88 | 5893 | @item naked |
d77de738 ML |
5894 | This attribute allows the compiler to construct the |
5895 | requisite function declaration, while allowing the body of the | |
5896 | function to be assembly code. The specified function will not have | |
5897 | prologue/epilogue sequences generated by the compiler. Only basic | |
5898 | @code{asm} statements can safely be included in naked functions | |
5899 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5900 | basic @code{asm} and C code may appear to work, they cannot be | |
5901 | depended upon to work reliably and are not supported. | |
5902 | ||
d77de738 | 5903 | @cindex @code{reentrant} function attribute, MSP430 |
f33d7a88 | 5904 | @item reentrant |
d77de738 ML |
5905 | Reentrant functions disable interrupts upon entry and enable them |
5906 | upon exit. Reentrant functions cannot also have the @code{naked} | |
5907 | or @code{critical} attributes. They can have the @code{interrupt} | |
5908 | attribute. | |
5909 | ||
d77de738 | 5910 | @cindex @code{wakeup} function attribute, MSP430 |
f33d7a88 | 5911 | @item wakeup |
d77de738 ML |
5912 | This attribute only applies to interrupt functions. It is silently |
5913 | ignored if applied to a non-interrupt function. A wakeup interrupt | |
5914 | function will rouse the processor from any low-power state that it | |
5915 | might be in when the function exits. | |
5916 | ||
d77de738 ML |
5917 | @cindex @code{lower} function attribute, MSP430 |
5918 | @cindex @code{upper} function attribute, MSP430 | |
5919 | @cindex @code{either} function attribute, MSP430 | |
f33d7a88 AA |
5920 | @item lower |
5921 | @itemx upper | |
5922 | @itemx either | |
d77de738 ML |
5923 | On the MSP430 target these attributes can be used to specify whether |
5924 | the function or variable should be placed into low memory, high | |
5925 | memory, or the placement should be left to the linker to decide. The | |
5926 | attributes are only significant if compiling for the MSP430X | |
5927 | architecture in the large memory model. | |
5928 | ||
5929 | The attributes work in conjunction with a linker script that has been | |
5930 | augmented to specify where to place sections with a @code{.lower} and | |
5931 | a @code{.upper} prefix. So, for example, as well as placing the | |
5932 | @code{.data} section, the script also specifies the placement of a | |
5933 | @code{.lower.data} and a @code{.upper.data} section. The intention | |
5934 | is that @code{lower} sections are placed into a small but easier to | |
5935 | access memory region and the upper sections are placed into a larger, but | |
5936 | slower to access, region. | |
5937 | ||
5938 | The @code{either} attribute is special. It tells the linker to place | |
5939 | the object into the corresponding @code{lower} section if there is | |
5940 | room for it. If there is insufficient room then the object is placed | |
5941 | into the corresponding @code{upper} section instead. Note that the | |
5942 | placement algorithm is not very sophisticated. It does not attempt to | |
5943 | find an optimal packing of the @code{lower} sections. It just makes | |
5944 | one pass over the objects and does the best that it can. Using the | |
5945 | @option{-ffunction-sections} and @option{-fdata-sections} command-line | |
5946 | options can help the packing, however, since they produce smaller, | |
5947 | easier to pack regions. | |
5948 | @end table | |
5949 | ||
5950 | @node NDS32 Function Attributes | |
5951 | @subsection NDS32 Function Attributes | |
5952 | ||
5953 | These function attributes are supported by the NDS32 back end: | |
5954 | ||
5955 | @table @code | |
d77de738 ML |
5956 | @cindex @code{exception} function attribute |
5957 | @cindex exception handler functions, NDS32 | |
f33d7a88 | 5958 | @item exception |
d77de738 ML |
5959 | Use this attribute on the NDS32 target to indicate that the specified function |
5960 | is an exception handler. The compiler will generate corresponding sections | |
5961 | for use in an exception handler. | |
5962 | ||
d77de738 | 5963 | @cindex @code{interrupt} function attribute, NDS32 |
f33d7a88 | 5964 | @item interrupt |
d77de738 ML |
5965 | On NDS32 target, this attribute indicates that the specified function |
5966 | is an interrupt handler. The compiler generates corresponding sections | |
5967 | for use in an interrupt handler. You can use the following attributes | |
5968 | to modify the behavior: | |
5969 | @table @code | |
d77de738 | 5970 | @cindex @code{nested} function attribute, NDS32 |
f33d7a88 | 5971 | @item nested |
d77de738 | 5972 | This interrupt service routine is interruptible. |
d77de738 | 5973 | @cindex @code{not_nested} function attribute, NDS32 |
f33d7a88 | 5974 | @item not_nested |
d77de738 | 5975 | This interrupt service routine is not interruptible. |
d77de738 | 5976 | @cindex @code{nested_ready} function attribute, NDS32 |
f33d7a88 | 5977 | @item nested_ready |
d77de738 ML |
5978 | This interrupt service routine is interruptible after @code{PSW.GIE} |
5979 | (global interrupt enable) is set. This allows interrupt service routine to | |
5980 | finish some short critical code before enabling interrupts. | |
d77de738 | 5981 | @cindex @code{save_all} function attribute, NDS32 |
f33d7a88 | 5982 | @item save_all |
d77de738 ML |
5983 | The system will help save all registers into stack before entering |
5984 | interrupt handler. | |
d77de738 | 5985 | @cindex @code{partial_save} function attribute, NDS32 |
f33d7a88 | 5986 | @item partial_save |
d77de738 ML |
5987 | The system will help save caller registers into stack before entering |
5988 | interrupt handler. | |
5989 | @end table | |
5990 | ||
d77de738 | 5991 | @cindex @code{naked} function attribute, NDS32 |
f33d7a88 | 5992 | @item naked |
d77de738 ML |
5993 | This attribute allows the compiler to construct the |
5994 | requisite function declaration, while allowing the body of the | |
5995 | function to be assembly code. The specified function will not have | |
5996 | prologue/epilogue sequences generated by the compiler. Only basic | |
5997 | @code{asm} statements can safely be included in naked functions | |
5998 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
5999 | basic @code{asm} and C code may appear to work, they cannot be | |
6000 | depended upon to work reliably and are not supported. | |
6001 | ||
d77de738 ML |
6002 | @cindex @code{reset} function attribute, NDS32 |
6003 | @cindex reset handler functions | |
f33d7a88 | 6004 | @item reset |
d77de738 ML |
6005 | Use this attribute on the NDS32 target to indicate that the specified function |
6006 | is a reset handler. The compiler will generate corresponding sections | |
6007 | for use in a reset handler. You can use the following attributes | |
6008 | to provide extra exception handling: | |
6009 | @table @code | |
d77de738 | 6010 | @cindex @code{nmi} function attribute, NDS32 |
f33d7a88 | 6011 | @item nmi |
d77de738 | 6012 | Provide a user-defined function to handle NMI exception. |
d77de738 | 6013 | @cindex @code{warm} function attribute, NDS32 |
f33d7a88 | 6014 | @item warm |
d77de738 ML |
6015 | Provide a user-defined function to handle warm reset exception. |
6016 | @end table | |
6017 | @end table | |
6018 | ||
6019 | @node Nios II Function Attributes | |
6020 | @subsection Nios II Function Attributes | |
6021 | ||
6022 | These function attributes are supported by the Nios II back end: | |
6023 | ||
6024 | @table @code | |
d77de738 | 6025 | @cindex @code{target} function attribute |
f33d7a88 | 6026 | @item target (@var{options}) |
d77de738 ML |
6027 | As discussed in @ref{Common Function Attributes}, this attribute |
6028 | allows specification of target-specific compilation options. | |
6029 | ||
6030 | When compiling for Nios II, the following options are allowed: | |
6031 | ||
6032 | @table @samp | |
d77de738 ML |
6033 | @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II |
6034 | @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II | |
f33d7a88 AA |
6035 | @item custom-@var{insn}=@var{N} |
6036 | @itemx no-custom-@var{insn} | |
d77de738 ML |
6037 | Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a |
6038 | custom instruction with encoding @var{N} when generating code that uses | |
6039 | @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of | |
6040 | the custom instruction @var{insn}. | |
6041 | These target attributes correspond to the | |
6042 | @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}} | |
6043 | command-line options, and support the same set of @var{insn} keywords. | |
6044 | @xref{Nios II Options}, for more information. | |
6045 | ||
d77de738 | 6046 | @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II |
f33d7a88 | 6047 | @item custom-fpu-cfg=@var{name} |
d77de738 ML |
6048 | This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}} |
6049 | command-line option, to select a predefined set of custom instructions | |
6050 | named @var{name}. | |
6051 | @xref{Nios II Options}, for more information. | |
6052 | @end table | |
6053 | @end table | |
6054 | ||
6055 | @node Nvidia PTX Function Attributes | |
6056 | @subsection Nvidia PTX Function Attributes | |
6057 | ||
6058 | These function attributes are supported by the Nvidia PTX back end: | |
6059 | ||
6060 | @table @code | |
d77de738 | 6061 | @cindex @code{kernel} attribute, Nvidia PTX |
f33d7a88 | 6062 | @item kernel |
d77de738 ML |
6063 | This attribute indicates that the corresponding function should be compiled |
6064 | as a kernel function, which can be invoked from the host via the CUDA RT | |
6065 | library. | |
6066 | By default functions are only callable only from other PTX functions. | |
6067 | ||
6068 | Kernel functions must have @code{void} return type. | |
6069 | @end table | |
6070 | ||
6071 | @node PowerPC Function Attributes | |
6072 | @subsection PowerPC Function Attributes | |
6073 | ||
6074 | These function attributes are supported by the PowerPC back end: | |
6075 | ||
6076 | @table @code | |
d77de738 ML |
6077 | @cindex indirect calls, PowerPC |
6078 | @cindex @code{longcall} function attribute, PowerPC | |
6079 | @cindex @code{shortcall} function attribute, PowerPC | |
f33d7a88 AA |
6080 | @item longcall |
6081 | @itemx shortcall | |
d77de738 ML |
6082 | The @code{longcall} attribute |
6083 | indicates that the function might be far away from the call site and | |
6084 | require a different (more expensive) calling sequence. The | |
6085 | @code{shortcall} attribute indicates that the function is always close | |
6086 | enough for the shorter calling sequence to be used. These attributes | |
6087 | override both the @option{-mlongcall} switch and | |
6088 | the @code{#pragma longcall} setting. | |
6089 | ||
6090 | @xref{RS/6000 and PowerPC Options}, for more information on whether long | |
6091 | calls are necessary. | |
6092 | ||
d77de738 | 6093 | @cindex @code{target} function attribute |
f33d7a88 | 6094 | @item target (@var{options}) |
d77de738 ML |
6095 | As discussed in @ref{Common Function Attributes}, this attribute |
6096 | allows specification of target-specific compilation options. | |
6097 | ||
6098 | On the PowerPC, the following options are allowed: | |
6099 | ||
6100 | @table @samp | |
f33d7a88 | 6101 | @cindex @code{target("altivec")} function attribute, PowerPC |
d77de738 ML |
6102 | @item altivec |
6103 | @itemx no-altivec | |
d77de738 ML |
6104 | Generate code that uses (does not use) AltiVec instructions. In |
6105 | 32-bit code, you cannot enable AltiVec instructions unless | |
6106 | @option{-mabi=altivec} is used on the command line. | |
6107 | ||
f33d7a88 | 6108 | @cindex @code{target("cmpb")} function attribute, PowerPC |
d77de738 ML |
6109 | @item cmpb |
6110 | @itemx no-cmpb | |
d77de738 ML |
6111 | Generate code that uses (does not use) the compare bytes instruction |
6112 | implemented on the POWER6 processor and other processors that support | |
6113 | the PowerPC V2.05 architecture. | |
6114 | ||
f33d7a88 | 6115 | @cindex @code{target("dlmzb")} function attribute, PowerPC |
d77de738 ML |
6116 | @item dlmzb |
6117 | @itemx no-dlmzb | |
d77de738 ML |
6118 | Generate code that uses (does not use) the string-search @samp{dlmzb} |
6119 | instruction on the IBM 405, 440, 464 and 476 processors. This instruction is | |
6120 | generated by default when targeting those processors. | |
6121 | ||
f33d7a88 | 6122 | @cindex @code{target("fprnd")} function attribute, PowerPC |
d77de738 ML |
6123 | @item fprnd |
6124 | @itemx no-fprnd | |
d77de738 ML |
6125 | Generate code that uses (does not use) the FP round to integer |
6126 | instructions implemented on the POWER5+ processor and other processors | |
6127 | that support the PowerPC V2.03 architecture. | |
6128 | ||
f33d7a88 | 6129 | @cindex @code{target("hard-dfp")} function attribute, PowerPC |
d77de738 ML |
6130 | @item hard-dfp |
6131 | @itemx no-hard-dfp | |
d77de738 ML |
6132 | Generate code that uses (does not use) the decimal floating-point |
6133 | instructions implemented on some POWER processors. | |
6134 | ||
f33d7a88 | 6135 | @cindex @code{target("isel")} function attribute, PowerPC |
d77de738 ML |
6136 | @item isel |
6137 | @itemx no-isel | |
d77de738 ML |
6138 | Generate code that uses (does not use) ISEL instruction. |
6139 | ||
f33d7a88 | 6140 | @cindex @code{target("mfcrf")} function attribute, PowerPC |
d77de738 ML |
6141 | @item mfcrf |
6142 | @itemx no-mfcrf | |
d77de738 ML |
6143 | Generate code that uses (does not use) the move from condition |
6144 | register field instruction implemented on the POWER4 processor and | |
6145 | other processors that support the PowerPC V2.01 architecture. | |
6146 | ||
f33d7a88 | 6147 | @cindex @code{target("mulhw")} function attribute, PowerPC |
d77de738 ML |
6148 | @item mulhw |
6149 | @itemx no-mulhw | |
d77de738 ML |
6150 | Generate code that uses (does not use) the half-word multiply and |
6151 | multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. | |
6152 | These instructions are generated by default when targeting those | |
6153 | processors. | |
6154 | ||
f33d7a88 | 6155 | @cindex @code{target("multiple")} function attribute, PowerPC |
d77de738 ML |
6156 | @item multiple |
6157 | @itemx no-multiple | |
d77de738 ML |
6158 | Generate code that uses (does not use) the load multiple word |
6159 | instructions and the store multiple word instructions. | |
6160 | ||
f33d7a88 | 6161 | @cindex @code{target("update")} function attribute, PowerPC |
d77de738 ML |
6162 | @item update |
6163 | @itemx no-update | |
d77de738 ML |
6164 | Generate code that uses (does not use) the load or store instructions |
6165 | that update the base register to the address of the calculated memory | |
6166 | location. | |
6167 | ||
f33d7a88 | 6168 | @cindex @code{target("popcntb")} function attribute, PowerPC |
d77de738 ML |
6169 | @item popcntb |
6170 | @itemx no-popcntb | |
d77de738 ML |
6171 | Generate code that uses (does not use) the popcount and double-precision |
6172 | FP reciprocal estimate instruction implemented on the POWER5 | |
6173 | processor and other processors that support the PowerPC V2.02 | |
6174 | architecture. | |
6175 | ||
f33d7a88 | 6176 | @cindex @code{target("popcntd")} function attribute, PowerPC |
d77de738 ML |
6177 | @item popcntd |
6178 | @itemx no-popcntd | |
d77de738 ML |
6179 | Generate code that uses (does not use) the popcount instruction |
6180 | implemented on the POWER7 processor and other processors that support | |
6181 | the PowerPC V2.06 architecture. | |
6182 | ||
f33d7a88 | 6183 | @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC |
d77de738 ML |
6184 | @item powerpc-gfxopt |
6185 | @itemx no-powerpc-gfxopt | |
d77de738 ML |
6186 | Generate code that uses (does not use) the optional PowerPC |
6187 | architecture instructions in the Graphics group, including | |
6188 | floating-point select. | |
6189 | ||
f33d7a88 | 6190 | @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC |
d77de738 ML |
6191 | @item powerpc-gpopt |
6192 | @itemx no-powerpc-gpopt | |
d77de738 ML |
6193 | Generate code that uses (does not use) the optional PowerPC |
6194 | architecture instructions in the General Purpose group, including | |
6195 | floating-point square root. | |
6196 | ||
f33d7a88 | 6197 | @cindex @code{target("recip-precision")} function attribute, PowerPC |
d77de738 ML |
6198 | @item recip-precision |
6199 | @itemx no-recip-precision | |
d77de738 ML |
6200 | Assume (do not assume) that the reciprocal estimate instructions |
6201 | provide higher-precision estimates than is mandated by the PowerPC | |
6202 | ABI. | |
6203 | ||
f33d7a88 | 6204 | @cindex @code{target("string")} function attribute, PowerPC |
d77de738 ML |
6205 | @item string |
6206 | @itemx no-string | |
d77de738 ML |
6207 | Generate code that uses (does not use) the load string instructions |
6208 | and the store string word instructions to save multiple registers and | |
6209 | do small block moves. | |
6210 | ||
f33d7a88 | 6211 | @cindex @code{target("vsx")} function attribute, PowerPC |
d77de738 ML |
6212 | @item vsx |
6213 | @itemx no-vsx | |
d77de738 ML |
6214 | Generate code that uses (does not use) vector/scalar (VSX) |
6215 | instructions, and also enable the use of built-in functions that allow | |
6216 | more direct access to the VSX instruction set. In 32-bit code, you | |
6217 | cannot enable VSX or AltiVec instructions unless | |
6218 | @option{-mabi=altivec} is used on the command line. | |
6219 | ||
f33d7a88 | 6220 | @cindex @code{target("friz")} function attribute, PowerPC |
d77de738 ML |
6221 | @item friz |
6222 | @itemx no-friz | |
d77de738 ML |
6223 | Generate (do not generate) the @code{friz} instruction when the |
6224 | @option{-funsafe-math-optimizations} option is used to optimize | |
6225 | rounding a floating-point value to 64-bit integer and back to floating | |
6226 | point. The @code{friz} instruction does not return the same value if | |
6227 | the floating-point number is too large to fit in an integer. | |
6228 | ||
f33d7a88 | 6229 | @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC |
d77de738 ML |
6230 | @item avoid-indexed-addresses |
6231 | @itemx no-avoid-indexed-addresses | |
d77de738 ML |
6232 | Generate code that tries to avoid (not avoid) the use of indexed load |
6233 | or store instructions. | |
6234 | ||
f33d7a88 | 6235 | @cindex @code{target("paired")} function attribute, PowerPC |
d77de738 ML |
6236 | @item paired |
6237 | @itemx no-paired | |
d77de738 ML |
6238 | Generate code that uses (does not use) the generation of PAIRED simd |
6239 | instructions. | |
6240 | ||
f33d7a88 | 6241 | @cindex @code{target("longcall")} function attribute, PowerPC |
d77de738 ML |
6242 | @item longcall |
6243 | @itemx no-longcall | |
d77de738 ML |
6244 | Generate code that assumes (does not assume) that all calls are far |
6245 | away so that a longer more expensive calling sequence is required. | |
6246 | ||
d77de738 | 6247 | @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC |
f33d7a88 | 6248 | @item cpu=@var{CPU} |
d77de738 ML |
6249 | Specify the architecture to generate code for when compiling the |
6250 | function. If you select the @code{target("cpu=power7")} attribute when | |
6251 | generating 32-bit code, VSX and AltiVec instructions are not generated | |
6252 | unless you use the @option{-mabi=altivec} option on the command line. | |
6253 | ||
d77de738 | 6254 | @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC |
f33d7a88 | 6255 | @item tune=@var{TUNE} |
d77de738 ML |
6256 | Specify the architecture to tune for when compiling the function. If |
6257 | you do not specify the @code{target("tune=@var{TUNE}")} attribute and | |
6258 | you do specify the @code{target("cpu=@var{CPU}")} attribute, | |
6259 | compilation tunes for the @var{CPU} architecture, and not the | |
6260 | default tuning specified on the command line. | |
6261 | @end table | |
6262 | ||
6263 | On the PowerPC, the inliner does not inline a | |
6264 | function that has different target options than the caller, unless the | |
6265 | callee has a subset of the target options of the caller. | |
6266 | @end table | |
6267 | ||
6268 | @node RISC-V Function Attributes | |
6269 | @subsection RISC-V Function Attributes | |
6270 | ||
6271 | These function attributes are supported by the RISC-V back end: | |
6272 | ||
6273 | @table @code | |
d77de738 | 6274 | @cindex @code{naked} function attribute, RISC-V |
f33d7a88 | 6275 | @item naked |
d77de738 ML |
6276 | This attribute allows the compiler to construct the |
6277 | requisite function declaration, while allowing the body of the | |
6278 | function to be assembly code. The specified function will not have | |
6279 | prologue/epilogue sequences generated by the compiler. Only basic | |
6280 | @code{asm} statements can safely be included in naked functions | |
6281 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
6282 | basic @code{asm} and C code may appear to work, they cannot be | |
6283 | depended upon to work reliably and are not supported. | |
6284 | ||
d77de738 | 6285 | @cindex @code{interrupt} function attribute, RISC-V |
f33d7a88 | 6286 | @item interrupt |
d77de738 ML |
6287 | Use this attribute to indicate that the specified function is an interrupt |
6288 | handler. The compiler generates function entry and exit sequences suitable | |
6289 | for use in an interrupt handler when this attribute is present. | |
6290 | ||
6291 | You can specify the kind of interrupt to be handled by adding an optional | |
6292 | parameter to the interrupt attribute like this: | |
6293 | ||
6294 | @smallexample | |
6295 | void f (void) __attribute__ ((interrupt ("user"))); | |
6296 | @end smallexample | |
6297 | ||
6298 | Permissible values for this parameter are @code{user}, @code{supervisor}, | |
6299 | and @code{machine}. If there is no parameter, then it defaults to | |
6300 | @code{machine}. | |
5f110561 KC |
6301 | |
6302 | @end table | |
6303 | ||
6304 | The following target-specific function attributes are available for the | |
6305 | RISC-V target. For the most part, these options mirror the behavior of | |
6306 | similar command-line options (@pxref{RISC-V Options}), but on a | |
6307 | per-function basis. | |
6308 | ||
6309 | @table @code | |
6310 | @cindex @code{arch=} function attribute, RISC-V | |
6311 | @item arch= | |
6312 | Specifies the architecture version and architectural extensions to use | |
6313 | for this function. The behavior and permissible arguments are the same as | |
6314 | for the @option{-march=} command-line option, in addtion, it also support | |
6315 | extension enablement list, a list of extension name and prefixed with @code{+}, | |
6316 | like @code{arch=+zba} means enable @code{zba} extension. | |
6317 | Multiple extension can be enabled by separating them with a comma. For example: | |
6318 | @code{arch=+zba,+zbb}. | |
6319 | ||
6320 | @cindex @code{tune=} function attribute, RISC-V | |
6321 | @item tune= | |
6322 | Specifies the core for which to tune the performance of this function. | |
6323 | The behavior and permissible arguments are the same as for the @option{-mtune=} | |
6324 | command-line option. | |
6325 | ||
6326 | @cindex @code{cpu=} function attribute, RISC-V | |
6327 | @item cpu= | |
6328 | Specifies the core for which to tune the performance of this function and also | |
6329 | whose architectural features to use. The behavior and valid arguments are the | |
6330 | same as for the @option{-mcpu=} command-line option. | |
6331 | ||
d77de738 ML |
6332 | @end table |
6333 | ||
5f110561 KC |
6334 | The above target attributes can be specified as follows: |
6335 | ||
6336 | @smallexample | |
6337 | __attribute__((target("@var{attr-string}"))) | |
6338 | int | |
6339 | f (int a) | |
6340 | @{ | |
6341 | return a + 5; | |
6342 | @} | |
6343 | @end smallexample | |
6344 | ||
6345 | where @code{@var{attr-string}} is one of the attribute strings specified above. | |
6346 | ||
6347 | Multiple target function attributes can be specified by separating them with | |
6348 | a semicolon. For example: | |
6349 | @smallexample | |
6350 | __attribute__((target("arch=+zba,+zbb;tune=rocket"))) | |
6351 | int | |
6352 | foo (int a) | |
6353 | @{ | |
6354 | return a + 5; | |
6355 | @} | |
6356 | @end smallexample | |
6357 | ||
6358 | is valid and compiles function @code{foo} with @code{zba} | |
6359 | and @code{zbb} extensions and tunes it for @code{rocket}. | |
6360 | ||
d77de738 ML |
6361 | @node RL78 Function Attributes |
6362 | @subsection RL78 Function Attributes | |
6363 | ||
6364 | These function attributes are supported by the RL78 back end: | |
6365 | ||
6366 | @table @code | |
d77de738 ML |
6367 | @cindex @code{interrupt} function attribute, RL78 |
6368 | @cindex @code{brk_interrupt} function attribute, RL78 | |
f33d7a88 AA |
6369 | @item interrupt |
6370 | @itemx brk_interrupt | |
d77de738 ML |
6371 | These attributes 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 this attribute is present. | |
6375 | ||
6376 | Use @code{brk_interrupt} instead of @code{interrupt} for | |
6377 | handlers intended to be used with the @code{BRK} opcode (i.e.@: those | |
6378 | that must end with @code{RETB} instead of @code{RETI}). | |
6379 | ||
d77de738 | 6380 | @cindex @code{naked} function attribute, RL78 |
f33d7a88 | 6381 | @item naked |
d77de738 ML |
6382 | This attribute allows the compiler to construct the |
6383 | requisite function declaration, while allowing the body of the | |
6384 | function to be assembly code. The specified function will not have | |
6385 | prologue/epilogue sequences generated by the compiler. Only basic | |
6386 | @code{asm} statements can safely be included in naked functions | |
6387 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
6388 | basic @code{asm} and C code may appear to work, they cannot be | |
6389 | depended upon to work reliably and are not supported. | |
6390 | @end table | |
6391 | ||
6392 | @node RX Function Attributes | |
6393 | @subsection RX Function Attributes | |
6394 | ||
6395 | These function attributes are supported by the RX back end: | |
6396 | ||
6397 | @table @code | |
d77de738 | 6398 | @cindex @code{fast_interrupt} function attribute, RX |
f33d7a88 | 6399 | @item fast_interrupt |
d77de738 ML |
6400 | Use this attribute on the RX port to indicate that the specified |
6401 | function is a fast interrupt handler. This is just like the | |
6402 | @code{interrupt} attribute, except that @code{freit} is used to return | |
6403 | instead of @code{reit}. | |
6404 | ||
d77de738 | 6405 | @cindex @code{interrupt} function attribute, RX |
f33d7a88 | 6406 | @item interrupt |
d77de738 ML |
6407 | Use this attribute to indicate |
6408 | that the specified function is an interrupt handler. The compiler generates | |
6409 | function entry and exit sequences suitable for use in an interrupt handler | |
6410 | when this attribute is present. | |
6411 | ||
6412 | On RX and RL78 targets, you may specify one or more vector numbers as arguments | |
6413 | to the attribute, as well as naming an alternate table name. | |
6414 | Parameters are handled sequentially, so one handler can be assigned to | |
6415 | multiple entries in multiple tables. One may also pass the magic | |
6416 | string @code{"$default"} which causes the function to be used for any | |
6417 | unfilled slots in the current table. | |
6418 | ||
6419 | This example shows a simple assignment of a function to one vector in | |
6420 | the default table (note that preprocessor macros may be used for | |
6421 | chip-specific symbolic vector names): | |
6422 | @smallexample | |
6423 | void __attribute__ ((interrupt (5))) txd1_handler (); | |
6424 | @end smallexample | |
6425 | ||
6426 | This example assigns a function to two slots in the default table | |
6427 | (using preprocessor macros defined elsewhere) and makes it the default | |
6428 | for the @code{dct} table: | |
6429 | @smallexample | |
6430 | void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default"))) | |
6431 | txd1_handler (); | |
6432 | @end smallexample | |
6433 | ||
d77de738 | 6434 | @cindex @code{naked} function attribute, RX |
f33d7a88 | 6435 | @item naked |
d77de738 ML |
6436 | This attribute allows the compiler to construct the |
6437 | requisite function declaration, while allowing the body of the | |
6438 | function to be assembly code. The specified function will not have | |
6439 | prologue/epilogue sequences generated by the compiler. Only basic | |
6440 | @code{asm} statements can safely be included in naked functions | |
6441 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
6442 | basic @code{asm} and C code may appear to work, they cannot be | |
6443 | depended upon to work reliably and are not supported. | |
6444 | ||
d77de738 | 6445 | @cindex @code{vector} function attribute, RX |
f33d7a88 | 6446 | @item vector |
d77de738 ML |
6447 | This RX attribute is similar to the @code{interrupt} attribute, including its |
6448 | parameters, but does not make the function an interrupt-handler type | |
6449 | function (i.e.@: it retains the normal C function calling ABI). See the | |
6450 | @code{interrupt} attribute for a description of its arguments. | |
6451 | @end table | |
6452 | ||
6453 | @node S/390 Function Attributes | |
6454 | @subsection S/390 Function Attributes | |
6455 | ||
6456 | These function attributes are supported on the S/390: | |
6457 | ||
6458 | @table @code | |
d77de738 | 6459 | @cindex @code{hotpatch} function attribute, S/390 |
f33d7a88 | 6460 | @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label}) |
d77de738 ML |
6461 | |
6462 | On S/390 System z targets, you can use this function attribute to | |
6463 | make GCC generate a ``hot-patching'' function prologue. If the | |
6464 | @option{-mhotpatch=} command-line option is used at the same time, | |
6465 | the @code{hotpatch} attribute takes precedence. The first of the | |
6466 | two arguments specifies the number of halfwords to be added before | |
6467 | the function label. A second argument can be used to specify the | |
6468 | number of halfwords to be added after the function label. For | |
6469 | both arguments the maximum allowed value is 1000000. | |
6470 | ||
6471 | If both arguments are zero, hotpatching is disabled. | |
6472 | ||
d77de738 | 6473 | @cindex @code{target} function attribute |
f33d7a88 | 6474 | @item target (@var{options}) |
d77de738 ML |
6475 | As discussed in @ref{Common Function Attributes}, this attribute |
6476 | allows specification of target-specific compilation options. | |
6477 | ||
6478 | On S/390, the following options are supported: | |
6479 | ||
6480 | @table @samp | |
6481 | @item arch= | |
6482 | @item tune= | |
6483 | @item stack-guard= | |
6484 | @item stack-size= | |
6485 | @item branch-cost= | |
6486 | @item warn-framesize= | |
6487 | @item backchain | |
6488 | @itemx no-backchain | |
6489 | @item hard-dfp | |
6490 | @itemx no-hard-dfp | |
6491 | @item hard-float | |
6492 | @itemx soft-float | |
6493 | @item htm | |
6494 | @itemx no-htm | |
6495 | @item vx | |
6496 | @itemx no-vx | |
6497 | @item packed-stack | |
6498 | @itemx no-packed-stack | |
6499 | @item small-exec | |
6500 | @itemx no-small-exec | |
6501 | @item mvcle | |
6502 | @itemx no-mvcle | |
6503 | @item warn-dynamicstack | |
6504 | @itemx no-warn-dynamicstack | |
6505 | @end table | |
6506 | ||
6507 | The options work exactly like the S/390 specific command line | |
6508 | options (without the prefix @option{-m}) except that they do not | |
6509 | change any feature macros. For example, | |
6510 | ||
6511 | @smallexample | |
6512 | @code{target("no-vx")} | |
6513 | @end smallexample | |
6514 | ||
6515 | does not undefine the @code{__VEC__} macro. | |
6516 | @end table | |
6517 | ||
6518 | @node SH Function Attributes | |
6519 | @subsection SH Function Attributes | |
6520 | ||
6521 | These function attributes are supported on the SH family of processors: | |
6522 | ||
6523 | @table @code | |
d77de738 ML |
6524 | @cindex @code{function_vector} function attribute, SH |
6525 | @cindex calling functions through the function vector on SH2A | |
f33d7a88 | 6526 | @item function_vector |
d77de738 ML |
6527 | On SH2A targets, this attribute declares a function to be called using the |
6528 | TBR relative addressing mode. The argument to this attribute is the entry | |
6529 | number of the same function in a vector table containing all the TBR | |
6530 | relative addressable functions. For correct operation the TBR must be setup | |
6531 | accordingly to point to the start of the vector table before any functions with | |
6532 | this attribute are invoked. Usually a good place to do the initialization is | |
6533 | the startup routine. The TBR relative vector table can have at max 256 function | |
6534 | entries. The jumps to these functions are generated using a SH2A specific, | |
6535 | non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD | |
6536 | from GNU binutils version 2.7 or later for this attribute to work correctly. | |
6537 | ||
6538 | In an application, for a function being called once, this attribute | |
6539 | saves at least 8 bytes of code; and if other successive calls are being | |
6540 | made to the same function, it saves 2 bytes of code per each of these | |
6541 | calls. | |
6542 | ||
d77de738 | 6543 | @cindex @code{interrupt_handler} function attribute, SH |
f33d7a88 | 6544 | @item interrupt_handler |
d77de738 ML |
6545 | Use this attribute to |
6546 | indicate that the specified function is an interrupt handler. The compiler | |
6547 | generates function entry and exit sequences suitable for use in an | |
6548 | interrupt handler when this attribute is present. | |
6549 | ||
d77de738 | 6550 | @cindex @code{nosave_low_regs} function attribute, SH |
f33d7a88 | 6551 | @item nosave_low_regs |
d77de738 ML |
6552 | Use this attribute on SH targets to indicate that an @code{interrupt_handler} |
6553 | function should not save and restore registers R0..R7. This can be used on SH3* | |
6554 | and SH4* targets that have a second R0..R7 register bank for non-reentrant | |
6555 | interrupt handlers. | |
6556 | ||
d77de738 | 6557 | @cindex @code{renesas} function attribute, SH |
f33d7a88 | 6558 | @item renesas |
d77de738 ML |
6559 | On SH targets this attribute specifies that the function or struct follows the |
6560 | Renesas ABI. | |
6561 | ||
d77de738 | 6562 | @cindex @code{resbank} function attribute, SH |
f33d7a88 | 6563 | @item resbank |
d77de738 ML |
6564 | On the SH2A target, this attribute enables the high-speed register |
6565 | saving and restoration using a register bank for @code{interrupt_handler} | |
6566 | routines. Saving to the bank is performed automatically after the CPU | |
6567 | accepts an interrupt that uses a register bank. | |
6568 | ||
6569 | The nineteen 32-bit registers comprising general register R0 to R14, | |
6570 | control register GBR, and system registers MACH, MACL, and PR and the | |
6571 | vector table address offset are saved into a register bank. Register | |
6572 | banks are stacked in first-in last-out (FILO) sequence. Restoration | |
6573 | from the bank is executed by issuing a RESBANK instruction. | |
6574 | ||
d77de738 | 6575 | @cindex @code{sp_switch} function attribute, SH |
f33d7a88 | 6576 | @item sp_switch |
d77de738 ML |
6577 | Use this attribute on the SH to indicate an @code{interrupt_handler} |
6578 | function should switch to an alternate stack. It expects a string | |
6579 | argument that names a global variable holding the address of the | |
6580 | alternate stack. | |
6581 | ||
6582 | @smallexample | |
6583 | void *alt_stack; | |
6584 | void f () __attribute__ ((interrupt_handler, | |
6585 | sp_switch ("alt_stack"))); | |
6586 | @end smallexample | |
6587 | ||
d77de738 | 6588 | @cindex @code{trap_exit} function attribute, SH |
f33d7a88 | 6589 | @item trap_exit |
d77de738 ML |
6590 | Use this attribute on the SH for an @code{interrupt_handler} to return using |
6591 | @code{trapa} instead of @code{rte}. This attribute expects an integer | |
6592 | argument specifying the trap number to be used. | |
6593 | ||
d77de738 | 6594 | @cindex @code{trapa_handler} function attribute, SH |
f33d7a88 | 6595 | @item trapa_handler |
d77de738 ML |
6596 | On SH targets this function attribute is similar to @code{interrupt_handler} |
6597 | but it does not save and restore all registers. | |
6598 | @end table | |
6599 | ||
6600 | @node Symbian OS Function Attributes | |
6601 | @subsection Symbian OS Function Attributes | |
6602 | ||
6603 | @xref{Microsoft Windows Function Attributes}, for discussion of the | |
6604 | @code{dllexport} and @code{dllimport} attributes. | |
6605 | ||
6606 | @node V850 Function Attributes | |
6607 | @subsection V850 Function Attributes | |
6608 | ||
6609 | The V850 back end supports these function attributes: | |
6610 | ||
6611 | @table @code | |
d77de738 ML |
6612 | @cindex @code{interrupt} function attribute, V850 |
6613 | @cindex @code{interrupt_handler} function attribute, V850 | |
f33d7a88 AA |
6614 | @item interrupt |
6615 | @itemx interrupt_handler | |
d77de738 ML |
6616 | Use these attributes to indicate |
6617 | that the specified function is an interrupt handler. The compiler generates | |
6618 | function entry and exit sequences suitable for use in an interrupt handler | |
6619 | when either attribute is present. | |
6620 | @end table | |
6621 | ||
6622 | @node Visium Function Attributes | |
6623 | @subsection Visium Function Attributes | |
6624 | ||
6625 | These function attributes are supported by the Visium back end: | |
6626 | ||
6627 | @table @code | |
d77de738 | 6628 | @cindex @code{interrupt} function attribute, Visium |
f33d7a88 | 6629 | @item interrupt |
d77de738 ML |
6630 | Use this attribute to indicate |
6631 | that the specified function is an interrupt handler. The compiler generates | |
6632 | function entry and exit sequences suitable for use in an interrupt handler | |
6633 | when this attribute is present. | |
6634 | @end table | |
6635 | ||
6636 | @node x86 Function Attributes | |
6637 | @subsection x86 Function Attributes | |
6638 | ||
6639 | These function attributes are supported by the x86 back end: | |
6640 | ||
6641 | @table @code | |
d77de738 ML |
6642 | @cindex @code{cdecl} function attribute, x86-32 |
6643 | @cindex functions that pop the argument stack on x86-32 | |
6644 | @opindex mrtd | |
f33d7a88 | 6645 | @item cdecl |
d77de738 ML |
6646 | On the x86-32 targets, the @code{cdecl} attribute causes the compiler to |
6647 | assume that the calling function pops off the stack space used to | |
6648 | pass arguments. This is | |
6649 | useful to override the effects of the @option{-mrtd} switch. | |
6650 | ||
d77de738 ML |
6651 | @cindex @code{fastcall} function attribute, x86-32 |
6652 | @cindex functions that pop the argument stack on x86-32 | |
f33d7a88 | 6653 | @item fastcall |
d77de738 ML |
6654 | On x86-32 targets, the @code{fastcall} attribute causes the compiler to |
6655 | pass the first argument (if of integral type) in the register ECX and | |
6656 | the second argument (if of integral type) in the register EDX@. Subsequent | |
6657 | and other typed arguments are passed on the stack. The called function | |
6658 | pops the arguments off the stack. If the number of arguments is variable all | |
6659 | arguments are pushed on the stack. | |
6660 | ||
d77de738 ML |
6661 | @cindex @code{thiscall} function attribute, x86-32 |
6662 | @cindex functions that pop the argument stack on x86-32 | |
f33d7a88 | 6663 | @item thiscall |
d77de738 ML |
6664 | On x86-32 targets, the @code{thiscall} attribute causes the compiler to |
6665 | pass the first argument (if of integral type) in the register ECX. | |
6666 | Subsequent and other typed arguments are passed on the stack. The called | |
6667 | function pops the arguments off the stack. | |
6668 | If the number of arguments is variable all arguments are pushed on the | |
6669 | stack. | |
6670 | The @code{thiscall} attribute is intended for C++ non-static member functions. | |
6671 | As a GCC extension, this calling convention can be used for C functions | |
6672 | and for static member methods. | |
6673 | ||
d77de738 ML |
6674 | @cindex @code{ms_abi} function attribute, x86 |
6675 | @cindex @code{sysv_abi} function attribute, x86 | |
f33d7a88 AA |
6676 | @item ms_abi |
6677 | @itemx sysv_abi | |
d77de738 ML |
6678 | |
6679 | On 32-bit and 64-bit x86 targets, you can use an ABI attribute | |
6680 | to indicate which calling convention should be used for a function. The | |
6681 | @code{ms_abi} attribute tells the compiler to use the Microsoft ABI, | |
6682 | while the @code{sysv_abi} attribute tells the compiler to use the System V | |
6683 | ELF ABI, which is used on GNU/Linux and other systems. The default is to use | |
6684 | the Microsoft ABI when targeting Windows. On all other systems, the default | |
6685 | is the System V ELF ABI. | |
6686 | ||
6687 | Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently | |
6688 | requires the @option{-maccumulate-outgoing-args} option. | |
6689 | ||
d77de738 | 6690 | @cindex @code{callee_pop_aggregate_return} function attribute, x86 |
f33d7a88 | 6691 | @item callee_pop_aggregate_return (@var{number}) |
d77de738 ML |
6692 | |
6693 | On x86-32 targets, you can use this attribute to control how | |
6694 | aggregates are returned in memory. If the caller is responsible for | |
6695 | popping the hidden pointer together with the rest of the arguments, specify | |
6696 | @var{number} equal to zero. If callee is responsible for popping the | |
6697 | hidden pointer, specify @var{number} equal to one. | |
6698 | ||
6699 | The default x86-32 ABI assumes that the callee pops the | |
6700 | stack for hidden pointer. However, on x86-32 Microsoft Windows targets, | |
6701 | the compiler assumes that the | |
6702 | caller pops the stack for hidden pointer. | |
6703 | ||
d77de738 | 6704 | @cindex @code{ms_hook_prologue} function attribute, x86 |
f33d7a88 | 6705 | @item ms_hook_prologue |
d77de738 ML |
6706 | |
6707 | On 32-bit and 64-bit x86 targets, you can use | |
6708 | this function attribute to make GCC generate the ``hot-patching'' function | |
6709 | prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 | |
6710 | and newer. | |
6711 | ||
d77de738 | 6712 | @cindex @code{naked} function attribute, x86 |
f33d7a88 | 6713 | @item naked |
d77de738 ML |
6714 | This attribute allows the compiler to construct the |
6715 | requisite function declaration, while allowing the body of the | |
6716 | function to be assembly code. The specified function will not have | |
6717 | prologue/epilogue sequences generated by the compiler. Only basic | |
6718 | @code{asm} statements can safely be included in naked functions | |
6719 | (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of | |
6720 | basic @code{asm} and C code may appear to work, they cannot be | |
6721 | depended upon to work reliably and are not supported. | |
6722 | ||
d77de738 ML |
6723 | @cindex @code{regparm} function attribute, x86 |
6724 | @cindex functions that are passed arguments in registers on x86-32 | |
f33d7a88 | 6725 | @item regparm (@var{number}) |
d77de738 ML |
6726 | On x86-32 targets, the @code{regparm} attribute causes the compiler to |
6727 | pass arguments number one to @var{number} if they are of integral type | |
6728 | in registers EAX, EDX, and ECX instead of on the stack. Functions that | |
6729 | take a variable number of arguments continue to be passed all of their | |
6730 | arguments on the stack. | |
6731 | ||
6732 | Beware that on some ELF systems this attribute is unsuitable for | |
6733 | global functions in shared libraries with lazy binding (which is the | |
6734 | default). Lazy binding sends the first call via resolving code in | |
6735 | the loader, which might assume EAX, EDX and ECX can be clobbered, as | |
6736 | per the standard calling conventions. Solaris 8 is affected by this. | |
6737 | Systems with the GNU C Library version 2.1 or higher | |
6738 | and FreeBSD are believed to be | |
6739 | safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be | |
6740 | disabled with the linker or the loader if desired, to avoid the | |
6741 | problem.) | |
6742 | ||
d77de738 | 6743 | @cindex @code{sseregparm} function attribute, x86 |
f33d7a88 | 6744 | @item sseregparm |
d77de738 ML |
6745 | On x86-32 targets with SSE support, the @code{sseregparm} attribute |
6746 | causes the compiler to pass up to 3 floating-point arguments in | |
6747 | SSE registers instead of on the stack. Functions that take a | |
6748 | variable number of arguments continue to pass all of their | |
6749 | floating-point arguments on the stack. | |
6750 | ||
d77de738 | 6751 | @cindex @code{force_align_arg_pointer} function attribute, x86 |
f33d7a88 | 6752 | @item force_align_arg_pointer |
d77de738 ML |
6753 | On x86 targets, the @code{force_align_arg_pointer} attribute may be |
6754 | applied to individual function definitions, generating an alternate | |
6755 | prologue and epilogue that realigns the run-time stack if necessary. | |
6756 | This supports mixing legacy codes that run with a 4-byte aligned stack | |
6757 | with modern codes that keep a 16-byte stack for SSE compatibility. | |
6758 | ||
d77de738 ML |
6759 | @cindex @code{stdcall} function attribute, x86-32 |
6760 | @cindex functions that pop the argument stack on x86-32 | |
f33d7a88 | 6761 | @item stdcall |
d77de738 ML |
6762 | On x86-32 targets, the @code{stdcall} attribute causes the compiler to |
6763 | assume that the called function pops off the stack space used to | |
6764 | pass arguments, unless it takes a variable number of arguments. | |
6765 | ||
d77de738 | 6766 | @cindex @code{no_caller_saved_registers} function attribute, x86 |
f33d7a88 | 6767 | @item no_caller_saved_registers |
d77de738 ML |
6768 | Use this attribute to indicate that the specified function has no |
6769 | caller-saved registers. That is, all registers are callee-saved. For | |
6770 | example, this attribute can be used for a function called from an | |
6771 | interrupt handler. The compiler generates proper function entry and | |
6772 | exit sequences to save and restore any modified registers, except for | |
6773 | the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87 | |
6774 | states, the GCC option @option{-mgeneral-regs-only} should be used to | |
6775 | compile functions with @code{no_caller_saved_registers} attribute. | |
6776 | ||
d77de738 | 6777 | @cindex @code{interrupt} function attribute, x86 |
f33d7a88 | 6778 | @item interrupt |
d77de738 ML |
6779 | Use this attribute to indicate that the specified function is an |
6780 | interrupt handler or an exception handler (depending on parameters passed | |
6781 | to the function, explained further). The compiler generates function | |
6782 | entry and exit sequences suitable for use in an interrupt handler when | |
6783 | this attribute is present. The @code{IRET} instruction, instead of the | |
6784 | @code{RET} instruction, is used to return from interrupt handlers. All | |
6785 | registers, except for the EFLAGS register which is restored by the | |
6786 | @code{IRET} instruction, are preserved by the compiler. Since GCC | |
6787 | doesn't preserve SSE, MMX nor x87 states, the GCC option | |
6788 | @option{-mgeneral-regs-only} should be used to compile interrupt and | |
6789 | exception handlers. | |
6790 | ||
6791 | Any interruptible-without-stack-switch code must be compiled with | |
6792 | @option{-mno-red-zone} since interrupt handlers can and will, because | |
6793 | of the hardware design, touch the red zone. | |
6794 | ||
6795 | An interrupt handler must be declared with a mandatory pointer | |
6796 | argument: | |
6797 | ||
6798 | @smallexample | |
6799 | struct interrupt_frame; | |
6800 | ||
6801 | __attribute__ ((interrupt)) | |
6802 | void | |
6803 | f (struct interrupt_frame *frame) | |
6804 | @{ | |
6805 | @} | |
6806 | @end smallexample | |
6807 | ||
6808 | @noindent | |
6809 | and you must define @code{struct interrupt_frame} as described in the | |
6810 | processor's manual. | |
6811 | ||
6812 | Exception handlers differ from interrupt handlers because the system | |
6813 | pushes an error code on the stack. An exception handler declaration is | |
6814 | similar to that for an interrupt handler, but with a different mandatory | |
6815 | function signature. The compiler arranges to pop the error code off the | |
6816 | stack before the @code{IRET} instruction. | |
6817 | ||
6818 | @smallexample | |
6819 | #ifdef __x86_64__ | |
6820 | typedef unsigned long long int uword_t; | |
6821 | #else | |
6822 | typedef unsigned int uword_t; | |
6823 | #endif | |
6824 | ||
6825 | struct interrupt_frame; | |
6826 | ||
6827 | __attribute__ ((interrupt)) | |
6828 | void | |
6829 | f (struct interrupt_frame *frame, uword_t error_code) | |
6830 | @{ | |
6831 | ... | |
6832 | @} | |
6833 | @end smallexample | |
6834 | ||
6835 | Exception handlers should only be used for exceptions that push an error | |
6836 | code; you should use an interrupt handler in other cases. The system | |
6837 | will crash if the wrong kind of handler is used. | |
6838 | ||
d77de738 | 6839 | @cindex @code{target} function attribute |
f33d7a88 | 6840 | @item target (@var{options}) |
d77de738 ML |
6841 | As discussed in @ref{Common Function Attributes}, this attribute |
6842 | allows specification of target-specific compilation options. | |
6843 | ||
6844 | On the x86, the following options are allowed: | |
6845 | @table @samp | |
f33d7a88 | 6846 | @cindex @code{target("3dnow")} function attribute, x86 |
d77de738 ML |
6847 | @item 3dnow |
6848 | @itemx no-3dnow | |
d77de738 ML |
6849 | Enable/disable the generation of the 3DNow!@: instructions. |
6850 | ||
f33d7a88 | 6851 | @cindex @code{target("3dnowa")} function attribute, x86 |
d77de738 ML |
6852 | @item 3dnowa |
6853 | @itemx no-3dnowa | |
d77de738 ML |
6854 | Enable/disable the generation of the enhanced 3DNow!@: instructions. |
6855 | ||
f33d7a88 | 6856 | @cindex @code{target("abm")} function attribute, x86 |
d77de738 ML |
6857 | @item abm |
6858 | @itemx no-abm | |
d77de738 ML |
6859 | Enable/disable the generation of the advanced bit instructions. |
6860 | ||
f33d7a88 | 6861 | @cindex @code{target("adx")} function attribute, x86 |
d77de738 ML |
6862 | @item adx |
6863 | @itemx no-adx | |
d77de738 ML |
6864 | Enable/disable the generation of the ADX instructions. |
6865 | ||
f33d7a88 | 6866 | @cindex @code{target("aes")} function attribute, x86 |
d77de738 ML |
6867 | @item aes |
6868 | @itemx no-aes | |
d77de738 ML |
6869 | Enable/disable the generation of the AES instructions. |
6870 | ||
f33d7a88 | 6871 | @cindex @code{target("avx")} function attribute, x86 |
d77de738 ML |
6872 | @item avx |
6873 | @itemx no-avx | |
d77de738 ML |
6874 | Enable/disable the generation of the AVX instructions. |
6875 | ||
f33d7a88 | 6876 | @cindex @code{target("avx2")} function attribute, x86 |
d77de738 ML |
6877 | @item avx2 |
6878 | @itemx no-avx2 | |
d77de738 ML |
6879 | Enable/disable the generation of the AVX2 instructions. |
6880 | ||
f33d7a88 | 6881 | @cindex @code{target("avx5124fmaps")} function attribute, x86 |
d77de738 ML |
6882 | @item avx5124fmaps |
6883 | @itemx no-avx5124fmaps | |
d77de738 ML |
6884 | Enable/disable the generation of the AVX5124FMAPS instructions. |
6885 | ||
f33d7a88 | 6886 | @cindex @code{target("avx5124vnniw")} function attribute, x86 |
d77de738 ML |
6887 | @item avx5124vnniw |
6888 | @itemx no-avx5124vnniw | |
d77de738 ML |
6889 | Enable/disable the generation of the AVX5124VNNIW instructions. |
6890 | ||
f33d7a88 | 6891 | @cindex @code{target("avx512bitalg")} function attribute, x86 |
d77de738 ML |
6892 | @item avx512bitalg |
6893 | @itemx no-avx512bitalg | |
d77de738 ML |
6894 | Enable/disable the generation of the AVX512BITALG instructions. |
6895 | ||
f33d7a88 | 6896 | @cindex @code{target("avx512bw")} function attribute, x86 |
d77de738 ML |
6897 | @item avx512bw |
6898 | @itemx no-avx512bw | |
d77de738 ML |
6899 | Enable/disable the generation of the AVX512BW instructions. |
6900 | ||
f33d7a88 | 6901 | @cindex @code{target("avx512cd")} function attribute, x86 |
d77de738 ML |
6902 | @item avx512cd |
6903 | @itemx no-avx512cd | |
d77de738 ML |
6904 | Enable/disable the generation of the AVX512CD instructions. |
6905 | ||
f33d7a88 | 6906 | @cindex @code{target("avx512dq")} function attribute, x86 |
d77de738 ML |
6907 | @item avx512dq |
6908 | @itemx no-avx512dq | |
d77de738 ML |
6909 | Enable/disable the generation of the AVX512DQ instructions. |
6910 | ||
f33d7a88 | 6911 | @cindex @code{target("avx512er")} function attribute, x86 |
d77de738 ML |
6912 | @item avx512er |
6913 | @itemx no-avx512er | |
d77de738 ML |
6914 | Enable/disable the generation of the AVX512ER instructions. |
6915 | ||
f33d7a88 | 6916 | @cindex @code{target("avx512f")} function attribute, x86 |
d77de738 ML |
6917 | @item avx512f |
6918 | @itemx no-avx512f | |
d77de738 ML |
6919 | Enable/disable the generation of the AVX512F instructions. |
6920 | ||
f33d7a88 | 6921 | @cindex @code{target("avx512ifma")} function attribute, x86 |
d77de738 ML |
6922 | @item avx512ifma |
6923 | @itemx no-avx512ifma | |
d77de738 ML |
6924 | Enable/disable the generation of the AVX512IFMA instructions. |
6925 | ||
f33d7a88 | 6926 | @cindex @code{target("avx512pf")} function attribute, x86 |
d77de738 ML |
6927 | @item avx512pf |
6928 | @itemx no-avx512pf | |
d77de738 ML |
6929 | Enable/disable the generation of the AVX512PF instructions. |
6930 | ||
f33d7a88 | 6931 | @cindex @code{target("avx512vbmi")} function attribute, x86 |
d77de738 ML |
6932 | @item avx512vbmi |
6933 | @itemx no-avx512vbmi | |
d77de738 ML |
6934 | Enable/disable the generation of the AVX512VBMI instructions. |
6935 | ||
f33d7a88 | 6936 | @cindex @code{target("avx512vbmi2")} function attribute, x86 |
d77de738 ML |
6937 | @item avx512vbmi2 |
6938 | @itemx no-avx512vbmi2 | |
d77de738 ML |
6939 | Enable/disable the generation of the AVX512VBMI2 instructions. |
6940 | ||
f33d7a88 | 6941 | @cindex @code{target("avx512vl")} function attribute, x86 |
d77de738 ML |
6942 | @item avx512vl |
6943 | @itemx no-avx512vl | |
d77de738 ML |
6944 | Enable/disable the generation of the AVX512VL instructions. |
6945 | ||
f33d7a88 | 6946 | @cindex @code{target("avx512vnni")} function attribute, x86 |
d77de738 ML |
6947 | @item avx512vnni |
6948 | @itemx no-avx512vnni | |
d77de738 ML |
6949 | Enable/disable the generation of the AVX512VNNI instructions. |
6950 | ||
f33d7a88 | 6951 | @cindex @code{target("avx512vpopcntdq")} function attribute, x86 |
d77de738 ML |
6952 | @item avx512vpopcntdq |
6953 | @itemx no-avx512vpopcntdq | |
d77de738 ML |
6954 | Enable/disable the generation of the AVX512VPOPCNTDQ instructions. |
6955 | ||
f33d7a88 | 6956 | @cindex @code{target("bmi")} function attribute, x86 |
d77de738 ML |
6957 | @item bmi |
6958 | @itemx no-bmi | |
d77de738 ML |
6959 | Enable/disable the generation of the BMI instructions. |
6960 | ||
f33d7a88 | 6961 | @cindex @code{target("bmi2")} function attribute, x86 |
d77de738 ML |
6962 | @item bmi2 |
6963 | @itemx no-bmi2 | |
d77de738 ML |
6964 | Enable/disable the generation of the BMI2 instructions. |
6965 | ||
f33d7a88 | 6966 | @cindex @code{target("cldemote")} function attribute, x86 |
d77de738 ML |
6967 | @item cldemote |
6968 | @itemx no-cldemote | |
d77de738 ML |
6969 | Enable/disable the generation of the CLDEMOTE instructions. |
6970 | ||
f33d7a88 | 6971 | @cindex @code{target("clflushopt")} function attribute, x86 |
d77de738 ML |
6972 | @item clflushopt |
6973 | @itemx no-clflushopt | |
d77de738 ML |
6974 | Enable/disable the generation of the CLFLUSHOPT instructions. |
6975 | ||
f33d7a88 | 6976 | @cindex @code{target("clwb")} function attribute, x86 |
d77de738 ML |
6977 | @item clwb |
6978 | @itemx no-clwb | |
d77de738 ML |
6979 | Enable/disable the generation of the CLWB instructions. |
6980 | ||
f33d7a88 | 6981 | @cindex @code{target("clzero")} function attribute, x86 |
d77de738 ML |
6982 | @item clzero |
6983 | @itemx no-clzero | |
d77de738 ML |
6984 | Enable/disable the generation of the CLZERO instructions. |
6985 | ||
f33d7a88 | 6986 | @cindex @code{target("crc32")} function attribute, x86 |
d77de738 ML |
6987 | @item crc32 |
6988 | @itemx no-crc32 | |
d77de738 ML |
6989 | Enable/disable the generation of the CRC32 instructions. |
6990 | ||
f33d7a88 | 6991 | @cindex @code{target("cx16")} function attribute, x86 |
d77de738 ML |
6992 | @item cx16 |
6993 | @itemx no-cx16 | |
d77de738 ML |
6994 | Enable/disable the generation of the CMPXCHG16B instructions. |
6995 | ||
d77de738 | 6996 | @cindex @code{target("default")} function attribute, x86 |
f33d7a88 | 6997 | @item default |
d77de738 ML |
6998 | @xref{Function Multiversioning}, where it is used to specify the |
6999 | default function version. | |
7000 | ||
f33d7a88 | 7001 | @cindex @code{target("f16c")} function attribute, x86 |
d77de738 ML |
7002 | @item f16c |
7003 | @itemx no-f16c | |
d77de738 ML |
7004 | Enable/disable the generation of the F16C instructions. |
7005 | ||
f33d7a88 | 7006 | @cindex @code{target("fma")} function attribute, x86 |
d77de738 ML |
7007 | @item fma |
7008 | @itemx no-fma | |
d77de738 ML |
7009 | Enable/disable the generation of the FMA instructions. |
7010 | ||
f33d7a88 | 7011 | @cindex @code{target("fma4")} function attribute, x86 |
d77de738 ML |
7012 | @item fma4 |
7013 | @itemx no-fma4 | |
d77de738 ML |
7014 | Enable/disable the generation of the FMA4 instructions. |
7015 | ||
f33d7a88 | 7016 | @cindex @code{target("fsgsbase")} function attribute, x86 |
d77de738 ML |
7017 | @item fsgsbase |
7018 | @itemx no-fsgsbase | |
d77de738 ML |
7019 | Enable/disable the generation of the FSGSBASE instructions. |
7020 | ||
f33d7a88 | 7021 | @cindex @code{target("fxsr")} function attribute, x86 |
d77de738 ML |
7022 | @item fxsr |
7023 | @itemx no-fxsr | |
d77de738 ML |
7024 | Enable/disable the generation of the FXSR instructions. |
7025 | ||
f33d7a88 | 7026 | @cindex @code{target("gfni")} function attribute, x86 |
d77de738 ML |
7027 | @item gfni |
7028 | @itemx no-gfni | |
d77de738 ML |
7029 | Enable/disable the generation of the GFNI instructions. |
7030 | ||
f33d7a88 | 7031 | @cindex @code{target("hle")} function attribute, x86 |
d77de738 ML |
7032 | @item hle |
7033 | @itemx no-hle | |
d77de738 ML |
7034 | Enable/disable the generation of the HLE instruction prefixes. |
7035 | ||
f33d7a88 | 7036 | @cindex @code{target("lwp")} function attribute, x86 |
d77de738 ML |
7037 | @item lwp |
7038 | @itemx no-lwp | |
d77de738 ML |
7039 | Enable/disable the generation of the LWP instructions. |
7040 | ||
f33d7a88 | 7041 | @cindex @code{target("lzcnt")} function attribute, x86 |
d77de738 ML |
7042 | @item lzcnt |
7043 | @itemx no-lzcnt | |
d77de738 ML |
7044 | Enable/disable the generation of the LZCNT instructions. |
7045 | ||
f33d7a88 | 7046 | @cindex @code{target("mmx")} function attribute, x86 |
d77de738 ML |
7047 | @item mmx |
7048 | @itemx no-mmx | |
d77de738 ML |
7049 | Enable/disable the generation of the MMX instructions. |
7050 | ||
f33d7a88 | 7051 | @cindex @code{target("movbe")} function attribute, x86 |
d77de738 ML |
7052 | @item movbe |
7053 | @itemx no-movbe | |
d77de738 ML |
7054 | Enable/disable the generation of the MOVBE instructions. |
7055 | ||
f33d7a88 | 7056 | @cindex @code{target("movdir64b")} function attribute, x86 |
d77de738 ML |
7057 | @item movdir64b |
7058 | @itemx no-movdir64b | |
d77de738 ML |
7059 | Enable/disable the generation of the MOVDIR64B instructions. |
7060 | ||
f33d7a88 | 7061 | @cindex @code{target("movdiri")} function attribute, x86 |
d77de738 ML |
7062 | @item movdiri |
7063 | @itemx no-movdiri | |
d77de738 ML |
7064 | Enable/disable the generation of the MOVDIRI instructions. |
7065 | ||
f33d7a88 | 7066 | @cindex @code{target("mwait")} function attribute, x86 |
d77de738 ML |
7067 | @item mwait |
7068 | @itemx no-mwait | |
d77de738 ML |
7069 | Enable/disable the generation of the MWAIT and MONITOR instructions. |
7070 | ||
f33d7a88 | 7071 | @cindex @code{target("mwaitx")} function attribute, x86 |
d77de738 ML |
7072 | @item mwaitx |
7073 | @itemx no-mwaitx | |
d77de738 ML |
7074 | Enable/disable the generation of the MWAITX instructions. |
7075 | ||
f33d7a88 | 7076 | @cindex @code{target("pclmul")} function attribute, x86 |
d77de738 ML |
7077 | @item pclmul |
7078 | @itemx no-pclmul | |
d77de738 ML |
7079 | Enable/disable the generation of the PCLMUL instructions. |
7080 | ||
f33d7a88 | 7081 | @cindex @code{target("pconfig")} function attribute, x86 |
d77de738 ML |
7082 | @item pconfig |
7083 | @itemx no-pconfig | |
d77de738 ML |
7084 | Enable/disable the generation of the PCONFIG instructions. |
7085 | ||
f33d7a88 | 7086 | @cindex @code{target("pku")} function attribute, x86 |
d77de738 ML |
7087 | @item pku |
7088 | @itemx no-pku | |
d77de738 ML |
7089 | Enable/disable the generation of the PKU instructions. |
7090 | ||
f33d7a88 | 7091 | @cindex @code{target("popcnt")} function attribute, x86 |
d77de738 ML |
7092 | @item popcnt |
7093 | @itemx no-popcnt | |
d77de738 ML |
7094 | Enable/disable the generation of the POPCNT instruction. |
7095 | ||
f33d7a88 | 7096 | @cindex @code{target("prefetchwt1")} function attribute, x86 |
d77de738 ML |
7097 | @item prefetchwt1 |
7098 | @itemx no-prefetchwt1 | |
d77de738 ML |
7099 | Enable/disable the generation of the PREFETCHWT1 instructions. |
7100 | ||
f33d7a88 | 7101 | @cindex @code{target("prfchw")} function attribute, x86 |
d77de738 ML |
7102 | @item prfchw |
7103 | @itemx no-prfchw | |
d77de738 ML |
7104 | Enable/disable the generation of the PREFETCHW instruction. |
7105 | ||
f33d7a88 | 7106 | @cindex @code{target("ptwrite")} function attribute, x86 |
d77de738 ML |
7107 | @item ptwrite |
7108 | @itemx no-ptwrite | |
d77de738 ML |
7109 | Enable/disable the generation of the PTWRITE instructions. |
7110 | ||
f33d7a88 | 7111 | @cindex @code{target("rdpid")} function attribute, x86 |
d77de738 ML |
7112 | @item rdpid |
7113 | @itemx no-rdpid | |
d77de738 ML |
7114 | Enable/disable the generation of the RDPID instructions. |
7115 | ||
f33d7a88 | 7116 | @cindex @code{target("rdrnd")} function attribute, x86 |
d77de738 ML |
7117 | @item rdrnd |
7118 | @itemx no-rdrnd | |
d77de738 ML |
7119 | Enable/disable the generation of the RDRND instructions. |
7120 | ||
f33d7a88 | 7121 | @cindex @code{target("rdseed")} function attribute, x86 |
d77de738 ML |
7122 | @item rdseed |
7123 | @itemx no-rdseed | |
d77de738 ML |
7124 | Enable/disable the generation of the RDSEED instructions. |
7125 | ||
f33d7a88 | 7126 | @cindex @code{target("rtm")} function attribute, x86 |
d77de738 ML |
7127 | @item rtm |
7128 | @itemx no-rtm | |
d77de738 ML |
7129 | Enable/disable the generation of the RTM instructions. |
7130 | ||
f33d7a88 | 7131 | @cindex @code{target("sahf")} function attribute, x86 |
d77de738 ML |
7132 | @item sahf |
7133 | @itemx no-sahf | |
d77de738 ML |
7134 | Enable/disable the generation of the SAHF instructions. |
7135 | ||
f33d7a88 | 7136 | @cindex @code{target("sgx")} function attribute, x86 |
d77de738 ML |
7137 | @item sgx |
7138 | @itemx no-sgx | |
d77de738 ML |
7139 | Enable/disable the generation of the SGX instructions. |
7140 | ||
f33d7a88 | 7141 | @cindex @code{target("sha")} function attribute, x86 |
d77de738 ML |
7142 | @item sha |
7143 | @itemx no-sha | |
d77de738 ML |
7144 | Enable/disable the generation of the SHA instructions. |
7145 | ||
f33d7a88 | 7146 | @cindex @code{target("shstk")} function attribute, x86 |
d77de738 ML |
7147 | @item shstk |
7148 | @itemx no-shstk | |
d77de738 ML |
7149 | Enable/disable the shadow stack built-in functions from CET. |
7150 | ||
f33d7a88 | 7151 | @cindex @code{target("sse")} function attribute, x86 |
d77de738 ML |
7152 | @item sse |
7153 | @itemx no-sse | |
d77de738 ML |
7154 | Enable/disable the generation of the SSE instructions. |
7155 | ||
f33d7a88 | 7156 | @cindex @code{target("sse2")} function attribute, x86 |
d77de738 ML |
7157 | @item sse2 |
7158 | @itemx no-sse2 | |
d77de738 ML |
7159 | Enable/disable the generation of the SSE2 instructions. |
7160 | ||
f33d7a88 | 7161 | @cindex @code{target("sse3")} function attribute, x86 |
d77de738 ML |
7162 | @item sse3 |
7163 | @itemx no-sse3 | |
d77de738 ML |
7164 | Enable/disable the generation of the SSE3 instructions. |
7165 | ||
f33d7a88 | 7166 | @cindex @code{target("sse4")} function attribute, x86 |
d77de738 ML |
7167 | @item sse4 |
7168 | @itemx no-sse4 | |
d77de738 ML |
7169 | Enable/disable the generation of the SSE4 instructions (both SSE4.1 |
7170 | and SSE4.2). | |
7171 | ||
f33d7a88 | 7172 | @cindex @code{target("sse4.1")} function attribute, x86 |
d77de738 ML |
7173 | @item sse4.1 |
7174 | @itemx no-sse4.1 | |
d77de738 ML |
7175 | Enable/disable the generation of the SSE4.1 instructions. |
7176 | ||
f33d7a88 | 7177 | @cindex @code{target("sse4.2")} function attribute, x86 |
d77de738 ML |
7178 | @item sse4.2 |
7179 | @itemx no-sse4.2 | |
d77de738 ML |
7180 | Enable/disable the generation of the SSE4.2 instructions. |
7181 | ||
f33d7a88 | 7182 | @cindex @code{target("sse4a")} function attribute, x86 |
d77de738 ML |
7183 | @item sse4a |
7184 | @itemx no-sse4a | |
d77de738 ML |
7185 | Enable/disable the generation of the SSE4A instructions. |
7186 | ||
f33d7a88 | 7187 | @cindex @code{target("ssse3")} function attribute, x86 |
d77de738 ML |
7188 | @item ssse3 |
7189 | @itemx no-ssse3 | |
d77de738 ML |
7190 | Enable/disable the generation of the SSSE3 instructions. |
7191 | ||
f33d7a88 | 7192 | @cindex @code{target("tbm")} function attribute, x86 |
d77de738 ML |
7193 | @item tbm |
7194 | @itemx no-tbm | |
d77de738 ML |
7195 | Enable/disable the generation of the TBM instructions. |
7196 | ||
f33d7a88 | 7197 | @cindex @code{target("vaes")} function attribute, x86 |
d77de738 ML |
7198 | @item vaes |
7199 | @itemx no-vaes | |
d77de738 ML |
7200 | Enable/disable the generation of the VAES instructions. |
7201 | ||
f33d7a88 | 7202 | @cindex @code{target("vpclmulqdq")} function attribute, x86 |
d77de738 ML |
7203 | @item vpclmulqdq |
7204 | @itemx no-vpclmulqdq | |
d77de738 ML |
7205 | Enable/disable the generation of the VPCLMULQDQ instructions. |
7206 | ||
f33d7a88 | 7207 | @cindex @code{target("waitpkg")} function attribute, x86 |
d77de738 ML |
7208 | @item waitpkg |
7209 | @itemx no-waitpkg | |
d77de738 ML |
7210 | Enable/disable the generation of the WAITPKG instructions. |
7211 | ||
f33d7a88 | 7212 | @cindex @code{target("wbnoinvd")} function attribute, x86 |
d77de738 ML |
7213 | @item wbnoinvd |
7214 | @itemx no-wbnoinvd | |
d77de738 ML |
7215 | Enable/disable the generation of the WBNOINVD instructions. |
7216 | ||
f33d7a88 | 7217 | @cindex @code{target("xop")} function attribute, x86 |
d77de738 ML |
7218 | @item xop |
7219 | @itemx no-xop | |
d77de738 ML |
7220 | Enable/disable the generation of the XOP instructions. |
7221 | ||
f33d7a88 | 7222 | @cindex @code{target("xsave")} function attribute, x86 |
d77de738 ML |
7223 | @item xsave |
7224 | @itemx no-xsave | |
d77de738 ML |
7225 | Enable/disable the generation of the XSAVE instructions. |
7226 | ||
f33d7a88 | 7227 | @cindex @code{target("xsavec")} function attribute, x86 |
d77de738 ML |
7228 | @item xsavec |
7229 | @itemx no-xsavec | |
d77de738 ML |
7230 | Enable/disable the generation of the XSAVEC instructions. |
7231 | ||
f33d7a88 | 7232 | @cindex @code{target("xsaveopt")} function attribute, x86 |
d77de738 ML |
7233 | @item xsaveopt |
7234 | @itemx no-xsaveopt | |
d77de738 ML |
7235 | Enable/disable the generation of the XSAVEOPT instructions. |
7236 | ||
f33d7a88 | 7237 | @cindex @code{target("xsaves")} function attribute, x86 |
d77de738 ML |
7238 | @item xsaves |
7239 | @itemx no-xsaves | |
d77de738 ML |
7240 | Enable/disable the generation of the XSAVES instructions. |
7241 | ||
f33d7a88 | 7242 | @cindex @code{target("amx-tile")} function attribute, x86 |
d77de738 ML |
7243 | @item amx-tile |
7244 | @itemx no-amx-tile | |
d77de738 ML |
7245 | Enable/disable the generation of the AMX-TILE instructions. |
7246 | ||
f33d7a88 | 7247 | @cindex @code{target("amx-int8")} function attribute, x86 |
d77de738 ML |
7248 | @item amx-int8 |
7249 | @itemx no-amx-int8 | |
d77de738 ML |
7250 | Enable/disable the generation of the AMX-INT8 instructions. |
7251 | ||
f33d7a88 | 7252 | @cindex @code{target("amx-bf16")} function attribute, x86 |
d77de738 ML |
7253 | @item amx-bf16 |
7254 | @itemx no-amx-bf16 | |
d77de738 ML |
7255 | Enable/disable the generation of the AMX-BF16 instructions. |
7256 | ||
f33d7a88 | 7257 | @cindex @code{target("uintr")} function attribute, x86 |
d77de738 ML |
7258 | @item uintr |
7259 | @itemx no-uintr | |
d77de738 ML |
7260 | Enable/disable the generation of the UINTR instructions. |
7261 | ||
f33d7a88 | 7262 | @cindex @code{target("hreset")} function attribute, x86 |
d77de738 ML |
7263 | @item hreset |
7264 | @itemx no-hreset | |
d77de738 ML |
7265 | Enable/disable the generation of the HRESET instruction. |
7266 | ||
f33d7a88 | 7267 | @cindex @code{target("kl")} function attribute, x86 |
d77de738 ML |
7268 | @item kl |
7269 | @itemx no-kl | |
d77de738 ML |
7270 | Enable/disable the generation of the KEYLOCKER instructions. |
7271 | ||
f33d7a88 | 7272 | @cindex @code{target("widekl")} function attribute, x86 |
d77de738 ML |
7273 | @item widekl |
7274 | @itemx no-widekl | |
d77de738 ML |
7275 | Enable/disable the generation of the WIDEKL instructions. |
7276 | ||
f33d7a88 | 7277 | @cindex @code{target("avxvnni")} function attribute, x86 |
d77de738 ML |
7278 | @item avxvnni |
7279 | @itemx no-avxvnni | |
d77de738 ML |
7280 | Enable/disable the generation of the AVXVNNI instructions. |
7281 | ||
f33d7a88 | 7282 | @cindex @code{target("avxifma")} function attribute, x86 |
d77de738 ML |
7283 | @item avxifma |
7284 | @itemx no-avxifma | |
d77de738 ML |
7285 | Enable/disable the generation of the AVXIFMA instructions. |
7286 | ||
f33d7a88 | 7287 | @cindex @code{target("avxvnniint8")} function attribute, x86 |
d77de738 ML |
7288 | @item avxvnniint8 |
7289 | @itemx no-avxvnniint8 | |
d77de738 ML |
7290 | Enable/disable the generation of the AVXVNNIINT8 instructions. |
7291 | ||
f33d7a88 | 7292 | @cindex @code{target("avxneconvert")} function attribute, x86 |
d77de738 ML |
7293 | @item avxneconvert |
7294 | @itemx no-avxneconvert | |
d77de738 ML |
7295 | Enable/disable the generation of the AVXNECONVERT instructions. |
7296 | ||
f33d7a88 | 7297 | @cindex @code{target("cmpccxadd")} function attribute, x86 |
d77de738 ML |
7298 | @item cmpccxadd |
7299 | @itemx no-cmpccxadd | |
d77de738 ML |
7300 | Enable/disable the generation of the CMPccXADD instructions. |
7301 | ||
f33d7a88 | 7302 | @cindex @code{target("amx-fp16")} function attribute, x86 |
d77de738 ML |
7303 | @item amx-fp16 |
7304 | @itemx no-amx-fp16 | |
d77de738 ML |
7305 | Enable/disable the generation of the AMX-FP16 instructions. |
7306 | ||
f33d7a88 | 7307 | @cindex @code{target("prefetchi")} function attribute, x86 |
d77de738 ML |
7308 | @item prefetchi |
7309 | @itemx no-prefetchi | |
d77de738 ML |
7310 | Enable/disable the generation of the PREFETCHI instructions. |
7311 | ||
f33d7a88 | 7312 | @cindex @code{target("raoint")} function attribute, x86 |
d77de738 ML |
7313 | @item raoint |
7314 | @itemx no-raoint | |
d77de738 ML |
7315 | Enable/disable the generation of the RAOINT instructions. |
7316 | ||
efa6a82b HJ |
7317 | @cindex @code{target("amx-complex")} function attribute, x86 |
7318 | @item amx-complex | |
7319 | @itemx no-amx-complex | |
7320 | Enable/disable the generation of the AMX-COMPLEX instructions. | |
7321 | ||
1dbc1081 KL |
7322 | @cindex @code{target("avxvnniint16")} function attribute, x86 |
7323 | @item avxvnniint16 | |
7324 | @itemx no-avxvnniint16 | |
7325 | Enable/disable the generation of the AVXVNNIINT16 instructions. | |
7326 | ||
8643bcba HJ |
7327 | @cindex @code{target("sm3")} function attribute, x86 |
7328 | @item sm3 | |
7329 | @itemx no-sm3 | |
7330 | Enable/disable the generation of the SM3 instructions. | |
7331 | ||
86446132 HJ |
7332 | @cindex @code{target("sha512")} function attribute, x86 |
7333 | @item sha512 | |
7334 | @itemx no-sha512 | |
7335 | Enable/disable the generation of the SHA512 instructions. | |
7336 | ||
37bdeb8f HJ |
7337 | @cindex @code{target("sm4")} function attribute, x86 |
7338 | @item sm4 | |
7339 | @itemx no-sm4 | |
7340 | Enable/disable the generation of the SM4 instructions. | |
7341 | ||
5fbd91b1 HL |
7342 | @cindex @code{target("usermsr")} function attribute, x86 |
7343 | @item usermsr | |
7344 | @itemx no-usermsr | |
7345 | Enable/disable the generation of the USER_MSR instructions. | |
7346 | ||
2f8f7ee2 HJ |
7347 | @cindex @code{target("avx10.1")} function attribute, x86 |
7348 | @item avx10.1 | |
7349 | @itemx no-avx10.1 | |
7350 | Enable/disable the generation of the AVX10.1 instructions. | |
7351 | ||
7352 | @cindex @code{target("avx10.1-256")} function attribute, x86 | |
7353 | @item avx10.1-256 | |
7354 | @itemx no-avx10.1-256 | |
7355 | Enable/disable the generation of the AVX10.1 instructions. | |
7356 | ||
7357 | @cindex @code{target("avx10.1-512")} function attribute, x86 | |
7358 | @item avx10.1-512 | |
7359 | @itemx no-avx10.1-512 | |
7360 | Enable/disable the generation of the AVX10.1 512 bit instructions. | |
7361 | ||
f33d7a88 | 7362 | @cindex @code{target("cld")} function attribute, x86 |
d77de738 ML |
7363 | @item cld |
7364 | @itemx no-cld | |
d77de738 ML |
7365 | Enable/disable the generation of the CLD before string moves. |
7366 | ||
f33d7a88 | 7367 | @cindex @code{target("fancy-math-387")} function attribute, x86 |
d77de738 ML |
7368 | @item fancy-math-387 |
7369 | @itemx no-fancy-math-387 | |
d77de738 ML |
7370 | Enable/disable the generation of the @code{sin}, @code{cos}, and |
7371 | @code{sqrt} instructions on the 387 floating-point unit. | |
7372 | ||
f33d7a88 | 7373 | @cindex @code{target("ieee-fp")} function attribute, x86 |
d77de738 ML |
7374 | @item ieee-fp |
7375 | @itemx no-ieee-fp | |
d77de738 ML |
7376 | Enable/disable the generation of floating point that depends on IEEE arithmetic. |
7377 | ||
f33d7a88 | 7378 | @cindex @code{target("inline-all-stringops")} function attribute, x86 |
d77de738 ML |
7379 | @item inline-all-stringops |
7380 | @itemx no-inline-all-stringops | |
d77de738 ML |
7381 | Enable/disable inlining of string operations. |
7382 | ||
f33d7a88 | 7383 | @cindex @code{target("inline-stringops-dynamically")} function attribute, x86 |
d77de738 ML |
7384 | @item inline-stringops-dynamically |
7385 | @itemx no-inline-stringops-dynamically | |
d77de738 ML |
7386 | Enable/disable the generation of the inline code to do small string |
7387 | operations and calling the library routines for large operations. | |
7388 | ||
f33d7a88 | 7389 | @cindex @code{target("align-stringops")} function attribute, x86 |
d77de738 ML |
7390 | @item align-stringops |
7391 | @itemx no-align-stringops | |
d77de738 ML |
7392 | Do/do not align destination of inlined string operations. |
7393 | ||
f33d7a88 | 7394 | @cindex @code{target("recip")} function attribute, x86 |
d77de738 ML |
7395 | @item recip |
7396 | @itemx no-recip | |
d77de738 ML |
7397 | Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS |
7398 | instructions followed an additional Newton-Raphson step instead of | |
7399 | doing a floating-point division. | |
7400 | ||
d77de738 | 7401 | @cindex @code{target("general-regs-only")} function attribute, x86 |
f33d7a88 | 7402 | @item general-regs-only |
d77de738 ML |
7403 | Generate code which uses only the general registers. |
7404 | ||
d77de738 | 7405 | @cindex @code{target("arch=@var{ARCH}")} function attribute, x86 |
f33d7a88 | 7406 | @item arch=@var{ARCH} |
d77de738 ML |
7407 | Specify the architecture to generate code for in compiling the function. |
7408 | ||
d77de738 | 7409 | @cindex @code{target("tune=@var{TUNE}")} function attribute, x86 |
f33d7a88 | 7410 | @item tune=@var{TUNE} |
d77de738 ML |
7411 | Specify the architecture to tune for in compiling the function. |
7412 | ||
d77de738 | 7413 | @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86 |
f33d7a88 | 7414 | @item fpmath=@var{FPMATH} |
d77de738 ML |
7415 | Specify which floating-point unit to use. You must specify the |
7416 | @code{target("fpmath=sse,387")} option as | |
7417 | @code{target("fpmath=sse+387")} because the comma would separate | |
7418 | different options. | |
7419 | ||
d77de738 | 7420 | @cindex @code{prefer-vector-width} function attribute, x86 |
f33d7a88 | 7421 | @item prefer-vector-width=@var{OPT} |
d77de738 ML |
7422 | On x86 targets, the @code{prefer-vector-width} attribute informs the |
7423 | compiler to use @var{OPT}-bit vector width in instructions | |
7424 | instead of the default on the selected platform. | |
7425 | ||
7426 | Valid @var{OPT} values are: | |
7427 | ||
7428 | @table @samp | |
7429 | @item none | |
7430 | No extra limitations applied to GCC other than defined by the selected platform. | |
7431 | ||
7432 | @item 128 | |
7433 | Prefer 128-bit vector width for instructions. | |
7434 | ||
7435 | @item 256 | |
7436 | Prefer 256-bit vector width for instructions. | |
7437 | ||
7438 | @item 512 | |
7439 | Prefer 512-bit vector width for instructions. | |
7440 | @end table | |
7441 | ||
d77de738 ML |
7442 | @end table |
7443 | ||
d77de738 | 7444 | @cindex @code{indirect_branch} function attribute, x86 |
f33d7a88 | 7445 | @item indirect_branch("@var{choice}") |
d77de738 ML |
7446 | On x86 targets, the @code{indirect_branch} attribute causes the compiler |
7447 | to convert indirect call and jump with @var{choice}. @samp{keep} | |
7448 | keeps indirect call and jump unmodified. @samp{thunk} converts indirect | |
7449 | call and jump to call and return thunk. @samp{thunk-inline} converts | |
7450 | indirect call and jump to inlined call and return thunk. | |
7451 | @samp{thunk-extern} converts indirect call and jump to external call | |
7452 | and return thunk provided in a separate object file. | |
7453 | ||
d77de738 | 7454 | @cindex @code{function_return} function attribute, x86 |
f33d7a88 | 7455 | @item function_return("@var{choice}") |
d77de738 ML |
7456 | On x86 targets, the @code{function_return} attribute causes the compiler |
7457 | to convert function return with @var{choice}. @samp{keep} keeps function | |
7458 | return unmodified. @samp{thunk} converts function return to call and | |
7459 | return thunk. @samp{thunk-inline} converts function return to inlined | |
7460 | call and return thunk. @samp{thunk-extern} converts function return to | |
7461 | external call and return thunk provided in a separate object file. | |
7462 | ||
d77de738 | 7463 | @cindex @code{nocf_check} function attribute |
f33d7a88 | 7464 | @item nocf_check |
d77de738 ML |
7465 | The @code{nocf_check} attribute on a function is used to inform the |
7466 | compiler that the function's prologue should not be instrumented when | |
7467 | compiled with the @option{-fcf-protection=branch} option. The | |
7468 | compiler assumes that the function's address is a valid target for a | |
7469 | control-flow transfer. | |
7470 | ||
7471 | The @code{nocf_check} attribute on a type of pointer to function is | |
7472 | used to inform the compiler that a call through the pointer should | |
7473 | not be instrumented when compiled with the | |
7474 | @option{-fcf-protection=branch} option. The compiler assumes | |
7475 | that the function's address from the pointer is a valid target for | |
7476 | a control-flow transfer. A direct function call through a function | |
7477 | name is assumed to be a safe call thus direct calls are not | |
7478 | instrumented by the compiler. | |
7479 | ||
7480 | The @code{nocf_check} attribute is applied to an object's type. | |
7481 | In case of assignment of a function address or a function pointer to | |
7482 | another pointer, the attribute is not carried over from the right-hand | |
7483 | object's type; the type of left-hand object stays unchanged. The | |
7484 | compiler checks for @code{nocf_check} attribute mismatch and reports | |
7485 | a warning in case of mismatch. | |
7486 | ||
7487 | @smallexample | |
7488 | @{ | |
7489 | int foo (void) __attribute__(nocf_check); | |
7490 | void (*foo1)(void) __attribute__(nocf_check); | |
7491 | void (*foo2)(void); | |
7492 | ||
7493 | /* foo's address is assumed to be valid. */ | |
7494 | int | |
7495 | foo (void) | |
7496 | ||
7497 | /* This call site is not checked for control-flow | |
7498 | validity. */ | |
7499 | (*foo1)(); | |
7500 | ||
7501 | /* A warning is issued about attribute mismatch. */ | |
7502 | foo1 = foo2; | |
7503 | ||
7504 | /* This call site is still not checked. */ | |
7505 | (*foo1)(); | |
7506 | ||
7507 | /* This call site is checked. */ | |
7508 | (*foo2)(); | |
7509 | ||
7510 | /* A warning is issued about attribute mismatch. */ | |
7511 | foo2 = foo1; | |
7512 | ||
7513 | /* This call site is still checked. */ | |
7514 | (*foo2)(); | |
7515 | ||
7516 | return 0; | |
7517 | @} | |
7518 | @end smallexample | |
7519 | ||
d77de738 | 7520 | @cindex @code{cf_check} function attribute, x86 |
f33d7a88 | 7521 | @item cf_check |
d77de738 ML |
7522 | |
7523 | The @code{cf_check} attribute on a function is used to inform the | |
7524 | compiler that ENDBR instruction should be placed at the function | |
7525 | entry when @option{-fcf-protection=branch} is enabled. | |
7526 | ||
d77de738 | 7527 | @cindex @code{indirect_return} function attribute, x86 |
f33d7a88 | 7528 | @item indirect_return |
d77de738 ML |
7529 | |
7530 | The @code{indirect_return} attribute can be applied to a function, | |
7531 | as well as variable or type of function pointer to inform the | |
7532 | compiler that the function may return via indirect branch. | |
7533 | ||
d77de738 | 7534 | @cindex @code{fentry_name} function attribute, x86 |
f33d7a88 | 7535 | @item fentry_name("@var{name}") |
d77de738 ML |
7536 | On x86 targets, the @code{fentry_name} attribute sets the function to |
7537 | call on function entry when function instrumentation is enabled | |
7538 | with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte | |
7539 | nop sequence is generated. | |
7540 | ||
d77de738 | 7541 | @cindex @code{fentry_section} function attribute, x86 |
f33d7a88 | 7542 | @item fentry_section("@var{name}") |
d77de738 ML |
7543 | On x86 targets, the @code{fentry_section} attribute sets the name |
7544 | of the section to record function entry instrumentation calls in when | |
7545 | enabled with @option{-pg -mrecord-mcount} | |
7546 | ||
d77de738 ML |
7547 | @cindex @code{nodirect_extern_access} function attribute |
7548 | @opindex mno-direct-extern-access | |
f33d7a88 | 7549 | @item nodirect_extern_access |
d77de738 ML |
7550 | This attribute, attached to a global variable or function, is the |
7551 | counterpart to option @option{-mno-direct-extern-access}. | |
7552 | ||
7553 | @end table | |
7554 | ||
6ded65b8 HW |
7555 | @subsubsection Inlining rules |
7556 | On the x86, the inliner does not inline a | |
7557 | function that has different target options than the caller, unless the | |
7558 | callee has a subset of the target options of the caller. For example | |
7559 | a function declared with @code{target("sse3")} can inline a function | |
7560 | with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. | |
7561 | ||
7562 | Besides the basic rule, when a function specifies | |
7563 | @code{target("arch=@var{ARCH}")} or @code{target("tune=@var{TUNE}")} | |
7564 | attribute, the inlining rule will be different. It allows inlining of | |
7565 | a function with default @option{-march=x86-64} and | |
7566 | @option{-mtune=generic} specified, or a function that has a subset | |
7567 | of ISA features and marked with always_inline. | |
7568 | ||
d77de738 ML |
7569 | @node Xstormy16 Function Attributes |
7570 | @subsection Xstormy16 Function Attributes | |
7571 | ||
7572 | These function attributes are supported by the Xstormy16 back end: | |
7573 | ||
7574 | @table @code | |
d77de738 | 7575 | @cindex @code{interrupt} function attribute, Xstormy16 |
f33d7a88 | 7576 | @item interrupt |
d77de738 ML |
7577 | Use this attribute to indicate |
7578 | that the specified function is an interrupt handler. The compiler generates | |
7579 | function entry and exit sequences suitable for use in an interrupt handler | |
7580 | when this attribute is present. | |
7581 | @end table | |
7582 | ||
7583 | @node Variable Attributes | |
7584 | @section Specifying Attributes of Variables | |
7585 | @cindex attribute of variables | |
7586 | @cindex variable attributes | |
7587 | ||
837a12a2 | 7588 | You can use attributes to specify special properties |
d77de738 | 7589 | of variables, function parameters, or structure, union, and, in C++, class |
837a12a2 | 7590 | members. Some attributes are currently |
d77de738 ML |
7591 | defined generically for variables. Other attributes are defined for |
7592 | variables on particular target systems. Other attributes are available | |
7593 | for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}), | |
7594 | enumerators (@pxref{Enumerator Attributes}), statements | |
7595 | (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). | |
7596 | Other front ends might define more attributes | |
7597 | (@pxref{C++ Extensions,,Extensions to the C++ Language}). | |
7598 | ||
837a12a2 SL |
7599 | GCC provides two different ways to specify attributes: the traditional |
7600 | GNU syntax using @samp{__attribute__ ((...))} annotations, and the | |
7601 | newer standard C and C++ syntax using @samp{[[...]]} with the | |
7602 | @samp{gnu::} prefix on attribute names. Note that the exact rules for | |
7603 | placement of attributes in your source code are different depending on | |
7604 | which syntax you use. @xref{Attribute Syntax}, for details. | |
d77de738 ML |
7605 | |
7606 | @menu | |
7607 | * Common Variable Attributes:: | |
7608 | * ARC Variable Attributes:: | |
7609 | * AVR Variable Attributes:: | |
7610 | * Blackfin Variable Attributes:: | |
7611 | * H8/300 Variable Attributes:: | |
7612 | * IA-64 Variable Attributes:: | |
7613 | * LoongArch Variable Attributes:: | |
7614 | * M32R/D Variable Attributes:: | |
d77de738 ML |
7615 | * Microsoft Windows Variable Attributes:: |
7616 | * MSP430 Variable Attributes:: | |
7617 | * Nvidia PTX Variable Attributes:: | |
7618 | * PowerPC Variable Attributes:: | |
7619 | * RL78 Variable Attributes:: | |
7620 | * V850 Variable Attributes:: | |
7621 | * x86 Variable Attributes:: | |
7622 | * Xstormy16 Variable Attributes:: | |
7623 | @end menu | |
7624 | ||
7625 | @node Common Variable Attributes | |
7626 | @subsection Common Variable Attributes | |
7627 | ||
7628 | The following attributes are supported on most targets. | |
7629 | ||
7630 | @table @code | |
7631 | ||
d77de738 | 7632 | @cindex @code{alias} variable attribute |
f33d7a88 | 7633 | @item alias ("@var{target}") |
d77de738 ML |
7634 | The @code{alias} variable attribute causes the declaration to be emitted |
7635 | as an alias for another symbol known as an @dfn{alias target}. Except | |
7636 | for top-level qualifiers the alias target must have the same type as | |
7637 | the alias. For instance, the following | |
7638 | ||
7639 | @smallexample | |
7640 | int var_target; | |
7641 | extern int __attribute__ ((alias ("var_target"))) var_alias; | |
7642 | @end smallexample | |
7643 | ||
7644 | @noindent | |
7645 | defines @code{var_alias} to be an alias for the @code{var_target} variable. | |
7646 | ||
7647 | It is an error if the alias target is not defined in the same translation | |
7648 | unit as the alias. | |
7649 | ||
7650 | Note that in the absence of the attribute GCC assumes that distinct | |
7651 | declarations with external linkage denote distinct objects. Using both | |
7652 | the alias and the alias target to access the same object is undefined | |
7653 | in a translation unit without a declaration of the alias with the attribute. | |
7654 | ||
7655 | This attribute requires assembler and object file support, and may not be | |
7656 | available on all targets. | |
7657 | ||
7658 | @cindex @code{aligned} variable attribute | |
7659 | @item aligned | |
7660 | @itemx aligned (@var{alignment}) | |
7661 | The @code{aligned} attribute specifies a minimum alignment for the variable | |
7662 | or structure field, measured in bytes. When specified, @var{alignment} must | |
7663 | be an integer constant power of 2. Specifying no @var{alignment} argument | |
7664 | implies the maximum alignment for the target, which is often, but by no | |
7665 | means always, 8 or 16 bytes. | |
7666 | ||
7667 | For example, the declaration: | |
7668 | ||
7669 | @smallexample | |
7670 | int x __attribute__ ((aligned (16))) = 0; | |
7671 | @end smallexample | |
7672 | ||
7673 | @noindent | |
7674 | causes the compiler to allocate the global variable @code{x} on a | |
7675 | 16-byte boundary. On a 68040, this could be used in conjunction with | |
7676 | an @code{asm} expression to access the @code{move16} instruction which | |
7677 | requires 16-byte aligned operands. | |
7678 | ||
7679 | You can also specify the alignment of structure fields. For example, to | |
7680 | create a double-word aligned @code{int} pair, you could write: | |
7681 | ||
7682 | @smallexample | |
7683 | struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; | |
7684 | @end smallexample | |
7685 | ||
7686 | @noindent | |
7687 | This is an alternative to creating a union with a @code{double} member, | |
7688 | which forces the union to be double-word aligned. | |
7689 | ||
7690 | As in the preceding examples, you can explicitly specify the alignment | |
7691 | (in bytes) that you wish the compiler to use for a given variable or | |
7692 | structure field. Alternatively, you can leave out the alignment factor | |
7693 | and just ask the compiler to align a variable or field to the | |
7694 | default alignment for the target architecture you are compiling for. | |
7695 | The default alignment is sufficient for all scalar types, but may not be | |
7696 | enough for all vector types on a target that supports vector operations. | |
7697 | The default alignment is fixed for a particular target ABI. | |
7698 | ||
7699 | GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, | |
7700 | which is the largest alignment ever used for any data type on the | |
7701 | target machine you are compiling for. For example, you could write: | |
7702 | ||
7703 | @smallexample | |
7704 | short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); | |
7705 | @end smallexample | |
7706 | ||
7707 | The compiler automatically sets the alignment for the declared | |
7708 | variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can | |
7709 | often make copy operations more efficient, because the compiler can | |
7710 | use whatever instructions copy the biggest chunks of memory when | |
7711 | performing copies to or from the variables or fields that you have | |
7712 | aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} | |
7713 | may change depending on command-line options. | |
7714 | ||
7715 | When used on a struct, or struct member, the @code{aligned} attribute can | |
7716 | only increase the alignment; in order to decrease it, the @code{packed} | |
7717 | attribute must be specified as well. When used as part of a typedef, the | |
7718 | @code{aligned} attribute can both increase and decrease alignment, and | |
7719 | specifying the @code{packed} attribute generates a warning. | |
7720 | ||
7721 | Note that the effectiveness of @code{aligned} attributes for static | |
7722 | variables may be limited by inherent limitations in the system linker | |
7723 | and/or object file format. On some systems, the linker is | |
7724 | only able to arrange for variables to be aligned up to a certain maximum | |
7725 | alignment. (For some linkers, the maximum supported alignment may | |
7726 | be very very small.) If your linker is only able to align variables | |
7727 | up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} | |
7728 | in an @code{__attribute__} still only provides you with 8-byte | |
7729 | alignment. See your linker documentation for further information. | |
7730 | ||
7731 | Stack variables are not affected by linker restrictions; GCC can properly | |
7732 | align them on any target. | |
7733 | ||
7734 | The @code{aligned} attribute can also be used for functions | |
7735 | (@pxref{Common Function Attributes}.) | |
7736 | ||
7737 | @cindex @code{warn_if_not_aligned} variable attribute | |
7738 | @item warn_if_not_aligned (@var{alignment}) | |
7739 | This attribute specifies a threshold for the structure field, measured | |
7740 | in bytes. If the structure field is aligned below the threshold, a | |
7741 | warning will be issued. For example, the declaration: | |
7742 | ||
7743 | @smallexample | |
7744 | struct foo | |
7745 | @{ | |
7746 | int i1; | |
7747 | int i2; | |
7748 | unsigned long long x __attribute__ ((warn_if_not_aligned (16))); | |
7749 | @}; | |
7750 | @end smallexample | |
7751 | ||
7752 | @noindent | |
7753 | causes the compiler to issue an warning on @code{struct foo}, like | |
7754 | @samp{warning: alignment 8 of 'struct foo' is less than 16}. | |
7755 | The compiler also issues a warning, like @samp{warning: 'x' offset | |
7756 | 8 in 'struct foo' isn't aligned to 16}, when the structure field has | |
7757 | the misaligned offset: | |
7758 | ||
7759 | @smallexample | |
7760 | struct __attribute__ ((aligned (16))) foo | |
7761 | @{ | |
7762 | int i1; | |
7763 | int i2; | |
7764 | unsigned long long x __attribute__ ((warn_if_not_aligned (16))); | |
7765 | @}; | |
7766 | @end smallexample | |
7767 | ||
7768 | This warning can be disabled by @option{-Wno-if-not-aligned}. | |
7769 | The @code{warn_if_not_aligned} attribute can also be used for types | |
7770 | (@pxref{Common Type Attributes}.) | |
7771 | ||
7772 | @cindex @code{strict_flex_array} variable attribute | |
7773 | @item strict_flex_array (@var{level}) | |
7774 | The @code{strict_flex_array} attribute should be attached to the trailing | |
7775 | array field of a structure. It controls when to treat the trailing array | |
7776 | field of a structure as a flexible array member for the purposes of accessing | |
7777 | the elements of such an array. | |
7778 | @var{level} must be an integer betwen 0 to 3. | |
7779 | ||
7780 | @var{level}=0 is the least strict level, all trailing arrays of structures | |
7781 | are treated as flexible array members. @var{level}=3 is the strictest level, | |
7782 | only when the trailing array is declared as a flexible array member per C99 | |
7783 | standard onwards (@samp{[]}), it is treated as a flexible array member. | |
7784 | ||
7785 | There are two more levels in between 0 and 3, which are provided to support | |
7786 | older codes that use GCC zero-length array extension (@samp{[0]}) or one-element | |
7787 | array as flexible array members (@samp{[1]}): | |
7788 | When @var{level} is 1, the trailing array is treated as a flexible array member | |
7789 | when it is declared as either @samp{[]}, @samp{[0]}, or @samp{[1]}; | |
7790 | When @var{level} is 2, the trailing array is treated as a flexible array member | |
7791 | when it is declared as either @samp{[]}, or @samp{[0]}. | |
7792 | ||
7793 | This attribute can be used with or without the @option{-fstrict-flex-arrays}. | |
7794 | When both the attribute and the option present at the same time, the level of | |
7795 | the strictness for the specific trailing array field is determined by the | |
7796 | attribute. | |
7797 | ||
f33d7a88 | 7798 | @cindex @code{alloc_size} variable attribute |
d77de738 ML |
7799 | @item alloc_size (@var{position}) |
7800 | @itemx alloc_size (@var{position-1}, @var{position-2}) | |
d77de738 ML |
7801 | The @code{alloc_size} variable attribute may be applied to the declaration |
7802 | of a pointer to a function that returns a pointer and takes at least one | |
7803 | argument of an integer type. It indicates that the returned pointer points | |
7804 | to an object whose size is given by the function argument at @var{position}, | |
7805 | or by the product of the arguments at @var{position-1} and @var{position-2}. | |
7806 | Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other | |
7807 | sizes are diagnosed when detected. GCC uses this information to improve | |
7808 | the results of @code{__builtin_object_size}. | |
7809 | ||
7810 | For instance, the following declarations | |
7811 | ||
7812 | @smallexample | |
7813 | typedef __attribute__ ((alloc_size (1, 2))) void* | |
7814 | (*calloc_ptr) (size_t, size_t); | |
7815 | typedef __attribute__ ((alloc_size (1))) void* | |
7816 | (*malloc_ptr) (size_t); | |
7817 | @end smallexample | |
7818 | ||
7819 | @noindent | |
7820 | specify that @code{calloc_ptr} is a pointer of a function that, like | |
7821 | the standard C function @code{calloc}, returns an object whose size | |
7822 | is given by the product of arguments 1 and 2, and similarly, that | |
7823 | @code{malloc_ptr}, like the standard C function @code{malloc}, | |
7824 | returns an object whose size is given by argument 1 to the function. | |
7825 | ||
d77de738 | 7826 | @cindex @code{cleanup} variable attribute |
f33d7a88 | 7827 | @item cleanup (@var{cleanup_function}) |
d77de738 ML |
7828 | The @code{cleanup} attribute runs a function when the variable goes |
7829 | out of scope. This attribute can only be applied to auto function | |
7830 | scope variables; it may not be applied to parameters or variables | |
7831 | with static storage duration. The function must take one parameter, | |
7832 | a pointer to a type compatible with the variable. The return value | |
7833 | of the function (if any) is ignored. | |
7834 | ||
7835 | If @option{-fexceptions} is enabled, then @var{cleanup_function} | |
7836 | is run during the stack unwinding that happens during the | |
7837 | processing of the exception. Note that the @code{cleanup} attribute | |
7838 | does not allow the exception to be caught, only to perform an action. | |
7839 | It is undefined what happens if @var{cleanup_function} does not | |
7840 | return normally. | |
7841 | ||
d77de738 ML |
7842 | @cindex @code{common} variable attribute |
7843 | @cindex @code{nocommon} variable attribute | |
7844 | @opindex fcommon | |
7845 | @opindex fno-common | |
f33d7a88 AA |
7846 | @item common |
7847 | @itemx nocommon | |
d77de738 ML |
7848 | The @code{common} attribute requests GCC to place a variable in |
7849 | ``common'' storage. The @code{nocommon} attribute requests the | |
7850 | opposite---to allocate space for it directly. | |
7851 | ||
7852 | These attributes override the default chosen by the | |
7853 | @option{-fno-common} and @option{-fcommon} flags respectively. | |
7854 | ||
f33d7a88 | 7855 | @cindex @code{copy} variable attribute |
d77de738 ML |
7856 | @item copy |
7857 | @itemx copy (@var{variable}) | |
d77de738 ML |
7858 | The @code{copy} attribute applies the set of attributes with which |
7859 | @var{variable} has been declared to the declaration of the variable | |
7860 | to which the attribute is applied. The attribute is designed for | |
7861 | libraries that define aliases that are expected to specify the same | |
7862 | set of attributes as the aliased symbols. The @code{copy} attribute | |
7863 | can be used with variables, functions or types. However, the kind | |
7864 | of symbol to which the attribute is applied (either varible or | |
7865 | function) must match the kind of symbol to which the argument refers. | |
7866 | The @code{copy} attribute copies only syntactic and semantic attributes | |
7867 | but not attributes that affect a symbol's linkage or visibility such as | |
7868 | @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} | |
7869 | attribute is also not copied. @xref{Common Function Attributes}. | |
7870 | @xref{Common Type Attributes}. | |
7871 | ||
f33d7a88 | 7872 | @cindex @code{deprecated} variable attribute |
d77de738 ML |
7873 | @item deprecated |
7874 | @itemx deprecated (@var{msg}) | |
d77de738 ML |
7875 | The @code{deprecated} attribute results in a warning if the variable |
7876 | is used anywhere in the source file. This is useful when identifying | |
7877 | variables that are expected to be removed in a future version of a | |
7878 | program. The warning also includes the location of the declaration | |
7879 | of the deprecated variable, to enable users to easily find further | |
7880 | information about why the variable is deprecated, or what they should | |
7881 | do instead. Note that the warning only occurs for uses: | |
7882 | ||
7883 | @smallexample | |
7884 | extern int old_var __attribute__ ((deprecated)); | |
7885 | extern int old_var; | |
7886 | int new_fn () @{ return old_var; @} | |
7887 | @end smallexample | |
7888 | ||
7889 | @noindent | |
7890 | results in a warning on line 3 but not line 2. The optional @var{msg} | |
7891 | argument, which must be a string, is printed in the warning if | |
7892 | present. | |
7893 | ||
7894 | The @code{deprecated} attribute can also be used for functions and | |
7895 | types (@pxref{Common Function Attributes}, | |
7896 | @pxref{Common Type Attributes}). | |
7897 | ||
7898 | The message attached to the attribute is affected by the setting of | |
7899 | the @option{-fmessage-length} option. | |
7900 | ||
f33d7a88 | 7901 | @cindex @code{unavailable} variable attribute |
d77de738 ML |
7902 | @item unavailable |
7903 | @itemx unavailable (@var{msg}) | |
d77de738 ML |
7904 | The @code{unavailable} attribute indicates that the variable so marked |
7905 | is not available, if it is used anywhere in the source file. It behaves | |
7906 | in the same manner as the @code{deprecated} attribute except that the | |
7907 | compiler will emit an error rather than a warning. | |
7908 | ||
7909 | It is expected that items marked as @code{deprecated} will eventually be | |
7910 | withdrawn from interfaces, and then become unavailable. This attribute | |
7911 | allows for marking them appropriately. | |
7912 | ||
7913 | The @code{unavailable} attribute can also be used for functions and | |
7914 | types (@pxref{Common Function Attributes}, | |
7915 | @pxref{Common Type Attributes}). | |
7916 | ||
d77de738 | 7917 | @cindex @code{mode} variable attribute |
f33d7a88 | 7918 | @item mode (@var{mode}) |
d77de738 ML |
7919 | This attribute specifies the data type for the declaration---whichever |
7920 | type corresponds to the mode @var{mode}. This in effect lets you | |
7921 | request an integer or floating-point type according to its width. | |
7922 | ||
7923 | @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, | |
7924 | for a list of the possible keywords for @var{mode}. | |
7925 | You may also specify a mode of @code{byte} or @code{__byte__} to | |
7926 | indicate the mode corresponding to a one-byte integer, @code{word} or | |
7927 | @code{__word__} for the mode of a one-word integer, and @code{pointer} | |
7928 | or @code{__pointer__} for the mode used to represent pointers. | |
7929 | ||
d77de738 | 7930 | @cindex @code{nonstring} variable attribute |
f33d7a88 | 7931 | @item nonstring |
d77de738 ML |
7932 | The @code{nonstring} variable attribute specifies that an object or member |
7933 | declaration with type array of @code{char}, @code{signed char}, or | |
7934 | @code{unsigned char}, or pointer to such a type is intended to store | |
7935 | character arrays that do not necessarily contain a terminating @code{NUL}. | |
7936 | This is useful in detecting uses of such arrays or pointers with functions | |
7937 | that expect @code{NUL}-terminated strings, and to avoid warnings when such | |
7938 | an array or pointer is used as an argument to a bounded string manipulation | |
7939 | function such as @code{strncpy}. For example, without the attribute, GCC | |
7940 | will issue a warning for the @code{strncpy} call below because it may | |
7941 | truncate the copy without appending the terminating @code{NUL} character. | |
7942 | Using the attribute makes it possible to suppress the warning. However, | |
7943 | when the array is declared with the attribute the call to @code{strlen} is | |
7944 | diagnosed because when the array doesn't contain a @code{NUL}-terminated | |
7945 | string the call is undefined. To copy, compare, of search non-string | |
7946 | character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, | |
7947 | and other functions that operate on arrays of bytes. In addition, | |
7948 | calling @code{strnlen} and @code{strndup} with such arrays is safe | |
7949 | provided a suitable bound is specified, and not diagnosed. | |
7950 | ||
7951 | @smallexample | |
7952 | struct Data | |
7953 | @{ | |
7954 | char name [32] __attribute__ ((nonstring)); | |
7955 | @}; | |
7956 | ||
7957 | int f (struct Data *pd, const char *s) | |
7958 | @{ | |
7959 | strncpy (pd->name, s, sizeof pd->name); | |
7960 | @dots{} | |
7961 | return strlen (pd->name); // unsafe, gets a warning | |
7962 | @} | |
7963 | @end smallexample | |
7964 | ||
d77de738 | 7965 | @cindex @code{packed} variable attribute |
f33d7a88 | 7966 | @item packed |
d77de738 ML |
7967 | The @code{packed} attribute specifies that a structure member should have |
7968 | the smallest possible alignment---one bit for a bit-field and one byte | |
7969 | otherwise, unless a larger value is specified with the @code{aligned} | |
7970 | attribute. The attribute does not apply to non-member objects. | |
7971 | ||
7972 | For example in the structure below, the member array @code{x} is packed | |
7973 | so that it immediately follows @code{a} with no intervening padding: | |
7974 | ||
7975 | @smallexample | |
7976 | struct foo | |
7977 | @{ | |
7978 | char a; | |
7979 | int x[2] __attribute__ ((packed)); | |
7980 | @}; | |
7981 | @end smallexample | |
7982 | ||
7983 | @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the | |
7984 | @code{packed} attribute on bit-fields of type @code{char}. This has | |
7985 | been fixed in GCC 4.4 but the change can lead to differences in the | |
7986 | structure layout. See the documentation of | |
7987 | @option{-Wpacked-bitfield-compat} for more information. | |
7988 | ||
d77de738 | 7989 | @cindex @code{section} variable attribute |
f33d7a88 | 7990 | @item section ("@var{section-name}") |
d77de738 ML |
7991 | Normally, the compiler places the objects it generates in sections like |
7992 | @code{data} and @code{bss}. Sometimes, however, you need additional sections, | |
7993 | or you need certain particular variables to appear in special sections, | |
7994 | for example to map to special hardware. The @code{section} | |
7995 | attribute specifies that a variable (or function) lives in a particular | |
7996 | section. For example, this small program uses several specific section names: | |
7997 | ||
7998 | @smallexample | |
7999 | struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; | |
8000 | struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; | |
8001 | char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; | |
8002 | int init_data __attribute__ ((section ("INITDATA"))); | |
8003 | ||
8004 | main() | |
8005 | @{ | |
8006 | /* @r{Initialize stack pointer} */ | |
8007 | init_sp (stack + sizeof (stack)); | |
8008 | ||
8009 | /* @r{Initialize initialized data} */ | |
8010 | memcpy (&init_data, &data, &edata - &data); | |
8011 | ||
8012 | /* @r{Turn on the serial ports} */ | |
8013 | init_duart (&a); | |
8014 | init_duart (&b); | |
8015 | @} | |
8016 | @end smallexample | |
8017 | ||
8018 | @noindent | |
8019 | Use the @code{section} attribute with | |
8020 | @emph{global} variables and not @emph{local} variables, | |
8021 | as shown in the example. | |
8022 | ||
8023 | You may use the @code{section} attribute with initialized or | |
8024 | uninitialized global variables but the linker requires | |
8025 | each object be defined once, with the exception that uninitialized | |
8026 | variables tentatively go in the @code{common} (or @code{bss}) section | |
8027 | and can be multiply ``defined''. Using the @code{section} attribute | |
8028 | changes what section the variable goes into and may cause the | |
8029 | linker to issue an error if an uninitialized variable has multiple | |
8030 | definitions. You can force a variable to be initialized with the | |
8031 | @option{-fno-common} flag or the @code{nocommon} attribute. | |
8032 | ||
8033 | Some file formats do not support arbitrary sections so the @code{section} | |
8034 | attribute is not available on all platforms. | |
8035 | If you need to map the entire contents of a module to a particular | |
8036 | section, consider using the facilities of the linker instead. | |
8037 | ||
d77de738 | 8038 | @cindex @code{tls_model} variable attribute |
f33d7a88 | 8039 | @item tls_model ("@var{tls_model}") |
d77de738 ML |
8040 | The @code{tls_model} attribute sets thread-local storage model |
8041 | (@pxref{Thread-Local}) of a particular @code{__thread} variable, | |
8042 | overriding @option{-ftls-model=} command-line switch on a per-variable | |
8043 | basis. | |
8044 | The @var{tls_model} argument should be one of @code{global-dynamic}, | |
8045 | @code{local-dynamic}, @code{initial-exec} or @code{local-exec}. | |
8046 | ||
8047 | Not all targets support this attribute. | |
8048 | ||
d77de738 | 8049 | @cindex @code{unused} variable attribute |
f33d7a88 | 8050 | @item unused |
d77de738 ML |
8051 | This attribute, attached to a variable or structure field, means that |
8052 | the variable or field is meant to be possibly unused. GCC does not | |
8053 | produce a warning for this variable or field. | |
8054 | ||
d77de738 | 8055 | @cindex @code{used} variable attribute |
f33d7a88 | 8056 | @item used |
d77de738 ML |
8057 | This attribute, attached to a variable with static storage, means that |
8058 | the variable must be emitted even if it appears that the variable is not | |
8059 | referenced. | |
8060 | ||
8061 | When applied to a static data member of a C++ class template, the | |
8062 | attribute also means that the member is instantiated if the | |
8063 | class itself is instantiated. | |
8064 | ||
d77de738 | 8065 | @cindex @code{retain} variable attribute |
f33d7a88 | 8066 | @item retain |
d77de738 ML |
8067 | For ELF targets that support the GNU or FreeBSD OSABIs, this attribute |
8068 | will save the variable from linker garbage collection. To support | |
8069 | this behavior, variables that have not been placed in specific sections | |
8070 | (e.g. by the @code{section} attribute, or the @code{-fdata-sections} option), | |
8071 | will be placed in new, unique sections. | |
8072 | ||
8073 | This additional functionality requires Binutils version 2.36 or later. | |
8074 | ||
d77de738 | 8075 | @cindex @code{uninitialized} variable attribute |
f33d7a88 | 8076 | @item uninitialized |
d77de738 ML |
8077 | This attribute, attached to a variable with automatic storage, means that |
8078 | the variable should not be automatically initialized by the compiler when | |
8079 | the option @code{-ftrivial-auto-var-init} presents. | |
8080 | ||
8081 | With the option @code{-ftrivial-auto-var-init}, all the automatic variables | |
8082 | that do not have explicit initializers will be initialized by the compiler. | |
8083 | These additional compiler initializations might incur run-time overhead, | |
8084 | sometimes dramatically. This attribute can be used to mark some variables | |
8085 | to be excluded from such automatical initialization in order to reduce runtime | |
8086 | overhead. | |
8087 | ||
8088 | This attribute has no effect when the option @code{-ftrivial-auto-var-init} | |
8089 | does not present. | |
8090 | ||
d77de738 | 8091 | @cindex @code{vector_size} variable attribute |
f33d7a88 | 8092 | @item vector_size (@var{bytes}) |
d77de738 ML |
8093 | This attribute specifies the vector size for the type of the declared |
8094 | variable, measured in bytes. The type to which it applies is known as | |
8095 | the @dfn{base type}. The @var{bytes} argument must be a positive | |
8096 | power-of-two multiple of the base type size. For example, the declaration: | |
8097 | ||
8098 | @smallexample | |
8099 | int foo __attribute__ ((vector_size (16))); | |
8100 | @end smallexample | |
8101 | ||
8102 | @noindent | |
8103 | causes the compiler to set the mode for @code{foo}, to be 16 bytes, | |
8104 | divided into @code{int} sized units. Assuming a 32-bit @code{int}, | |
8105 | @code{foo}'s type is a vector of four units of four bytes each, and | |
8106 | the corresponding mode of @code{foo} is @code{V4SI}. | |
8107 | @xref{Vector Extensions}, for details of manipulating vector variables. | |
8108 | ||
8109 | This attribute is only applicable to integral and floating scalars, | |
8110 | although arrays, pointers, and function return values are allowed in | |
8111 | conjunction with this construct. | |
8112 | ||
8113 | Aggregates with this attribute are invalid, even if they are of the same | |
8114 | size as a corresponding scalar. For example, the declaration: | |
8115 | ||
8116 | @smallexample | |
8117 | struct S @{ int a; @}; | |
8118 | struct S __attribute__ ((vector_size (16))) foo; | |
8119 | @end smallexample | |
8120 | ||
8121 | @noindent | |
8122 | is invalid even if the size of the structure is the same as the size of | |
8123 | the @code{int}. | |
8124 | ||
d77de738 | 8125 | @cindex @code{visibility} variable attribute |
f33d7a88 | 8126 | @item visibility ("@var{visibility_type}") |
d77de738 ML |
8127 | This attribute affects the linkage of the declaration to which it is attached. |
8128 | The @code{visibility} attribute is described in | |
8129 | @ref{Common Function Attributes}. | |
8130 | ||
d77de738 | 8131 | @cindex @code{weak} variable attribute |
f33d7a88 | 8132 | @item weak |
d77de738 ML |
8133 | The @code{weak} attribute is described in |
8134 | @ref{Common Function Attributes}. | |
8135 | ||
d77de738 | 8136 | @cindex @code{noinit} variable attribute |
f33d7a88 | 8137 | @item noinit |
d77de738 ML |
8138 | Any data with the @code{noinit} attribute will not be initialized by |
8139 | the C runtime startup code, or the program loader. Not initializing | |
8140 | data in this way can reduce program startup times. | |
8141 | ||
8142 | This attribute is specific to ELF targets and relies on the linker | |
8143 | script to place sections with the @code{.noinit} prefix in the right | |
8144 | location. | |
8145 | ||
d77de738 | 8146 | @cindex @code{persistent} variable attribute |
f33d7a88 | 8147 | @item persistent |
d77de738 ML |
8148 | Any data with the @code{persistent} attribute will not be initialized by |
8149 | the C runtime startup code, but will be initialized by the program | |
8150 | loader. This enables the value of the variable to @samp{persist} | |
8151 | between processor resets. | |
8152 | ||
8153 | This attribute is specific to ELF targets and relies on the linker | |
8154 | script to place the sections with the @code{.persistent} prefix in the | |
8155 | right location. Specifically, some type of non-volatile, writeable | |
8156 | memory is required. | |
8157 | ||
eee13a37 RB |
8158 | @cindex @code{no_icf} variable attribute |
8159 | @item no_icf | |
8160 | This variable attribute prevents a variable from being merged with another | |
8161 | equivalent variable. | |
8162 | ||
d77de738 | 8163 | @cindex @code{objc_nullability} variable attribute |
f33d7a88 | 8164 | @item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)} |
d77de738 ML |
8165 | This attribute applies to pointer variables only. It allows marking the |
8166 | pointer with one of four possible values describing the conditions under | |
8167 | which the pointer might have a @code{nil} value. In most cases, the | |
8168 | attribute is intended to be an internal representation for property and | |
8169 | method nullability (specified by language keywords); it is not recommended | |
8170 | to use it directly. | |
8171 | ||
8172 | When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is | |
8173 | known about the conditions in which the pointer might be @code{nil}. Making | |
8174 | this state specific serves to avoid false positives in diagnostics. | |
8175 | ||
8176 | When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has | |
8177 | no meaning if it is @code{nil} and thus the compiler is free to emit | |
8178 | diagnostics if it can be determined that the value will be @code{nil}. | |
8179 | ||
8180 | When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might | |
8181 | be @code{nil} and carry meaning as such. | |
8182 | ||
8183 | When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in | |
8184 | the context of property attribute lists) this describes the case in which a | |
8185 | property setter may take the value @code{nil} (which perhaps causes the | |
8186 | property to be reset in some manner to a default) but for which the property | |
8187 | getter will never validly return @code{nil}. | |
8188 | ||
8189 | @end table | |
8190 | ||
8191 | @node ARC Variable Attributes | |
8192 | @subsection ARC Variable Attributes | |
8193 | ||
8194 | @table @code | |
d77de738 | 8195 | @cindex @code{aux} variable attribute, ARC |
f33d7a88 | 8196 | @item aux |
d77de738 ML |
8197 | The @code{aux} attribute is used to directly access the ARC's |
8198 | auxiliary register space from C. The auxilirary register number is | |
8199 | given via attribute argument. | |
8200 | ||
8201 | @end table | |
8202 | ||
8203 | @node AVR Variable Attributes | |
8204 | @subsection AVR Variable Attributes | |
8205 | ||
8206 | @table @code | |
d77de738 | 8207 | @cindex @code{progmem} variable attribute, AVR |
f33d7a88 | 8208 | @item progmem |
d77de738 ML |
8209 | The @code{progmem} attribute is used on the AVR to place read-only |
8210 | data in the non-volatile program memory (flash). The @code{progmem} | |
8211 | attribute accomplishes this by putting respective variables into a | |
8212 | section whose name starts with @code{.progmem}. | |
8213 | ||
8214 | This attribute works similar to the @code{section} attribute | |
8215 | but adds additional checking. | |
8216 | ||
8217 | @table @asis | |
8218 | @item @bullet{} Ordinary AVR cores with 32 general purpose registers: | |
8219 | @code{progmem} affects the location | |
8220 | of the data but not how this data is accessed. | |
8221 | In order to read data located with the @code{progmem} attribute | |
8222 | (inline) assembler must be used. | |
8223 | @smallexample | |
1be72408 | 8224 | /* Use custom macros from AVR-LibC */ |
d77de738 ML |
8225 | #include <avr/pgmspace.h> |
8226 | ||
8227 | /* Locate var in flash memory */ | |
8228 | const int var[2] PROGMEM = @{ 1, 2 @}; | |
8229 | ||
8230 | int read_var (int i) | |
8231 | @{ | |
8232 | /* Access var[] by accessor macro from avr/pgmspace.h */ | |
8233 | return (int) pgm_read_word (& var[i]); | |
8234 | @} | |
8235 | @end smallexample | |
8236 | ||
8237 | AVR is a Harvard architecture processor and data and read-only data | |
8238 | normally resides in the data memory (RAM). | |
8239 | ||
8240 | See also the @ref{AVR Named Address Spaces} section for | |
8241 | an alternate way to locate and access data in flash memory. | |
8242 | ||
8243 | @item @bullet{} AVR cores with flash memory visible in the RAM address range: | |
8244 | On such devices, there is no need for attribute @code{progmem} or | |
8245 | @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all. | |
8246 | Just use standard C / C++. The compiler will generate @code{LD*} | |
8247 | instructions. As flash memory is visible in the RAM address range, | |
8248 | and the default linker script does @emph{not} locate @code{.rodata} in | |
8249 | RAM, no special features are needed in order not to waste RAM for | |
8250 | read-only data or to read from flash. You might even get slightly better | |
8251 | performance by | |
8252 | avoiding @code{progmem} and @code{__flash}. This applies to devices from | |
8253 | families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for | |
8254 | an overview. | |
8255 | ||
8256 | @item @bullet{} Reduced AVR Tiny cores like ATtiny40: | |
8257 | The compiler adds @code{0x4000} | |
8258 | to the addresses of objects and declarations in @code{progmem} and locates | |
8259 | the objects in flash memory, namely in section @code{.progmem.data}. | |
8260 | The offset is needed because the flash memory is visible in the RAM | |
8261 | address space starting at address @code{0x4000}. | |
8262 | ||
8263 | Data in @code{progmem} can be accessed by means of ordinary C@tie{}code, | |
8264 | no special functions or macros are needed. | |
8265 | ||
8266 | @smallexample | |
8267 | /* var is located in flash memory */ | |
8268 | extern const int var[2] __attribute__((progmem)); | |
8269 | ||
8270 | int read_var (int i) | |
8271 | @{ | |
8272 | return var[i]; | |
8273 | @} | |
8274 | @end smallexample | |
8275 | ||
8276 | Please notice that on these devices, there is no need for @code{progmem} | |
8277 | at all. | |
8278 | ||
8279 | @end table | |
8280 | ||
f33d7a88 | 8281 | @cindex @code{io} variable attribute, AVR |
d77de738 ML |
8282 | @item io |
8283 | @itemx io (@var{addr}) | |
d77de738 ML |
8284 | Variables with the @code{io} attribute are used to address |
8285 | memory-mapped peripherals in the io address range. | |
8286 | If an address is specified, the variable | |
8287 | is assigned that address, and the value is interpreted as an | |
8288 | address in the data address space. | |
8289 | Example: | |
8290 | ||
8291 | @smallexample | |
8292 | volatile int porta __attribute__((io (0x22))); | |
8293 | @end smallexample | |
8294 | ||
8295 | The address specified in the address in the data address range. | |
8296 | ||
8297 | Otherwise, the variable it is not assigned an address, but the | |
8298 | compiler will still use in/out instructions where applicable, | |
8299 | assuming some other module assigns an address in the io address range. | |
8300 | Example: | |
8301 | ||
8302 | @smallexample | |
8303 | extern volatile int porta __attribute__((io)); | |
8304 | @end smallexample | |
8305 | ||
f33d7a88 | 8306 | @cindex @code{io_low} variable attribute, AVR |
d77de738 ML |
8307 | @item io_low |
8308 | @itemx io_low (@var{addr}) | |
d77de738 ML |
8309 | This is like the @code{io} attribute, but additionally it informs the |
8310 | compiler that the object lies in the lower half of the I/O area, | |
8311 | allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} | |
8312 | instructions. | |
8313 | ||
f33d7a88 | 8314 | @cindex @code{address} variable attribute, AVR |
d77de738 ML |
8315 | @item address |
8316 | @itemx address (@var{addr}) | |
d77de738 ML |
8317 | Variables with the @code{address} attribute are used to address |
8318 | memory-mapped peripherals that may lie outside the io address range. | |
8319 | ||
8320 | @smallexample | |
8321 | volatile int porta __attribute__((address (0x600))); | |
8322 | @end smallexample | |
8323 | ||
d77de738 | 8324 | @cindex @code{absdata} variable attribute, AVR |
f33d7a88 | 8325 | @item absdata |
d77de738 ML |
8326 | Variables in static storage and with the @code{absdata} attribute can |
8327 | be accessed by the @code{LDS} and @code{STS} instructions which take | |
8328 | absolute addresses. | |
8329 | ||
8330 | @itemize @bullet | |
8331 | @item | |
8332 | This attribute is only supported for the reduced AVR Tiny core | |
8333 | like ATtiny40. | |
8334 | ||
8335 | @item | |
8336 | You must make sure that respective data is located in the | |
8337 | address range @code{0x40}@dots{}@code{0xbf} accessible by | |
8338 | @code{LDS} and @code{STS}. One way to achieve this as an | |
8339 | appropriate linker description file. | |
8340 | ||
8341 | @item | |
8342 | If the location does not fit the address range of @code{LDS} | |
8343 | and @code{STS}, there is currently (Binutils 2.26) just an unspecific | |
8344 | warning like | |
8345 | @quotation | |
8346 | @code{module.cc:(.text+0x1c): warning: internal error: out of range error} | |
8347 | @end quotation | |
8348 | ||
8349 | @end itemize | |
8350 | ||
8351 | See also the @option{-mabsdata} @ref{AVR Options,command-line option}. | |
8352 | ||
8353 | @end table | |
8354 | ||
8355 | @node Blackfin Variable Attributes | |
8356 | @subsection Blackfin Variable Attributes | |
8357 | ||
8358 | Three attributes are currently defined for the Blackfin. | |
8359 | ||
8360 | @table @code | |
d77de738 ML |
8361 | @cindex @code{l1_data} variable attribute, Blackfin |
8362 | @cindex @code{l1_data_A} variable attribute, Blackfin | |
8363 | @cindex @code{l1_data_B} variable attribute, Blackfin | |
f33d7a88 AA |
8364 | @item l1_data |
8365 | @itemx l1_data_A | |
8366 | @itemx l1_data_B | |
d77de738 ML |
8367 | Use these attributes on the Blackfin to place the variable into L1 Data SRAM. |
8368 | Variables with @code{l1_data} attribute are put into the specific section | |
8369 | named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into | |
8370 | the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} | |
8371 | attribute are put into the specific section named @code{.l1.data.B}. | |
8372 | ||
d77de738 | 8373 | @cindex @code{l2} variable attribute, Blackfin |
f33d7a88 | 8374 | @item l2 |
d77de738 ML |
8375 | Use this attribute on the Blackfin to place the variable into L2 SRAM. |
8376 | Variables with @code{l2} attribute are put into the specific section | |
8377 | named @code{.l2.data}. | |
8378 | @end table | |
8379 | ||
8380 | @node H8/300 Variable Attributes | |
8381 | @subsection H8/300 Variable Attributes | |
8382 | ||
8383 | These variable attributes are available for H8/300 targets: | |
8384 | ||
8385 | @table @code | |
d77de738 ML |
8386 | @cindex @code{eightbit_data} variable attribute, H8/300 |
8387 | @cindex eight-bit data on the H8/300, H8/300H, and H8S | |
f33d7a88 | 8388 | @item eightbit_data |
d77de738 ML |
8389 | Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified |
8390 | variable should be placed into the eight-bit data section. | |
8391 | The compiler generates more efficient code for certain operations | |
8392 | on data in the eight-bit data area. Note the eight-bit data area is limited to | |
8393 | 256 bytes of data. | |
8394 | ||
8395 | You must use GAS and GLD from GNU binutils version 2.7 or later for | |
8396 | this attribute to work correctly. | |
8397 | ||
d77de738 ML |
8398 | @cindex @code{tiny_data} variable attribute, H8/300 |
8399 | @cindex tiny data section on the H8/300H and H8S | |
f33d7a88 | 8400 | @item tiny_data |
d77de738 ML |
8401 | Use this attribute on the H8/300H and H8S to indicate that the specified |
8402 | variable should be placed into the tiny data section. | |
8403 | The compiler generates more efficient code for loads and stores | |
8404 | on data in the tiny data section. Note the tiny data area is limited to | |
8405 | slightly under 32KB of data. | |
8406 | ||
8407 | @end table | |
8408 | ||
8409 | @node IA-64 Variable Attributes | |
8410 | @subsection IA-64 Variable Attributes | |
8411 | ||
8412 | The IA-64 back end supports the following variable attribute: | |
8413 | ||
8414 | @table @code | |
d77de738 | 8415 | @cindex @code{model} variable attribute, IA-64 |
f33d7a88 | 8416 | @item model (@var{model-name}) |
d77de738 ML |
8417 | |
8418 | On IA-64, use this attribute to set the addressability of an object. | |
8419 | At present, the only supported identifier for @var{model-name} is | |
8420 | @code{small}, indicating addressability via ``small'' (22-bit) | |
8421 | addresses (so that their addresses can be loaded with the @code{addl} | |
8422 | instruction). Caveat: such addressing is by definition not position | |
8423 | independent and hence this attribute must not be used for objects | |
8424 | defined by shared libraries. | |
8425 | ||
8426 | @end table | |
8427 | ||
8428 | @node LoongArch Variable Attributes | |
8429 | @subsection LoongArch Variable Attributes | |
8430 | ||
8431 | One attribute is currently defined for the LoongArch. | |
8432 | ||
8433 | @table @code | |
d77de738 | 8434 | @cindex @code{model} variable attribute, LoongArch |
f33d7a88 | 8435 | @item model("@var{name}") |
d77de738 ML |
8436 | Use this attribute on the LoongArch to use a different code model for |
8437 | addressing this variable, than the code model specified by the global | |
8438 | @option{-mcmodel} option. This attribute is mostly useful if a | |
8439 | @code{section} attribute and/or a linker script will locate this object | |
8440 | specially. Currently the only supported values of @var{name} are | |
8441 | @code{normal} and @code{extreme}. | |
8442 | @end table | |
8443 | ||
8444 | @node M32R/D Variable Attributes | |
8445 | @subsection M32R/D Variable Attributes | |
8446 | ||
8447 | One attribute is currently defined for the M32R/D@. | |
8448 | ||
8449 | @table @code | |
d77de738 ML |
8450 | @cindex @code{model-name} variable attribute, M32R/D |
8451 | @cindex variable addressability on the M32R/D | |
f33d7a88 | 8452 | @item model (@var{model-name}) |
d77de738 ML |
8453 | Use this attribute on the M32R/D to set the addressability of an object. |
8454 | The identifier @var{model-name} is one of @code{small}, @code{medium}, | |
8455 | or @code{large}, representing each of the code models. | |
8456 | ||
8457 | Small model objects live in the lower 16MB of memory (so that their | |
8458 | addresses can be loaded with the @code{ld24} instruction). | |
8459 | ||
8460 | Medium and large model objects may live anywhere in the 32-bit address space | |
8461 | (the compiler generates @code{seth/add3} instructions to load their | |
8462 | addresses). | |
8463 | @end table | |
8464 | ||
d77de738 ML |
8465 | @node Microsoft Windows Variable Attributes |
8466 | @subsection Microsoft Windows Variable Attributes | |
8467 | ||
8468 | You can use these attributes on Microsoft Windows targets. | |
8469 | @ref{x86 Variable Attributes} for additional Windows compatibility | |
8470 | attributes available on all x86 targets. | |
8471 | ||
8472 | @table @code | |
d77de738 ML |
8473 | @cindex @code{dllimport} variable attribute |
8474 | @cindex @code{dllexport} variable attribute | |
f33d7a88 AA |
8475 | @item dllimport |
8476 | @itemx dllexport | |
d77de738 ML |
8477 | The @code{dllimport} and @code{dllexport} attributes are described in |
8478 | @ref{Microsoft Windows Function Attributes}. | |
8479 | ||
d77de738 | 8480 | @cindex @code{selectany} variable attribute |
f33d7a88 | 8481 | @item selectany |
d77de738 ML |
8482 | The @code{selectany} attribute causes an initialized global variable to |
8483 | have link-once semantics. When multiple definitions of the variable are | |
8484 | encountered by the linker, the first is selected and the remainder are | |
8485 | discarded. Following usage by the Microsoft compiler, the linker is told | |
8486 | @emph{not} to warn about size or content differences of the multiple | |
8487 | definitions. | |
8488 | ||
8489 | Although the primary usage of this attribute is for POD types, the | |
8490 | attribute can also be applied to global C++ objects that are initialized | |
8491 | by a constructor. In this case, the static initialization and destruction | |
8492 | code for the object is emitted in each translation defining the object, | |
8493 | but the calls to the constructor and destructor are protected by a | |
8494 | link-once guard variable. | |
8495 | ||
8496 | The @code{selectany} attribute is only available on Microsoft Windows | |
8497 | targets. You can use @code{__declspec (selectany)} as a synonym for | |
8498 | @code{__attribute__ ((selectany))} for compatibility with other | |
8499 | compilers. | |
8500 | ||
d77de738 | 8501 | @cindex @code{shared} variable attribute |
f33d7a88 | 8502 | @item shared |
d77de738 ML |
8503 | On Microsoft Windows, in addition to putting variable definitions in a named |
8504 | section, the section can also be shared among all running copies of an | |
8505 | executable or DLL@. For example, this small program defines shared data | |
8506 | by putting it in a named section @code{shared} and marking the section | |
8507 | shareable: | |
8508 | ||
8509 | @smallexample | |
8510 | int foo __attribute__((section ("shared"), shared)) = 0; | |
8511 | ||
8512 | int | |
8513 | main() | |
8514 | @{ | |
8515 | /* @r{Read and write foo. All running | |
8516 | copies see the same value.} */ | |
8517 | return 0; | |
8518 | @} | |
8519 | @end smallexample | |
8520 | ||
8521 | @noindent | |
8522 | You may only use the @code{shared} attribute along with @code{section} | |
8523 | attribute with a fully-initialized global definition because of the way | |
8524 | linkers work. See @code{section} attribute for more information. | |
8525 | ||
8526 | The @code{shared} attribute is only available on Microsoft Windows@. | |
8527 | ||
8528 | @end table | |
8529 | ||
8530 | @node MSP430 Variable Attributes | |
8531 | @subsection MSP430 Variable Attributes | |
8532 | ||
8533 | @table @code | |
d77de738 ML |
8534 | @cindex @code{upper} variable attribute, MSP430 |
8535 | @cindex @code{either} variable attribute, MSP430 | |
f33d7a88 AA |
8536 | @item upper |
8537 | @itemx either | |
d77de738 ML |
8538 | These attributes are the same as the MSP430 function attributes of the |
8539 | same name (@pxref{MSP430 Function Attributes}). | |
8540 | ||
d77de738 | 8541 | @cindex @code{lower} variable attribute, MSP430 |
f33d7a88 | 8542 | @item lower |
d77de738 ML |
8543 | This option behaves mostly the same as the MSP430 function attribute of the |
8544 | same name (@pxref{MSP430 Function Attributes}), but it has some additional | |
8545 | functionality. | |
8546 | ||
8547 | If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or | |
8548 | the @code{section} attribute is applied to a variable, the compiler will | |
8549 | generate 430X instructions to handle it. This is because the compiler has | |
8550 | to assume that the variable could get placed in the upper memory region | |
8551 | (above address 0xFFFF). Marking the variable with the @code{lower} attribute | |
8552 | informs the compiler that the variable will be placed in lower memory so it | |
8553 | is safe to use 430 instructions to handle it. | |
8554 | ||
8555 | In the case of the @code{section} attribute, the section name given | |
8556 | will be used, and the @code{.lower} prefix will not be added. | |
8557 | ||
8558 | @end table | |
8559 | ||
8560 | @node Nvidia PTX Variable Attributes | |
8561 | @subsection Nvidia PTX Variable Attributes | |
8562 | ||
8563 | These variable attributes are supported by the Nvidia PTX back end: | |
8564 | ||
8565 | @table @code | |
d77de738 | 8566 | @cindex @code{shared} attribute, Nvidia PTX |
f33d7a88 | 8567 | @item shared |
d77de738 ML |
8568 | Use this attribute to place a variable in the @code{.shared} memory space. |
8569 | This memory space is private to each cooperative thread array; only threads | |
8570 | within one thread block refer to the same instance of the variable. | |
8571 | The runtime does not initialize variables in this memory space. | |
8572 | @end table | |
8573 | ||
8574 | @node PowerPC Variable Attributes | |
8575 | @subsection PowerPC Variable Attributes | |
8576 | ||
8577 | Three attributes currently are defined for PowerPC configurations: | |
8578 | @code{altivec}, @code{ms_struct} and @code{gcc_struct}. | |
8579 | ||
8580 | @cindex @code{ms_struct} variable attribute, PowerPC | |
8581 | @cindex @code{gcc_struct} variable attribute, PowerPC | |
8582 | For full documentation of the struct attributes please see the | |
8583 | documentation in @ref{x86 Variable Attributes}. | |
8584 | ||
8585 | @cindex @code{altivec} variable attribute, PowerPC | |
8586 | For documentation of @code{altivec} attribute please see the | |
8587 | documentation in @ref{PowerPC Type Attributes}. | |
8588 | ||
8589 | @node RL78 Variable Attributes | |
8590 | @subsection RL78 Variable Attributes | |
8591 | ||
8592 | @cindex @code{saddr} variable attribute, RL78 | |
8593 | The RL78 back end supports the @code{saddr} variable attribute. This | |
8594 | specifies placement of the corresponding variable in the SADDR area, | |
8595 | which can be accessed more efficiently than the default memory region. | |
8596 | ||
8597 | @node V850 Variable Attributes | |
8598 | @subsection V850 Variable Attributes | |
8599 | ||
8600 | These variable attributes are supported by the V850 back end: | |
8601 | ||
8602 | @table @code | |
8603 | ||
d77de738 | 8604 | @cindex @code{sda} variable attribute, V850 |
f33d7a88 | 8605 | @item sda |
d77de738 ML |
8606 | Use this attribute to explicitly place a variable in the small data area, |
8607 | which can hold up to 64 kilobytes. | |
8608 | ||
d77de738 | 8609 | @cindex @code{tda} variable attribute, V850 |
f33d7a88 | 8610 | @item tda |
d77de738 ML |
8611 | Use this attribute to explicitly place a variable in the tiny data area, |
8612 | which can hold up to 256 bytes in total. | |
8613 | ||
d77de738 | 8614 | @cindex @code{zda} variable attribute, V850 |
f33d7a88 | 8615 | @item zda |
d77de738 ML |
8616 | Use this attribute to explicitly place a variable in the first 32 kilobytes |
8617 | of memory. | |
8618 | @end table | |
8619 | ||
8620 | @node x86 Variable Attributes | |
8621 | @subsection x86 Variable Attributes | |
8622 | ||
8623 | Two attributes are currently defined for x86 configurations: | |
8624 | @code{ms_struct} and @code{gcc_struct}. | |
8625 | ||
8626 | @table @code | |
d77de738 ML |
8627 | @cindex @code{ms_struct} variable attribute, x86 |
8628 | @cindex @code{gcc_struct} variable attribute, x86 | |
f33d7a88 AA |
8629 | @item ms_struct |
8630 | @itemx gcc_struct | |
d77de738 ML |
8631 | |
8632 | If @code{packed} is used on a structure, or if bit-fields are used, | |
8633 | it may be that the Microsoft ABI lays out the structure differently | |
8634 | than the way GCC normally does. Particularly when moving packed | |
8635 | data between functions compiled with GCC and the native Microsoft compiler | |
8636 | (either via function call or as data in a file), it may be necessary to access | |
8637 | either format. | |
8638 | ||
8639 | The @code{ms_struct} and @code{gcc_struct} attributes correspond | |
8640 | to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} | |
8641 | command-line options, respectively; | |
8642 | see @ref{x86 Options}, for details of how structure layout is affected. | |
8643 | @xref{x86 Type Attributes}, for information about the corresponding | |
8644 | attributes on types. | |
8645 | ||
8646 | @end table | |
8647 | ||
8648 | @node Xstormy16 Variable Attributes | |
8649 | @subsection Xstormy16 Variable Attributes | |
8650 | ||
8651 | One attribute is currently defined for xstormy16 configurations: | |
8652 | @code{below100}. | |
8653 | ||
8654 | @table @code | |
d77de738 | 8655 | @cindex @code{below100} variable attribute, Xstormy16 |
f33d7a88 | 8656 | @item below100 |
d77de738 ML |
8657 | |
8658 | If a variable has the @code{below100} attribute (@code{BELOW100} is | |
8659 | allowed also), GCC places the variable in the first 0x100 bytes of | |
8660 | memory and use special opcodes to access it. Such variables are | |
8661 | placed in either the @code{.bss_below100} section or the | |
8662 | @code{.data_below100} section. | |
8663 | ||
8664 | @end table | |
8665 | ||
8666 | @node Type Attributes | |
8667 | @section Specifying Attributes of Types | |
8668 | @cindex attribute of types | |
8669 | @cindex type attributes | |
8670 | ||
837a12a2 | 8671 | You can use attributes to specify various special |
d77de738 ML |
8672 | properties of types. Some type attributes apply only to structure and |
8673 | union types, and in C++, also class types, while others can apply to | |
8674 | any type defined via a @code{typedef} declaration. Unless otherwise | |
8675 | specified, the same restrictions and effects apply to attributes regardless | |
8676 | of whether a type is a trivial structure or a C++ class with user-defined | |
8677 | constructors, destructors, or a copy assignment. | |
8678 | ||
8679 | Other attributes are defined for functions (@pxref{Function Attributes}), | |
8680 | labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator | |
8681 | Attributes}), statements (@pxref{Statement Attributes}), and for variables | |
8682 | (@pxref{Variable Attributes}). | |
8683 | ||
837a12a2 SL |
8684 | GCC provides two different ways to specify attributes: the traditional |
8685 | GNU syntax using @samp{__attribute__ ((...))} annotations, and the | |
8686 | newer standard C and C++ syntax using @samp{[[...]]} with the | |
8687 | @samp{gnu::} prefix on attribute names. Note that the exact rules for | |
8688 | placement of attributes in your source code are different depending on | |
8689 | which syntax you use. @xref{Attribute Syntax}, for details. | |
d77de738 ML |
8690 | |
8691 | You may specify type attributes in an enum, struct or union type | |
8692 | declaration or definition by placing them immediately after the | |
8693 | @code{struct}, @code{union} or @code{enum} keyword. You can also place | |
8694 | them just past the closing curly brace of the definition, but this is less | |
8695 | preferred because logically the type should be fully defined at | |
837a12a2 SL |
8696 | the closing brace. You can also include type attributes in a |
8697 | @code{typedef} declaration. | |
d77de738 ML |
8698 | |
8699 | @menu | |
8700 | * Common Type Attributes:: | |
8701 | * ARC Type Attributes:: | |
8702 | * ARM Type Attributes:: | |
8703 | * BPF Type Attributes:: | |
d77de738 ML |
8704 | * PowerPC Type Attributes:: |
8705 | * x86 Type Attributes:: | |
8706 | @end menu | |
8707 | ||
8708 | @node Common Type Attributes | |
8709 | @subsection Common Type Attributes | |
8710 | ||
8711 | The following type attributes are supported on most targets. | |
8712 | ||
8713 | @table @code | |
8714 | @cindex @code{aligned} type attribute | |
8715 | @item aligned | |
8716 | @itemx aligned (@var{alignment}) | |
8717 | The @code{aligned} attribute specifies a minimum alignment (in bytes) for | |
8718 | variables of the specified type. When specified, @var{alignment} must be | |
8719 | a power of 2. Specifying no @var{alignment} argument implies the maximum | |
8720 | alignment for the target, which is often, but by no means always, 8 or 16 | |
8721 | bytes. For example, the declarations: | |
8722 | ||
8723 | @smallexample | |
8724 | struct __attribute__ ((aligned (8))) S @{ short f[3]; @}; | |
8725 | typedef int more_aligned_int __attribute__ ((aligned (8))); | |
8726 | @end smallexample | |
8727 | ||
8728 | @noindent | |
8729 | force the compiler to ensure (as far as it can) that each variable whose | |
8730 | type is @code{struct S} or @code{more_aligned_int} is allocated and | |
8731 | aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all | |
8732 | variables of type @code{struct S} aligned to 8-byte boundaries allows | |
8733 | the compiler to use the @code{ldd} and @code{std} (doubleword load and | |
8734 | store) instructions when copying one variable of type @code{struct S} to | |
8735 | another, thus improving run-time efficiency. | |
8736 | ||
8737 | Note that the alignment of any given @code{struct} or @code{union} type | |
8738 | is required by the ISO C standard to be at least a perfect multiple of | |
8739 | the lowest common multiple of the alignments of all of the members of | |
8740 | the @code{struct} or @code{union} in question. This means that you @emph{can} | |
8741 | effectively adjust the alignment of a @code{struct} or @code{union} | |
8742 | type by attaching an @code{aligned} attribute to any one of the members | |
8743 | of such a type, but the notation illustrated in the example above is a | |
8744 | more obvious, intuitive, and readable way to request the compiler to | |
8745 | adjust the alignment of an entire @code{struct} or @code{union} type. | |
8746 | ||
8747 | As in the preceding example, you can explicitly specify the alignment | |
8748 | (in bytes) that you wish the compiler to use for a given @code{struct} | |
8749 | or @code{union} type. Alternatively, you can leave out the alignment factor | |
8750 | and just ask the compiler to align a type to the maximum | |
8751 | useful alignment for the target machine you are compiling for. For | |
8752 | example, you could write: | |
8753 | ||
8754 | @smallexample | |
8755 | struct __attribute__ ((aligned)) S @{ short f[3]; @}; | |
8756 | @end smallexample | |
8757 | ||
8758 | Whenever you leave out the alignment factor in an @code{aligned} | |
8759 | attribute specification, the compiler automatically sets the alignment | |
8760 | for the type to the largest alignment that is ever used for any data | |
8761 | type on the target machine you are compiling for. Doing this can often | |
8762 | make copy operations more efficient, because the compiler can use | |
8763 | whatever instructions copy the biggest chunks of memory when performing | |
8764 | copies to or from the variables that have types that you have aligned | |
8765 | this way. | |
8766 | ||
8767 | In the example above, if the size of each @code{short} is 2 bytes, then | |
8768 | the size of the entire @code{struct S} type is 6 bytes. The smallest | |
8769 | power of two that is greater than or equal to that is 8, so the | |
8770 | compiler sets the alignment for the entire @code{struct S} type to 8 | |
8771 | bytes. | |
8772 | ||
8773 | Note that although you can ask the compiler to select a time-efficient | |
8774 | alignment for a given type and then declare only individual stand-alone | |
8775 | objects of that type, the compiler's ability to select a time-efficient | |
8776 | alignment is primarily useful only when you plan to create arrays of | |
8777 | variables having the relevant (efficiently aligned) type. If you | |
8778 | declare or use arrays of variables of an efficiently-aligned type, then | |
8779 | it is likely that your program also does pointer arithmetic (or | |
8780 | subscripting, which amounts to the same thing) on pointers to the | |
8781 | relevant type, and the code that the compiler generates for these | |
8782 | pointer arithmetic operations is often more efficient for | |
8783 | efficiently-aligned types than for other types. | |
8784 | ||
8785 | Note that the effectiveness of @code{aligned} attributes may be limited | |
8786 | by inherent limitations in your linker. On many systems, the linker is | |
8787 | only able to arrange for variables to be aligned up to a certain maximum | |
8788 | alignment. (For some linkers, the maximum supported alignment may | |
8789 | be very very small.) If your linker is only able to align variables | |
8790 | up to a maximum of 8-byte alignment, then specifying @code{aligned (16)} | |
8791 | in an @code{__attribute__} still only provides you with 8-byte | |
8792 | alignment. See your linker documentation for further information. | |
8793 | ||
8794 | When used on a struct, or struct member, the @code{aligned} attribute can | |
8795 | only increase the alignment; in order to decrease it, the @code{packed} | |
8796 | attribute must be specified as well. When used as part of a typedef, the | |
8797 | @code{aligned} attribute can both increase and decrease alignment, and | |
8798 | specifying the @code{packed} attribute generates a warning. | |
8799 | ||
8800 | @cindex @code{warn_if_not_aligned} type attribute | |
8801 | @item warn_if_not_aligned (@var{alignment}) | |
8802 | This attribute specifies a threshold for the structure field, measured | |
8803 | in bytes. If the structure field is aligned below the threshold, a | |
8804 | warning will be issued. For example, the declaration: | |
8805 | ||
8806 | @smallexample | |
8807 | typedef unsigned long long __u64 | |
8808 | __attribute__((aligned (4), warn_if_not_aligned (8))); | |
8809 | ||
8810 | struct foo | |
8811 | @{ | |
8812 | int i1; | |
8813 | int i2; | |
8814 | __u64 x; | |
8815 | @}; | |
8816 | @end smallexample | |
8817 | ||
8818 | @noindent | |
8819 | causes the compiler to issue an warning on @code{struct foo}, like | |
8820 | @samp{warning: alignment 4 of 'struct foo' is less than 8}. | |
8821 | It is used to define @code{struct foo} in such a way that | |
8822 | @code{struct foo} has the same layout and the structure field @code{x} | |
8823 | has the same alignment when @code{__u64} is aligned at either 4 or | |
8824 | 8 bytes. Align @code{struct foo} to 8 bytes: | |
8825 | ||
8826 | @smallexample | |
8827 | struct __attribute__ ((aligned (8))) foo | |
8828 | @{ | |
8829 | int i1; | |
8830 | int i2; | |
8831 | __u64 x; | |
8832 | @}; | |
8833 | @end smallexample | |
8834 | ||
8835 | @noindent | |
8836 | silences the warning. The compiler also issues a warning, like | |
8837 | @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8}, | |
8838 | when the structure field has the misaligned offset: | |
8839 | ||
8840 | @smallexample | |
8841 | struct __attribute__ ((aligned (8))) foo | |
8842 | @{ | |
8843 | int i1; | |
8844 | int i2; | |
8845 | int i3; | |
8846 | __u64 x; | |
8847 | @}; | |
8848 | @end smallexample | |
8849 | ||
8850 | This warning can be disabled by @option{-Wno-if-not-aligned}. | |
8851 | ||
f33d7a88 | 8852 | @cindex @code{alloc_size} type attribute |
d77de738 ML |
8853 | @item alloc_size (@var{position}) |
8854 | @itemx alloc_size (@var{position-1}, @var{position-2}) | |
d77de738 ML |
8855 | The @code{alloc_size} type attribute may be applied to the definition |
8856 | of a type of a function that returns a pointer and takes at least one | |
8857 | argument of an integer type. It indicates that the returned pointer | |
8858 | points to an object whose size is given by the function argument at | |
8859 | @var{position-1}, or by the product of the arguments at @var{position-1} | |
8860 | and @var{position-2}. Meaningful sizes are positive values less than | |
8861 | @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses | |
8862 | this information to improve the results of @code{__builtin_object_size}. | |
8863 | ||
8864 | For instance, the following declarations | |
8865 | ||
8866 | @smallexample | |
8867 | typedef __attribute__ ((alloc_size (1, 2))) void* | |
8868 | calloc_type (size_t, size_t); | |
8869 | typedef __attribute__ ((alloc_size (1))) void* | |
8870 | malloc_type (size_t); | |
8871 | @end smallexample | |
8872 | ||
8873 | @noindent | |
8874 | specify that @code{calloc_type} is a type of a function that, like | |
8875 | the standard C function @code{calloc}, returns an object whose size | |
8876 | is given by the product of arguments 1 and 2, and that | |
8877 | @code{malloc_type}, like the standard C function @code{malloc}, | |
8878 | returns an object whose size is given by argument 1 to the function. | |
8879 | ||
f33d7a88 | 8880 | @cindex @code{copy} type attribute |
d77de738 ML |
8881 | @item copy |
8882 | @itemx copy (@var{expression}) | |
d77de738 ML |
8883 | The @code{copy} attribute applies the set of attributes with which |
8884 | the type of the @var{expression} has been declared to the declaration | |
8885 | of the type to which the attribute is applied. The attribute is | |
8886 | designed for libraries that define aliases that are expected to | |
8887 | specify the same set of attributes as the aliased symbols. | |
8888 | The @code{copy} attribute can be used with types, variables, or | |
8889 | functions. However, the kind of symbol to which the attribute is | |
8890 | applied (either varible or function) must match the kind of symbol | |
8891 | to which the argument refers. | |
8892 | The @code{copy} attribute copies only syntactic and semantic attributes | |
8893 | but not attributes that affect a symbol's linkage or visibility such as | |
8894 | @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} | |
8895 | attribute is also not copied. @xref{Common Function Attributes}. | |
8896 | @xref{Common Variable Attributes}. | |
8897 | ||
8898 | For example, suppose @code{struct A} below is defined in some third | |
8899 | party library header to have the alignment requirement @code{N} and | |
8900 | to force a warning whenever a variable of the type is not so aligned | |
8901 | due to attribute @code{packed}. Specifying the @code{copy} attribute | |
8902 | on the definition on the unrelated @code{struct B} has the effect of | |
8903 | copying all relevant attributes from the type referenced by the pointer | |
8904 | expression to @code{struct B}. | |
8905 | ||
8906 | @smallexample | |
8907 | struct __attribute__ ((aligned (N), warn_if_not_aligned (N))) | |
8908 | A @{ /* @r{@dots{}} */ @}; | |
8909 | struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @}; | |
8910 | @end smallexample | |
8911 | ||
f33d7a88 | 8912 | @cindex @code{deprecated} type attribute |
d77de738 ML |
8913 | @item deprecated |
8914 | @itemx deprecated (@var{msg}) | |
d77de738 ML |
8915 | The @code{deprecated} attribute results in a warning if the type |
8916 | is used anywhere in the source file. This is useful when identifying | |
8917 | types that are expected to be removed in a future version of a program. | |
8918 | If possible, the warning also includes the location of the declaration | |
8919 | of the deprecated type, to enable users to easily find further | |
8920 | information about why the type is deprecated, or what they should do | |
8921 | instead. Note that the warnings only occur for uses and then only | |
8922 | if the type is being applied to an identifier that itself is not being | |
8923 | declared as deprecated. | |
8924 | ||
8925 | @smallexample | |
8926 | typedef int T1 __attribute__ ((deprecated)); | |
8927 | T1 x; | |
8928 | typedef T1 T2; | |
8929 | T2 y; | |
8930 | typedef T1 T3 __attribute__ ((deprecated)); | |
8931 | T3 z __attribute__ ((deprecated)); | |
8932 | @end smallexample | |
8933 | ||
8934 | @noindent | |
8935 | results in a warning on line 2 and 3 but not lines 4, 5, or 6. No | |
8936 | warning is issued for line 4 because T2 is not explicitly | |
8937 | deprecated. Line 5 has no warning because T3 is explicitly | |
8938 | deprecated. Similarly for line 6. The optional @var{msg} | |
8939 | argument, which must be a string, is printed in the warning if | |
8940 | present. Control characters in the string will be replaced with | |
8941 | escape sequences, and if the @option{-fmessage-length} option is set | |
8942 | to 0 (its default value) then any newline characters will be ignored. | |
8943 | ||
8944 | The @code{deprecated} attribute can also be used for functions and | |
8945 | variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) | |
8946 | ||
8947 | The message attached to the attribute is affected by the setting of | |
8948 | the @option{-fmessage-length} option. | |
8949 | ||
f33d7a88 | 8950 | @cindex @code{unavailable} type attribute |
d77de738 ML |
8951 | @item unavailable |
8952 | @itemx unavailable (@var{msg}) | |
d77de738 ML |
8953 | The @code{unavailable} attribute behaves in the same manner as the |
8954 | @code{deprecated} one, but emits an error rather than a warning. It is | |
8955 | used to indicate that a (perhaps previously @code{deprecated}) type is | |
8956 | no longer usable. | |
8957 | ||
8958 | The @code{unavailable} attribute can also be used for functions and | |
8959 | variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) | |
8960 | ||
d77de738 | 8961 | @cindex @code{designated_init} type attribute |
f33d7a88 | 8962 | @item designated_init |
d77de738 ML |
8963 | This attribute may only be applied to structure types. It indicates |
8964 | that any initialization of an object of this type must use designated | |
8965 | initializers rather than positional initializers. The intent of this | |
8966 | attribute is to allow the programmer to indicate that a structure's | |
8967 | layout may change, and that therefore relying on positional | |
8968 | initialization will result in future breakage. | |
8969 | ||
8970 | GCC emits warnings based on this attribute by default; use | |
8971 | @option{-Wno-designated-init} to suppress them. | |
8972 | ||
862867ea AO |
8973 | @cindex @code{hardbool} type attribute |
8974 | @item hardbool | |
8975 | @itemx hardbool (@var{false_value}) | |
8976 | @itemx hardbool (@var{false_value}, @var{true_value}) | |
8977 | This attribute may only be applied to integral types in C, to introduce | |
8978 | hardened boolean types. It turns the integral type into a boolean-like | |
8979 | type with the same size and precision, that uses the specified values as | |
8980 | representations for @code{false} and @code{true}. Underneath, it is | |
8981 | actually an enumerate type, but its observable behavior is like that of | |
8982 | @code{_Bool}, except for the strict internal representations, verified | |
8983 | by runtime checks. | |
8984 | ||
8985 | If @var{true_value} is omitted, the bitwise negation of | |
8986 | @var{false_value} is used. If @var{false_value} is omitted, zero is | |
8987 | used. The named representation values must be different when converted | |
8988 | to the original integral type. Narrower bitfields are rejected if the | |
8989 | representations become indistinguishable. | |
8990 | ||
8991 | Values of such types automatically decay to @code{_Bool}, at which | |
8992 | point, the selected representation values are mapped to the | |
8993 | corresponding @code{_Bool} values. When the represented value is not | |
8994 | determined, at compile time, to be either @var{false_value} or | |
8995 | @var{true_value}, runtime verification calls @code{__builtin_trap} if it | |
8996 | is neither. This is what makes them hardened boolean types. | |
8997 | ||
8998 | When converting scalar types to such hardened boolean types, implicitly | |
8999 | or explicitly, behavior corresponds to a conversion to @code{_Bool}, | |
9000 | followed by a mapping from @code{false} and @code{true} to | |
9001 | @var{false_value} and @var{true_value}, respectively. | |
9002 | ||
9003 | @smallexample | |
9004 | typedef char __attribute__ ((__hardbool__ (0x5a))) hbool; | |
9005 | hbool first = 0; /* False, stored as (char)0x5a. */ | |
9006 | hbool second = !first; /* True, stored as ~(char)0x5a. */ | |
9007 | ||
9008 | static hbool zeroinit; /* False, stored as (char)0x5a. */ | |
9009 | auto hbool uninit; /* Undefined, may trap. */ | |
9010 | @end smallexample | |
9011 | ||
9012 | When zero-initializing a variable or field of hardened boolean type | |
9013 | (presumably held in static storage) the implied zero initializer gets | |
9014 | converted to @code{_Bool}, and then to the hardened boolean type, so | |
9015 | that the initial value is the hardened representation for @code{false}. | |
9016 | Using that value is well defined. This is @emph{not} the case when | |
9017 | variables and fields of such types are uninitialized (presumably held in | |
9018 | automatic or dynamic storage): their values are indeterminate, and using | |
9019 | them invokes undefined behavior. Using them may trap or not, depending | |
9020 | on the bits held in the storage (re)used for the variable, if any, and | |
9021 | on optimizations the compiler may perform on the grounds that using | |
9022 | uninitialized values invokes undefined behavior. | |
9023 | ||
9024 | Users of @option{-ftrivial-auto-var-init} should be aware that the bit | |
9025 | patterns used as initializers are @emph{not} converted to | |
9026 | @code{hardbool} types, so using a @code{hardbool} variable that is | |
9027 | implicitly initialized by the @option{-ftrivial-auto-var-init} may trap | |
9028 | if the representations values chosen for @code{false} and @code{true} do | |
9029 | not match the initializer. | |
9030 | ||
9031 | Since this is a language extension only available in C, interoperation | |
9032 | with other languages may pose difficulties. It should interoperate with | |
9033 | Ada Booleans defined with the same size and equivalent representation | |
9034 | clauses, and with enumerations or other languages' integral types that | |
9035 | correspond to C's chosen integral type. | |
9036 | ||
9037 | ||
d77de738 | 9038 | @cindex @code{may_alias} type attribute |
f33d7a88 | 9039 | @item may_alias |
d77de738 ML |
9040 | Accesses through pointers to types with this attribute are not subject |
9041 | to type-based alias analysis, but are instead assumed to be able to alias | |
9042 | any other type of objects. | |
9043 | In the context of section 6.5 paragraph 7 of the C99 standard, | |
9044 | an lvalue expression | |
9045 | dereferencing such a pointer is treated like having a character type. | |
9046 | See @option{-fstrict-aliasing} for more information on aliasing issues. | |
9047 | This extension exists to support some vector APIs, in which pointers to | |
9048 | one vector type are permitted to alias pointers to a different vector type. | |
9049 | ||
9050 | Note that an object of a type with this attribute does not have any | |
9051 | special semantics. | |
9052 | ||
9053 | Example of use: | |
9054 | ||
9055 | @smallexample | |
9056 | typedef short __attribute__ ((__may_alias__)) short_a; | |
9057 | ||
9058 | int | |
9059 | main (void) | |
9060 | @{ | |
9061 | int a = 0x12345678; | |
9062 | short_a *b = (short_a *) &a; | |
9063 | ||
9064 | b[1] = 0; | |
9065 | ||
9066 | if (a == 0x12345678) | |
9067 | abort(); | |
9068 | ||
9069 | exit(0); | |
9070 | @} | |
9071 | @end smallexample | |
9072 | ||
9073 | @noindent | |
9074 | If you replaced @code{short_a} with @code{short} in the variable | |
9075 | declaration, the above program would abort when compiled with | |
9076 | @option{-fstrict-aliasing}, which is on by default at @option{-O2} or | |
9077 | above. | |
9078 | ||
d77de738 | 9079 | @cindex @code{mode} type attribute |
f33d7a88 | 9080 | @item mode (@var{mode}) |
d77de738 ML |
9081 | This attribute specifies the data type for the declaration---whichever |
9082 | type corresponds to the mode @var{mode}. This in effect lets you | |
9083 | request an integer or floating-point type according to its width. | |
9084 | ||
9085 | @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, | |
9086 | for a list of the possible keywords for @var{mode}. | |
9087 | You may also specify a mode of @code{byte} or @code{__byte__} to | |
9088 | indicate the mode corresponding to a one-byte integer, @code{word} or | |
9089 | @code{__word__} for the mode of a one-word integer, and @code{pointer} | |
9090 | or @code{__pointer__} for the mode used to represent pointers. | |
9091 | ||
d77de738 | 9092 | @cindex @code{packed} type attribute |
f33d7a88 | 9093 | @item packed |
d77de738 ML |
9094 | This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class} |
9095 | type definition, specifies that each of its members (other than zero-width | |
9096 | bit-fields) is placed to minimize the memory required. This is equivalent | |
9097 | to specifying the @code{packed} attribute on each of the members. | |
9098 | ||
9099 | @opindex fshort-enums | |
9100 | When attached to an @code{enum} definition, the @code{packed} attribute | |
9101 | indicates that the smallest integral type should be used. | |
9102 | Specifying the @option{-fshort-enums} flag on the command line | |
9103 | is equivalent to specifying the @code{packed} | |
9104 | attribute on all @code{enum} definitions. | |
9105 | ||
9106 | In the following example @code{struct my_packed_struct}'s members are | |
9107 | packed closely together, but the internal layout of its @code{s} member | |
9108 | is not packed---to do that, @code{struct my_unpacked_struct} needs to | |
9109 | be packed too. | |
9110 | ||
9111 | @smallexample | |
9112 | struct my_unpacked_struct | |
9113 | @{ | |
9114 | char c; | |
9115 | int i; | |
9116 | @}; | |
9117 | ||
9118 | struct __attribute__ ((__packed__)) my_packed_struct | |
9119 | @{ | |
9120 | char c; | |
9121 | int i; | |
9122 | struct my_unpacked_struct s; | |
9123 | @}; | |
9124 | @end smallexample | |
9125 | ||
9126 | You may only specify the @code{packed} attribute on the definition | |
9127 | of an @code{enum}, @code{struct}, @code{union}, or @code{class}, | |
9128 | not on a @code{typedef} that does not also define the enumerated type, | |
9129 | structure, union, or class. | |
9130 | ||
d77de738 | 9131 | @cindex @code{scalar_storage_order} type attribute |
f33d7a88 | 9132 | @item scalar_storage_order ("@var{endianness}") |
d77de738 ML |
9133 | When attached to a @code{union} or a @code{struct}, this attribute sets |
9134 | the storage order, aka endianness, of the scalar fields of the type, as | |
9135 | well as the array fields whose component is scalar. The supported | |
9136 | endiannesses are @code{big-endian} and @code{little-endian}. The attribute | |
9137 | has no effects on fields which are themselves a @code{union}, a @code{struct} | |
9138 | or an array whose component is a @code{union} or a @code{struct}, and it is | |
9139 | possible for these fields to have a different scalar storage order than the | |
9140 | enclosing type. | |
9141 | ||
9142 | Note that neither pointer nor vector fields are considered scalar fields in | |
9143 | this context, so the attribute has no effects on these fields. | |
9144 | ||
9145 | This attribute is supported only for targets that use a uniform default | |
9146 | scalar storage order (fortunately, most of them), i.e.@: targets that store | |
9147 | the scalars either all in big-endian or all in little-endian. | |
9148 | ||
9149 | Additional restrictions are enforced for types with the reverse scalar | |
9150 | storage order with regard to the scalar storage order of the target: | |
9151 | ||
9152 | @itemize | |
9153 | @item Taking the address of a scalar field of a @code{union} or a | |
9154 | @code{struct} with reverse scalar storage order is not permitted and yields | |
9155 | an error. | |
9156 | @item Taking the address of an array field, whose component is scalar, of | |
9157 | a @code{union} or a @code{struct} with reverse scalar storage order is | |
9158 | permitted but yields a warning, unless @option{-Wno-scalar-storage-order} | |
9159 | is specified. | |
9160 | @item Taking the address of a @code{union} or a @code{struct} with reverse | |
9161 | scalar storage order is permitted. | |
9162 | @end itemize | |
9163 | ||
9164 | These restrictions exist because the storage order attribute is lost when | |
9165 | the address of a scalar or the address of an array with scalar component is | |
9166 | taken, so storing indirectly through this address generally does not work. | |
9167 | The second case is nevertheless allowed to be able to perform a block copy | |
9168 | from or to the array. | |
9169 | ||
9170 | Moreover, the use of type punning or aliasing to toggle the storage order | |
9171 | is not supported; that is to say, if a given scalar object can be accessed | |
9172 | through distinct types that assign a different storage order to it, then the | |
9173 | behavior is undefined. | |
9174 | ||
d77de738 | 9175 | @cindex @code{transparent_union} type attribute |
f33d7a88 | 9176 | @item transparent_union |
d77de738 ML |
9177 | |
9178 | This attribute, attached to a @code{union} type definition, indicates | |
9179 | that any function parameter having that union type causes calls to that | |
9180 | function to be treated in a special way. | |
9181 | ||
9182 | First, the argument corresponding to a transparent union type can be of | |
9183 | any type in the union; no cast is required. Also, if the union contains | |
9184 | a pointer type, the corresponding argument can be a null pointer | |
9185 | constant or a void pointer expression; and if the union contains a void | |
9186 | pointer type, the corresponding argument can be any pointer expression. | |
9187 | If the union member type is a pointer, qualifiers like @code{const} on | |
9188 | the referenced type must be respected, just as with normal pointer | |
9189 | conversions. | |
9190 | ||
9191 | Second, the argument is passed to the function using the calling | |
9192 | conventions of the first member of the transparent union, not the calling | |
9193 | conventions of the union itself. All members of the union must have the | |
9194 | same machine representation; this is necessary for this argument passing | |
9195 | to work properly. | |
9196 | ||
9197 | Transparent unions are designed for library functions that have multiple | |
9198 | interfaces for compatibility reasons. For example, suppose the | |
9199 | @code{wait} function must accept either a value of type @code{int *} to | |
9200 | comply with POSIX, or a value of type @code{union wait *} to comply with | |
9201 | the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, | |
9202 | @code{wait} would accept both kinds of arguments, but it would also | |
9203 | accept any other pointer type and this would make argument type checking | |
9204 | less useful. Instead, @code{<sys/wait.h>} might define the interface | |
9205 | as follows: | |
9206 | ||
9207 | @smallexample | |
9208 | typedef union __attribute__ ((__transparent_union__)) | |
9209 | @{ | |
9210 | int *__ip; | |
9211 | union wait *__up; | |
9212 | @} wait_status_ptr_t; | |
9213 | ||
9214 | pid_t wait (wait_status_ptr_t); | |
9215 | @end smallexample | |
9216 | ||
9217 | @noindent | |
9218 | This interface allows either @code{int *} or @code{union wait *} | |
9219 | arguments to be passed, using the @code{int *} calling convention. | |
9220 | The program can call @code{wait} with arguments of either type: | |
9221 | ||
9222 | @smallexample | |
9223 | int w1 () @{ int w; return wait (&w); @} | |
9224 | int w2 () @{ union wait w; return wait (&w); @} | |
9225 | @end smallexample | |
9226 | ||
9227 | @noindent | |
9228 | With this interface, @code{wait}'s implementation might look like this: | |
9229 | ||
9230 | @smallexample | |
9231 | pid_t wait (wait_status_ptr_t p) | |
9232 | @{ | |
9233 | return waitpid (-1, p.__ip, 0); | |
9234 | @} | |
9235 | @end smallexample | |
9236 | ||
f0a90c7d AO |
9237 | @cindex @code{strub} type attribute |
9238 | @item strub | |
9239 | This attribute defines stack-scrubbing properties of functions and | |
9240 | variables, so that functions that access sensitive data can have their | |
9241 | stack frames zeroed-out upon returning or propagating exceptions. This | |
9242 | may be enabled explicitly, by selecting certain @code{strub} modes for | |
9243 | specific functions, or implicitly, by means of @code{strub} variables. | |
9244 | ||
9245 | Being a type attribute, it attaches to types, even when specified in | |
9246 | function and variable declarations. When applied to function types, it | |
9247 | takes an optional string argument. When applied to a | |
9248 | pointer-to-function type, if the optional argument is given, it gets | |
9249 | propagated to the function type. | |
9250 | ||
9251 | @smallexample | |
9252 | /* A strub variable. */ | |
9253 | int __attribute__ ((strub)) var; | |
9254 | /* A strub variable that happens to be a pointer. */ | |
9255 | __attribute__ ((strub)) int *strub_ptr_to_int; | |
9256 | /* A pointer type that may point to a strub variable. */ | |
9257 | typedef int __attribute__ ((strub)) *ptr_to_strub_int_type; | |
9258 | ||
9259 | /* A declaration of a strub function. */ | |
9260 | extern int __attribute__ ((strub)) foo (void); | |
9261 | /* A pointer to that strub function. */ | |
9262 | int __attribute__ ((strub ("at-calls"))) (*ptr_to_strub_fn)(void) = foo; | |
9263 | @end smallexample | |
9264 | ||
9265 | A function associated with @code{at-calls} @code{strub} mode | |
9266 | (@code{strub("at-calls")}, or just @code{strub}) undergoes interface | |
9267 | changes. Its callers are adjusted to match the changes, and to scrub | |
9268 | (overwrite with zeros) the stack space used by the called function after | |
9269 | it returns. The interface change makes the function type incompatible | |
9270 | with an unadorned but otherwise equivalent type, so @emph{every} | |
9271 | declaration and every type that may be used to call the function must be | |
9272 | associated with this strub mode. | |
9273 | ||
9274 | A function associated with @code{internal} @code{strub} mode | |
9275 | (@code{strub("internal")}) retains an unmodified, type-compatible | |
9276 | interface, but it may be turned into a wrapper that calls the wrapped | |
9277 | body using a custom interface. The wrapper then scrubs the stack space | |
9278 | used by the wrapped body. Though the wrapped body has its stack space | |
9279 | scrubbed, the wrapper does not, so arguments and return values may | |
9280 | remain unscrubbed even when such a function is called by another | |
9281 | function that enables @code{strub}. This is why, when compiling with | |
9282 | @option{-fstrub=strict}, a @code{strub} context is not allowed to call | |
9283 | @code{internal} @code{strub} functions. | |
9284 | ||
9285 | @smallexample | |
9286 | /* A declaration of an internal-strub function. */ | |
9287 | extern int __attribute__ ((strub ("internal"))) bar (void); | |
9288 | ||
9289 | int __attribute__ ((strub)) | |
9290 | baz (void) | |
9291 | @{ | |
9292 | /* Ok, foo was declared above as an at-calls strub function. */ | |
9293 | foo (); | |
9294 | /* Not allowed in strict mode, otherwise allowed. */ | |
9295 | bar (); | |
9296 | @} | |
9297 | @end smallexample | |
9298 | ||
9299 | An automatically-allocated variable associated with the @code{strub} | |
9300 | attribute causes the (immediately) enclosing function to have | |
9301 | @code{strub} enabled. | |
9302 | ||
9303 | A statically-allocated variable associated with the @code{strub} | |
9304 | attribute causes functions that @emph{read} it, through its @code{strub} | |
9305 | data type, to have @code{strub} enabled. Reading data by dereferencing | |
9306 | a pointer to a @code{strub} data type has the same effect. Note: The | |
9307 | attribute does not carry over from a composite type to the types of its | |
9308 | components, so the intended effect may not be obtained with non-scalar | |
9309 | types. | |
9310 | ||
9311 | When selecting a @code{strub}-enabled mode for a function that is not | |
9312 | explicitly associated with one, because of @code{strub} variables or | |
9313 | data pointers, the function must satisfy @code{internal} mode viability | |
9314 | requirements (see below), even when @code{at-calls} mode is also viable | |
9315 | and, being more efficient, ends up selected as an optimization. | |
9316 | ||
9317 | @smallexample | |
9318 | /* zapme is implicitly strub-enabled because of strub variables. | |
9319 | Optimization may change its strub mode, but not the requirements. */ | |
9320 | static int | |
9321 | zapme (int i) | |
9322 | @{ | |
9323 | /* A local strub variable enables strub. */ | |
9324 | int __attribute__ ((strub)) lvar; | |
9325 | /* Reading strub data through a pointer-to-strub enables strub. */ | |
9326 | lvar = * (ptr_to_strub_int_type) &i; | |
9327 | /* Writing to a global strub variable does not enable strub. */ | |
9328 | var = lvar; | |
9329 | /* Reading from a global strub variable enables strub. */ | |
9330 | return var; | |
9331 | @} | |
9332 | @end smallexample | |
9333 | ||
9334 | A @code{strub} context is the body (as opposed to the interface) of a | |
9335 | function that has @code{strub} enabled, be it explicitly, by | |
9336 | @code{at-calls} or @code{internal} mode, or implicitly, due to | |
9337 | @code{strub} variables or command-line options. | |
9338 | ||
9339 | A function of a type associated with the @code{disabled} @code{strub} | |
9340 | mode (@code{strub("disabled")} will not have its own stack space | |
9341 | scrubbed. Such functions @emph{cannot} be called from within | |
9342 | @code{strub} contexts. | |
9343 | ||
9344 | In order to enable a function to be called from within @code{strub} | |
9345 | contexts without having its stack space scrubbed, associate it with the | |
9346 | @code{callable} @code{strub} mode (@code{strub("callable")}). | |
9347 | ||
9348 | When a function is not assigned a @code{strub} mode, explicitly or | |
9349 | implicitly, the mode defaults to @code{callable}, except when compiling | |
9350 | with @option{-fstrub=strict}, that causes @code{strub} mode to default | |
9351 | to @code{disabled}. | |
9352 | ||
9353 | @example | |
9354 | extern int __attribute__ ((strub ("callable"))) bac (void); | |
9355 | extern int __attribute__ ((strub ("disabled"))) bad (void); | |
9356 | /* Implicitly disabled with -fstrub=strict, otherwise callable. */ | |
9357 | extern int bah (void); | |
9358 | ||
9359 | int __attribute__ ((strub)) | |
9360 | bal (void) | |
9361 | @{ | |
9362 | /* Not allowed, bad is not strub-callable. */ | |
9363 | bad (); | |
9364 | /* Ok, bac is strub-callable. */ | |
9365 | bac (); | |
9366 | /* Not allowed with -fstrub=strict, otherwise allowed. */ | |
9367 | bah (); | |
9368 | @} | |
9369 | @end example | |
9370 | ||
9371 | Function types marked @code{callable} and @code{disabled} are not | |
9372 | mutually compatible types, but the underlying interfaces are compatible, | |
9373 | so it is safe to convert pointers between them, and to use such pointers | |
9374 | or alternate declarations to call them. Interfaces are also | |
9375 | interchangeable between them and @code{internal} (but not | |
9376 | @code{at-calls}!), but adding @code{internal} to a pointer type will not | |
9377 | cause the pointed-to function to perform stack scrubbing. | |
9378 | ||
9379 | @example | |
9380 | void __attribute__ ((strub)) | |
9381 | bap (void) | |
9382 | @{ | |
9383 | /* Assign a callable function to pointer-to-disabled. | |
9384 | Flagged as not quite compatible with -Wpedantic. */ | |
9385 | int __attribute__ ((strub ("disabled"))) (*d_p) (void) = bac; | |
9386 | /* Not allowed: calls disabled type in a strub context. */ | |
9387 | d_p (); | |
9388 | ||
9389 | /* Assign a disabled function to pointer-to-callable. | |
9390 | Flagged as not quite compatible with -Wpedantic. */ | |
9391 | int __attribute__ ((strub ("callable"))) (*c_p) (void) = bad; | |
9392 | /* Ok, safe. */ | |
9393 | c_p (); | |
9394 | ||
9395 | /* Assign an internal function to pointer-to-callable. | |
9396 | Flagged as not quite compatible with -Wpedantic. */ | |
9397 | c_p = bar; | |
9398 | /* Ok, safe. */ | |
9399 | c_p (); | |
9400 | ||
9401 | /* Assign an at-calls function to pointer-to-callable. | |
9402 | Flaggged as incompatible. */ | |
9403 | c_p = bal; | |
9404 | /* The call through an interface-incompatible type will not use the | |
9405 | modified interface expected by the at-calls function, so it is | |
9406 | likely to misbehave at runtime. */ | |
9407 | c_p (); | |
9408 | @} | |
9409 | @end example | |
9410 | ||
9411 | @code{Strub} contexts are never inlined into non-@code{strub} contexts. | |
9412 | When an @code{internal}-strub function is split up, the wrapper can | |
9413 | often be inlined, but the wrapped body @emph{never} is. A function | |
9414 | marked as @code{always_inline}, even if explicitly assigned | |
9415 | @code{internal} strub mode, will not undergo wrapping, so its body gets | |
9416 | inlined as required. | |
9417 | ||
9418 | @example | |
9419 | inline int __attribute__ ((strub ("at-calls"))) | |
9420 | inl_atc (void) | |
9421 | @{ | |
9422 | /* This body may get inlined into strub contexts. */ | |
9423 | @} | |
9424 | ||
9425 | inline int __attribute__ ((strub ("internal"))) | |
9426 | inl_int (void) | |
9427 | @{ | |
9428 | /* This body NEVER gets inlined, though its wrapper may. */ | |
9429 | @} | |
9430 | ||
9431 | inline int __attribute__ ((strub ("internal"), always_inline)) | |
9432 | inl_int_ali (void) | |
9433 | @{ | |
9434 | /* No internal wrapper, so this body ALWAYS gets inlined, | |
9435 | but it cannot be called from non-strub contexts. */ | |
9436 | @} | |
9437 | ||
9438 | void __attribute__ ((strub ("disabled"))) | |
9439 | bat (void) | |
9440 | @{ | |
9441 | /* Not allowed, cannot inline into a non-strub context. */ | |
9442 | inl_int_ali (); | |
9443 | @} | |
9444 | @end example | |
9445 | ||
9446 | @cindex strub eligibility and viability | |
9447 | Some @option{-fstrub=*} command line options enable @code{strub} modes | |
9448 | implicitly where viable. A @code{strub} mode is only viable for a | |
9449 | function if the function is eligible for that mode, and if other | |
9450 | conditions, detailed below, are satisfied. If it's not eligible for a | |
9451 | mode, attempts to explicitly associate it with that mode are rejected | |
9452 | with an error message. If it is eligible, that mode may be assigned | |
9453 | explicitly through this attribute, but implicit assignment through | |
9454 | command-line options may involve additional viability requirements. | |
9455 | ||
9456 | A function is ineligible for @code{at-calls} @code{strub} mode if a | |
9457 | different @code{strub} mode is explicitly requested, if attribute | |
9458 | @code{noipa} is present, or if it calls @code{__builtin_apply_args}. | |
9459 | @code{At-calls} @code{strub} mode, if not requested through the function | |
9460 | type, is only viable for an eligible function if the function is not | |
9461 | visible to other translation units, if it doesn't have its address | |
9462 | taken, and if it is never called with a function type overrider. | |
9463 | ||
9464 | @smallexample | |
9465 | /* bar is eligible for at-calls strub mode, | |
9466 | but not viable for that mode because it is visible to other units. | |
9467 | It is eligible and viable for internal strub mode. */ | |
9468 | void bav () @{@} | |
9469 | ||
9470 | /* setp is eligible for at-calls strub mode, | |
9471 | but not viable for that mode because its address is taken. | |
9472 | It is eligible and viable for internal strub mode. */ | |
9473 | void setp (void) @{ static void (*p)(void); = setp; @} | |
9474 | @end smallexample | |
9475 | ||
9476 | A function is ineligible for @code{internal} @code{strub} mode if a | |
9477 | different @code{strub} mode is explicitly requested, or if attribute | |
9478 | @code{noipa} is present. For an @code{always_inline} function, meeting | |
9479 | these requirements is enough to make it eligible. Any function that has | |
9480 | attribute @code{noclone}, that uses such extensions as non-local labels, | |
9481 | computed gotos, alternate variable argument passing interfaces, | |
9482 | @code{__builtin_next_arg}, or @code{__builtin_return_address}, or that | |
9483 | takes too many (about 64Ki) arguments is ineligible, unless it is | |
9484 | @code{always_inline}. For @code{internal} @code{strub} mode, all | |
9485 | eligible functions are viable. | |
9486 | ||
9487 | @smallexample | |
9488 | /* flop is not eligible, thus not viable, for at-calls strub mode. | |
9489 | Likewise for internal strub mode. */ | |
9490 | __attribute__ ((noipa)) void flop (void) @{@} | |
9491 | ||
9492 | /* flip is eligible and viable for at-calls strub mode. | |
9493 | It would be ineligible for internal strub mode, because of noclone, | |
9494 | if it weren't for always_inline. With always_inline, noclone is not | |
9495 | an obstacle, so it is also eligible and viable for internal strub mode. */ | |
9496 | inline __attribute__ ((noclone, always_inline)) void flip (void) @{@} | |
9497 | @end smallexample | |
9498 | ||
d77de738 | 9499 | @cindex @code{unused} type attribute |
f33d7a88 | 9500 | @item unused |
d77de738 ML |
9501 | When attached to a type (including a @code{union} or a @code{struct}), |
9502 | this attribute means that variables of that type are meant to appear | |
9503 | possibly unused. GCC does not produce a warning for any variables of | |
9504 | that type, even if the variable appears to do nothing. This is often | |
9505 | the case with lock or thread classes, which are usually defined and then | |
9506 | not referenced, but contain constructors and destructors that have | |
9507 | nontrivial bookkeeping functions. | |
9508 | ||
d77de738 | 9509 | @cindex @code{vector_size} type attribute |
f33d7a88 | 9510 | @item vector_size (@var{bytes}) |
d77de738 ML |
9511 | This attribute specifies the vector size for the type, measured in bytes. |
9512 | The type to which it applies is known as the @dfn{base type}. The @var{bytes} | |
9513 | argument must be a positive power-of-two multiple of the base type size. For | |
9514 | example, the following declarations: | |
9515 | ||
9516 | @smallexample | |
9517 | typedef __attribute__ ((vector_size (32))) int int_vec32_t ; | |
9518 | typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t; | |
9519 | typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3]; | |
9520 | @end smallexample | |
9521 | ||
9522 | @noindent | |
9523 | define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int} | |
9524 | sized units. With @code{int} having a size of 4 bytes, the type defines | |
9525 | a vector of eight units, four bytes each. The mode of variables of type | |
9526 | @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined | |
9527 | to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be | |
9528 | an array of three such vectors. @xref{Vector Extensions}, for details of | |
9529 | manipulating objects of vector types. | |
9530 | ||
9531 | This attribute is only applicable to integral and floating scalar types. | |
9532 | In function declarations the attribute applies to the function return | |
9533 | type. | |
9534 | ||
9535 | For example, the following: | |
9536 | @smallexample | |
9537 | __attribute__ ((vector_size (16))) float get_flt_vec16 (void); | |
9538 | @end smallexample | |
9539 | declares @code{get_flt_vec16} to be a function returning a 16-byte vector | |
9540 | with the base type @code{float}. | |
9541 | ||
d77de738 | 9542 | @cindex @code{visibility} type attribute |
f33d7a88 | 9543 | @item visibility |
d77de738 ML |
9544 | In C++, attribute visibility (@pxref{Function Attributes}) can also be |
9545 | applied to class, struct, union and enum types. Unlike other type | |
9546 | attributes, the attribute must appear between the initial keyword and | |
9547 | the name of the type; it cannot appear after the body of the type. | |
9548 | ||
9549 | Note that the type visibility is applied to vague linkage entities | |
9550 | associated with the class (vtable, typeinfo node, etc.). In | |
9551 | particular, if a class is thrown as an exception in one shared object | |
9552 | and caught in another, the class must have default visibility. | |
9553 | Otherwise the two shared objects are unable to use the same | |
9554 | typeinfo node and exception handling will break. | |
9555 | ||
d77de738 | 9556 | @cindex @code{objc_root_class} type attribute |
f33d7a88 | 9557 | @item objc_root_class @r{(Objective-C and Objective-C++ only)} |
d77de738 ML |
9558 | This attribute marks a class as being a root class, and thus allows |
9559 | the compiler to elide any warnings about a missing superclass and to | |
9560 | make additional checks for mandatory methods as needed. | |
9561 | ||
9562 | @end table | |
9563 | ||
9564 | To specify multiple attributes, separate them by commas within the | |
9565 | double parentheses: for example, @samp{__attribute__ ((aligned (16), | |
9566 | packed))}. | |
9567 | ||
9568 | @node ARC Type Attributes | |
9569 | @subsection ARC Type Attributes | |
9570 | ||
9571 | @cindex @code{uncached} type attribute, ARC | |
9572 | Declaring objects with @code{uncached} allows you to exclude | |
9573 | data-cache participation in load and store operations on those objects | |
9574 | without involving the additional semantic implications of | |
9575 | @code{volatile}. The @code{.di} instruction suffix is used for all | |
9576 | loads and stores of data declared @code{uncached}. | |
9577 | ||
9578 | @node ARM Type Attributes | |
9579 | @subsection ARM Type Attributes | |
9580 | ||
9581 | @cindex @code{notshared} type attribute, ARM | |
9582 | On those ARM targets that support @code{dllimport} (such as Symbian | |
9583 | OS), you can use the @code{notshared} attribute to indicate that the | |
9584 | virtual table and other similar data for a class should not be | |
9585 | exported from a DLL@. For example: | |
9586 | ||
9587 | @smallexample | |
9588 | class __declspec(notshared) C @{ | |
9589 | public: | |
9590 | __declspec(dllimport) C(); | |
9591 | virtual void f(); | |
9592 | @} | |
9593 | ||
9594 | __declspec(dllexport) | |
9595 | C::C() @{@} | |
9596 | @end smallexample | |
9597 | ||
9598 | @noindent | |
9599 | In this code, @code{C::C} is exported from the current DLL, but the | |
9600 | virtual table for @code{C} is not exported. (You can use | |
9601 | @code{__attribute__} instead of @code{__declspec} if you prefer, but | |
9602 | most Symbian OS code uses @code{__declspec}.) | |
9603 | ||
9604 | @node BPF Type Attributes | |
9605 | @subsection BPF Type Attributes | |
9606 | ||
9607 | @cindex @code{preserve_access_index} type attribute, BPF | |
9608 | BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a | |
9609 | @code{struct} or @code{union} type definition, indicates that CO-RE | |
9610 | relocation information should be generated for any access to a variable | |
9611 | of that type. The behavior is equivalent to the programmer manually | |
9612 | wrapping every such access with @code{__builtin_preserve_access_index}. | |
9613 | ||
9614 | ||
d77de738 ML |
9615 | @node PowerPC Type Attributes |
9616 | @subsection PowerPC Type Attributes | |
9617 | ||
9618 | Three attributes currently are defined for PowerPC configurations: | |
9619 | @code{altivec}, @code{ms_struct} and @code{gcc_struct}. | |
9620 | ||
9621 | @cindex @code{ms_struct} type attribute, PowerPC | |
9622 | @cindex @code{gcc_struct} type attribute, PowerPC | |
9623 | For full documentation of the @code{ms_struct} and @code{gcc_struct} | |
9624 | attributes please see the documentation in @ref{x86 Type Attributes}. | |
9625 | ||
9626 | @cindex @code{altivec} type attribute, PowerPC | |
9627 | The @code{altivec} attribute allows one to declare AltiVec vector data | |
9628 | types supported by the AltiVec Programming Interface Manual. The | |
9629 | attribute requires an argument to specify one of three vector types: | |
9630 | @code{vector__}, @code{pixel__} (always followed by unsigned short), | |
9631 | and @code{bool__} (always followed by unsigned). | |
9632 | ||
9633 | @smallexample | |
9634 | __attribute__((altivec(vector__))) | |
9635 | __attribute__((altivec(pixel__))) unsigned short | |
9636 | __attribute__((altivec(bool__))) unsigned | |
9637 | @end smallexample | |
9638 | ||
9639 | These attributes mainly are intended to support the @code{__vector}, | |
9640 | @code{__pixel}, and @code{__bool} AltiVec keywords. | |
9641 | ||
9642 | @node x86 Type Attributes | |
9643 | @subsection x86 Type Attributes | |
9644 | ||
9645 | Two attributes are currently defined for x86 configurations: | |
9646 | @code{ms_struct} and @code{gcc_struct}. | |
9647 | ||
9648 | @table @code | |
9649 | ||
d77de738 ML |
9650 | @cindex @code{ms_struct} type attribute, x86 |
9651 | @cindex @code{gcc_struct} type attribute, x86 | |
f33d7a88 AA |
9652 | @item ms_struct |
9653 | @itemx gcc_struct | |
d77de738 ML |
9654 | |
9655 | If @code{packed} is used on a structure, or if bit-fields are used | |
9656 | it may be that the Microsoft ABI packs them differently | |
9657 | than GCC normally packs them. Particularly when moving packed | |
9658 | data between functions compiled with GCC and the native Microsoft compiler | |
9659 | (either via function call or as data in a file), it may be necessary to access | |
9660 | either format. | |
9661 | ||
9662 | The @code{ms_struct} and @code{gcc_struct} attributes correspond | |
9663 | to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} | |
9664 | command-line options, respectively; | |
9665 | see @ref{x86 Options}, for details of how structure layout is affected. | |
9666 | @xref{x86 Variable Attributes}, for information about the corresponding | |
9667 | attributes on variables. | |
9668 | ||
9669 | @end table | |
9670 | ||
9671 | @node Label Attributes | |
9672 | @section Label Attributes | |
9673 | @cindex Label Attributes | |
9674 | ||
9675 | GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for | |
9676 | details of the exact syntax for using attributes. Other attributes are | |
9677 | available for functions (@pxref{Function Attributes}), variables | |
9678 | (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}), | |
9679 | statements (@pxref{Statement Attributes}), and for types | |
9680 | (@pxref{Type Attributes}). A label attribute followed | |
9681 | by a declaration appertains to the label and not the declaration. | |
9682 | ||
9683 | This example uses the @code{cold} label attribute to indicate the | |
9684 | @code{ErrorHandling} branch is unlikely to be taken and that the | |
9685 | @code{ErrorHandling} label is unused: | |
9686 | ||
9687 | @smallexample | |
9688 | ||
9689 | asm goto ("some asm" : : : : NoError); | |
9690 | ||
9691 | /* This branch (the fall-through from the asm) is less commonly used */ | |
9692 | ErrorHandling: | |
9693 | __attribute__((cold, unused)); /* Semi-colon is required here */ | |
9694 | printf("error\n"); | |
9695 | return 0; | |
9696 | ||
9697 | NoError: | |
9698 | printf("no error\n"); | |
9699 | return 1; | |
9700 | @end smallexample | |
9701 | ||
9702 | @table @code | |
d77de738 | 9703 | @cindex @code{unused} label attribute |
f33d7a88 | 9704 | @item unused |
d77de738 ML |
9705 | This feature is intended for program-generated code that may contain |
9706 | unused labels, but which is compiled with @option{-Wall}. It is | |
9707 | not normally appropriate to use in it human-written code, though it | |
9708 | could be useful in cases where the code that jumps to the label is | |
9709 | contained within an @code{#ifdef} conditional. | |
9710 | ||
d77de738 | 9711 | @cindex @code{hot} label attribute |
f33d7a88 | 9712 | @item hot |
d77de738 ML |
9713 | The @code{hot} attribute on a label is used to inform the compiler that |
9714 | the path following the label is more likely than paths that are not so | |
9715 | annotated. This attribute is used in cases where @code{__builtin_expect} | |
9716 | cannot be used, for instance with computed goto or @code{asm goto}. | |
9717 | ||
d77de738 | 9718 | @cindex @code{cold} label attribute |
f33d7a88 | 9719 | @item cold |
d77de738 ML |
9720 | The @code{cold} attribute on labels is used to inform the compiler that |
9721 | the path following the label is unlikely to be executed. This attribute | |
9722 | is used in cases where @code{__builtin_expect} cannot be used, for instance | |
9723 | with computed goto or @code{asm goto}. | |
9724 | ||
9725 | @end table | |
9726 | ||
9727 | @node Enumerator Attributes | |
9728 | @section Enumerator Attributes | |
9729 | @cindex Enumerator Attributes | |
9730 | ||
9731 | GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for | |
9732 | details of the exact syntax for using attributes. Other attributes are | |
9733 | available for functions (@pxref{Function Attributes}), variables | |
9734 | (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements | |
9735 | (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). | |
9736 | ||
9737 | This example uses the @code{deprecated} enumerator attribute to indicate the | |
9738 | @code{oldval} enumerator is deprecated: | |
9739 | ||
9740 | @smallexample | |
9741 | enum E @{ | |
9742 | oldval __attribute__((deprecated)), | |
9743 | newval | |
9744 | @}; | |
9745 | ||
9746 | int | |
9747 | fn (void) | |
9748 | @{ | |
9749 | return oldval; | |
9750 | @} | |
9751 | @end smallexample | |
9752 | ||
9753 | @table @code | |
d77de738 | 9754 | @cindex @code{deprecated} enumerator attribute |
f33d7a88 | 9755 | @item deprecated |
d77de738 ML |
9756 | The @code{deprecated} attribute results in a warning if the enumerator |
9757 | is used anywhere in the source file. This is useful when identifying | |
9758 | enumerators that are expected to be removed in a future version of a | |
9759 | program. The warning also includes the location of the declaration | |
9760 | of the deprecated enumerator, to enable users to easily find further | |
9761 | information about why the enumerator is deprecated, or what they should | |
9762 | do instead. Note that the warnings only occurs for uses. | |
9763 | ||
d77de738 | 9764 | @cindex @code{unavailable} enumerator attribute |
f33d7a88 | 9765 | @item unavailable |
d77de738 ML |
9766 | The @code{unavailable} attribute results in an error if the enumerator |
9767 | is used anywhere in the source file. In other respects it behaves in the | |
9768 | same manner as the @code{deprecated} attribute. | |
9769 | ||
9770 | @end table | |
9771 | ||
9772 | @node Statement Attributes | |
9773 | @section Statement Attributes | |
9774 | @cindex Statement Attributes | |
9775 | ||
9776 | GCC allows attributes to be set on null statements. @xref{Attribute Syntax}, | |
9777 | for details of the exact syntax for using attributes. Other attributes are | |
9778 | available for functions (@pxref{Function Attributes}), variables | |
9779 | (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators | |
9780 | (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}). | |
9781 | ||
9782 | @table @code | |
d77de738 | 9783 | @cindex @code{fallthrough} statement attribute |
f33d7a88 | 9784 | @item fallthrough |
d77de738 ML |
9785 | The @code{fallthrough} attribute with a null statement serves as a |
9786 | fallthrough statement. It hints to the compiler that a statement | |
9787 | that falls through to another case label, or user-defined label | |
9788 | in a switch statement is intentional and thus the | |
9789 | @option{-Wimplicit-fallthrough} warning must not trigger. The | |
9790 | fallthrough attribute may appear at most once in each attribute | |
9791 | list, and may not be mixed with other attributes. It can only | |
9792 | be used in a switch statement (the compiler will issue an error | |
9793 | otherwise), after a preceding statement and before a logically | |
9794 | succeeding case label, or user-defined label. | |
9795 | ||
9796 | This example uses the @code{fallthrough} statement attribute to indicate that | |
9797 | the @option{-Wimplicit-fallthrough} warning should not be emitted: | |
9798 | ||
9799 | @smallexample | |
9800 | switch (cond) | |
9801 | @{ | |
9802 | case 1: | |
9803 | bar (1); | |
9804 | __attribute__((fallthrough)); | |
9805 | case 2: | |
9806 | @dots{} | |
9807 | @} | |
9808 | @end smallexample | |
9809 | ||
d77de738 | 9810 | @cindex @code{assume} statement attribute |
f33d7a88 | 9811 | @item assume |
d77de738 ML |
9812 | The @code{assume} attribute with a null statement serves as portable |
9813 | assumption. It should have a single argument, a conditional expression, | |
9814 | which is not evaluated. If the argument would evaluate to true | |
9815 | at the point where it appears, it has no effect, otherwise there | |
9816 | is undefined behavior. This is a GNU variant of the ISO C++23 | |
9817 | standard @code{assume} attribute, but it can be used in any version of | |
9818 | both C and C++. | |
9819 | ||
9820 | @smallexample | |
9821 | int | |
9822 | foo (int x, int y) | |
9823 | @{ | |
9824 | __attribute__((assume(x == 42))); | |
9825 | __attribute__((assume(++y == 43))); | |
9826 | return x + y; | |
9827 | @} | |
9828 | @end smallexample | |
9829 | ||
9830 | @code{y} is not actually incremented and the compiler can but does not | |
9831 | have to optimize it to just @code{return 42 + 42;}. | |
9832 | ||
9833 | @end table | |
9834 | ||
9835 | @node Attribute Syntax | |
9836 | @section Attribute Syntax | |
9837 | @cindex attribute syntax | |
837a12a2 SL |
9838 | @cindex C standard attributes |
9839 | @cindex C++ standard attributes | |
9840 | @cindex standard attribute syntax | |
9841 | @cindex GNU attribute syntax | |
9842 | ||
9843 | GCC provides two different ways to specify attributes: the standard C | |
9844 | and C++ syntax using double square brackets, and the older GNU | |
9845 | extension syntax using the @code{@w{__attribute__}} keyword, which predates | |
9846 | the adoption of the standard syntax and is still widely used in older | |
9847 | code. | |
9848 | ||
9849 | The standard @samp{[[]]} attribute syntax is recognized by GCC's | |
9850 | default language dialect for both C and C++. More specifically, this | |
9851 | syntax was first introduced in the C++11 language standard | |
9852 | (@pxref{Standards}), and is supported by GCC in C++ code with | |
9853 | @option{-std=c++11} or @option{-std=gnu++11} or later. It is also | |
fad61bf7 JM |
9854 | part of the C23 language standard and is supported when compiling C |
9855 | code with @option{-std=c23} or @option{-std=gnu17} or later. | |
837a12a2 SL |
9856 | |
9857 | When using GNU-specific attributes in the standard syntax, you must | |
9858 | prefix their names with @samp{gnu::}, such as @code{gnu::section}. | |
9859 | Refer to the relevant language standards for exact details on the | |
9860 | placement of @samp{[[]]} attributes within your code, as they differ | |
9861 | in some details from the rules for the GNU attribute syntax. | |
9862 | ||
9863 | The remainder of this section describes the details of the GNU extension | |
9864 | @code{__attribute__} syntax, | |
9865 | and the constructs to which attribute specifiers bind, for the C | |
d77de738 | 9866 | language. Some details may vary for C++ and Objective-C@. Because of |
d9922e4b | 9867 | limitations in the grammar for attributes, some forms described here |
d77de738 ML |
9868 | may not be successfully parsed in all cases. |
9869 | ||
9870 | There are some problems with the semantics of attributes in C++. For | |
9871 | example, there are no manglings for attributes, although they may affect | |
9872 | code generation, so problems may arise when attributed types are used in | |
9873 | conjunction with templates or overloading. Similarly, @code{typeid} | |
9874 | does not distinguish between types with different attributes. Support | |
9875 | for attributes in C++ may be restricted in future to attributes on | |
9876 | declarations only, but not on nested declarators. | |
9877 | ||
9878 | @xref{Function Attributes}, for details of the semantics of attributes | |
9879 | applying to functions. @xref{Variable Attributes}, for details of the | |
9880 | semantics of attributes applying to variables. @xref{Type Attributes}, | |
9881 | for details of the semantics of attributes applying to structure, union | |
9882 | and enumerated types. | |
9883 | @xref{Label Attributes}, for details of the semantics of attributes | |
9884 | applying to labels. | |
9885 | @xref{Enumerator Attributes}, for details of the semantics of attributes | |
9886 | applying to enumerators. | |
9887 | @xref{Statement Attributes}, for details of the semantics of attributes | |
9888 | applying to statements. | |
9889 | ||
9890 | An @dfn{attribute specifier} is of the form | |
9891 | @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} | |
9892 | is a possibly empty comma-separated sequence of @dfn{attributes}, where | |
9893 | each attribute is one of the following: | |
9894 | ||
9895 | @itemize @bullet | |
9896 | @item | |
9897 | Empty. Empty attributes are ignored. | |
9898 | ||
9899 | @item | |
9900 | An attribute name | |
9901 | (which may be an identifier such as @code{unused}, or a reserved | |
9902 | word such as @code{const}). | |
9903 | ||
9904 | @item | |
9905 | An attribute name followed by a parenthesized list of | |
9906 | parameters for the attribute. | |
9907 | These parameters take one of the following forms: | |
9908 | ||
9909 | @itemize @bullet | |
9910 | @item | |
9911 | An identifier. For example, @code{mode} attributes use this form. | |
9912 | ||
9913 | @item | |
9914 | An identifier followed by a comma and a non-empty comma-separated list | |
9915 | of expressions. For example, @code{format} attributes use this form. | |
9916 | ||
9917 | @item | |
9918 | A possibly empty comma-separated list of expressions. For example, | |
9919 | @code{format_arg} attributes use this form with the list being a single | |
9920 | integer constant expression, and @code{alias} attributes use this form | |
9921 | with the list being a single string constant. | |
9922 | @end itemize | |
9923 | @end itemize | |
9924 | ||
9925 | An @dfn{attribute specifier list} is a sequence of one or more attribute | |
9926 | specifiers, not separated by any other tokens. | |
9927 | ||
9928 | You may optionally specify attribute names with @samp{__} | |
9929 | preceding and following the name. | |
9930 | This allows you to use them in header files without | |
9931 | being concerned about a possible macro of the same name. For example, | |
9932 | you may use the attribute name @code{__noreturn__} instead of @code{noreturn}. | |
9933 | ||
9934 | ||
9935 | @subsubheading Label Attributes | |
9936 | ||
9937 | In GNU C, an attribute specifier list may appear after the colon following a | |
9938 | label, other than a @code{case} or @code{default} label. GNU C++ only permits | |
9939 | attributes on labels if the attribute specifier is immediately | |
9940 | followed by a semicolon (i.e., the label applies to an empty | |
9941 | statement). If the semicolon is missing, C++ label attributes are | |
9942 | ambiguous, as it is permissible for a declaration, which could begin | |
9943 | with an attribute list, to be labelled in C++. Declarations cannot be | |
9944 | labelled in C90 or C99, so the ambiguity does not arise there. | |
9945 | ||
9946 | @subsubheading Enumerator Attributes | |
9947 | ||
9948 | In GNU C, an attribute specifier list may appear as part of an enumerator. | |
9949 | The attribute goes after the enumeration constant, before @code{=}, if | |
9950 | present. The optional attribute in the enumerator appertains to the | |
9951 | enumeration constant. It is not possible to place the attribute after | |
9952 | the constant expression, if present. | |
9953 | ||
9954 | @subsubheading Statement Attributes | |
9955 | In GNU C, an attribute specifier list may appear as part of a null | |
9956 | statement. The attribute goes before the semicolon. | |
9957 | ||
9958 | @subsubheading Type Attributes | |
9959 | ||
9960 | An attribute specifier list may appear as part of a @code{struct}, | |
9961 | @code{union} or @code{enum} specifier. It may go either immediately | |
9962 | after the @code{struct}, @code{union} or @code{enum} keyword, or after | |
9963 | the closing brace. The former syntax is preferred. | |
9964 | Where attribute specifiers follow the closing brace, they are considered | |
9965 | to relate to the structure, union or enumerated type defined, not to any | |
9966 | enclosing declaration the type specifier appears in, and the type | |
9967 | defined is not complete until after the attribute specifiers. | |
9968 | @c Otherwise, there would be the following problems: a shift/reduce | |
9969 | @c conflict between attributes binding the struct/union/enum and | |
9970 | @c binding to the list of specifiers/qualifiers; and "aligned" | |
9971 | @c attributes could use sizeof for the structure, but the size could be | |
9972 | @c changed later by "packed" attributes. | |
9973 | ||
9974 | ||
9975 | @subsubheading All other attributes | |
9976 | ||
9977 | Otherwise, an attribute specifier appears as part of a declaration, | |
9978 | counting declarations of unnamed parameters and type names, and relates | |
9979 | to that declaration (which may be nested in another declaration, for | |
9980 | example in the case of a parameter declaration), or to a particular declarator | |
9981 | within a declaration. Where an | |
9982 | attribute specifier is applied to a parameter declared as a function or | |
9983 | an array, it should apply to the function or array rather than the | |
9984 | pointer to which the parameter is implicitly converted, but this is not | |
9985 | yet correctly implemented. | |
9986 | ||
9987 | Any list of specifiers and qualifiers at the start of a declaration may | |
9988 | contain attribute specifiers, whether or not such a list may in that | |
9989 | context contain storage class specifiers. (Some attributes, however, | |
9990 | are essentially in the nature of storage class specifiers, and only make | |
9991 | sense where storage class specifiers may be used; for example, | |
9992 | @code{section}.) There is one necessary limitation to this syntax: the | |
9993 | first old-style parameter declaration in a function definition cannot | |
9994 | begin with an attribute specifier, because such an attribute applies to | |
9995 | the function instead by syntax described below (which, however, is not | |
9996 | yet implemented in this case). In some other cases, attribute | |
9997 | specifiers are permitted by this grammar but not yet supported by the | |
9998 | compiler. All attribute specifiers in this place relate to the | |
9999 | declaration as a whole. In the obsolescent usage where a type of | |
10000 | @code{int} is implied by the absence of type specifiers, such a list of | |
10001 | specifiers and qualifiers may be an attribute specifier list with no | |
10002 | other specifiers or qualifiers. | |
10003 | ||
10004 | At present, the first parameter in a function prototype must have some | |
10005 | type specifier that is not an attribute specifier; this resolves an | |
10006 | ambiguity in the interpretation of @code{void f(int | |
10007 | (__attribute__((foo)) x))}, but is subject to change. At present, if | |
10008 | the parentheses of a function declarator contain only attributes then | |
10009 | those attributes are ignored, rather than yielding an error or warning | |
10010 | or implying a single parameter of type int, but this is subject to | |
10011 | change. | |
10012 | ||
10013 | An attribute specifier list may appear immediately before a declarator | |
10014 | (other than the first) in a comma-separated list of declarators in a | |
10015 | declaration of more than one identifier using a single list of | |
10016 | specifiers and qualifiers. Such attribute specifiers apply | |
10017 | only to the identifier before whose declarator they appear. For | |
10018 | example, in | |
10019 | ||
10020 | @smallexample | |
10021 | __attribute__((noreturn)) void d0 (void), | |
10022 | __attribute__((format(printf, 1, 2))) d1 (const char *, ...), | |
10023 | d2 (void); | |
10024 | @end smallexample | |
10025 | ||
10026 | @noindent | |
10027 | the @code{noreturn} attribute applies to all the functions | |
10028 | declared; the @code{format} attribute only applies to @code{d1}. | |
10029 | ||
10030 | An attribute specifier list may appear immediately before the comma, | |
10031 | @code{=} or semicolon terminating the declaration of an identifier other | |
10032 | than a function definition. Such attribute specifiers apply | |
10033 | to the declared object or function. Where an | |
10034 | assembler name for an object or function is specified (@pxref{Asm | |
10035 | Labels}), the attribute must follow the @code{asm} | |
10036 | specification. | |
10037 | ||
10038 | An attribute specifier list may, in future, be permitted to appear after | |
10039 | the declarator in a function definition (before any old-style parameter | |
10040 | declarations or the function body). | |
10041 | ||
10042 | Attribute specifiers may be mixed with type qualifiers appearing inside | |
10043 | the @code{[]} of a parameter array declarator, in the C99 construct by | |
10044 | which such qualifiers are applied to the pointer to which the array is | |
10045 | implicitly converted. Such attribute specifiers apply to the pointer, | |
10046 | not to the array, but at present this is not implemented and they are | |
10047 | ignored. | |
10048 | ||
10049 | An attribute specifier list may appear at the start of a nested | |
10050 | declarator. At present, there are some limitations in this usage: the | |
10051 | attributes correctly apply to the declarator, but for most individual | |
10052 | attributes the semantics this implies are not implemented. | |
10053 | When attribute specifiers follow the @code{*} of a pointer | |
10054 | declarator, they may be mixed with any type qualifiers present. | |
10055 | The following describes the formal semantics of this syntax. It makes the | |
10056 | most sense if you are familiar with the formal specification of | |
10057 | declarators in the ISO C standard. | |
10058 | ||
10059 | Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T | |
10060 | D1}, where @code{T} contains declaration specifiers that specify a type | |
10061 | @var{Type} (such as @code{int}) and @code{D1} is a declarator that | |
10062 | contains an identifier @var{ident}. The type specified for @var{ident} | |
10063 | for derived declarators whose type does not include an attribute | |
10064 | specifier is as in the ISO C standard. | |
10065 | ||
10066 | If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, | |
10067 | and the declaration @code{T D} specifies the type | |
10068 | ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then | |
10069 | @code{T D1} specifies the type ``@var{derived-declarator-type-list} | |
10070 | @var{attribute-specifier-list} @var{Type}'' for @var{ident}. | |
10071 | ||
10072 | If @code{D1} has the form @code{* | |
10073 | @var{type-qualifier-and-attribute-specifier-list} D}, and the | |
10074 | declaration @code{T D} specifies the type | |
10075 | ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then | |
10076 | @code{T D1} specifies the type ``@var{derived-declarator-type-list} | |
10077 | @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for | |
10078 | @var{ident}. | |
10079 | ||
10080 | For example, | |
10081 | ||
10082 | @smallexample | |
10083 | void (__attribute__((noreturn)) ****f) (void); | |
10084 | @end smallexample | |
10085 | ||
10086 | @noindent | |
10087 | specifies the type ``pointer to pointer to pointer to pointer to | |
10088 | non-returning function returning @code{void}''. As another example, | |
10089 | ||
10090 | @smallexample | |
10091 | char *__attribute__((aligned(8))) *f; | |
10092 | @end smallexample | |
10093 | ||
10094 | @noindent | |
10095 | specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. | |
10096 | Note again that this does not work with most attributes; for example, | |
10097 | the usage of @samp{aligned} and @samp{noreturn} attributes given above | |
10098 | is not yet supported. | |
10099 | ||
10100 | For compatibility with existing code written for compiler versions that | |
10101 | did not implement attributes on nested declarators, some laxity is | |
10102 | allowed in the placing of attributes. If an attribute that only applies | |
10103 | to types is applied to a declaration, it is treated as applying to | |
10104 | the type of that declaration. If an attribute that only applies to | |
10105 | declarations is applied to the type of a declaration, it is treated | |
10106 | as applying to that declaration; and, for compatibility with code | |
10107 | placing the attributes immediately before the identifier declared, such | |
10108 | an attribute applied to a function return type is treated as | |
10109 | applying to the function type, and such an attribute applied to an array | |
10110 | element type is treated as applying to the array type. If an | |
10111 | attribute that only applies to function types is applied to a | |
10112 | pointer-to-function type, it is treated as applying to the pointer | |
10113 | target type; if such an attribute is applied to a function return type | |
10114 | that is not a pointer-to-function type, it is treated as applying | |
10115 | to the function type. | |
10116 | ||
10117 | @node Function Prototypes | |
10118 | @section Prototypes and Old-Style Function Definitions | |
10119 | @cindex function prototype declarations | |
10120 | @cindex old-style function definitions | |
10121 | @cindex promotion of formal parameters | |
10122 | ||
10123 | GNU C extends ISO C to allow a function prototype to override a later | |
10124 | old-style non-prototype definition. Consider the following example: | |
10125 | ||
10126 | @smallexample | |
10127 | /* @r{Use prototypes unless the compiler is old-fashioned.} */ | |
10128 | #ifdef __STDC__ | |
10129 | #define P(x) x | |
10130 | #else | |
10131 | #define P(x) () | |
10132 | #endif | |
10133 | ||
10134 | /* @r{Prototype function declaration.} */ | |
10135 | int isroot P((uid_t)); | |
10136 | ||
10137 | /* @r{Old-style function definition.} */ | |
10138 | int | |
10139 | isroot (x) /* @r{??? lossage here ???} */ | |
10140 | uid_t x; | |
10141 | @{ | |
10142 | return x == 0; | |
10143 | @} | |
10144 | @end smallexample | |
10145 | ||
10146 | Suppose the type @code{uid_t} happens to be @code{short}. ISO C does | |
10147 | not allow this example, because subword arguments in old-style | |
10148 | non-prototype definitions are promoted. Therefore in this example the | |
10149 | function definition's argument is really an @code{int}, which does not | |
10150 | match the prototype argument type of @code{short}. | |
10151 | ||
10152 | This restriction of ISO C makes it hard to write code that is portable | |
10153 | to traditional C compilers, because the programmer does not know | |
10154 | whether the @code{uid_t} type is @code{short}, @code{int}, or | |
10155 | @code{long}. Therefore, in cases like these GNU C allows a prototype | |
10156 | to override a later old-style definition. More precisely, in GNU C, a | |
10157 | function prototype argument type overrides the argument type specified | |
10158 | by a later old-style definition if the former type is the same as the | |
10159 | latter type before promotion. Thus in GNU C the above example is | |
10160 | equivalent to the following: | |
10161 | ||
10162 | @smallexample | |
10163 | int isroot (uid_t); | |
10164 | ||
10165 | int | |
10166 | isroot (uid_t x) | |
10167 | @{ | |
10168 | return x == 0; | |
10169 | @} | |
10170 | @end smallexample | |
10171 | ||
10172 | @noindent | |
10173 | GNU C++ does not support old-style function definitions, so this | |
10174 | extension is irrelevant. | |
10175 | ||
10176 | @node C++ Comments | |
10177 | @section C++ Style Comments | |
10178 | @cindex @code{//} | |
10179 | @cindex C++ comments | |
10180 | @cindex comments, C++ style | |
10181 | ||
10182 | In GNU C, you may use C++ style comments, which start with @samp{//} and | |
10183 | continue until the end of the line. Many other C implementations allow | |
10184 | such comments, and they are included in the 1999 C standard. However, | |
10185 | C++ style comments are not recognized if you specify an @option{-std} | |
10186 | option specifying a version of ISO C before C99, or @option{-ansi} | |
10187 | (equivalent to @option{-std=c90}). | |
10188 | ||
10189 | @node Dollar Signs | |
10190 | @section Dollar Signs in Identifier Names | |
10191 | @cindex $ | |
10192 | @cindex dollar signs in identifier names | |
10193 | @cindex identifier names, dollar signs in | |
10194 | ||
10195 | In GNU C, you may normally use dollar signs in identifier names. | |
10196 | This is because many traditional C implementations allow such identifiers. | |
10197 | However, dollar signs in identifiers are not supported on a few target | |
10198 | machines, typically because the target assembler does not allow them. | |
10199 | ||
10200 | @node Character Escapes | |
10201 | @section The Character @key{ESC} in Constants | |
10202 | ||
10203 | You can use the sequence @samp{\e} in a string or character constant to | |
10204 | stand for the ASCII character @key{ESC}. | |
10205 | ||
10206 | @node Alignment | |
10207 | @section Determining the Alignment of Functions, Types or Variables | |
10208 | @cindex alignment | |
10209 | @cindex type alignment | |
10210 | @cindex variable alignment | |
10211 | ||
10212 | The keyword @code{__alignof__} determines the alignment requirement of | |
10213 | a function, object, or a type, or the minimum alignment usually required | |
10214 | by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}. | |
10215 | ||
10216 | For example, if the target machine requires a @code{double} value to be | |
10217 | aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. | |
10218 | This is true on many RISC machines. On more traditional machine | |
10219 | designs, @code{__alignof__ (double)} is 4 or even 2. | |
10220 | ||
10221 | Some machines never actually require alignment; they allow references to any | |
10222 | data type even at an odd address. For these machines, @code{__alignof__} | |
10223 | reports the smallest alignment that GCC gives the data type, usually as | |
10224 | mandated by the target ABI. | |
10225 | ||
10226 | If the operand of @code{__alignof__} is an lvalue rather than a type, | |
10227 | its value is the required alignment for its type, taking into account | |
10228 | any minimum alignment specified by attribute @code{aligned} | |
10229 | (@pxref{Common Variable Attributes}). For example, after this | |
10230 | declaration: | |
10231 | ||
10232 | @smallexample | |
10233 | struct foo @{ int x; char y; @} foo1; | |
10234 | @end smallexample | |
10235 | ||
10236 | @noindent | |
10237 | the value of @code{__alignof__ (foo1.y)} is 1, even though its actual | |
10238 | alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. | |
10239 | It is an error to ask for the alignment of an incomplete type other | |
10240 | than @code{void}. | |
10241 | ||
10242 | If the operand of the @code{__alignof__} expression is a function, | |
10243 | the expression evaluates to the alignment of the function which may | |
10244 | be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). | |
10245 | ||
10246 | @node Inline | |
10247 | @section An Inline Function is As Fast As a Macro | |
10248 | @cindex inline functions | |
10249 | @cindex integrating function code | |
10250 | @cindex open coding | |
10251 | @cindex macros, inline alternative | |
10252 | ||
10253 | By declaring a function inline, you can direct GCC to make | |
10254 | calls to that function faster. One way GCC can achieve this is to | |
10255 | integrate that function's code into the code for its callers. This | |
10256 | makes execution faster by eliminating the function-call overhead; in | |
10257 | addition, if any of the actual argument values are constant, their | |
10258 | known values may permit simplifications at compile time so that not | |
10259 | all of the inline function's code needs to be included. The effect on | |
10260 | code size is less predictable; object code may be larger or smaller | |
10261 | with function inlining, depending on the particular case. You can | |
10262 | also direct GCC to try to integrate all ``simple enough'' functions | |
10263 | into their callers with the option @option{-finline-functions}. | |
10264 | ||
10265 | GCC implements three different semantics of declaring a function | |
10266 | inline. One is available with @option{-std=gnu89} or | |
10267 | @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present | |
10268 | on all inline declarations, another when | |
10269 | @option{-std=c99}, | |
10270 | @option{-std=gnu99} or an option for a later C version is used | |
10271 | (without @option{-fgnu89-inline}), and the third | |
10272 | is used when compiling C++. | |
10273 | ||
10274 | To declare a function inline, use the @code{inline} keyword in its | |
10275 | declaration, like this: | |
10276 | ||
10277 | @smallexample | |
10278 | static inline int | |
10279 | inc (int *a) | |
10280 | @{ | |
10281 | return (*a)++; | |
10282 | @} | |
10283 | @end smallexample | |
10284 | ||
10285 | If you are writing a header file to be included in ISO C90 programs, write | |
10286 | @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. | |
10287 | ||
10288 | The three types of inlining behave similarly in two important cases: | |
10289 | when the @code{inline} keyword is used on a @code{static} function, | |
10290 | like the example above, and when a function is first declared without | |
10291 | using the @code{inline} keyword and then is defined with | |
10292 | @code{inline}, like this: | |
10293 | ||
10294 | @smallexample | |
10295 | extern int inc (int *a); | |
10296 | inline int | |
10297 | inc (int *a) | |
10298 | @{ | |
10299 | return (*a)++; | |
10300 | @} | |
10301 | @end smallexample | |
10302 | ||
10303 | In both of these common cases, the program behaves the same as if you | |
10304 | had not used the @code{inline} keyword, except for its speed. | |
10305 | ||
10306 | @cindex inline functions, omission of | |
10307 | @opindex fkeep-inline-functions | |
10308 | When a function is both inline and @code{static}, if all calls to the | |
10309 | function are integrated into the caller, and the function's address is | |
10310 | never used, then the function's own assembler code is never referenced. | |
10311 | In this case, GCC does not actually output assembler code for the | |
10312 | function, unless you specify the option @option{-fkeep-inline-functions}. | |
10313 | If there is a nonintegrated call, then the function is compiled to | |
10314 | assembler code as usual. The function must also be compiled as usual if | |
10315 | the program refers to its address, because that cannot be inlined. | |
10316 | ||
10317 | @opindex Winline | |
10318 | Note that certain usages in a function definition can make it unsuitable | |
10319 | for inline substitution. Among these usages are: variadic functions, | |
10320 | use of @code{alloca}, use of computed goto (@pxref{Labels as Values}), | |
10321 | use of nonlocal goto, use of nested functions, use of @code{setjmp}, use | |
10322 | of @code{__builtin_longjmp} and use of @code{__builtin_return} or | |
10323 | @code{__builtin_apply_args}. Using @option{-Winline} warns when a | |
10324 | function marked @code{inline} could not be substituted, and gives the | |
10325 | reason for the failure. | |
10326 | ||
10327 | @cindex automatic @code{inline} for C++ member fns | |
10328 | @cindex @code{inline} automatic for C++ member fns | |
10329 | @cindex member fns, automatically @code{inline} | |
10330 | @cindex C++ member fns, automatically @code{inline} | |
10331 | @opindex fno-default-inline | |
10332 | As required by ISO C++, GCC considers member functions defined within | |
10333 | the body of a class to be marked inline even if they are | |
10334 | not explicitly declared with the @code{inline} keyword. You can | |
10335 | override this with @option{-fno-default-inline}; @pxref{C++ Dialect | |
10336 | Options,,Options Controlling C++ Dialect}. | |
10337 | ||
10338 | GCC does not inline any functions when not optimizing unless you specify | |
10339 | the @samp{always_inline} attribute for the function, like this: | |
10340 | ||
10341 | @smallexample | |
10342 | /* @r{Prototype.} */ | |
10343 | inline void foo (const char) __attribute__((always_inline)); | |
10344 | @end smallexample | |
10345 | ||
10346 | The remainder of this section is specific to GNU C90 inlining. | |
10347 | ||
10348 | @cindex non-static inline function | |
10349 | When an inline function is not @code{static}, then the compiler must assume | |
10350 | that there may be calls from other source files; since a global symbol can | |
10351 | be defined only once in any program, the function must not be defined in | |
10352 | the other source files, so the calls therein cannot be integrated. | |
10353 | Therefore, a non-@code{static} inline function is always compiled on its | |
10354 | own in the usual fashion. | |
10355 | ||
10356 | If you specify both @code{inline} and @code{extern} in the function | |
10357 | definition, then the definition is used only for inlining. In no case | |
10358 | is the function compiled on its own, not even if you refer to its | |
10359 | address explicitly. Such an address becomes an external reference, as | |
10360 | if you had only declared the function, and had not defined it. | |
10361 | ||
10362 | This combination of @code{inline} and @code{extern} has almost the | |
10363 | effect of a macro. The way to use it is to put a function definition in | |
10364 | a header file with these keywords, and put another copy of the | |
10365 | definition (lacking @code{inline} and @code{extern}) in a library file. | |
10366 | The definition in the header file causes most calls to the function | |
10367 | to be inlined. If any uses of the function remain, they refer to | |
10368 | the single copy in the library. | |
10369 | ||
10370 | @node Volatiles | |
10371 | @section When is a Volatile Object Accessed? | |
10372 | @cindex accessing volatiles | |
10373 | @cindex volatile read | |
10374 | @cindex volatile write | |
10375 | @cindex volatile access | |
10376 | ||
10377 | C has the concept of volatile objects. These are normally accessed by | |
10378 | pointers and used for accessing hardware or inter-thread | |
10379 | communication. The standard encourages compilers to refrain from | |
10380 | optimizations concerning accesses to volatile objects, but leaves it | |
10381 | implementation defined as to what constitutes a volatile access. The | |
10382 | minimum requirement is that at a sequence point all previous accesses | |
10383 | to volatile objects have stabilized and no subsequent accesses have | |
10384 | occurred. Thus an implementation is free to reorder and combine | |
10385 | volatile accesses that occur between sequence points, but cannot do | |
10386 | so for accesses across a sequence point. The use of volatile does | |
10387 | not allow you to violate the restriction on updating objects multiple | |
10388 | times between two sequence points. | |
10389 | ||
10390 | Accesses to non-volatile objects are not ordered with respect to | |
10391 | volatile accesses. You cannot use a volatile object as a memory | |
10392 | barrier to order a sequence of writes to non-volatile memory. For | |
10393 | instance: | |
10394 | ||
10395 | @smallexample | |
10396 | int *ptr = @var{something}; | |
10397 | volatile int vobj; | |
10398 | *ptr = @var{something}; | |
10399 | vobj = 1; | |
10400 | @end smallexample | |
10401 | ||
10402 | @noindent | |
10403 | Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed | |
10404 | that the write to @var{*ptr} occurs by the time the update | |
10405 | of @var{vobj} happens. If you need this guarantee, you must use | |
10406 | a stronger memory barrier such as: | |
10407 | ||
10408 | @smallexample | |
10409 | int *ptr = @var{something}; | |
10410 | volatile int vobj; | |
10411 | *ptr = @var{something}; | |
10412 | asm volatile ("" : : : "memory"); | |
10413 | vobj = 1; | |
10414 | @end smallexample | |
10415 | ||
10416 | A scalar volatile object is read when it is accessed in a void context: | |
10417 | ||
10418 | @smallexample | |
10419 | volatile int *src = @var{somevalue}; | |
10420 | *src; | |
10421 | @end smallexample | |
10422 | ||
10423 | Such expressions are rvalues, and GCC implements this as a | |
10424 | read of the volatile object being pointed to. | |
10425 | ||
10426 | Assignments are also expressions and have an rvalue. However when | |
10427 | assigning to a scalar volatile, the volatile object is not reread, | |
10428 | regardless of whether the assignment expression's rvalue is used or | |
10429 | not. If the assignment's rvalue is used, the value is that assigned | |
10430 | to the volatile object. For instance, there is no read of @var{vobj} | |
10431 | in all the following cases: | |
10432 | ||
10433 | @smallexample | |
10434 | int obj; | |
10435 | volatile int vobj; | |
10436 | vobj = @var{something}; | |
10437 | obj = vobj = @var{something}; | |
10438 | obj ? vobj = @var{onething} : vobj = @var{anotherthing}; | |
10439 | obj = (@var{something}, vobj = @var{anotherthing}); | |
10440 | @end smallexample | |
10441 | ||
10442 | If you need to read the volatile object after an assignment has | |
10443 | occurred, you must use a separate expression with an intervening | |
10444 | sequence point. | |
10445 | ||
10446 | As bit-fields are not individually addressable, volatile bit-fields may | |
10447 | be implicitly read when written to, or when adjacent bit-fields are | |
10448 | accessed. Bit-field operations may be optimized such that adjacent | |
10449 | bit-fields are only partially accessed, if they straddle a storage unit | |
10450 | boundary. For these reasons it is unwise to use volatile bit-fields to | |
10451 | access hardware. | |
10452 | ||
10453 | @node Using Assembly Language with C | |
10454 | @section How to Use Inline Assembly Language in C Code | |
10455 | @cindex @code{asm} keyword | |
10456 | @cindex assembly language in C | |
10457 | @cindex inline assembly language | |
10458 | @cindex mixing assembly language and C | |
10459 | ||
10460 | The @code{asm} keyword allows you to embed assembler instructions | |
10461 | within C code. GCC provides two forms of inline @code{asm} | |
10462 | statements. A @dfn{basic @code{asm}} statement is one with no | |
10463 | operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}} | |
10464 | statement (@pxref{Extended Asm}) includes one or more operands. | |
10465 | The extended form is preferred for mixing C and assembly language | |
10466 | within a function, but to include assembly language at | |
10467 | top level you must use basic @code{asm}. | |
10468 | ||
10469 | You can also use the @code{asm} keyword to override the assembler name | |
10470 | for a C symbol, or to place a C variable in a specific register. | |
10471 | ||
10472 | @menu | |
10473 | * Basic Asm:: Inline assembler without operands. | |
10474 | * Extended Asm:: Inline assembler with operands. | |
10475 | * Constraints:: Constraints for @code{asm} operands | |
10476 | * Asm Labels:: Specifying the assembler name to use for a C symbol. | |
10477 | * Explicit Register Variables:: Defining variables residing in specified | |
10478 | registers. | |
10479 | * Size of an asm:: How GCC calculates the size of an @code{asm} block. | |
10480 | @end menu | |
10481 | ||
10482 | @node Basic Asm | |
10483 | @subsection Basic Asm --- Assembler Instructions Without Operands | |
10484 | @cindex basic @code{asm} | |
10485 | @cindex assembly language in C, basic | |
10486 | ||
10487 | A basic @code{asm} statement has the following syntax: | |
10488 | ||
10489 | @example | |
10490 | asm @var{asm-qualifiers} ( @var{AssemblerInstructions} ) | |
10491 | @end example | |
10492 | ||
10493 | For the C language, the @code{asm} keyword is a GNU extension. | |
10494 | When writing C code that can be compiled with @option{-ansi} and the | |
10495 | @option{-std} options that select C dialects without GNU extensions, use | |
10496 | @code{__asm__} instead of @code{asm} (@pxref{Alternate Keywords}). For | |
10497 | the C++ language, @code{asm} is a standard keyword, but @code{__asm__} | |
10498 | can be used for code compiled with @option{-fno-asm}. | |
10499 | ||
10500 | @subsubheading Qualifiers | |
10501 | @table @code | |
10502 | @item volatile | |
10503 | The optional @code{volatile} qualifier has no effect. | |
10504 | All basic @code{asm} blocks are implicitly volatile. | |
10505 | ||
10506 | @item inline | |
10507 | If you use the @code{inline} qualifier, then for inlining purposes the size | |
10508 | of the @code{asm} statement is taken as the smallest size possible (@pxref{Size | |
10509 | of an asm}). | |
10510 | @end table | |
10511 | ||
10512 | @subsubheading Parameters | |
10513 | @table @var | |
10514 | ||
10515 | @item AssemblerInstructions | |
10516 | This is a literal string that specifies the assembler code. The string can | |
10517 | contain any instructions recognized by the assembler, including directives. | |
10518 | GCC does not parse the assembler instructions themselves and | |
10519 | does not know what they mean or even whether they are valid assembler input. | |
10520 | ||
10521 | You may place multiple assembler instructions together in a single @code{asm} | |
10522 | string, separated by the characters normally used in assembly code for the | |
10523 | system. A combination that works in most places is a newline to break the | |
10524 | line, plus a tab character (written as @samp{\n\t}). | |
10525 | Some assemblers allow semicolons as a line separator. However, | |
10526 | note that some assembler dialects use semicolons to start a comment. | |
10527 | @end table | |
10528 | ||
10529 | @subsubheading Remarks | |
10530 | Using extended @code{asm} (@pxref{Extended Asm}) typically produces | |
10531 | smaller, safer, and more efficient code, and in most cases it is a | |
10532 | better solution than basic @code{asm}. However, there are two | |
10533 | situations where only basic @code{asm} can be used: | |
10534 | ||
10535 | @itemize @bullet | |
10536 | @item | |
10537 | Extended @code{asm} statements have to be inside a C | |
10538 | function, so to write inline assembly language at file scope (``top-level''), | |
10539 | outside of C functions, you must use basic @code{asm}. | |
10540 | You can use this technique to emit assembler directives, | |
10541 | define assembly language macros that can be invoked elsewhere in the file, | |
10542 | or write entire functions in assembly language. | |
10543 | Basic @code{asm} statements outside of functions may not use any | |
10544 | qualifiers. | |
10545 | ||
10546 | @item | |
10547 | Functions declared | |
10548 | with the @code{naked} attribute also require basic @code{asm} | |
10549 | (@pxref{Function Attributes}). | |
10550 | @end itemize | |
10551 | ||
10552 | Safely accessing C data and calling functions from basic @code{asm} is more | |
10553 | complex than it may appear. To access C data, it is better to use extended | |
10554 | @code{asm}. | |
10555 | ||
10556 | Do not expect a sequence of @code{asm} statements to remain perfectly | |
10557 | consecutive after compilation. If certain instructions need to remain | |
10558 | consecutive in the output, put them in a single multi-instruction @code{asm} | |
10559 | statement. Note that GCC's optimizers can move @code{asm} statements | |
10560 | relative to other code, including across jumps. | |
10561 | ||
10562 | @code{asm} statements may not perform jumps into other @code{asm} statements. | |
10563 | GCC does not know about these jumps, and therefore cannot take | |
10564 | account of them when deciding how to optimize. Jumps from @code{asm} to C | |
10565 | labels are only supported in extended @code{asm}. | |
10566 | ||
10567 | Under certain circumstances, GCC may duplicate (or remove duplicates of) your | |
10568 | assembly code when optimizing. This can lead to unexpected duplicate | |
10569 | symbol errors during compilation if your assembly code defines symbols or | |
10570 | labels. | |
10571 | ||
10572 | @strong{Warning:} The C standards do not specify semantics for @code{asm}, | |
10573 | making it a potential source of incompatibilities between compilers. These | |
10574 | incompatibilities may not produce compiler warnings/errors. | |
10575 | ||
10576 | GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which | |
10577 | means there is no way to communicate to the compiler what is happening | |
10578 | inside them. GCC has no visibility of symbols in the @code{asm} and may | |
10579 | discard them as unreferenced. It also does not know about side effects of | |
10580 | the assembler code, such as modifications to memory or registers. Unlike | |
10581 | some compilers, GCC assumes that no changes to general purpose registers | |
10582 | occur. This assumption may change in a future release. | |
10583 | ||
10584 | To avoid complications from future changes to the semantics and the | |
10585 | compatibility issues between compilers, consider replacing basic @code{asm} | |
10586 | with extended @code{asm}. See | |
10587 | @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert | |
10588 | from basic asm to extended asm} for information about how to perform this | |
10589 | conversion. | |
10590 | ||
10591 | The compiler copies the assembler instructions in a basic @code{asm} | |
10592 | verbatim to the assembly language output file, without | |
10593 | processing dialects or any of the @samp{%} operators that are available with | |
10594 | extended @code{asm}. This results in minor differences between basic | |
10595 | @code{asm} strings and extended @code{asm} templates. For example, to refer to | |
10596 | registers you might use @samp{%eax} in basic @code{asm} and | |
10597 | @samp{%%eax} in extended @code{asm}. | |
10598 | ||
10599 | On targets such as x86 that support multiple assembler dialects, | |
10600 | all basic @code{asm} blocks use the assembler dialect specified by the | |
10601 | @option{-masm} command-line option (@pxref{x86 Options}). | |
10602 | Basic @code{asm} provides no | |
10603 | mechanism to provide different assembler strings for different dialects. | |
10604 | ||
10605 | For basic @code{asm} with non-empty assembler string GCC assumes | |
10606 | the assembler block does not change any general purpose registers, | |
10607 | but it may read or write any globally accessible variable. | |
10608 | ||
10609 | Here is an example of basic @code{asm} for i386: | |
10610 | ||
10611 | @example | |
10612 | /* Note that this code will not compile with -masm=intel */ | |
10613 | #define DebugBreak() asm("int $3") | |
10614 | @end example | |
10615 | ||
10616 | @node Extended Asm | |
10617 | @subsection Extended Asm - Assembler Instructions with C Expression Operands | |
10618 | @cindex extended @code{asm} | |
10619 | @cindex assembly language in C, extended | |
10620 | ||
10621 | With extended @code{asm} you can read and write C variables from | |
10622 | assembler and perform jumps from assembler code to C labels. | |
10623 | Extended @code{asm} syntax uses colons (@samp{:}) to delimit | |
10624 | the operand parameters after the assembler template: | |
10625 | ||
10626 | @example | |
10627 | asm @var{asm-qualifiers} ( @var{AssemblerTemplate} | |
10628 | : @var{OutputOperands} | |
10629 | @r{[} : @var{InputOperands} | |
10630 | @r{[} : @var{Clobbers} @r{]} @r{]}) | |
10631 | ||
10632 | asm @var{asm-qualifiers} ( @var{AssemblerTemplate} | |
10633 | : @var{OutputOperands} | |
10634 | : @var{InputOperands} | |
10635 | : @var{Clobbers} | |
10636 | : @var{GotoLabels}) | |
10637 | @end example | |
10638 | where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the | |
10639 | first form, not). | |
10640 | ||
10641 | The @code{asm} keyword is a GNU extension. | |
10642 | When writing code that can be compiled with @option{-ansi} and the | |
10643 | various @option{-std} options, use @code{__asm__} instead of | |
10644 | @code{asm} (@pxref{Alternate Keywords}). | |
10645 | ||
10646 | @subsubheading Qualifiers | |
10647 | @table @code | |
10648 | ||
10649 | @item volatile | |
10650 | The typical use of extended @code{asm} statements is to manipulate input | |
10651 | values to produce output values. However, your @code{asm} statements may | |
10652 | also produce side effects. If so, you may need to use the @code{volatile} | |
10653 | qualifier to disable certain optimizations. @xref{Volatile}. | |
10654 | ||
10655 | @item inline | |
10656 | If you use the @code{inline} qualifier, then for inlining purposes the size | |
10657 | of the @code{asm} statement is taken as the smallest size possible | |
10658 | (@pxref{Size of an asm}). | |
10659 | ||
10660 | @item goto | |
10661 | This qualifier informs the compiler that the @code{asm} statement may | |
10662 | perform a jump to one of the labels listed in the @var{GotoLabels}. | |
10663 | @xref{GotoLabels}. | |
10664 | @end table | |
10665 | ||
10666 | @subsubheading Parameters | |
10667 | @table @var | |
10668 | @item AssemblerTemplate | |
10669 | This is a literal string that is the template for the assembler code. It is a | |
10670 | combination of fixed text and tokens that refer to the input, output, | |
10671 | and goto parameters. @xref{AssemblerTemplate}. | |
10672 | ||
10673 | @item OutputOperands | |
10674 | A comma-separated list of the C variables modified by the instructions in the | |
10675 | @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}. | |
10676 | ||
10677 | @item InputOperands | |
10678 | A comma-separated list of C expressions read by the instructions in the | |
10679 | @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}. | |
10680 | ||
10681 | @item Clobbers | |
10682 | A comma-separated list of registers or other values changed by the | |
10683 | @var{AssemblerTemplate}, beyond those listed as outputs. | |
10684 | An empty list is permitted. @xref{Clobbers and Scratch Registers}. | |
10685 | ||
10686 | @item GotoLabels | |
10687 | When you are using the @code{goto} form of @code{asm}, this section contains | |
10688 | the list of all C labels to which the code in the | |
10689 | @var{AssemblerTemplate} may jump. | |
10690 | @xref{GotoLabels}. | |
10691 | ||
10692 | @code{asm} statements may not perform jumps into other @code{asm} statements, | |
10693 | only to the listed @var{GotoLabels}. | |
10694 | GCC's optimizers do not know about other jumps; therefore they cannot take | |
10695 | account of them when deciding how to optimize. | |
10696 | @end table | |
10697 | ||
10698 | The total number of input + output + goto operands is limited to 30. | |
10699 | ||
10700 | @subsubheading Remarks | |
10701 | The @code{asm} statement allows you to include assembly instructions directly | |
10702 | within C code. This may help you to maximize performance in time-sensitive | |
10703 | code or to access assembly instructions that are not readily available to C | |
10704 | programs. | |
10705 | ||
10706 | Note that extended @code{asm} statements must be inside a function. Only | |
10707 | basic @code{asm} may be outside functions (@pxref{Basic Asm}). | |
10708 | Functions declared with the @code{naked} attribute also require basic | |
10709 | @code{asm} (@pxref{Function Attributes}). | |
10710 | ||
10711 | While the uses of @code{asm} are many and varied, it may help to think of an | |
10712 | @code{asm} statement as a series of low-level instructions that convert input | |
10713 | parameters to output parameters. So a simple (if not particularly useful) | |
10714 | example for i386 using @code{asm} might look like this: | |
10715 | ||
10716 | @example | |
10717 | int src = 1; | |
10718 | int dst; | |
10719 | ||
10720 | asm ("mov %1, %0\n\t" | |
10721 | "add $1, %0" | |
10722 | : "=r" (dst) | |
10723 | : "r" (src)); | |
10724 | ||
10725 | printf("%d\n", dst); | |
10726 | @end example | |
10727 | ||
10728 | This code copies @code{src} to @code{dst} and add 1 to @code{dst}. | |
10729 | ||
10730 | @anchor{Volatile} | |
10731 | @subsubsection Volatile | |
10732 | @cindex volatile @code{asm} | |
10733 | @cindex @code{asm} volatile | |
10734 | ||
10735 | GCC's optimizers sometimes discard @code{asm} statements if they determine | |
10736 | there is no need for the output variables. Also, the optimizers may move | |
10737 | code out of loops if they believe that the code will always return the same | |
10738 | result (i.e.@: none of its input values change between calls). Using the | |
10739 | @code{volatile} qualifier disables these optimizations. @code{asm} statements | |
10740 | that have no output operands and @code{asm goto} statements, | |
10741 | are implicitly volatile. | |
10742 | ||
10743 | This i386 code demonstrates a case that does not use (or require) the | |
10744 | @code{volatile} qualifier. If it is performing assertion checking, this code | |
10745 | uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is | |
10746 | unreferenced by any code. As a result, the optimizers can discard the | |
10747 | @code{asm} statement, which in turn removes the need for the entire | |
10748 | @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it | |
10749 | isn't needed you allow the optimizers to produce the most efficient code | |
10750 | possible. | |
10751 | ||
10752 | @example | |
10753 | void DoCheck(uint32_t dwSomeValue) | |
10754 | @{ | |
10755 | uint32_t dwRes; | |
10756 | ||
10757 | // Assumes dwSomeValue is not zero. | |
10758 | asm ("bsfl %1,%0" | |
10759 | : "=r" (dwRes) | |
10760 | : "r" (dwSomeValue) | |
10761 | : "cc"); | |
10762 | ||
10763 | assert(dwRes > 3); | |
10764 | @} | |
10765 | @end example | |
10766 | ||
10767 | The next example shows a case where the optimizers can recognize that the input | |
10768 | (@code{dwSomeValue}) never changes during the execution of the function and can | |
10769 | therefore move the @code{asm} outside the loop to produce more efficient code. | |
10770 | Again, using the @code{volatile} qualifier disables this type of optimization. | |
10771 | ||
10772 | @example | |
10773 | void do_print(uint32_t dwSomeValue) | |
10774 | @{ | |
10775 | uint32_t dwRes; | |
10776 | ||
10777 | for (uint32_t x=0; x < 5; x++) | |
10778 | @{ | |
10779 | // Assumes dwSomeValue is not zero. | |
10780 | asm ("bsfl %1,%0" | |
10781 | : "=r" (dwRes) | |
10782 | : "r" (dwSomeValue) | |
10783 | : "cc"); | |
10784 | ||
10785 | printf("%u: %u %u\n", x, dwSomeValue, dwRes); | |
10786 | @} | |
10787 | @} | |
10788 | @end example | |
10789 | ||
10790 | The following example demonstrates a case where you need to use the | |
10791 | @code{volatile} qualifier. | |
10792 | It uses the x86 @code{rdtsc} instruction, which reads | |
10793 | the computer's time-stamp counter. Without the @code{volatile} qualifier, | |
10794 | the optimizers might assume that the @code{asm} block will always return the | |
10795 | same value and therefore optimize away the second call. | |
10796 | ||
10797 | @example | |
10798 | uint64_t msr; | |
10799 | ||
10800 | asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. | |
10801 | "shl $32, %%rdx\n\t" // Shift the upper bits left. | |
10802 | "or %%rdx, %0" // 'Or' in the lower bits. | |
10803 | : "=a" (msr) | |
10804 | : | |
10805 | : "rdx"); | |
10806 | ||
10807 | printf("msr: %llx\n", msr); | |
10808 | ||
10809 | // Do other work... | |
10810 | ||
10811 | // Reprint the timestamp | |
10812 | asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. | |
10813 | "shl $32, %%rdx\n\t" // Shift the upper bits left. | |
10814 | "or %%rdx, %0" // 'Or' in the lower bits. | |
10815 | : "=a" (msr) | |
10816 | : | |
10817 | : "rdx"); | |
10818 | ||
10819 | printf("msr: %llx\n", msr); | |
10820 | @end example | |
10821 | ||
10822 | GCC's optimizers do not treat this code like the non-volatile code in the | |
10823 | earlier examples. They do not move it out of loops or omit it on the | |
10824 | assumption that the result from a previous call is still valid. | |
10825 | ||
10826 | Note that the compiler can move even @code{volatile asm} instructions relative | |
10827 | to other code, including across jump instructions. For example, on many | |
10828 | targets there is a system register that controls the rounding mode of | |
10829 | floating-point operations. Setting it with a @code{volatile asm} statement, | |
10830 | as in the following PowerPC example, does not work reliably. | |
10831 | ||
10832 | @example | |
10833 | asm volatile("mtfsf 255, %0" : : "f" (fpenv)); | |
10834 | sum = x + y; | |
10835 | @end example | |
10836 | ||
10837 | The compiler may move the addition back before the @code{volatile asm} | |
10838 | statement. To make it work as expected, add an artificial dependency to | |
10839 | the @code{asm} by referencing a variable in the subsequent code, for | |
10840 | example: | |
10841 | ||
10842 | @example | |
10843 | asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv)); | |
10844 | sum = x + y; | |
10845 | @end example | |
10846 | ||
10847 | Under certain circumstances, GCC may duplicate (or remove duplicates of) your | |
10848 | assembly code when optimizing. This can lead to unexpected duplicate symbol | |
10849 | errors during compilation if your @code{asm} code defines symbols or labels. | |
10850 | Using @samp{%=} | |
10851 | (@pxref{AssemblerTemplate}) may help resolve this problem. | |
10852 | ||
10853 | @anchor{AssemblerTemplate} | |
10854 | @subsubsection Assembler Template | |
10855 | @cindex @code{asm} assembler template | |
10856 | ||
10857 | An assembler template is a literal string containing assembler instructions. | |
10858 | The compiler replaces tokens in the template that refer | |
10859 | to inputs, outputs, and goto labels, | |
10860 | and then outputs the resulting string to the assembler. The | |
10861 | string can contain any instructions recognized by the assembler, including | |
10862 | directives. GCC does not parse the assembler instructions | |
10863 | themselves and does not know what they mean or even whether they are valid | |
10864 | assembler input. However, it does count the statements | |
10865 | (@pxref{Size of an asm}). | |
10866 | ||
10867 | You may place multiple assembler instructions together in a single @code{asm} | |
10868 | string, separated by the characters normally used in assembly code for the | |
10869 | system. A combination that works in most places is a newline to break the | |
10870 | line, plus a tab character to move to the instruction field (written as | |
10871 | @samp{\n\t}). | |
10872 | Some assemblers allow semicolons as a line separator. However, note | |
10873 | that some assembler dialects use semicolons to start a comment. | |
10874 | ||
10875 | Do not expect a sequence of @code{asm} statements to remain perfectly | |
10876 | consecutive after compilation, even when you are using the @code{volatile} | |
10877 | qualifier. If certain instructions need to remain consecutive in the output, | |
10878 | put them in a single multi-instruction @code{asm} statement. | |
10879 | ||
10880 | Accessing data from C programs without using input/output operands (such as | |
10881 | by using global symbols directly from the assembler template) may not work as | |
10882 | expected. Similarly, calling functions directly from an assembler template | |
10883 | requires a detailed understanding of the target assembler and ABI. | |
10884 | ||
10885 | Since GCC does not parse the assembler template, | |
10886 | it has no visibility of any | |
10887 | symbols it references. This may result in GCC discarding those symbols as | |
10888 | unreferenced unless they are also listed as input, output, or goto operands. | |
10889 | ||
10890 | @subsubheading Special format strings | |
10891 | ||
10892 | In addition to the tokens described by the input, output, and goto operands, | |
10893 | these tokens have special meanings in the assembler template: | |
10894 | ||
10895 | @table @samp | |
10896 | @item %% | |
10897 | Outputs a single @samp{%} into the assembler code. | |
10898 | ||
10899 | @item %= | |
10900 | Outputs a number that is unique to each instance of the @code{asm} | |
10901 | statement in the entire compilation. This option is useful when creating local | |
10902 | labels and referring to them multiple times in a single template that | |
10903 | generates multiple assembler instructions. | |
10904 | ||
10905 | @item %@{ | |
10906 | @itemx %| | |
10907 | @itemx %@} | |
10908 | Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively) | |
10909 | into the assembler code. When unescaped, these characters have special | |
10910 | meaning to indicate multiple assembler dialects, as described below. | |
10911 | @end table | |
10912 | ||
10913 | @subsubheading Multiple assembler dialects in @code{asm} templates | |
10914 | ||
10915 | On targets such as x86, GCC supports multiple assembler dialects. | |
10916 | The @option{-masm} option controls which dialect GCC uses as its | |
10917 | default for inline assembler. The target-specific documentation for the | |
10918 | @option{-masm} option contains the list of supported dialects, as well as the | |
10919 | default dialect if the option is not specified. This information may be | |
10920 | important to understand, since assembler code that works correctly when | |
10921 | compiled using one dialect will likely fail if compiled using another. | |
10922 | @xref{x86 Options}. | |
10923 | ||
10924 | If your code needs to support multiple assembler dialects (for example, if | |
10925 | you are writing public headers that need to support a variety of compilation | |
10926 | options), use constructs of this form: | |
10927 | ||
10928 | @example | |
10929 | @{ dialect0 | dialect1 | dialect2... @} | |
10930 | @end example | |
10931 | ||
10932 | This construct outputs @code{dialect0} | |
10933 | when using dialect #0 to compile the code, | |
10934 | @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the | |
10935 | braces than the number of dialects the compiler supports, the construct | |
10936 | outputs nothing. | |
10937 | ||
10938 | For example, if an x86 compiler supports two dialects | |
10939 | (@samp{att}, @samp{intel}), an | |
10940 | assembler template such as this: | |
10941 | ||
10942 | @example | |
10943 | "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2" | |
10944 | @end example | |
10945 | ||
10946 | @noindent | |
10947 | is equivalent to one of | |
10948 | ||
10949 | @example | |
10950 | "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */} | |
10951 | "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */} | |
10952 | @end example | |
10953 | ||
10954 | Using that same compiler, this code: | |
10955 | ||
10956 | @example | |
10957 | "xchg@{l@}\t@{%%@}ebx, %1" | |
10958 | @end example | |
10959 | ||
10960 | @noindent | |
10961 | corresponds to either | |
10962 | ||
10963 | @example | |
10964 | "xchgl\t%%ebx, %1" @r{/* att dialect */} | |
10965 | "xchg\tebx, %1" @r{/* intel dialect */} | |
10966 | @end example | |
10967 | ||
10968 | There is no support for nesting dialect alternatives. | |
10969 | ||
10970 | @anchor{OutputOperands} | |
10971 | @subsubsection Output Operands | |
10972 | @cindex @code{asm} output operands | |
10973 | ||
10974 | An @code{asm} statement has zero or more output operands indicating the names | |
10975 | of C variables modified by the assembler code. | |
10976 | ||
10977 | In this i386 example, @code{old} (referred to in the template string as | |
10978 | @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset} | |
10979 | (@code{%2}) is an input: | |
10980 | ||
10981 | @example | |
10982 | bool old; | |
10983 | ||
10984 | __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base. | |
10985 | "sbb %0,%0" // Use the CF to calculate old. | |
10986 | : "=r" (old), "+rm" (*Base) | |
10987 | : "Ir" (Offset) | |
10988 | : "cc"); | |
10989 | ||
10990 | return old; | |
10991 | @end example | |
10992 | ||
10993 | Operands are separated by commas. Each operand has this format: | |
10994 | ||
10995 | @example | |
10996 | @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename}) | |
10997 | @end example | |
10998 | ||
10999 | @table @var | |
11000 | @item asmSymbolicName | |
11001 | Specifies a symbolic name for the operand. | |
11002 | Reference the name in the assembler template | |
11003 | by enclosing it in square brackets | |
11004 | (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement | |
11005 | that contains the definition. Any valid C variable name is acceptable, | |
11006 | including names already defined in the surrounding code. No two operands | |
11007 | within the same @code{asm} statement can use the same symbolic name. | |
11008 | ||
11009 | When not using an @var{asmSymbolicName}, use the (zero-based) position | |
11010 | of the operand | |
11011 | in the list of operands in the assembler template. For example if there are | |
11012 | three output operands, use @samp{%0} in the template to refer to the first, | |
11013 | @samp{%1} for the second, and @samp{%2} for the third. | |
11014 | ||
11015 | @item constraint | |
11016 | A string constant specifying constraints on the placement of the operand; | |
11017 | @xref{Constraints}, for details. | |
11018 | ||
11019 | Output constraints must begin with either @samp{=} (a variable overwriting an | |
11020 | existing value) or @samp{+} (when reading and writing). When using | |
11021 | @samp{=}, do not assume the location contains the existing value | |
11022 | on entry to the @code{asm}, except | |
11023 | when the operand is tied to an input; @pxref{InputOperands,,Input Operands}. | |
11024 | ||
11025 | After the prefix, there must be one or more additional constraints | |
11026 | (@pxref{Constraints}) that describe where the value resides. Common | |
11027 | constraints include @samp{r} for register and @samp{m} for memory. | |
11028 | When you list more than one possible location (for example, @code{"=rm"}), | |
11029 | the compiler chooses the most efficient one based on the current context. | |
11030 | If you list as many alternates as the @code{asm} statement allows, you permit | |
11031 | the optimizers to produce the best possible code. | |
11032 | If you must use a specific register, but your Machine Constraints do not | |
11033 | provide sufficient control to select the specific register you want, | |
11034 | local register variables may provide a solution (@pxref{Local Register | |
11035 | Variables}). | |
11036 | ||
11037 | @item cvariablename | |
11038 | Specifies a C lvalue expression to hold the output, typically a variable name. | |
11039 | The enclosing parentheses are a required part of the syntax. | |
11040 | ||
11041 | @end table | |
11042 | ||
11043 | When the compiler selects the registers to use to | |
11044 | represent the output operands, it does not use any of the clobbered registers | |
11045 | (@pxref{Clobbers and Scratch Registers}). | |
11046 | ||
11047 | Output operand expressions must be lvalues. The compiler cannot check whether | |
11048 | the operands have data types that are reasonable for the instruction being | |
11049 | executed. For output expressions that are not directly addressable (for | |
11050 | example a bit-field), the constraint must allow a register. In that case, GCC | |
11051 | uses the register as the output of the @code{asm}, and then stores that | |
11052 | register into the output. | |
11053 | ||
11054 | Operands using the @samp{+} constraint modifier count as two operands | |
11055 | (that is, both as input and output) towards the total maximum of 30 operands | |
11056 | per @code{asm} statement. | |
11057 | ||
11058 | Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output | |
11059 | operands that must not overlap an input. Otherwise, | |
11060 | GCC may allocate the output operand in the same register as an unrelated | |
11061 | input operand, on the assumption that the assembler code consumes its | |
11062 | inputs before producing outputs. This assumption may be false if the assembler | |
11063 | code actually consists of more than one instruction. | |
11064 | ||
11065 | The same problem can occur if one output parameter (@var{a}) allows a register | |
11066 | constraint and another output parameter (@var{b}) allows a memory constraint. | |
11067 | The code generated by GCC to access the memory address in @var{b} can contain | |
11068 | registers which @emph{might} be shared by @var{a}, and GCC considers those | |
11069 | registers to be inputs to the asm. As above, GCC assumes that such input | |
11070 | registers are consumed before any outputs are written. This assumption may | |
11071 | result in incorrect behavior if the @code{asm} statement writes to @var{a} | |
11072 | before using | |
11073 | @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a} | |
11074 | ensures that modifying @var{a} does not affect the address referenced by | |
11075 | @var{b}. Otherwise, the location of @var{b} | |
11076 | is undefined if @var{a} is modified before using @var{b}. | |
11077 | ||
11078 | @code{asm} supports operand modifiers on operands (for example @samp{%k2} | |
b5ea0f07 LC |
11079 | instead of simply @samp{%2}). @ref{GenericOperandmodifiers, |
11080 | Generic Operand modifiers} lists the modifiers that are available | |
11081 | on all targets. Other modifiers are hardware dependent. | |
11082 | For example, the list of supported modifiers for x86 is found at | |
d77de738 ML |
11083 | @ref{x86Operandmodifiers,x86 Operand modifiers}. |
11084 | ||
11085 | If the C code that follows the @code{asm} makes no use of any of the output | |
11086 | operands, use @code{volatile} for the @code{asm} statement to prevent the | |
11087 | optimizers from discarding the @code{asm} statement as unneeded | |
11088 | (see @ref{Volatile}). | |
11089 | ||
11090 | This code makes no use of the optional @var{asmSymbolicName}. Therefore it | |
11091 | references the first output operand as @code{%0} (were there a second, it | |
11092 | would be @code{%1}, etc). The number of the first input operand is one greater | |
11093 | than that of the last output operand. In this i386 example, that makes | |
11094 | @code{Mask} referenced as @code{%1}: | |
11095 | ||
11096 | @example | |
11097 | uint32_t Mask = 1234; | |
11098 | uint32_t Index; | |
11099 | ||
11100 | asm ("bsfl %1, %0" | |
11101 | : "=r" (Index) | |
11102 | : "r" (Mask) | |
11103 | : "cc"); | |
11104 | @end example | |
11105 | ||
11106 | That code overwrites the variable @code{Index} (@samp{=}), | |
11107 | placing the value in a register (@samp{r}). | |
11108 | Using the generic @samp{r} constraint instead of a constraint for a specific | |
11109 | register allows the compiler to pick the register to use, which can result | |
11110 | in more efficient code. This may not be possible if an assembler instruction | |
11111 | requires a specific register. | |
11112 | ||
11113 | The following i386 example uses the @var{asmSymbolicName} syntax. | |
11114 | It produces the | |
11115 | same result as the code above, but some may consider it more readable or more | |
11116 | maintainable since reordering index numbers is not necessary when adding or | |
11117 | removing operands. The names @code{aIndex} and @code{aMask} | |
11118 | are only used in this example to emphasize which | |
11119 | names get used where. | |
11120 | It is acceptable to reuse the names @code{Index} and @code{Mask}. | |
11121 | ||
11122 | @example | |
11123 | uint32_t Mask = 1234; | |
11124 | uint32_t Index; | |
11125 | ||
11126 | asm ("bsfl %[aMask], %[aIndex]" | |
11127 | : [aIndex] "=r" (Index) | |
11128 | : [aMask] "r" (Mask) | |
11129 | : "cc"); | |
11130 | @end example | |
11131 | ||
11132 | Here are some more examples of output operands. | |
11133 | ||
11134 | @example | |
11135 | uint32_t c = 1; | |
11136 | uint32_t d; | |
11137 | uint32_t *e = &c; | |
11138 | ||
11139 | asm ("mov %[e], %[d]" | |
11140 | : [d] "=rm" (d) | |
11141 | : [e] "rm" (*e)); | |
11142 | @end example | |
11143 | ||
11144 | Here, @code{d} may either be in a register or in memory. Since the compiler | |
11145 | might already have the current value of the @code{uint32_t} location | |
11146 | pointed to by @code{e} | |
11147 | in a register, you can enable it to choose the best location | |
11148 | for @code{d} by specifying both constraints. | |
11149 | ||
11150 | @anchor{FlagOutputOperands} | |
11151 | @subsubsection Flag Output Operands | |
11152 | @cindex @code{asm} flag output operands | |
11153 | ||
11154 | Some targets have a special register that holds the ``flags'' for the | |
11155 | result of an operation or comparison. Normally, the contents of that | |
11156 | register are either unmodifed by the asm, or the @code{asm} statement is | |
11157 | considered to clobber the contents. | |
11158 | ||
11159 | On some targets, a special form of output operand exists by which | |
11160 | conditions in the flags register may be outputs of the asm. The set of | |
11161 | conditions supported are target specific, but the general rule is that | |
11162 | the output variable must be a scalar integer, and the value is boolean. | |
11163 | When supported, the target defines the preprocessor symbol | |
11164 | @code{__GCC_ASM_FLAG_OUTPUTS__}. | |
11165 | ||
11166 | Because of the special nature of the flag output operands, the constraint | |
11167 | may not include alternatives. | |
11168 | ||
11169 | Most often, the target has only one flags register, and thus is an implied | |
11170 | operand of many instructions. In this case, the operand should not be | |
11171 | referenced within the assembler template via @code{%0} etc, as there's | |
11172 | no corresponding text in the assembly language. | |
11173 | ||
11174 | @table @asis | |
11175 | @item ARM | |
11176 | @itemx AArch64 | |
11177 | The flag output constraints for the ARM family are of the form | |
11178 | @samp{=@@cc@var{cond}} where @var{cond} is one of the standard | |
11179 | conditions defined in the ARM ARM for @code{ConditionHolds}. | |
11180 | ||
11181 | @table @code | |
11182 | @item eq | |
11183 | Z flag set, or equal | |
11184 | @item ne | |
11185 | Z flag clear or not equal | |
11186 | @item cs | |
11187 | @itemx hs | |
11188 | C flag set or unsigned greater than equal | |
11189 | @item cc | |
11190 | @itemx lo | |
11191 | C flag clear or unsigned less than | |
11192 | @item mi | |
11193 | N flag set or ``minus'' | |
11194 | @item pl | |
11195 | N flag clear or ``plus'' | |
11196 | @item vs | |
11197 | V flag set or signed overflow | |
11198 | @item vc | |
11199 | V flag clear | |
11200 | @item hi | |
11201 | unsigned greater than | |
11202 | @item ls | |
11203 | unsigned less than equal | |
11204 | @item ge | |
11205 | signed greater than equal | |
11206 | @item lt | |
11207 | signed less than | |
11208 | @item gt | |
11209 | signed greater than | |
11210 | @item le | |
11211 | signed less than equal | |
11212 | @end table | |
11213 | ||
11214 | The flag output constraints are not supported in thumb1 mode. | |
11215 | ||
11216 | @item x86 family | |
11217 | The flag output constraints for the x86 family are of the form | |
11218 | @samp{=@@cc@var{cond}} where @var{cond} is one of the standard | |
11219 | conditions defined in the ISA manual for @code{j@var{cc}} or | |
11220 | @code{set@var{cc}}. | |
11221 | ||
11222 | @table @code | |
11223 | @item a | |
11224 | ``above'' or unsigned greater than | |
11225 | @item ae | |
11226 | ``above or equal'' or unsigned greater than or equal | |
11227 | @item b | |
11228 | ``below'' or unsigned less than | |
11229 | @item be | |
11230 | ``below or equal'' or unsigned less than or equal | |
11231 | @item c | |
11232 | carry flag set | |
11233 | @item e | |
11234 | @itemx z | |
11235 | ``equal'' or zero flag set | |
11236 | @item g | |
11237 | signed greater than | |
11238 | @item ge | |
11239 | signed greater than or equal | |
11240 | @item l | |
11241 | signed less than | |
11242 | @item le | |
11243 | signed less than or equal | |
11244 | @item o | |
11245 | overflow flag set | |
11246 | @item p | |
11247 | parity flag set | |
11248 | @item s | |
11249 | sign flag set | |
11250 | @item na | |
11251 | @itemx nae | |
11252 | @itemx nb | |
11253 | @itemx nbe | |
11254 | @itemx nc | |
11255 | @itemx ne | |
11256 | @itemx ng | |
11257 | @itemx nge | |
11258 | @itemx nl | |
11259 | @itemx nle | |
11260 | @itemx no | |
11261 | @itemx np | |
11262 | @itemx ns | |
11263 | @itemx nz | |
11264 | ``not'' @var{flag}, or inverted versions of those above | |
11265 | @end table | |
11266 | ||
466b100e JC |
11267 | @item s390 |
11268 | The flag output constraint for s390 is @samp{=@@cc}. Only one such | |
11269 | constraint is allowed. The variable has to be stored in a @samp{int} | |
11270 | variable. | |
11271 | ||
d77de738 ML |
11272 | @end table |
11273 | ||
11274 | @anchor{InputOperands} | |
11275 | @subsubsection Input Operands | |
11276 | @cindex @code{asm} input operands | |
11277 | @cindex @code{asm} expressions | |
11278 | ||
11279 | Input operands make values from C variables and expressions available to the | |
11280 | assembly code. | |
11281 | ||
11282 | Operands are separated by commas. Each operand has this format: | |
11283 | ||
11284 | @example | |
11285 | @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression}) | |
11286 | @end example | |
11287 | ||
11288 | @table @var | |
11289 | @item asmSymbolicName | |
11290 | Specifies a symbolic name for the operand. | |
11291 | Reference the name in the assembler template | |
11292 | by enclosing it in square brackets | |
11293 | (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement | |
11294 | that contains the definition. Any valid C variable name is acceptable, | |
11295 | including names already defined in the surrounding code. No two operands | |
11296 | within the same @code{asm} statement can use the same symbolic name. | |
11297 | ||
11298 | When not using an @var{asmSymbolicName}, use the (zero-based) position | |
11299 | of the operand | |
11300 | in the list of operands in the assembler template. For example if there are | |
11301 | two output operands and three inputs, | |
11302 | use @samp{%2} in the template to refer to the first input operand, | |
11303 | @samp{%3} for the second, and @samp{%4} for the third. | |
11304 | ||
11305 | @item constraint | |
11306 | A string constant specifying constraints on the placement of the operand; | |
11307 | @xref{Constraints}, for details. | |
11308 | ||
11309 | Input constraint strings may not begin with either @samp{=} or @samp{+}. | |
11310 | When you list more than one possible location (for example, @samp{"irm"}), | |
11311 | the compiler chooses the most efficient one based on the current context. | |
11312 | If you must use a specific register, but your Machine Constraints do not | |
11313 | provide sufficient control to select the specific register you want, | |
11314 | local register variables may provide a solution (@pxref{Local Register | |
11315 | Variables}). | |
11316 | ||
11317 | Input constraints can also be digits (for example, @code{"0"}). This indicates | |
11318 | that the specified input must be in the same place as the output constraint | |
11319 | at the (zero-based) index in the output constraint list. | |
11320 | When using @var{asmSymbolicName} syntax for the output operands, | |
11321 | you may use these names (enclosed in brackets @samp{[]}) instead of digits. | |
11322 | ||
11323 | @item cexpression | |
11324 | This is the C variable or expression being passed to the @code{asm} statement | |
11325 | as input. The enclosing parentheses are a required part of the syntax. | |
11326 | ||
11327 | @end table | |
11328 | ||
11329 | When the compiler selects the registers to use to represent the input | |
11330 | operands, it does not use any of the clobbered registers | |
11331 | (@pxref{Clobbers and Scratch Registers}). | |
11332 | ||
11333 | If there are no output operands but there are input operands, place two | |
11334 | consecutive colons where the output operands would go: | |
11335 | ||
11336 | @example | |
11337 | __asm__ ("some instructions" | |
11338 | : /* No outputs. */ | |
11339 | : "r" (Offset / 8)); | |
11340 | @end example | |
11341 | ||
11342 | @strong{Warning:} Do @emph{not} modify the contents of input-only operands | |
11343 | (except for inputs tied to outputs). The compiler assumes that on exit from | |
11344 | the @code{asm} statement these operands contain the same values as they | |
11345 | had before executing the statement. | |
11346 | It is @emph{not} possible to use clobbers | |
11347 | to inform the compiler that the values in these inputs are changing. One | |
11348 | common work-around is to tie the changing input variable to an output variable | |
11349 | that never gets used. Note, however, that if the code that follows the | |
11350 | @code{asm} statement makes no use of any of the output operands, the GCC | |
11351 | optimizers may discard the @code{asm} statement as unneeded | |
11352 | (see @ref{Volatile}). | |
11353 | ||
11354 | @code{asm} supports operand modifiers on operands (for example @samp{%k2} | |
b5ea0f07 LC |
11355 | instead of simply @samp{%2}). @ref{GenericOperandmodifiers, |
11356 | Generic Operand modifiers} lists the modifiers that are available | |
11357 | on all targets. Other modifiers are hardware dependent. | |
11358 | For example, the list of supported modifiers for x86 is found at | |
d77de738 ML |
11359 | @ref{x86Operandmodifiers,x86 Operand modifiers}. |
11360 | ||
11361 | In this example using the fictitious @code{combine} instruction, the | |
11362 | constraint @code{"0"} for input operand 1 says that it must occupy the same | |
11363 | location as output operand 0. Only input operands may use numbers in | |
11364 | constraints, and they must each refer to an output operand. Only a number (or | |
11365 | the symbolic assembler name) in the constraint can guarantee that one operand | |
11366 | is in the same place as another. The mere fact that @code{foo} is the value of | |
11367 | both operands is not enough to guarantee that they are in the same place in | |
11368 | the generated assembler code. | |
11369 | ||
11370 | @example | |
11371 | asm ("combine %2, %0" | |
11372 | : "=r" (foo) | |
11373 | : "0" (foo), "g" (bar)); | |
11374 | @end example | |
11375 | ||
11376 | Here is an example using symbolic names. | |
11377 | ||
11378 | @example | |
11379 | asm ("cmoveq %1, %2, %[result]" | |
11380 | : [result] "=r"(result) | |
11381 | : "r" (test), "r" (new), "[result]" (old)); | |
11382 | @end example | |
11383 | ||
11384 | @anchor{Clobbers and Scratch Registers} | |
11385 | @subsubsection Clobbers and Scratch Registers | |
11386 | @cindex @code{asm} clobbers | |
11387 | @cindex @code{asm} scratch registers | |
11388 | ||
11389 | While the compiler is aware of changes to entries listed in the output | |
11390 | operands, the inline @code{asm} code may modify more than just the outputs. For | |
11391 | example, calculations may require additional registers, or the processor may | |
11392 | overwrite a register as a side effect of a particular assembler instruction. | |
11393 | In order to inform the compiler of these changes, list them in the clobber | |
11394 | list. Clobber list items are either register names or the special clobbers | |
11395 | (listed below). Each clobber list item is a string constant | |
11396 | enclosed in double quotes and separated by commas. | |
11397 | ||
11398 | Clobber descriptions may not in any way overlap with an input or output | |
11399 | operand. For example, you may not have an operand describing a register class | |
11400 | with one member when listing that register in the clobber list. Variables | |
11401 | declared to live in specific registers (@pxref{Explicit Register | |
11402 | Variables}) and used | |
11403 | as @code{asm} input or output operands must have no part mentioned in the | |
11404 | clobber description. In particular, there is no way to specify that input | |
11405 | operands get modified without also specifying them as output operands. | |
11406 | ||
11407 | When the compiler selects which registers to use to represent input and output | |
11408 | operands, it does not use any of the clobbered registers. As a result, | |
11409 | clobbered registers are available for any use in the assembler code. | |
11410 | ||
11411 | Another restriction is that the clobber list should not contain the | |
11412 | stack pointer register. This is because the compiler requires the | |
11413 | value of the stack pointer to be the same after an @code{asm} | |
11414 | statement as it was on entry to the statement. However, previous | |
11415 | versions of GCC did not enforce this rule and allowed the stack | |
11416 | pointer to appear in the list, with unclear semantics. This behavior | |
11417 | is deprecated and listing the stack pointer may become an error in | |
11418 | future versions of GCC@. | |
11419 | ||
11420 | Here is a realistic example for the VAX showing the use of clobbered | |
11421 | registers: | |
11422 | ||
11423 | @example | |
11424 | asm volatile ("movc3 %0, %1, %2" | |
11425 | : /* No outputs. */ | |
11426 | : "g" (from), "g" (to), "g" (count) | |
11427 | : "r0", "r1", "r2", "r3", "r4", "r5", "memory"); | |
11428 | @end example | |
11429 | ||
11430 | Also, there are two special clobber arguments: | |
11431 | ||
11432 | @table @code | |
11433 | @item "cc" | |
11434 | The @code{"cc"} clobber indicates that the assembler code modifies the flags | |
11435 | register. On some machines, GCC represents the condition codes as a specific | |
11436 | hardware register; @code{"cc"} serves to name this register. | |
11437 | On other machines, condition code handling is different, | |
11438 | and specifying @code{"cc"} has no effect. But | |
11439 | it is valid no matter what the target. | |
11440 | ||
11441 | @item "memory" | |
11442 | The @code{"memory"} clobber tells the compiler that the assembly code | |
11443 | performs memory | |
11444 | reads or writes to items other than those listed in the input and output | |
11445 | operands (for example, accessing the memory pointed to by one of the input | |
11446 | parameters). To ensure memory contains correct values, GCC may need to flush | |
11447 | specific register values to memory before executing the @code{asm}. Further, | |
11448 | the compiler does not assume that any values read from memory before an | |
11449 | @code{asm} remain unchanged after that @code{asm}; it reloads them as | |
11450 | needed. | |
11451 | Using the @code{"memory"} clobber effectively forms a read/write | |
11452 | memory barrier for the compiler. | |
11453 | ||
11454 | Note that this clobber does not prevent the @emph{processor} from doing | |
11455 | speculative reads past the @code{asm} statement. To prevent that, you need | |
11456 | processor-specific fence instructions. | |
11457 | ||
11458 | @end table | |
11459 | ||
11460 | Flushing registers to memory has performance implications and may be | |
11461 | an issue for time-sensitive code. You can provide better information | |
11462 | to GCC to avoid this, as shown in the following examples. At a | |
11463 | minimum, aliasing rules allow GCC to know what memory @emph{doesn't} | |
11464 | need to be flushed. | |
11465 | ||
11466 | Here is a fictitious sum of squares instruction, that takes two | |
11467 | pointers to floating point values in memory and produces a floating | |
11468 | point register output. | |
11469 | Notice that @code{x}, and @code{y} both appear twice in the @code{asm} | |
11470 | parameters, once to specify memory accessed, and once to specify a | |
11471 | base register used by the @code{asm}. You won't normally be wasting a | |
11472 | register by doing this as GCC can use the same register for both | |
11473 | purposes. However, it would be foolish to use both @code{%1} and | |
11474 | @code{%3} for @code{x} in this @code{asm} and expect them to be the | |
11475 | same. In fact, @code{%3} may well not be a register. It might be a | |
11476 | symbolic memory reference to the object pointed to by @code{x}. | |
11477 | ||
11478 | @smallexample | |
11479 | asm ("sumsq %0, %1, %2" | |
11480 | : "+f" (result) | |
11481 | : "r" (x), "r" (y), "m" (*x), "m" (*y)); | |
11482 | @end smallexample | |
11483 | ||
11484 | Here is a fictitious @code{*z++ = *x++ * *y++} instruction. | |
11485 | Notice that the @code{x}, @code{y} and @code{z} pointer registers | |
11486 | must be specified as input/output because the @code{asm} modifies | |
11487 | them. | |
11488 | ||
11489 | @smallexample | |
11490 | asm ("vecmul %0, %1, %2" | |
11491 | : "+r" (z), "+r" (x), "+r" (y), "=m" (*z) | |
11492 | : "m" (*x), "m" (*y)); | |
11493 | @end smallexample | |
11494 | ||
11495 | An x86 example where the string memory argument is of unknown length. | |
11496 | ||
11497 | @smallexample | |
11498 | asm("repne scasb" | |
11499 | : "=c" (count), "+D" (p) | |
11500 | : "m" (*(const char (*)[]) p), "0" (-1), "a" (0)); | |
11501 | @end smallexample | |
11502 | ||
11503 | If you know the above will only be reading a ten byte array then you | |
11504 | could instead use a memory input like: | |
11505 | @code{"m" (*(const char (*)[10]) p)}. | |
11506 | ||
11507 | Here is an example of a PowerPC vector scale implemented in assembly, | |
11508 | complete with vector and condition code clobbers, and some initialized | |
11509 | offset registers that are unchanged by the @code{asm}. | |
11510 | ||
11511 | @smallexample | |
11512 | void | |
11513 | dscal (size_t n, double *x, double alpha) | |
11514 | @{ | |
11515 | asm ("/* lots of asm here */" | |
11516 | : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x) | |
11517 | : "d" (alpha), "b" (32), "b" (48), "b" (64), | |
11518 | "b" (80), "b" (96), "b" (112) | |
11519 | : "cr0", | |
11520 | "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39", | |
11521 | "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"); | |
11522 | @} | |
11523 | @end smallexample | |
11524 | ||
11525 | Rather than allocating fixed registers via clobbers to provide scratch | |
11526 | registers for an @code{asm} statement, an alternative is to define a | |
11527 | variable and make it an early-clobber output as with @code{a2} and | |
11528 | @code{a3} in the example below. This gives the compiler register | |
11529 | allocator more freedom. You can also define a variable and make it an | |
11530 | output tied to an input as with @code{a0} and @code{a1}, tied | |
11531 | respectively to @code{ap} and @code{lda}. Of course, with tied | |
11532 | outputs your @code{asm} can't use the input value after modifying the | |
11533 | output register since they are one and the same register. What's | |
11534 | more, if you omit the early-clobber on the output, it is possible that | |
11535 | GCC might allocate the same register to another of the inputs if GCC | |
11536 | could prove they had the same value on entry to the @code{asm}. This | |
11537 | is why @code{a1} has an early-clobber. Its tied input, @code{lda} | |
11538 | might conceivably be known to have the value 16 and without an | |
11539 | early-clobber share the same register as @code{%11}. On the other | |
11540 | hand, @code{ap} can't be the same as any of the other inputs, so an | |
11541 | early-clobber on @code{a0} is not needed. It is also not desirable in | |
11542 | this case. An early-clobber on @code{a0} would cause GCC to allocate | |
11543 | a separate register for the @code{"m" (*(const double (*)[]) ap)} | |
11544 | input. Note that tying an input to an output is the way to set up an | |
11545 | initialized temporary register modified by an @code{asm} statement. | |
11546 | An input not tied to an output is assumed by GCC to be unchanged, for | |
11547 | example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might | |
11548 | use that register in following code if the value 16 happened to be | |
11549 | needed. You can even use a normal @code{asm} output for a scratch if | |
11550 | all inputs that might share the same register are consumed before the | |
11551 | scratch is used. The VSX registers clobbered by the @code{asm} | |
11552 | statement could have used this technique except for GCC's limit on the | |
11553 | number of @code{asm} parameters. | |
11554 | ||
11555 | @smallexample | |
11556 | static void | |
11557 | dgemv_kernel_4x4 (long n, const double *ap, long lda, | |
11558 | const double *x, double *y, double alpha) | |
11559 | @{ | |
11560 | double *a0; | |
11561 | double *a1; | |
11562 | double *a2; | |
11563 | double *a3; | |
11564 | ||
11565 | __asm__ | |
11566 | ( | |
11567 | /* lots of asm here */ | |
11568 | "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n" | |
11569 | "#a0=%3 a1=%4 a2=%5 a3=%6" | |
11570 | : | |
11571 | "+m" (*(double (*)[n]) y), | |
11572 | "+&r" (n), // 1 | |
11573 | "+b" (y), // 2 | |
11574 | "=b" (a0), // 3 | |
11575 | "=&b" (a1), // 4 | |
11576 | "=&b" (a2), // 5 | |
11577 | "=&b" (a3) // 6 | |
11578 | : | |
11579 | "m" (*(const double (*)[n]) x), | |
11580 | "m" (*(const double (*)[]) ap), | |
11581 | "d" (alpha), // 9 | |
11582 | "r" (x), // 10 | |
11583 | "b" (16), // 11 | |
11584 | "3" (ap), // 12 | |
11585 | "4" (lda) // 13 | |
11586 | : | |
11587 | "cr0", | |
11588 | "vs32","vs33","vs34","vs35","vs36","vs37", | |
11589 | "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47" | |
11590 | ); | |
11591 | @} | |
11592 | @end smallexample | |
11593 | ||
11594 | @anchor{GotoLabels} | |
11595 | @subsubsection Goto Labels | |
11596 | @cindex @code{asm} goto labels | |
11597 | ||
11598 | @code{asm goto} allows assembly code to jump to one or more C labels. The | |
11599 | @var{GotoLabels} section in an @code{asm goto} statement contains | |
11600 | a comma-separated | |
11601 | list of all C labels to which the assembler code may jump. GCC assumes that | |
11602 | @code{asm} execution falls through to the next statement (if this is not the | |
11603 | case, consider using the @code{__builtin_unreachable} intrinsic after the | |
11604 | @code{asm} statement). Optimization of @code{asm goto} may be improved by | |
11605 | using the @code{hot} and @code{cold} label attributes (@pxref{Label | |
11606 | Attributes}). | |
11607 | ||
11608 | If the assembler code does modify anything, use the @code{"memory"} clobber | |
11609 | to force the | |
11610 | optimizers to flush all register values to memory and reload them if | |
11611 | necessary after the @code{asm} statement. | |
11612 | ||
11613 | Also note that an @code{asm goto} statement is always implicitly | |
11614 | considered volatile. | |
11615 | ||
11616 | Be careful when you set output operands inside @code{asm goto} only on | |
11617 | some possible control flow paths. If you don't set up the output on | |
11618 | given path and never use it on this path, it is okay. Otherwise, you | |
11619 | should use @samp{+} constraint modifier meaning that the operand is | |
11620 | input and output one. With this modifier you will have the correct | |
11621 | values on all possible paths from the @code{asm goto}. | |
11622 | ||
11623 | To reference a label in the assembler template, prefix it with | |
11624 | @samp{%l} (lowercase @samp{L}) followed by its (zero-based) position | |
11625 | in @var{GotoLabels} plus the number of input and output operands. | |
11626 | Output operand with constraint modifier @samp{+} is counted as two | |
11627 | operands because it is considered as one output and one input operand. | |
11628 | For example, if the @code{asm} has three inputs, one output operand | |
11629 | with constraint modifier @samp{+} and one output operand with | |
11630 | constraint modifier @samp{=} and references two labels, refer to the | |
11631 | first label as @samp{%l6} and the second as @samp{%l7}). | |
11632 | ||
11633 | Alternately, you can reference labels using the actual C label name | |
11634 | enclosed in brackets. For example, to reference a label named | |
11635 | @code{carry}, you can use @samp{%l[carry]}. The label must still be | |
11636 | listed in the @var{GotoLabels} section when using this approach. It | |
11637 | is better to use the named references for labels as in this case you | |
11638 | can avoid counting input and output operands and special treatment of | |
11639 | output operands with constraint modifier @samp{+}. | |
11640 | ||
11641 | Here is an example of @code{asm goto} for i386: | |
11642 | ||
11643 | @example | |
11644 | asm goto ( | |
11645 | "btl %1, %0\n\t" | |
11646 | "jc %l2" | |
11647 | : /* No outputs. */ | |
11648 | : "r" (p1), "r" (p2) | |
11649 | : "cc" | |
11650 | : carry); | |
11651 | ||
11652 | return 0; | |
11653 | ||
11654 | carry: | |
11655 | return 1; | |
11656 | @end example | |
11657 | ||
11658 | The following example shows an @code{asm goto} that uses a memory clobber. | |
11659 | ||
11660 | @example | |
11661 | int frob(int x) | |
11662 | @{ | |
11663 | int y; | |
11664 | asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" | |
11665 | : /* No outputs. */ | |
11666 | : "r"(x), "r"(&y) | |
11667 | : "r5", "memory" | |
11668 | : error); | |
11669 | return y; | |
11670 | error: | |
11671 | return -1; | |
11672 | @} | |
11673 | @end example | |
11674 | ||
11675 | The following example shows an @code{asm goto} that uses an output. | |
11676 | ||
11677 | @example | |
11678 | int foo(int count) | |
11679 | @{ | |
11680 | asm goto ("dec %0; jb %l[stop]" | |
11681 | : "+r" (count) | |
11682 | : | |
11683 | : | |
11684 | : stop); | |
11685 | return count; | |
11686 | stop: | |
11687 | return 0; | |
11688 | @} | |
11689 | @end example | |
11690 | ||
11691 | The following artificial example shows an @code{asm goto} that sets | |
11692 | up an output only on one path inside the @code{asm goto}. Usage of | |
11693 | constraint modifier @code{=} instead of @code{+} would be wrong as | |
11694 | @code{factor} is used on all paths from the @code{asm goto}. | |
11695 | ||
11696 | @example | |
11697 | int foo(int inp) | |
11698 | @{ | |
11699 | int factor = 0; | |
11700 | asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0" | |
11701 | : "+r" (factor) | |
11702 | : "r" (inp) | |
11703 | : | |
11704 | : lab); | |
11705 | lab: | |
11706 | return inp * factor; /* return 2 * inp or 0 if inp < 10 */ | |
11707 | @} | |
11708 | @end example | |
11709 | ||
b5ea0f07 LC |
11710 | @anchor{GenericOperandmodifiers} |
11711 | @subsubsection Generic Operand Modifiers | |
11712 | @noindent | |
11713 | The following table shows the modifiers supported by all targets and their effects: | |
11714 | ||
4ace81b6 | 11715 | @multitable @columnfractions 0.15 0.7 0.15 |
b5ea0f07 LC |
11716 | @headitem Modifier @tab Description @tab Example |
11717 | @item @code{c} | |
11718 | @tab Require a constant operand and print the constant expression with no punctuation. | |
11719 | @tab @code{%c0} | |
11720 | @item @code{n} | |
11721 | @tab Like @samp{%c} except that the value of the constant is negated before printing. | |
11722 | @tab @code{%n0} | |
11723 | @item @code{a} | |
11724 | @tab Substitute a memory reference, with the actual operand treated as the address. | |
11725 | This may be useful when outputting a ``load address'' instruction, because | |
11726 | often the assembler syntax for such an instruction requires you to write the | |
11727 | operand as if it were a memory reference. | |
11728 | @tab @code{%a0} | |
11729 | @item @code{l} | |
11730 | @tab Print the label name with no punctuation. | |
11731 | @tab @code{%l0} | |
11732 | @end multitable | |
11733 | ||
8cfc2804 AC |
11734 | @anchor{aarch64Operandmodifiers} |
11735 | @subsubsection AArch64 Operand Modifiers | |
11736 | ||
11737 | The following table shows the modifiers supported by AArch64 and their effects: | |
11738 | ||
11739 | @multitable @columnfractions .10 .90 | |
11740 | @headitem Modifier @tab Description | |
11741 | @item @code{w} @tab Print a 32-bit general-purpose register name or, given a | |
11742 | constant zero operand, the 32-bit zero register (@code{wzr}). | |
11743 | @item @code{x} @tab Print a 64-bit general-purpose register name or, given a | |
11744 | constant zero operand, the 64-bit zero register (@code{xzr}). | |
11745 | @item @code{b} @tab Print an FP/SIMD register name with a @code{b} (byte, 8-bit) | |
11746 | prefix. | |
11747 | @item @code{h} @tab Print an FP/SIMD register name with an @code{h} (halfword, | |
11748 | 16-bit) prefix. | |
11749 | @item @code{s} @tab Print an FP/SIMD register name with an @code{s} (single | |
11750 | word, 32-bit) prefix. | |
11751 | @item @code{d} @tab Print an FP/SIMD register name with a @code{d} (doubleword, | |
11752 | 64-bit) prefix. | |
11753 | @item @code{q} @tab Print an FP/SIMD register name with a @code{q} (quadword, | |
11754 | 128-bit) prefix. | |
11755 | @item @code{Z} @tab Print an FP/SIMD register name as an SVE register (i.e. with | |
11756 | a @code{z} prefix). This is a no-op for SVE register operands. | |
11757 | @end multitable | |
11758 | ||
d77de738 ML |
11759 | @anchor{x86Operandmodifiers} |
11760 | @subsubsection x86 Operand Modifiers | |
11761 | ||
11762 | References to input, output, and goto operands in the assembler template | |
11763 | of extended @code{asm} statements can use | |
11764 | modifiers to affect the way the operands are formatted in | |
11765 | the code output to the assembler. For example, the | |
11766 | following code uses the @samp{h} and @samp{b} modifiers for x86: | |
11767 | ||
11768 | @example | |
11769 | uint16_t num; | |
11770 | asm volatile ("xchg %h0, %b0" : "+a" (num) ); | |
11771 | @end example | |
11772 | ||
11773 | @noindent | |
11774 | These modifiers generate this assembler code: | |
11775 | ||
11776 | @example | |
11777 | xchg %ah, %al | |
11778 | @end example | |
11779 | ||
11780 | The rest of this discussion uses the following code for illustrative purposes. | |
11781 | ||
11782 | @example | |
11783 | int main() | |
11784 | @{ | |
11785 | int iInt = 1; | |
11786 | ||
11787 | top: | |
11788 | ||
11789 | asm volatile goto ("some assembler instructions here" | |
11790 | : /* No outputs. */ | |
11791 | : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42) | |
11792 | : /* No clobbers. */ | |
11793 | : top); | |
11794 | @} | |
11795 | @end example | |
11796 | ||
11797 | With no modifiers, this is what the output from the operands would be | |
11798 | for the @samp{att} and @samp{intel} dialects of assembler: | |
11799 | ||
11800 | @multitable {Operand} {$.L2} {OFFSET FLAT:.L2} | |
11801 | @headitem Operand @tab @samp{att} @tab @samp{intel} | |
11802 | @item @code{%0} | |
11803 | @tab @code{%eax} | |
11804 | @tab @code{eax} | |
11805 | @item @code{%1} | |
11806 | @tab @code{$2} | |
11807 | @tab @code{2} | |
11808 | @item @code{%3} | |
11809 | @tab @code{$.L3} | |
11810 | @tab @code{OFFSET FLAT:.L3} | |
11811 | @item @code{%4} | |
11812 | @tab @code{$8} | |
11813 | @tab @code{8} | |
11814 | @item @code{%5} | |
11815 | @tab @code{%xmm0} | |
11816 | @tab @code{xmm0} | |
11817 | @item @code{%7} | |
11818 | @tab @code{$0} | |
11819 | @tab @code{0} | |
11820 | @end multitable | |
11821 | ||
11822 | The table below shows the list of supported modifiers and their effects. | |
11823 | ||
11824 | @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}} | |
11825 | @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel} | |
11826 | @item @code{A} | |
11827 | @tab Print an absolute memory reference. | |
11828 | @tab @code{%A0} | |
11829 | @tab @code{*%rax} | |
11830 | @tab @code{rax} | |
11831 | @item @code{b} | |
11832 | @tab Print the QImode name of the register. | |
11833 | @tab @code{%b0} | |
11834 | @tab @code{%al} | |
11835 | @tab @code{al} | |
11836 | @item @code{B} | |
11837 | @tab print the opcode suffix of b. | |
11838 | @tab @code{%B0} | |
11839 | @tab @code{b} | |
11840 | @tab | |
11841 | @item @code{c} | |
11842 | @tab Require a constant operand and print the constant expression with no punctuation. | |
11843 | @tab @code{%c1} | |
11844 | @tab @code{2} | |
11845 | @tab @code{2} | |
11846 | @item @code{d} | |
11847 | @tab print duplicated register operand for AVX instruction. | |
11848 | @tab @code{%d5} | |
11849 | @tab @code{%xmm0, %xmm0} | |
11850 | @tab @code{xmm0, xmm0} | |
11851 | @item @code{E} | |
11852 | @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit. | |
11853 | Otherwise mode is unspecified (VOIDmode). | |
11854 | @tab @code{%E1} | |
11855 | @tab @code{%(rax)} | |
11856 | @tab @code{[rax]} | |
11857 | @item @code{g} | |
11858 | @tab Print the V16SFmode name of the register. | |
11859 | @tab @code{%g0} | |
11860 | @tab @code{%zmm0} | |
11861 | @tab @code{zmm0} | |
11862 | @item @code{h} | |
11863 | @tab Print the QImode name for a ``high'' register. | |
11864 | @tab @code{%h0} | |
11865 | @tab @code{%ah} | |
11866 | @tab @code{ah} | |
11867 | @item @code{H} | |
11868 | @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the | |
11869 | high 8 bytes of SSE values. For a memref in (%rax), it generates | |
11870 | @tab @code{%H0} | |
11871 | @tab @code{8(%rax)} | |
11872 | @tab @code{8[rax]} | |
11873 | @item @code{k} | |
11874 | @tab Print the SImode name of the register. | |
11875 | @tab @code{%k0} | |
11876 | @tab @code{%eax} | |
11877 | @tab @code{eax} | |
11878 | @item @code{l} | |
11879 | @tab Print the label name with no punctuation. | |
11880 | @tab @code{%l3} | |
11881 | @tab @code{.L3} | |
11882 | @tab @code{.L3} | |
11883 | @item @code{L} | |
11884 | @tab print the opcode suffix of l. | |
11885 | @tab @code{%L0} | |
11886 | @tab @code{l} | |
11887 | @tab | |
11888 | @item @code{N} | |
11889 | @tab print maskz. | |
11890 | @tab @code{%N7} | |
11891 | @tab @code{@{z@}} | |
11892 | @tab @code{@{z@}} | |
11893 | @item @code{p} | |
11894 | @tab Print raw symbol name (without syntax-specific prefixes). | |
11895 | @tab @code{%p2} | |
11896 | @tab @code{42} | |
11897 | @tab @code{42} | |
11898 | @item @code{P} | |
11899 | @tab If used for a function, print the PLT suffix and generate PIC code. | |
11900 | For example, emit @code{foo@@PLT} instead of 'foo' for the function | |
11901 | foo(). If used for a constant, drop all syntax-specific prefixes and | |
11902 | issue the bare constant. See @code{p} above. | |
11903 | @item @code{q} | |
11904 | @tab Print the DImode name of the register. | |
11905 | @tab @code{%q0} | |
11906 | @tab @code{%rax} | |
11907 | @tab @code{rax} | |
11908 | @item @code{Q} | |
11909 | @tab print the opcode suffix of q. | |
11910 | @tab @code{%Q0} | |
11911 | @tab @code{q} | |
11912 | @tab | |
11913 | @item @code{R} | |
11914 | @tab print embedded rounding and sae. | |
11915 | @tab @code{%R4} | |
11916 | @tab @code{@{rn-sae@}, } | |
11917 | @tab @code{, @{rn-sae@}} | |
11918 | @item @code{r} | |
11919 | @tab print only sae. | |
11920 | @tab @code{%r4} | |
11921 | @tab @code{@{sae@}, } | |
11922 | @tab @code{, @{sae@}} | |
11923 | @item @code{s} | |
11924 | @tab print a shift double count, followed by the assemblers argument | |
11925 | delimiterprint the opcode suffix of s. | |
11926 | @tab @code{%s1} | |
11927 | @tab @code{$2, } | |
11928 | @tab @code{2, } | |
11929 | @item @code{S} | |
11930 | @tab print the opcode suffix of s. | |
11931 | @tab @code{%S0} | |
11932 | @tab @code{s} | |
11933 | @tab | |
11934 | @item @code{t} | |
11935 | @tab print the V8SFmode name of the register. | |
11936 | @tab @code{%t5} | |
11937 | @tab @code{%ymm0} | |
11938 | @tab @code{ymm0} | |
11939 | @item @code{T} | |
11940 | @tab print the opcode suffix of t. | |
11941 | @tab @code{%T0} | |
11942 | @tab @code{t} | |
11943 | @tab | |
11944 | @item @code{V} | |
11945 | @tab print naked full integer register name without %. | |
11946 | @tab @code{%V0} | |
11947 | @tab @code{eax} | |
11948 | @tab @code{eax} | |
11949 | @item @code{w} | |
11950 | @tab Print the HImode name of the register. | |
11951 | @tab @code{%w0} | |
11952 | @tab @code{%ax} | |
11953 | @tab @code{ax} | |
11954 | @item @code{W} | |
11955 | @tab print the opcode suffix of w. | |
11956 | @tab @code{%W0} | |
11957 | @tab @code{w} | |
11958 | @tab | |
11959 | @item @code{x} | |
11960 | @tab print the V4SFmode name of the register. | |
11961 | @tab @code{%x5} | |
11962 | @tab @code{%xmm0} | |
11963 | @tab @code{xmm0} | |
11964 | @item @code{y} | |
11965 | @tab print "st(0)" instead of "st" as a register. | |
11966 | @tab @code{%y6} | |
11967 | @tab @code{%st(0)} | |
11968 | @tab @code{st(0)} | |
11969 | @item @code{z} | |
11970 | @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}). | |
11971 | @tab @code{%z0} | |
11972 | @tab @code{l} | |
11973 | @tab | |
11974 | @item @code{Z} | |
11975 | @tab Like @code{z}, with special suffixes for x87 instructions. | |
11976 | @end multitable | |
11977 | ||
11978 | ||
11979 | @anchor{x86floatingpointasmoperands} | |
11980 | @subsubsection x86 Floating-Point @code{asm} Operands | |
11981 | ||
11982 | On x86 targets, there are several rules on the usage of stack-like registers | |
11983 | in the operands of an @code{asm}. These rules apply only to the operands | |
11984 | that are stack-like registers: | |
11985 | ||
11986 | @enumerate | |
11987 | @item | |
11988 | Given a set of input registers that die in an @code{asm}, it is | |
11989 | necessary to know which are implicitly popped by the @code{asm}, and | |
11990 | which must be explicitly popped by GCC@. | |
11991 | ||
11992 | An input register that is implicitly popped by the @code{asm} must be | |
11993 | explicitly clobbered, unless it is constrained to match an | |
11994 | output operand. | |
11995 | ||
11996 | @item | |
11997 | For any input register that is implicitly popped by an @code{asm}, it is | |
11998 | necessary to know how to adjust the stack to compensate for the pop. | |
11999 | If any non-popped input is closer to the top of the reg-stack than | |
12000 | the implicitly popped register, it would not be possible to know what the | |
12001 | stack looked like---it's not clear how the rest of the stack ``slides | |
12002 | up''. | |
12003 | ||
12004 | All implicitly popped input registers must be closer to the top of | |
12005 | the reg-stack than any input that is not implicitly popped. | |
12006 | ||
12007 | It is possible that if an input dies in an @code{asm}, the compiler might | |
12008 | use the input register for an output reload. Consider this example: | |
12009 | ||
12010 | @smallexample | |
12011 | asm ("foo" : "=t" (a) : "f" (b)); | |
12012 | @end smallexample | |
12013 | ||
12014 | @noindent | |
12015 | This code says that input @code{b} is not popped by the @code{asm}, and that | |
12016 | the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one | |
12017 | deeper after the @code{asm} than it was before. But, it is possible that | |
12018 | reload may think that it can use the same register for both the input and | |
12019 | the output. | |
12020 | ||
12021 | To prevent this from happening, | |
12022 | if any input operand uses the @samp{f} constraint, all output register | |
12023 | constraints must use the @samp{&} early-clobber modifier. | |
12024 | ||
12025 | The example above is correctly written as: | |
12026 | ||
12027 | @smallexample | |
12028 | asm ("foo" : "=&t" (a) : "f" (b)); | |
12029 | @end smallexample | |
12030 | ||
12031 | @item | |
12032 | Some operands need to be in particular places on the stack. All | |
12033 | output operands fall in this category---GCC has no other way to | |
12034 | know which registers the outputs appear in unless you indicate | |
12035 | this in the constraints. | |
12036 | ||
12037 | Output operands must specifically indicate which register an output | |
12038 | appears in after an @code{asm}. @samp{=f} is not allowed: the operand | |
12039 | constraints must select a class with a single register. | |
12040 | ||
12041 | @item | |
12042 | Output operands may not be ``inserted'' between existing stack registers. | |
12043 | Since no 387 opcode uses a read/write operand, all output operands | |
12044 | are dead before the @code{asm}, and are pushed by the @code{asm}. | |
12045 | It makes no sense to push anywhere but the top of the reg-stack. | |
12046 | ||
12047 | Output operands must start at the top of the reg-stack: output | |
12048 | operands may not ``skip'' a register. | |
12049 | ||
12050 | @item | |
12051 | Some @code{asm} statements may need extra stack space for internal | |
12052 | calculations. This can be guaranteed by clobbering stack registers | |
12053 | unrelated to the inputs and outputs. | |
12054 | ||
12055 | @end enumerate | |
12056 | ||
12057 | This @code{asm} | |
12058 | takes one input, which is internally popped, and produces two outputs. | |
12059 | ||
12060 | @smallexample | |
12061 | asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); | |
12062 | @end smallexample | |
12063 | ||
12064 | @noindent | |
12065 | This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode, | |
12066 | and replaces them with one output. The @code{st(1)} clobber is necessary | |
12067 | for the compiler to know that @code{fyl2xp1} pops both inputs. | |
12068 | ||
12069 | @smallexample | |
12070 | asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); | |
12071 | @end smallexample | |
12072 | ||
12073 | @anchor{msp430Operandmodifiers} | |
12074 | @subsubsection MSP430 Operand Modifiers | |
12075 | ||
12076 | The list below describes the supported modifiers and their effects for MSP430. | |
12077 | ||
12078 | @multitable @columnfractions .10 .90 | |
12079 | @headitem Modifier @tab Description | |
12080 | @item @code{A} @tab Select low 16-bits of the constant/register/memory operand. | |
12081 | @item @code{B} @tab Select high 16-bits of the constant/register/memory | |
12082 | operand. | |
12083 | @item @code{C} @tab Select bits 32-47 of the constant/register/memory operand. | |
12084 | @item @code{D} @tab Select bits 48-63 of the constant/register/memory operand. | |
12085 | @item @code{H} @tab Equivalent to @code{B} (for backwards compatibility). | |
12086 | @item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant | |
12087 | value. | |
12088 | @item @code{J} @tab Print an integer without a @code{#} prefix. | |
12089 | @item @code{L} @tab Equivalent to @code{A} (for backwards compatibility). | |
12090 | @item @code{O} @tab Offset of the current frame from the top of the stack. | |
12091 | @item @code{Q} @tab Use the @code{A} instruction postfix. | |
12092 | @item @code{R} @tab Inverse of condition code, for unsigned comparisons. | |
12093 | @item @code{W} @tab Subtract 16 from the constant value. | |
12094 | @item @code{X} @tab Use the @code{X} instruction postfix. | |
12095 | @item @code{Y} @tab Subtract 4 from the constant value. | |
12096 | @item @code{Z} @tab Subtract 1 from the constant value. | |
12097 | @item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the | |
12098 | instruction, depending on the mode. | |
12099 | @item @code{d} @tab Offset 1 byte of a memory reference or constant value. | |
12100 | @item @code{e} @tab Offset 3 bytes of a memory reference or constant value. | |
12101 | @item @code{f} @tab Offset 5 bytes of a memory reference or constant value. | |
12102 | @item @code{g} @tab Offset 7 bytes of a memory reference or constant value. | |
12103 | @item @code{p} @tab Print the value of 2, raised to the power of the given | |
12104 | constant. Used to select the specified bit position. | |
12105 | @item @code{r} @tab Inverse of condition code, for signed comparisons. | |
12106 | @item @code{x} @tab Equivialent to @code{X}, but only for pointers. | |
12107 | @end multitable | |
12108 | ||
b5ea0f07 LC |
12109 | @anchor{loongarchOperandmodifiers} |
12110 | @subsubsection LoongArch Operand Modifiers | |
12111 | ||
12112 | The list below describes the supported modifiers and their effects for LoongArch. | |
12113 | ||
12114 | @multitable @columnfractions .10 .90 | |
12115 | @headitem Modifier @tab Description | |
12116 | @item @code{d} @tab Same as @code{c}. | |
12117 | @item @code{i} @tab Print the character ''@code{i}'' if the operand is not a register. | |
12118 | @item @code{m} @tab Same as @code{c}, but the printed value is @code{operand - 1}. | |
5bd5ef99 | 12119 | @item @code{u} @tab Print a LASX register. |
12120 | @item @code{w} @tab Print a LSX register. | |
b5ea0f07 LC |
12121 | @item @code{X} @tab Print a constant integer operand in hexadecimal. |
12122 | @item @code{z} @tab Print the operand in its unmodified form, followed by a comma. | |
12123 | @end multitable | |
12124 | ||
5bd5ef99 | 12125 | References to input and output operands in the assembler template of extended |
12126 | asm statements can use modifiers to affect the way the operands are formatted | |
12127 | in the code output to the assembler. For example, the following code uses the | |
12128 | 'w' modifier for LoongArch: | |
12129 | ||
12130 | @example | |
12131 | test-asm.c: | |
12132 | ||
12133 | #include <lsxintrin.h> | |
12134 | ||
12135 | __m128i foo (void) | |
12136 | @{ | |
12137 | __m128i a,b,c; | |
12138 | __asm__ ("vadd.d %w0,%w1,%w2\n\t" | |
12139 | :"=f" (c) | |
12140 | :"f" (a),"f" (b)); | |
12141 | ||
12142 | return c; | |
12143 | @} | |
12144 | ||
12145 | @end example | |
12146 | ||
12147 | @noindent | |
12148 | The compile command for the test case is as follows: | |
12149 | ||
12150 | @example | |
12151 | gcc test-asm.c -mlsx -S -o test-asm.s | |
12152 | @end example | |
12153 | ||
12154 | @noindent | |
12155 | The assembly statement produces the following assembly code: | |
12156 | ||
12157 | @example | |
12158 | vadd.d $vr0,$vr0,$vr1 | |
12159 | @end example | |
12160 | ||
12161 | This is a 128-bit vector addition instruction, @code{c} (referred to in the | |
12162 | template string as %0) is the output, and @code{a} (%1) and @code{b} (%2) are | |
12163 | the inputs. @code{__m128i} is a vector data type defined in the file | |
12164 | @code{lsxintrin.h} (@xref{LoongArch SX Vector Intrinsics}). The symbol '=f' | |
12165 | represents a constraint using a floating-point register as an output type, and | |
12166 | the 'f' in the input operand represents a constraint using a floating-point | |
12167 | register operand, which can refer to the definition of a constraint | |
12168 | (@xref{Constraints}) in gcc. | |
12169 | ||
1e2e5713 KC |
12170 | @anchor{riscvOperandmodifiers} |
12171 | @subsubsection RISC-V Operand Modifiers | |
12172 | ||
12173 | The list below describes the supported modifiers and their effects for RISC-V. | |
12174 | ||
12175 | @multitable @columnfractions .10 .90 | |
12176 | @headitem Modifier @tab Description | |
12177 | @item @code{z} @tab Print ''@code{zero}'' instead of 0 if the operand is an immediate with a value of zero. | |
12178 | @item @code{i} @tab Print the character ''@code{i}'' if the operand is an immediate. | |
12179 | @end multitable | |
b5ea0f07 | 12180 | |
d77de738 ML |
12181 | @lowersections |
12182 | @include md.texi | |
12183 | @raisesections | |
12184 | ||
12185 | @node Asm Labels | |
12186 | @subsection Controlling Names Used in Assembler Code | |
12187 | @cindex assembler names for identifiers | |
12188 | @cindex names used in assembler code | |
12189 | @cindex identifiers, names in assembler code | |
12190 | ||
12191 | You can specify the name to be used in the assembler code for a C | |
12192 | function or variable by writing the @code{asm} (or @code{__asm__}) | |
12193 | keyword after the declarator. | |
12194 | It is up to you to make sure that the assembler names you choose do not | |
12195 | conflict with any other assembler symbols, or reference registers. | |
12196 | ||
12197 | @subsubheading Assembler names for data | |
12198 | ||
12199 | This sample shows how to specify the assembler name for data: | |
12200 | ||
12201 | @smallexample | |
12202 | int foo asm ("myfoo") = 2; | |
12203 | @end smallexample | |
12204 | ||
12205 | @noindent | |
12206 | This specifies that the name to be used for the variable @code{foo} in | |
12207 | the assembler code should be @samp{myfoo} rather than the usual | |
12208 | @samp{_foo}. | |
12209 | ||
12210 | On systems where an underscore is normally prepended to the name of a C | |
12211 | variable, this feature allows you to define names for the | |
12212 | linker that do not start with an underscore. | |
12213 | ||
12214 | GCC does not support using this feature with a non-static local variable | |
12215 | since such variables do not have assembler names. If you are | |
12216 | trying to put the variable in a particular register, see | |
12217 | @ref{Explicit Register Variables}. | |
12218 | ||
12219 | @subsubheading Assembler names for functions | |
12220 | ||
12221 | To specify the assembler name for functions, write a declaration for the | |
12222 | function before its definition and put @code{asm} there, like this: | |
12223 | ||
12224 | @smallexample | |
12225 | int func (int x, int y) asm ("MYFUNC"); | |
12226 | ||
12227 | int func (int x, int y) | |
12228 | @{ | |
12229 | /* @r{@dots{}} */ | |
12230 | @end smallexample | |
12231 | ||
12232 | @noindent | |
12233 | This specifies that the name to be used for the function @code{func} in | |
12234 | the assembler code should be @code{MYFUNC}. | |
12235 | ||
12236 | @node Explicit Register Variables | |
12237 | @subsection Variables in Specified Registers | |
12238 | @anchor{Explicit Reg Vars} | |
12239 | @cindex explicit register variables | |
12240 | @cindex variables in specified registers | |
12241 | @cindex specified registers | |
12242 | ||
12243 | GNU C allows you to associate specific hardware registers with C | |
12244 | variables. In almost all cases, allowing the compiler to assign | |
12245 | registers produces the best code. However under certain unusual | |
12246 | circumstances, more precise control over the variable storage is | |
12247 | required. | |
12248 | ||
12249 | Both global and local variables can be associated with a register. The | |
12250 | consequences of performing this association are very different between | |
12251 | the two, as explained in the sections below. | |
12252 | ||
12253 | @menu | |
12254 | * Global Register Variables:: Variables declared at global scope. | |
12255 | * Local Register Variables:: Variables declared within a function. | |
12256 | @end menu | |
12257 | ||
12258 | @node Global Register Variables | |
12259 | @subsubsection Defining Global Register Variables | |
12260 | @anchor{Global Reg Vars} | |
12261 | @cindex global register variables | |
12262 | @cindex registers, global variables in | |
12263 | @cindex registers, global allocation | |
12264 | ||
12265 | You can define a global register variable and associate it with a specified | |
12266 | register like this: | |
12267 | ||
12268 | @smallexample | |
12269 | register int *foo asm ("r12"); | |
12270 | @end smallexample | |
12271 | ||
12272 | @noindent | |
12273 | Here @code{r12} is the name of the register that should be used. Note that | |
12274 | this is the same syntax used for defining local register variables, but for | |
12275 | a global variable the declaration appears outside a function. The | |
12276 | @code{register} keyword is required, and cannot be combined with | |
12277 | @code{static}. The register name must be a valid register name for the | |
12278 | target platform. | |
12279 | ||
12280 | Do not use type qualifiers such as @code{const} and @code{volatile}, as | |
12281 | the outcome may be contrary to expectations. In particular, using the | |
12282 | @code{volatile} qualifier does not fully prevent the compiler from | |
12283 | optimizing accesses to the register. | |
12284 | ||
12285 | Registers are a scarce resource on most systems and allowing the | |
12286 | compiler to manage their usage usually results in the best code. However, | |
12287 | under special circumstances it can make sense to reserve some globally. | |
12288 | For example this may be useful in programs such as programming language | |
12289 | interpreters that have a couple of global variables that are accessed | |
12290 | very often. | |
12291 | ||
12292 | After defining a global register variable, for the current compilation | |
12293 | unit: | |
12294 | ||
12295 | @itemize @bullet | |
12296 | @item If the register is a call-saved register, call ABI is affected: | |
12297 | the register will not be restored in function epilogue sequences after | |
12298 | the variable has been assigned. Therefore, functions cannot safely | |
12299 | return to callers that assume standard ABI. | |
12300 | @item Conversely, if the register is a call-clobbered register, making | |
12301 | calls to functions that use standard ABI may lose contents of the variable. | |
12302 | Such calls may be created by the compiler even if none are evident in | |
12303 | the original program, for example when libgcc functions are used to | |
12304 | make up for unavailable instructions. | |
12305 | @item Accesses to the variable may be optimized as usual and the register | |
12306 | remains available for allocation and use in any computations, provided that | |
12307 | observable values of the variable are not affected. | |
12308 | @item If the variable is referenced in inline assembly, the type of access | |
12309 | must be provided to the compiler via constraints (@pxref{Constraints}). | |
12310 | Accesses from basic asms are not supported. | |
12311 | @end itemize | |
12312 | ||
12313 | Note that these points @emph{only} apply to code that is compiled with the | |
12314 | definition. The behavior of code that is merely linked in (for example | |
12315 | code from libraries) is not affected. | |
12316 | ||
12317 | If you want to recompile source files that do not actually use your global | |
12318 | register variable so they do not use the specified register for any other | |
12319 | purpose, you need not actually add the global register declaration to | |
12320 | their source code. It suffices to specify the compiler option | |
12321 | @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the | |
12322 | register. | |
12323 | ||
12324 | @subsubheading Declaring the variable | |
12325 | ||
12326 | Global register variables cannot have initial values, because an | |
12327 | executable file has no means to supply initial contents for a register. | |
12328 | ||
12329 | When selecting a register, choose one that is normally saved and | |
12330 | restored by function calls on your machine. This ensures that code | |
12331 | which is unaware of this reservation (such as library routines) will | |
12332 | restore it before returning. | |
12333 | ||
12334 | On machines with register windows, be sure to choose a global | |
12335 | register that is not affected magically by the function call mechanism. | |
12336 | ||
12337 | @subsubheading Using the variable | |
12338 | ||
12339 | @cindex @code{qsort}, and global register variables | |
12340 | When calling routines that are not aware of the reservation, be | |
12341 | cautious if those routines call back into code which uses them. As an | |
12342 | example, if you call the system library version of @code{qsort}, it may | |
12343 | clobber your registers during execution, but (if you have selected | |
12344 | appropriate registers) it will restore them before returning. However | |
12345 | it will @emph{not} restore them before calling @code{qsort}'s comparison | |
12346 | function. As a result, global values will not reliably be available to | |
12347 | the comparison function unless the @code{qsort} function itself is rebuilt. | |
12348 | ||
12349 | Similarly, it is not safe to access the global register variables from signal | |
12350 | handlers or from more than one thread of control. Unless you recompile | |
12351 | them specially for the task at hand, the system library routines may | |
12352 | temporarily use the register for other things. Furthermore, since the register | |
12353 | is not reserved exclusively for the variable, accessing it from handlers of | |
12354 | asynchronous signals may observe unrelated temporary values residing in the | |
12355 | register. | |
12356 | ||
12357 | @cindex register variable after @code{longjmp} | |
12358 | @cindex global register after @code{longjmp} | |
12359 | @cindex value after @code{longjmp} | |
12360 | @findex longjmp | |
12361 | @findex setjmp | |
12362 | On most machines, @code{longjmp} restores to each global register | |
12363 | variable the value it had at the time of the @code{setjmp}. On some | |
12364 | machines, however, @code{longjmp} does not change the value of global | |
12365 | register variables. To be portable, the function that called @code{setjmp} | |
12366 | should make other arrangements to save the values of the global register | |
12367 | variables, and to restore them in a @code{longjmp}. This way, the same | |
12368 | thing happens regardless of what @code{longjmp} does. | |
12369 | ||
12370 | @node Local Register Variables | |
12371 | @subsubsection Specifying Registers for Local Variables | |
12372 | @anchor{Local Reg Vars} | |
12373 | @cindex local variables, specifying registers | |
12374 | @cindex specifying registers for local variables | |
12375 | @cindex registers for local variables | |
12376 | ||
12377 | You can define a local register variable and associate it with a specified | |
12378 | register like this: | |
12379 | ||
12380 | @smallexample | |
12381 | register int *foo asm ("r12"); | |
12382 | @end smallexample | |
12383 | ||
12384 | @noindent | |
12385 | Here @code{r12} is the name of the register that should be used. Note | |
12386 | that this is the same syntax used for defining global register variables, | |
12387 | but for a local variable the declaration appears within a function. The | |
12388 | @code{register} keyword is required, and cannot be combined with | |
12389 | @code{static}. The register name must be a valid register name for the | |
12390 | target platform. | |
12391 | ||
12392 | Do not use type qualifiers such as @code{const} and @code{volatile}, as | |
12393 | the outcome may be contrary to expectations. In particular, when the | |
12394 | @code{const} qualifier is used, the compiler may substitute the | |
12395 | variable with its initializer in @code{asm} statements, which may cause | |
12396 | the corresponding operand to appear in a different register. | |
12397 | ||
12398 | As with global register variables, it is recommended that you choose | |
12399 | a register that is normally saved and restored by function calls on your | |
12400 | machine, so that calls to library routines will not clobber it. | |
12401 | ||
12402 | The only supported use for this feature is to specify registers | |
12403 | for input and output operands when calling Extended @code{asm} | |
12404 | (@pxref{Extended Asm}). This may be necessary if the constraints for a | |
12405 | particular machine don't provide sufficient control to select the desired | |
12406 | register. To force an operand into a register, create a local variable | |
12407 | and specify the register name after the variable's declaration. Then use | |
12408 | the local variable for the @code{asm} operand and specify any constraint | |
12409 | letter that matches the register: | |
12410 | ||
12411 | @smallexample | |
12412 | register int *p1 asm ("r0") = @dots{}; | |
12413 | register int *p2 asm ("r1") = @dots{}; | |
12414 | register int *result asm ("r0"); | |
12415 | asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); | |
12416 | @end smallexample | |
12417 | ||
12418 | @emph{Warning:} In the above example, be aware that a register (for example | |
12419 | @code{r0}) can be call-clobbered by subsequent code, including function | |
12420 | calls and library calls for arithmetic operators on other variables (for | |
12421 | example the initialization of @code{p2}). In this case, use temporary | |
12422 | variables for expressions between the register assignments: | |
12423 | ||
12424 | @smallexample | |
12425 | int t1 = @dots{}; | |
12426 | register int *p1 asm ("r0") = @dots{}; | |
12427 | register int *p2 asm ("r1") = t1; | |
12428 | register int *result asm ("r0"); | |
12429 | asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); | |
12430 | @end smallexample | |
12431 | ||
12432 | Defining a register variable does not reserve the register. Other than | |
12433 | when invoking the Extended @code{asm}, the contents of the specified | |
12434 | register are not guaranteed. For this reason, the following uses | |
12435 | are explicitly @emph{not} supported. If they appear to work, it is only | |
12436 | happenstance, and may stop working as intended due to (seemingly) | |
12437 | unrelated changes in surrounding code, or even minor changes in the | |
12438 | optimization of a future version of gcc: | |
12439 | ||
12440 | @itemize @bullet | |
12441 | @item Passing parameters to or from Basic @code{asm} | |
12442 | @item Passing parameters to or from Extended @code{asm} without using input | |
12443 | or output operands. | |
12444 | @item Passing parameters to or from routines written in assembler (or | |
12445 | other languages) using non-standard calling conventions. | |
12446 | @end itemize | |
12447 | ||
12448 | Some developers use Local Register Variables in an attempt to improve | |
12449 | gcc's allocation of registers, especially in large functions. In this | |
12450 | case the register name is essentially a hint to the register allocator. | |
12451 | While in some instances this can generate better code, improvements are | |
12452 | subject to the whims of the allocator/optimizers. Since there are no | |
12453 | guarantees that your improvements won't be lost, this usage of Local | |
12454 | Register Variables is discouraged. | |
12455 | ||
12456 | On the MIPS platform, there is related use for local register variables | |
12457 | with slightly different characteristics (@pxref{MIPS Coprocessors,, | |
12458 | Defining coprocessor specifics for MIPS targets, gccint, | |
12459 | GNU Compiler Collection (GCC) Internals}). | |
12460 | ||
12461 | @node Size of an asm | |
12462 | @subsection Size of an @code{asm} | |
12463 | ||
12464 | Some targets require that GCC track the size of each instruction used | |
12465 | in order to generate correct code. Because the final length of the | |
12466 | code produced by an @code{asm} statement is only known by the | |
12467 | assembler, GCC must make an estimate as to how big it will be. It | |
12468 | does this by counting the number of instructions in the pattern of the | |
12469 | @code{asm} and multiplying that by the length of the longest | |
12470 | instruction supported by that processor. (When working out the number | |
12471 | of instructions, it assumes that any occurrence of a newline or of | |
12472 | whatever statement separator character is supported by the assembler --- | |
12473 | typically @samp{;} --- indicates the end of an instruction.) | |
12474 | ||
12475 | Normally, GCC's estimate is adequate to ensure that correct | |
12476 | code is generated, but it is possible to confuse the compiler if you use | |
12477 | pseudo instructions or assembler macros that expand into multiple real | |
12478 | instructions, or if you use assembler directives that expand to more | |
12479 | space in the object file than is needed for a single instruction. | |
12480 | If this happens then the assembler may produce a diagnostic saying that | |
12481 | a label is unreachable. | |
12482 | ||
12483 | @cindex @code{asm inline} | |
12484 | This size is also used for inlining decisions. If you use @code{asm inline} | |
12485 | instead of just @code{asm}, then for inlining purposes the size of the asm | |
12486 | is taken as the minimum size, ignoring how many instructions GCC thinks it is. | |
12487 | ||
12488 | @node Alternate Keywords | |
12489 | @section Alternate Keywords | |
12490 | @cindex alternate keywords | |
12491 | @cindex keywords, alternate | |
12492 | ||
12493 | @option{-ansi} and the various @option{-std} options disable certain | |
12494 | keywords. This causes trouble when you want to use GNU C extensions, or | |
12495 | a general-purpose header file that should be usable by all programs, | |
12496 | including ISO C programs. The keywords @code{asm}, @code{typeof} and | |
12497 | @code{inline} are not available in programs compiled with | |
12498 | @option{-ansi} or @option{-std} (although @code{inline} can be used in a | |
12499 | program compiled with @option{-std=c99} or a later standard). The | |
12500 | ISO C99 keyword | |
12501 | @code{restrict} is only available when @option{-std=gnu99} (which will | |
12502 | eventually be the default) or @option{-std=c99} (or the equivalent | |
12503 | @option{-std=iso9899:1999}), or an option for a later standard | |
12504 | version, is used. | |
12505 | ||
12506 | The way to solve these problems is to put @samp{__} at the beginning and | |
12507 | end of each problematical keyword. For example, use @code{__asm__} | |
12508 | instead of @code{asm}, and @code{__inline__} instead of @code{inline}. | |
12509 | ||
12510 | Other C compilers won't accept these alternative keywords; if you want to | |
12511 | compile with another compiler, you can define the alternate keywords as | |
12512 | macros to replace them with the customary keywords. It looks like this: | |
12513 | ||
12514 | @smallexample | |
12515 | #ifndef __GNUC__ | |
12516 | #define __asm__ asm | |
12517 | #endif | |
12518 | @end smallexample | |
12519 | ||
12520 | @findex __extension__ | |
12521 | @opindex pedantic | |
12522 | @option{-pedantic} and other options cause warnings for many GNU C extensions. | |
207a5daa RS |
12523 | You can suppress such warnings using the keyword @code{__extension__}. |
12524 | Specifically: | |
12525 | ||
12526 | @itemize @bullet | |
12527 | @item | |
12528 | Writing @code{__extension__} before an expression prevents warnings | |
12529 | about extensions within that expression. | |
12530 | ||
12531 | @item | |
12532 | In C, writing: | |
12533 | ||
12534 | @smallexample | |
12535 | [[__extension__ @dots{}]] | |
12536 | @end smallexample | |
12537 | ||
12538 | suppresses warnings about using @samp{[[]]} attributes in C versions | |
094a609c | 12539 | that predate C23@. Since the scope token @samp{::} is not a single |
207a5daa RS |
12540 | lexing token in earlier versions of C, this construct also allows two colons |
12541 | to be used in place of @code{::}. GCC does not check whether the two | |
12542 | colons are immediately adjacent. | |
12543 | @end itemize | |
12544 | ||
12545 | @code{__extension__} has no effect aside from this. | |
d77de738 ML |
12546 | |
12547 | @node Incomplete Enums | |
12548 | @section Incomplete @code{enum} Types | |
12549 | ||
12550 | You can define an @code{enum} tag without specifying its possible values. | |
12551 | This results in an incomplete type, much like what you get if you write | |
12552 | @code{struct foo} without describing the elements. A later declaration | |
12553 | that does specify the possible values completes the type. | |
12554 | ||
12555 | You cannot allocate variables or storage using the type while it is | |
12556 | incomplete. However, you can work with pointers to that type. | |
12557 | ||
12558 | This extension may not be very useful, but it makes the handling of | |
12559 | @code{enum} more consistent with the way @code{struct} and @code{union} | |
12560 | are handled. | |
12561 | ||
12562 | This extension is not supported by GNU C++. | |
12563 | ||
12564 | @node Function Names | |
12565 | @section Function Names as Strings | |
12566 | @cindex @code{__func__} identifier | |
12567 | @cindex @code{__FUNCTION__} identifier | |
12568 | @cindex @code{__PRETTY_FUNCTION__} identifier | |
12569 | ||
12570 | GCC provides three magic constants that hold the name of the current | |
12571 | function as a string. In C++11 and later modes, all three are treated | |
12572 | as constant expressions and can be used in @code{constexpr} constexts. | |
12573 | The first of these constants is @code{__func__}, which is part of | |
12574 | the C99 standard: | |
12575 | ||
12576 | The identifier @code{__func__} is implicitly declared by the translator | |
12577 | as if, immediately following the opening brace of each function | |
12578 | definition, the declaration | |
12579 | ||
12580 | @smallexample | |
12581 | static const char __func__[] = "function-name"; | |
12582 | @end smallexample | |
12583 | ||
12584 | @noindent | |
12585 | appeared, where function-name is the name of the lexically-enclosing | |
12586 | function. This name is the unadorned name of the function. As an | |
12587 | extension, at file (or, in C++, namespace scope), @code{__func__} | |
12588 | evaluates to the empty string. | |
12589 | ||
12590 | @code{__FUNCTION__} is another name for @code{__func__}, provided for | |
12591 | backward compatibility with old versions of GCC. | |
12592 | ||
12593 | In C, @code{__PRETTY_FUNCTION__} is yet another name for | |
12594 | @code{__func__}, except that at file scope (or, in C++, namespace scope), | |
12595 | it evaluates to the string @code{"top level"}. In addition, in C++, | |
12596 | @code{__PRETTY_FUNCTION__} contains the signature of the function as | |
12597 | well as its bare name. For example, this program: | |
12598 | ||
12599 | @smallexample | |
12600 | extern "C" int printf (const char *, ...); | |
12601 | ||
12602 | class a @{ | |
12603 | public: | |
12604 | void sub (int i) | |
12605 | @{ | |
12606 | printf ("__FUNCTION__ = %s\n", __FUNCTION__); | |
12607 | printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); | |
12608 | @} | |
12609 | @}; | |
12610 | ||
12611 | int | |
12612 | main (void) | |
12613 | @{ | |
12614 | a ax; | |
12615 | ax.sub (0); | |
12616 | return 0; | |
12617 | @} | |
12618 | @end smallexample | |
12619 | ||
12620 | @noindent | |
12621 | gives this output: | |
12622 | ||
12623 | @smallexample | |
12624 | __FUNCTION__ = sub | |
12625 | __PRETTY_FUNCTION__ = void a::sub(int) | |
12626 | @end smallexample | |
12627 | ||
12628 | These identifiers are variables, not preprocessor macros, and may not | |
12629 | be used to initialize @code{char} arrays or be concatenated with string | |
12630 | literals. | |
12631 | ||
12632 | @node Return Address | |
12633 | @section Getting the Return or Frame Address of a Function | |
12634 | ||
12635 | These functions may be used to get information about the callers of a | |
12636 | function. | |
12637 | ||
f25efe50 | 12638 | @defbuiltin{{void *} __builtin_return_address (unsigned int @var{level})} |
d77de738 ML |
12639 | This function returns the return address of the current function, or of |
12640 | one of its callers. The @var{level} argument is number of frames to | |
12641 | scan up the call stack. A value of @code{0} yields the return address | |
12642 | of the current function, a value of @code{1} yields the return address | |
12643 | of the caller of the current function, and so forth. When inlining | |
12644 | the expected behavior is that the function returns the address of | |
12645 | the function that is returned to. To work around this behavior use | |
12646 | the @code{noinline} function attribute. | |
12647 | ||
12648 | The @var{level} argument must be a constant integer. | |
12649 | ||
12650 | On some machines it may be impossible to determine the return address of | |
12651 | any function other than the current one; in such cases, or when the top | |
12652 | of the stack has been reached, this function returns an unspecified | |
12653 | value. In addition, @code{__builtin_frame_address} may be used | |
12654 | to determine if the top of the stack has been reached. | |
12655 | ||
12656 | Additional post-processing of the returned value may be needed, see | |
12657 | @code{__builtin_extract_return_addr}. | |
12658 | ||
12659 | The stored representation of the return address in memory may be different | |
12660 | from the address returned by @code{__builtin_return_address}. For example, | |
12661 | on AArch64 the stored address may be mangled with return address signing | |
12662 | whereas the address returned by @code{__builtin_return_address} is not. | |
12663 | ||
12664 | Calling this function with a nonzero argument can have unpredictable | |
12665 | effects, including crashing the calling program. As a result, calls | |
12666 | that are considered unsafe are diagnosed when the @option{-Wframe-address} | |
12667 | option is in effect. Such calls should only be made in debugging | |
12668 | situations. | |
12669 | ||
12670 | On targets where code addresses are representable as @code{void *}, | |
12671 | @smallexample | |
12672 | void *addr = __builtin_extract_return_addr (__builtin_return_address (0)); | |
12673 | @end smallexample | |
12674 | gives the code address where the current function would return. For example, | |
12675 | such an address may be used with @code{dladdr} or other interfaces that work | |
12676 | with code addresses. | |
f25efe50 | 12677 | @enddefbuiltin |
d77de738 | 12678 | |
f25efe50 | 12679 | @defbuiltin{{void *} __builtin_extract_return_addr (void *@var{addr})} |
d77de738 ML |
12680 | The address as returned by @code{__builtin_return_address} may have to be fed |
12681 | through this function to get the actual encoded address. For example, on the | |
12682 | 31-bit S/390 platform the highest bit has to be masked out, or on SPARC | |
12683 | platforms an offset has to be added for the true next instruction to be | |
12684 | executed. | |
12685 | ||
12686 | If no fixup is needed, this function simply passes through @var{addr}. | |
f25efe50 | 12687 | @enddefbuiltin |
d77de738 | 12688 | |
f25efe50 | 12689 | @defbuiltin{{void *} __builtin_frob_return_addr (void *@var{addr})} |
d77de738 | 12690 | This function does the reverse of @code{__builtin_extract_return_addr}. |
f25efe50 | 12691 | @enddefbuiltin |
d77de738 | 12692 | |
f25efe50 | 12693 | @defbuiltin{{void *} __builtin_frame_address (unsigned int @var{level})} |
d77de738 ML |
12694 | This function is similar to @code{__builtin_return_address}, but it |
12695 | returns the address of the function frame rather than the return address | |
12696 | of the function. Calling @code{__builtin_frame_address} with a value of | |
12697 | @code{0} yields the frame address of the current function, a value of | |
12698 | @code{1} yields the frame address of the caller of the current function, | |
12699 | and so forth. | |
12700 | ||
12701 | The frame is the area on the stack that holds local variables and saved | |
12702 | registers. The frame address is normally the address of the first word | |
12703 | pushed on to the stack by the function. However, the exact definition | |
12704 | depends upon the processor and the calling convention. If the processor | |
12705 | has a dedicated frame pointer register, and the function has a frame, | |
12706 | then @code{__builtin_frame_address} returns the value of the frame | |
12707 | pointer register. | |
12708 | ||
12709 | On some machines it may be impossible to determine the frame address of | |
12710 | any function other than the current one; in such cases, or when the top | |
12711 | of the stack has been reached, this function returns @code{0} if | |
12712 | the first frame pointer is properly initialized by the startup code. | |
12713 | ||
12714 | Calling this function with a nonzero argument can have unpredictable | |
12715 | effects, including crashing the calling program. As a result, calls | |
12716 | that are considered unsafe are diagnosed when the @option{-Wframe-address} | |
12717 | option is in effect. Such calls should only be made in debugging | |
12718 | situations. | |
f25efe50 | 12719 | @enddefbuiltin |
d77de738 | 12720 | |
f0a90c7d | 12721 | @deftypefn {Built-in Function} {void *} __builtin_stack_address () |
4e0a4673 AO |
12722 | This function returns the stack pointer register, offset by |
12723 | @code{STACK_POINTER_OFFSET}. | |
12724 | ||
12725 | Conceptually, the returned address returned by this built-in function is | |
12726 | the boundary between the stack area allocated for use by its caller, and | |
12727 | the area that could be modified by a function call, that the caller | |
12728 | could safely zero-out before or after (but not during) the call | |
12729 | sequence. | |
12730 | ||
12731 | Arguments for a callee may be preallocated as part of the caller's stack | |
12732 | frame, or allocated on a per-call basis, depending on the target, so | |
12733 | they may be on either side of this boundary. | |
12734 | ||
12735 | Even if the stack pointer is biased, the result is not. The register | |
12736 | save area on SPARC is regarded as modifiable by calls, rather than as | |
12737 | allocated for use by the caller function, since it is never in use while | |
12738 | the caller function itself is running. | |
12739 | ||
12740 | Red zones that only leaf functions could use are also regarded as | |
12741 | modifiable by calls, rather than as allocated for use by the caller. | |
12742 | This is only theoretical, since leaf functions do not issue calls, but a | |
12743 | constant offset makes this built-in function more predictable. | |
f0a90c7d AO |
12744 | @end deftypefn |
12745 | ||
12746 | @node Stack Scrubbing | |
12747 | @section Stack scrubbing internal interfaces | |
12748 | ||
12749 | Stack scrubbing involves cooperation between a @code{strub} context, | |
12750 | i.e., a function whose stack frame is to be zeroed-out, and its callers. | |
12751 | The caller initializes a stack watermark, the @code{strub} context | |
12752 | updates the watermark according to its stack use, and the caller zeroes | |
12753 | it out once it regains control, whether by the callee's returning or by | |
12754 | an exception. | |
12755 | ||
12756 | Each of these steps is performed by a different builtin function call. | |
12757 | Calls to these builtins are introduced automatically, in response to | |
12758 | @code{strub} attributes and command-line options; they are not expected | |
12759 | to be explicitly called by source code. | |
12760 | ||
12761 | The functions that implement the builtins are available in libgcc but, | |
12762 | depending on optimization levels, they are expanded internally, adjusted | |
12763 | to account for inlining, and sometimes combined/deferred (e.g. passing | |
12764 | the caller-supplied watermark on to callees, refraining from erasing | |
12765 | stack areas that the caller will) to enable tail calls and to optimize | |
12766 | for code size. | |
12767 | ||
12768 | @deftypefn {Built-in Function} {void} __builtin___strub_enter (void **@var{wmptr}) | |
12769 | This function initializes a stack @var{watermark} variable with the | |
12770 | current top of the stack. A call to this builtin function is introduced | |
12771 | before entering a @code{strub} context. It remains as a function call | |
12772 | if optimization is not enabled. | |
12773 | @end deftypefn | |
12774 | ||
12775 | @deftypefn {Built-in Function} {void} __builtin___strub_update (void **@var{wmptr}) | |
12776 | This function updates a stack @var{watermark} variable with the current | |
12777 | top of the stack, if it tops the previous watermark. A call to this | |
12778 | builtin function is inserted within @code{strub} contexts, whenever | |
12779 | additional stack space may have been used. It remains as a function | |
12780 | call at optimization levels lower than 2. | |
12781 | @end deftypefn | |
12782 | ||
12783 | @deftypefn {Built-in Function} {void} __builtin___strub_leave (void **@var{wmptr}) | |
12784 | This function overwrites the memory area between the current top of the | |
12785 | stack, and the @var{watermark}ed address. A call to this builtin | |
12786 | function is inserted after leaving a @code{strub} context. It remains | |
12787 | as a function call at optimization levels lower than 3, and it is guarded by | |
12788 | a condition at level 2. | |
12789 | @end deftypefn | |
12790 | ||
d77de738 ML |
12791 | @node Vector Extensions |
12792 | @section Using Vector Instructions through Built-in Functions | |
12793 | ||
12794 | On some targets, the instruction set contains SIMD vector instructions which | |
12795 | operate on multiple values contained in one large register at the same time. | |
12796 | For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used | |
12797 | this way. | |
12798 | ||
12799 | The first step in using these extensions is to provide the necessary data | |
12800 | types. This should be done using an appropriate @code{typedef}: | |
12801 | ||
12802 | @smallexample | |
12803 | typedef int v4si __attribute__ ((vector_size (16))); | |
12804 | @end smallexample | |
12805 | ||
12806 | @noindent | |
12807 | The @code{int} type specifies the @dfn{base type}, while the attribute specifies | |
12808 | the vector size for the variable, measured in bytes. For example, the | |
12809 | declaration above causes the compiler to set the mode for the @code{v4si} | |
12810 | type to be 16 bytes wide and divided into @code{int} sized units. For | |
12811 | a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the | |
12812 | corresponding mode of @code{foo} is @acronym{V4SI}. | |
12813 | ||
12814 | The @code{vector_size} attribute is only applicable to integral and | |
12815 | floating scalars, although arrays, pointers, and function return values | |
12816 | are allowed in conjunction with this construct. Only sizes that are | |
12817 | positive power-of-two multiples of the base type size are currently allowed. | |
12818 | ||
12819 | All the basic integer types can be used as base types, both as signed | |
12820 | and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, | |
12821 | @code{long long}. In addition, @code{float} and @code{double} can be | |
12822 | used to build floating-point vector types. | |
12823 | ||
12824 | Specifying a combination that is not valid for the current architecture | |
12825 | causes GCC to synthesize the instructions using a narrower mode. | |
12826 | For example, if you specify a variable of type @code{V4SI} and your | |
12827 | architecture does not allow for this specific SIMD type, GCC | |
12828 | produces code that uses 4 @code{SIs}. | |
12829 | ||
12830 | The types defined in this manner can be used with a subset of normal C | |
12831 | operations. Currently, GCC allows using the following operators | |
12832 | on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. | |
12833 | ||
12834 | The operations behave like C++ @code{valarrays}. Addition is defined as | |
12835 | the addition of the corresponding elements of the operands. For | |
12836 | example, in the code below, each of the 4 elements in @var{a} is | |
12837 | added to the corresponding 4 elements in @var{b} and the resulting | |
12838 | vector is stored in @var{c}. | |
12839 | ||
12840 | @smallexample | |
12841 | typedef int v4si __attribute__ ((vector_size (16))); | |
12842 | ||
12843 | v4si a, b, c; | |
12844 | ||
12845 | c = a + b; | |
12846 | @end smallexample | |
12847 | ||
12848 | Subtraction, multiplication, division, and the logical operations | |
12849 | operate in a similar manner. Likewise, the result of using the unary | |
12850 | minus or complement operators on a vector type is a vector whose | |
12851 | elements are the negative or complemented values of the corresponding | |
12852 | elements in the operand. | |
12853 | ||
12854 | It is possible to use shifting operators @code{<<}, @code{>>} on | |
12855 | integer-type vectors. The operation is defined as following: @code{@{a0, | |
12856 | a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, | |
9f926f3a AM |
12857 | @dots{}, an >> bn@}}@. Unlike OpenCL, values of @code{b} are not |
12858 | implicitly taken modulo bit width of the base type @code{B}, and the behavior | |
12859 | is undefined if any @code{bi} is greater than or equal to @code{B}. | |
12860 | ||
12861 | In contrast to scalar operations in C and C++, operands of integer vector | |
12862 | operations do not undergo integer promotions. | |
12863 | ||
12864 | Operands of binary vector operations must have the same number of | |
d77de738 ML |
12865 | elements. |
12866 | ||
12867 | For convenience, it is allowed to use a binary vector operation | |
12868 | where one operand is a scalar. In that case the compiler transforms | |
12869 | the scalar operand into a vector where each element is the scalar from | |
12870 | the operation. The transformation happens only if the scalar could be | |
12871 | safely converted to the vector-element type. | |
12872 | Consider the following code. | |
12873 | ||
12874 | @smallexample | |
12875 | typedef int v4si __attribute__ ((vector_size (16))); | |
12876 | ||
12877 | v4si a, b, c; | |
12878 | long l; | |
12879 | ||
12880 | a = b + 1; /* a = b + @{1,1,1,1@}; */ | |
12881 | a = 2 * b; /* a = @{2,2,2,2@} * b; */ | |
12882 | ||
12883 | a = l + a; /* Error, cannot convert long to int. */ | |
12884 | @end smallexample | |
12885 | ||
12886 | Vectors can be subscripted as if the vector were an array with | |
12887 | the same number of elements and base type. Out of bound accesses | |
12888 | invoke undefined behavior at run time. Warnings for out of bound | |
12889 | accesses for vector subscription can be enabled with | |
12890 | @option{-Warray-bounds}. | |
12891 | ||
12892 | Vector comparison is supported with standard comparison | |
12893 | operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be | |
12894 | vector expressions of integer-type or real-type. Comparison between | |
12895 | integer-type vectors and real-type vectors are not supported. The | |
12896 | result of the comparison is a vector of the same width and number of | |
12897 | elements as the comparison operands with a signed integral element | |
12898 | type. | |
12899 | ||
12900 | Vectors are compared element-wise producing 0 when comparison is false | |
12901 | and -1 (constant of the appropriate type where all bits are set) | |
12902 | otherwise. Consider the following example. | |
12903 | ||
12904 | @smallexample | |
12905 | typedef int v4si __attribute__ ((vector_size (16))); | |
12906 | ||
12907 | v4si a = @{1,2,3,4@}; | |
12908 | v4si b = @{3,2,1,4@}; | |
12909 | v4si c; | |
12910 | ||
12911 | c = a > b; /* The result would be @{0, 0,-1, 0@} */ | |
12912 | c = a == b; /* The result would be @{0,-1, 0,-1@} */ | |
12913 | @end smallexample | |
12914 | ||
12915 | In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where | |
12916 | @code{b} and @code{c} are vectors of the same type and @code{a} is an | |
12917 | integer vector with the same number of elements of the same size as @code{b} | |
12918 | and @code{c}, computes all three arguments and creates a vector | |
12919 | @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in | |
12920 | OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. | |
12921 | As in the case of binary operations, this syntax is also accepted when | |
12922 | one of @code{b} or @code{c} is a scalar that is then transformed into a | |
12923 | vector. If both @code{b} and @code{c} are scalars and the type of | |
12924 | @code{true?b:c} has the same size as the element type of @code{a}, then | |
12925 | @code{b} and @code{c} are converted to a vector type whose elements have | |
12926 | this type and with the same number of elements as @code{a}. | |
12927 | ||
12928 | In C++, the logic operators @code{!, &&, ||} are available for vectors. | |
12929 | @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to | |
12930 | @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. | |
12931 | For mixed operations between a scalar @code{s} and a vector @code{v}, | |
12932 | @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is | |
12933 | short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. | |
12934 | ||
12935 | @findex __builtin_shuffle | |
12936 | Vector shuffling is available using functions | |
12937 | @code{__builtin_shuffle (vec, mask)} and | |
12938 | @code{__builtin_shuffle (vec0, vec1, mask)}. | |
12939 | Both functions construct a permutation of elements from one or two | |
12940 | vectors and return a vector of the same type as the input vector(s). | |
12941 | The @var{mask} is an integral vector with the same width (@var{W}) | |
12942 | and element count (@var{N}) as the output vector. | |
12943 | ||
12944 | The elements of the input vectors are numbered in memory ordering of | |
12945 | @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The | |
12946 | elements of @var{mask} are considered modulo @var{N} in the single-operand | |
12947 | case and modulo @math{2*@var{N}} in the two-operand case. | |
12948 | ||
12949 | Consider the following example, | |
12950 | ||
12951 | @smallexample | |
12952 | typedef int v4si __attribute__ ((vector_size (16))); | |
12953 | ||
12954 | v4si a = @{1,2,3,4@}; | |
12955 | v4si b = @{5,6,7,8@}; | |
12956 | v4si mask1 = @{0,1,1,3@}; | |
12957 | v4si mask2 = @{0,4,2,5@}; | |
12958 | v4si res; | |
12959 | ||
12960 | res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ | |
12961 | res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ | |
12962 | @end smallexample | |
12963 | ||
12964 | Note that @code{__builtin_shuffle} is intentionally semantically | |
12965 | compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. | |
12966 | ||
12967 | You can declare variables and use them in function calls and returns, as | |
12968 | well as in assignments and some casts. You can specify a vector type as | |
12969 | a return type for a function. Vector types can also be used as function | |
12970 | arguments. It is possible to cast from one vector type to another, | |
12971 | provided they are of the same size (in fact, you can also cast vectors | |
12972 | to and from other datatypes of the same size). | |
12973 | ||
12974 | You cannot operate between vectors of different lengths or different | |
12975 | signedness without a cast. | |
12976 | ||
12977 | @findex __builtin_shufflevector | |
12978 | Vector shuffling is available using the | |
12979 | @code{__builtin_shufflevector (vec1, vec2, index...)} | |
12980 | function. @var{vec1} and @var{vec2} must be expressions with | |
12981 | vector type with a compatible element type. The result of | |
12982 | @code{__builtin_shufflevector} is a vector with the same element type | |
12983 | as @var{vec1} and @var{vec2} but that has an element count equal to | |
12984 | the number of indices specified. | |
12985 | ||
12986 | The @var{index} arguments are a list of integers that specify the | |
12987 | elements indices of the first two vectors that should be extracted and | |
12988 | returned in a new vector. These element indices are numbered sequentially | |
12989 | starting with the first vector, continuing into the second vector. | |
12990 | An index of -1 can be used to indicate that the corresponding element in | |
12991 | the returned vector is a don't care and can be freely chosen to optimized | |
12992 | the generated code sequence performing the shuffle operation. | |
12993 | ||
12994 | Consider the following example, | |
12995 | @smallexample | |
12996 | typedef int v4si __attribute__ ((vector_size (16))); | |
12997 | typedef int v8si __attribute__ ((vector_size (32))); | |
12998 | ||
12999 | v8si a = @{1,-2,3,-4,5,-6,7,-8@}; | |
13000 | v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */ | |
13001 | v4si c = @{-2,-4,-6,-8@}; | |
13002 | v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */ | |
13003 | @end smallexample | |
13004 | ||
13005 | @findex __builtin_convertvector | |
13006 | Vector conversion is available using the | |
13007 | @code{__builtin_convertvector (vec, vectype)} | |
13008 | function. @var{vec} must be an expression with integral or floating | |
13009 | vector type and @var{vectype} an integral or floating vector type with the | |
13010 | same number of elements. The result has @var{vectype} type and value of | |
13011 | a C cast of every element of @var{vec} to the element type of @var{vectype}. | |
13012 | ||
13013 | Consider the following example, | |
13014 | @smallexample | |
13015 | typedef int v4si __attribute__ ((vector_size (16))); | |
13016 | typedef float v4sf __attribute__ ((vector_size (16))); | |
13017 | typedef double v4df __attribute__ ((vector_size (32))); | |
13018 | typedef unsigned long long v4di __attribute__ ((vector_size (32))); | |
13019 | ||
13020 | v4si a = @{1,-2,3,-4@}; | |
13021 | v4sf b = @{1.5f,-2.5f,3.f,7.f@}; | |
13022 | v4di c = @{1ULL,5ULL,0ULL,10ULL@}; | |
13023 | v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */ | |
13024 | /* Equivalent of: | |
13025 | v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */ | |
13026 | v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */ | |
13027 | v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */ | |
13028 | v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */ | |
13029 | v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */ | |
13030 | @end smallexample | |
13031 | ||
13032 | @cindex vector types, using with x86 intrinsics | |
13033 | Sometimes it is desirable to write code using a mix of generic vector | |
13034 | operations (for clarity) and machine-specific vector intrinsics (to | |
13035 | access vector instructions that are not exposed via generic built-ins). | |
13036 | On x86, intrinsic functions for integer vectors typically use the same | |
13037 | vector type @code{__m128i} irrespective of how they interpret the vector, | |
13038 | making it necessary to cast their arguments and return values from/to | |
13039 | other vector types. In C, you can make use of a @code{union} type: | |
13040 | @c In C++ such type punning via a union is not allowed by the language | |
13041 | @smallexample | |
13042 | #include <immintrin.h> | |
13043 | ||
13044 | typedef unsigned char u8x16 __attribute__ ((vector_size (16))); | |
13045 | typedef unsigned int u32x4 __attribute__ ((vector_size (16))); | |
13046 | ||
13047 | typedef union @{ | |
13048 | __m128i mm; | |
13049 | u8x16 u8; | |
13050 | u32x4 u32; | |
13051 | @} v128; | |
13052 | @end smallexample | |
13053 | ||
13054 | @noindent | |
13055 | for variables that can be used with both built-in operators and x86 | |
13056 | intrinsics: | |
13057 | ||
13058 | @smallexample | |
13059 | v128 x, y = @{ 0 @}; | |
13060 | memcpy (&x, ptr, sizeof x); | |
13061 | y.u8 += 0x80; | |
13062 | x.mm = _mm_adds_epu8 (x.mm, y.mm); | |
13063 | x.u32 &= 0xffffff; | |
13064 | ||
13065 | /* Instead of a variable, a compound literal may be used to pass the | |
13066 | return value of an intrinsic call to a function expecting the union: */ | |
13067 | v128 foo (v128); | |
13068 | x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); | |
13069 | @c This could be done implicitly with __attribute__((transparent_union)), | |
13070 | @c but GCC does not accept it for unions of vector types (PR 88955). | |
13071 | @end smallexample | |
13072 | ||
13073 | @node Offsetof | |
13074 | @section Support for @code{offsetof} | |
13075 | @findex __builtin_offsetof | |
13076 | ||
13077 | GCC implements for both C and C++ a syntactic extension to implement | |
13078 | the @code{offsetof} macro. | |
13079 | ||
13080 | @smallexample | |
13081 | primary: | |
13082 | "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" | |
13083 | ||
13084 | offsetof_member_designator: | |
13085 | @code{identifier} | |
13086 | | offsetof_member_designator "." @code{identifier} | |
13087 | | offsetof_member_designator "[" @code{expr} "]" | |
13088 | @end smallexample | |
13089 | ||
13090 | This extension is sufficient such that | |
13091 | ||
13092 | @smallexample | |
13093 | #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) | |
13094 | @end smallexample | |
13095 | ||
13096 | @noindent | |
13097 | is a suitable definition of the @code{offsetof} macro. In C++, @var{type} | |
13098 | may be dependent. In either case, @var{member} may consist of a single | |
13099 | identifier, or a sequence of member accesses and array references. | |
13100 | ||
13101 | @node __sync Builtins | |
13102 | @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access | |
13103 | ||
13104 | The following built-in functions | |
13105 | are intended to be compatible with those described | |
13106 | in the @cite{Intel Itanium Processor-specific Application Binary Interface}, | |
13107 | section 7.4. As such, they depart from normal GCC practice by not using | |
13108 | the @samp{__builtin_} prefix and also by being overloaded so that they | |
13109 | work on multiple types. | |
13110 | ||
13111 | The definition given in the Intel documentation allows only for the use of | |
13112 | the types @code{int}, @code{long}, @code{long long} or their unsigned | |
13113 | counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in | |
13114 | size other than the C type @code{_Bool} or the C++ type @code{bool}. | |
13115 | Operations on pointer arguments are performed as if the operands were | |
13116 | of the @code{uintptr_t} type. That is, they are not scaled by the size | |
13117 | of the type to which the pointer points. | |
13118 | ||
13119 | These functions are implemented in terms of the @samp{__atomic} | |
13120 | builtins (@pxref{__atomic Builtins}). They should not be used for new | |
13121 | code which should use the @samp{__atomic} builtins instead. | |
13122 | ||
13123 | Not all operations are supported by all target processors. If a particular | |
13124 | operation cannot be implemented on the target processor, a warning is | |
13125 | generated and a call to an external function is generated. The external | |
13126 | function carries the same name as the built-in version, | |
13127 | with an additional suffix | |
13128 | @samp{_@var{n}} where @var{n} is the size of the data type. | |
13129 | ||
13130 | @c ??? Should we have a mechanism to suppress this warning? This is almost | |
13131 | @c useful for implementing the operation under the control of an external | |
13132 | @c mutex. | |
13133 | ||
13134 | In most cases, these built-in functions are considered a @dfn{full barrier}. | |
13135 | That is, | |
13136 | no memory operand is moved across the operation, either forward or | |
13137 | backward. Further, instructions are issued as necessary to prevent the | |
13138 | processor from speculating loads across the operation and from queuing stores | |
13139 | after the operation. | |
13140 | ||
13141 | All of the routines are described in the Intel documentation to take | |
13142 | ``an optional list of variables protected by the memory barrier''. It's | |
13143 | not clear what is meant by that; it could mean that @emph{only} the | |
13144 | listed variables are protected, or it could mean a list of additional | |
13145 | variables to be protected. The list is ignored by GCC which treats it as | |
13146 | empty. GCC interprets an empty list as meaning that all globally | |
13147 | accessible variables should be protected. | |
13148 | ||
23795106 JJ |
13149 | @defbuiltin{@var{type} __sync_fetch_and_add (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} |
13150 | @defbuiltinx{@var{type} __sync_fetch_and_sub (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
13151 | @defbuiltinx{@var{type} __sync_fetch_and_or (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
13152 | @defbuiltinx{@var{type} __sync_fetch_and_and (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
13153 | @defbuiltinx{@var{type} __sync_fetch_and_xor (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
13154 | @defbuiltinx{@var{type} __sync_fetch_and_nand (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
d77de738 ML |
13155 | These built-in functions perform the operation suggested by the name, and |
13156 | returns the value that had previously been in memory. That is, operations | |
13157 | on integer operands have the following semantics. Operations on pointer | |
13158 | arguments are performed as if the operands were of the @code{uintptr_t} | |
13159 | type. That is, they are not scaled by the size of the type to which | |
13160 | the pointer points. | |
13161 | ||
13162 | @smallexample | |
13163 | @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} | |
13164 | @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand | |
13165 | @end smallexample | |
13166 | ||
13167 | The object pointed to by the first argument must be of integer or pointer | |
13168 | type. It must not be a boolean type. | |
13169 | ||
13170 | @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} | |
13171 | as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. | |
f25efe50 AA |
13172 | @enddefbuiltin |
13173 | ||
23795106 JJ |
13174 | @defbuiltin{@var{type} __sync_add_and_fetch (@var{type} *@var{ptr}, @ |
13175 | @var{type} @var{value}, ...)} | |
13176 | @defbuiltinx{@var{type} __sync_sub_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
13177 | @defbuiltinx{@var{type} __sync_or_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
13178 | @defbuiltinx{@var{type} __sync_and_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
13179 | @defbuiltinx{@var{type} __sync_xor_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
13180 | @defbuiltinx{@var{type} __sync_nand_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} | |
d77de738 ML |
13181 | These built-in functions perform the operation suggested by the name, and |
13182 | return the new value. That is, operations on integer operands have | |
13183 | the following semantics. Operations on pointer operands are performed as | |
13184 | if the operand's type were @code{uintptr_t}. | |
13185 | ||
13186 | @smallexample | |
13187 | @{ *ptr @var{op}= value; return *ptr; @} | |
13188 | @{ *ptr = ~(*ptr & value); return *ptr; @} // nand | |
13189 | @end smallexample | |
13190 | ||
13191 | The same constraints on arguments apply as for the corresponding | |
13192 | @code{__sync_op_and_fetch} built-in functions. | |
13193 | ||
13194 | @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} | |
13195 | as @code{*ptr = ~(*ptr & value)} instead of | |
13196 | @code{*ptr = ~*ptr & value}. | |
f25efe50 | 13197 | @enddefbuiltin |
d77de738 | 13198 | |
23795106 JJ |
13199 | @defbuiltin{bool __sync_bool_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} |
13200 | @defbuiltinx{@var{type} __sync_val_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} | |
d77de738 ML |
13201 | These built-in functions perform an atomic compare and swap. |
13202 | That is, if the current | |
13203 | value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into | |
13204 | @code{*@var{ptr}}. | |
13205 | ||
13206 | The ``bool'' version returns @code{true} if the comparison is successful and | |
13207 | @var{newval} is written. The ``val'' version returns the contents | |
13208 | of @code{*@var{ptr}} before the operation. | |
f25efe50 | 13209 | @enddefbuiltin |
d77de738 | 13210 | |
f25efe50 | 13211 | @defbuiltin{void __sync_synchronize (...)} |
d77de738 | 13212 | This built-in function issues a full memory barrier. |
f25efe50 | 13213 | @enddefbuiltin |
d77de738 | 13214 | |
23795106 | 13215 | @defbuiltin{@var{type} __sync_lock_test_and_set (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} |
d77de738 ML |
13216 | This built-in function, as described by Intel, is not a traditional test-and-set |
13217 | operation, but rather an atomic exchange operation. It writes @var{value} | |
13218 | into @code{*@var{ptr}}, and returns the previous contents of | |
13219 | @code{*@var{ptr}}. | |
13220 | ||
13221 | Many targets have only minimal support for such locks, and do not support | |
13222 | a full exchange operation. In this case, a target may support reduced | |
13223 | functionality here by which the @emph{only} valid value to store is the | |
13224 | immediate constant 1. The exact value actually stored in @code{*@var{ptr}} | |
13225 | is implementation defined. | |
13226 | ||
13227 | This built-in function is not a full barrier, | |
13228 | but rather an @dfn{acquire barrier}. | |
13229 | This means that references after the operation cannot move to (or be | |
13230 | speculated to) before the operation, but previous memory stores may not | |
13231 | be globally visible yet, and previous memory loads may not yet be | |
13232 | satisfied. | |
f25efe50 | 13233 | @enddefbuiltin |
d77de738 | 13234 | |
23795106 | 13235 | @defbuiltin{void __sync_lock_release (@var{type} *@var{ptr}, ...)} |
d77de738 ML |
13236 | This built-in function releases the lock acquired by |
13237 | @code{__sync_lock_test_and_set}. | |
13238 | Normally this means writing the constant 0 to @code{*@var{ptr}}. | |
13239 | ||
13240 | This built-in function is not a full barrier, | |
13241 | but rather a @dfn{release barrier}. | |
13242 | This means that all previous memory stores are globally visible, and all | |
13243 | previous memory loads have been satisfied, but following memory reads | |
13244 | are not prevented from being speculated to before the barrier. | |
f25efe50 | 13245 | @enddefbuiltin |
d77de738 ML |
13246 | |
13247 | @node __atomic Builtins | |
13248 | @section Built-in Functions for Memory Model Aware Atomic Operations | |
13249 | ||
13250 | The following built-in functions approximately match the requirements | |
13251 | for the C++11 memory model. They are all | |
13252 | identified by being prefixed with @samp{__atomic} and most are | |
13253 | overloaded so that they work with multiple types. | |
13254 | ||
13255 | These functions are intended to replace the legacy @samp{__sync} | |
13256 | builtins. The main difference is that the memory order that is requested | |
13257 | is a parameter to the functions. New code should always use the | |
13258 | @samp{__atomic} builtins rather than the @samp{__sync} builtins. | |
13259 | ||
13260 | Note that the @samp{__atomic} builtins assume that programs will | |
13261 | conform to the C++11 memory model. In particular, they assume | |
13262 | that programs are free of data races. See the C++11 standard for | |
13263 | detailed requirements. | |
13264 | ||
13265 | The @samp{__atomic} builtins can be used with any integral scalar or | |
13266 | pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral | |
13267 | types are also allowed if @samp{__int128} (@pxref{__int128}) is | |
13268 | supported by the architecture. | |
13269 | ||
13270 | The four non-arithmetic functions (load, store, exchange, and | |
13271 | compare_exchange) all have a generic version as well. This generic | |
13272 | version works on any data type. It uses the lock-free built-in function | |
13273 | if the specific data type size makes that possible; otherwise, an | |
13274 | external call is left to be resolved at run time. This external call is | |
13275 | the same format with the addition of a @samp{size_t} parameter inserted | |
13276 | as the first parameter indicating the size of the object being pointed to. | |
13277 | All objects must be the same size. | |
13278 | ||
13279 | There are 6 different memory orders that can be specified. These map | |
13280 | to the C++11 memory orders with the same names, see the C++11 standard | |
13281 | or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki | |
13282 | on atomic synchronization} for detailed definitions. Individual | |
13283 | targets may also support additional memory orders for use on specific | |
13284 | architectures. Refer to the target documentation for details of | |
13285 | these. | |
13286 | ||
13287 | An atomic operation can both constrain code motion and | |
13288 | be mapped to hardware instructions for synchronization between threads | |
13289 | (e.g., a fence). To which extent this happens is controlled by the | |
13290 | memory orders, which are listed here in approximately ascending order of | |
13291 | strength. The description of each memory order is only meant to roughly | |
13292 | illustrate the effects and is not a specification; see the C++11 | |
13293 | memory model for precise semantics. | |
13294 | ||
13295 | @table @code | |
13296 | @item __ATOMIC_RELAXED | |
13297 | Implies no inter-thread ordering constraints. | |
13298 | @item __ATOMIC_CONSUME | |
13299 | This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE} | |
13300 | memory order because of a deficiency in C++11's semantics for | |
13301 | @code{memory_order_consume}. | |
13302 | @item __ATOMIC_ACQUIRE | |
13303 | Creates an inter-thread happens-before constraint from the release (or | |
13304 | stronger) semantic store to this acquire load. Can prevent hoisting | |
13305 | of code to before the operation. | |
13306 | @item __ATOMIC_RELEASE | |
13307 | Creates an inter-thread happens-before constraint to acquire (or stronger) | |
13308 | semantic loads that read from this release store. Can prevent sinking | |
13309 | of code to after the operation. | |
13310 | @item __ATOMIC_ACQ_REL | |
13311 | Combines the effects of both @code{__ATOMIC_ACQUIRE} and | |
13312 | @code{__ATOMIC_RELEASE}. | |
13313 | @item __ATOMIC_SEQ_CST | |
13314 | Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations. | |
13315 | @end table | |
13316 | ||
13317 | Note that in the C++11 memory model, @emph{fences} (e.g., | |
13318 | @samp{__atomic_thread_fence}) take effect in combination with other | |
13319 | atomic operations on specific memory locations (e.g., atomic loads); | |
13320 | operations on specific memory locations do not necessarily affect other | |
13321 | operations in the same way. | |
13322 | ||
13323 | Target architectures are encouraged to provide their own patterns for | |
13324 | each of the atomic built-in functions. If no target is provided, the original | |
13325 | non-memory model set of @samp{__sync} atomic built-in functions are | |
13326 | used, along with any required synchronization fences surrounding it in | |
13327 | order to achieve the proper behavior. Execution in this case is subject | |
13328 | to the same restrictions as those built-in functions. | |
13329 | ||
13330 | If there is no pattern or mechanism to provide a lock-free instruction | |
13331 | sequence, a call is made to an external routine with the same parameters | |
13332 | to be resolved at run time. | |
13333 | ||
13334 | When implementing patterns for these built-in functions, the memory order | |
13335 | parameter can be ignored as long as the pattern implements the most | |
13336 | restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory | |
13337 | orders execute correctly with this memory order but they may not execute as | |
13338 | efficiently as they could with a more appropriate implementation of the | |
13339 | relaxed requirements. | |
13340 | ||
13341 | Note that the C++11 standard allows for the memory order parameter to be | |
13342 | determined at run time rather than at compile time. These built-in | |
13343 | functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather | |
13344 | than invoke a runtime library call or inline a switch statement. This is | |
13345 | standard compliant, safe, and the simplest approach for now. | |
13346 | ||
13347 | The memory order parameter is a signed int, but only the lower 16 bits are | |
13348 | reserved for the memory order. The remainder of the signed int is reserved | |
13349 | for target use and should be 0. Use of the predefined atomic values | |
13350 | ensures proper usage. | |
13351 | ||
23795106 | 13352 | @defbuiltin{@var{type} __atomic_load_n (@var{type} *@var{ptr}, int @var{memorder})} |
d77de738 ML |
13353 | This built-in function implements an atomic load operation. It returns the |
13354 | contents of @code{*@var{ptr}}. | |
13355 | ||
13356 | The valid memory order variants are | |
13357 | @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, | |
13358 | and @code{__ATOMIC_CONSUME}. | |
13359 | ||
f25efe50 | 13360 | @enddefbuiltin |
d77de738 | 13361 | |
23795106 | 13362 | @defbuiltin{void __atomic_load (@var{type} *@var{ptr}, @var{type} *@var{ret}, int @var{memorder})} |
d77de738 ML |
13363 | This is the generic version of an atomic load. It returns the |
13364 | contents of @code{*@var{ptr}} in @code{*@var{ret}}. | |
13365 | ||
f25efe50 | 13366 | @enddefbuiltin |
d77de738 | 13367 | |
23795106 | 13368 | @defbuiltin{void __atomic_store_n (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} |
d77de738 ML |
13369 | This built-in function implements an atomic store operation. It writes |
13370 | @code{@var{val}} into @code{*@var{ptr}}. | |
13371 | ||
13372 | The valid memory order variants are | |
13373 | @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. | |
13374 | ||
f25efe50 | 13375 | @enddefbuiltin |
d77de738 | 13376 | |
23795106 | 13377 | @defbuiltin{void __atomic_store (@var{type} *@var{ptr}, @var{type} *@var{val}, int @var{memorder})} |
d77de738 ML |
13378 | This is the generic version of an atomic store. It stores the value |
13379 | of @code{*@var{val}} into @code{*@var{ptr}}. | |
13380 | ||
f25efe50 | 13381 | @enddefbuiltin |
d77de738 | 13382 | |
23795106 | 13383 | @defbuiltin{@var{type} __atomic_exchange_n (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} |
d77de738 ML |
13384 | This built-in function implements an atomic exchange operation. It writes |
13385 | @var{val} into @code{*@var{ptr}}, and returns the previous contents of | |
13386 | @code{*@var{ptr}}. | |
13387 | ||
13388 | All memory order variants are valid. | |
13389 | ||
f25efe50 | 13390 | @enddefbuiltin |
d77de738 | 13391 | |
23795106 | 13392 | @defbuiltin{void __atomic_exchange (@var{type} *@var{ptr}, @var{type} *@var{val}, @var{type} *@var{ret}, int @var{memorder})} |
d77de738 ML |
13393 | This is the generic version of an atomic exchange. It stores the |
13394 | contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value | |
13395 | of @code{*@var{ptr}} is copied into @code{*@var{ret}}. | |
13396 | ||
f25efe50 | 13397 | @enddefbuiltin |
d77de738 | 13398 | |
23795106 | 13399 | @defbuiltin{bool __atomic_compare_exchange_n (@var{type} *@var{ptr}, @var{type} *@var{expected}, @var{type} @var{desired}, bool @var{weak}, int @var{success_memorder}, int @var{failure_memorder})} |
d77de738 ML |
13400 | This built-in function implements an atomic compare and exchange operation. |
13401 | This compares the contents of @code{*@var{ptr}} with the contents of | |
13402 | @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} | |
13403 | operation that writes @var{desired} into @code{*@var{ptr}}. If they are not | |
13404 | equal, the operation is a @emph{read} and the current contents of | |
13405 | @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true} | |
13406 | for weak compare_exchange, which may fail spuriously, and @code{false} for | |
13407 | the strong variation, which never fails spuriously. Many targets | |
13408 | only offer the strong variation and ignore the parameter. When in doubt, use | |
13409 | the strong variation. | |
13410 | ||
13411 | If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned | |
13412 | and memory is affected according to the | |
13413 | memory order specified by @var{success_memorder}. There are no | |
13414 | restrictions on what memory order can be used here. | |
13415 | ||
13416 | Otherwise, @code{false} is returned and memory is affected according | |
13417 | to @var{failure_memorder}. This memory order cannot be | |
13418 | @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a | |
13419 | stronger order than that specified by @var{success_memorder}. | |
13420 | ||
f25efe50 | 13421 | @enddefbuiltin |
d77de738 | 13422 | |
23795106 | 13423 | @defbuiltin{bool __atomic_compare_exchange (@var{type} *@var{ptr}, @var{type} *@var{expected}, @var{type} *@var{desired}, bool @var{weak}, int @var{success_memorder}, int @var{failure_memorder})} |
d77de738 ML |
13424 | This built-in function implements the generic version of |
13425 | @code{__atomic_compare_exchange}. The function is virtually identical to | |
13426 | @code{__atomic_compare_exchange_n}, except the desired value is also a | |
13427 | pointer. | |
13428 | ||
f25efe50 | 13429 | @enddefbuiltin |
d77de738 | 13430 | |
23795106 JJ |
13431 | @defbuiltin{@var{type} __atomic_add_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} |
13432 | @defbuiltinx{@var{type} __atomic_sub_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
13433 | @defbuiltinx{@var{type} __atomic_and_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
13434 | @defbuiltinx{@var{type} __atomic_xor_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
13435 | @defbuiltinx{@var{type} __atomic_or_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
13436 | @defbuiltinx{@var{type} __atomic_nand_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
d77de738 ML |
13437 | These built-in functions perform the operation suggested by the name, and |
13438 | return the result of the operation. Operations on pointer arguments are | |
13439 | performed as if the operands were of the @code{uintptr_t} type. That is, | |
13440 | they are not scaled by the size of the type to which the pointer points. | |
13441 | ||
13442 | @smallexample | |
13443 | @{ *ptr @var{op}= val; return *ptr; @} | |
13444 | @{ *ptr = ~(*ptr & val); return *ptr; @} // nand | |
13445 | @end smallexample | |
13446 | ||
13447 | The object pointed to by the first argument must be of integer or pointer | |
13448 | type. It must not be a boolean type. All memory orders are valid. | |
13449 | ||
f25efe50 | 13450 | @enddefbuiltin |
d77de738 | 13451 | |
23795106 JJ |
13452 | @defbuiltin{@var{type} __atomic_fetch_add (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} |
13453 | @defbuiltinx{@var{type} __atomic_fetch_sub (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
13454 | @defbuiltinx{@var{type} __atomic_fetch_and (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
13455 | @defbuiltinx{@var{type} __atomic_fetch_xor (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
13456 | @defbuiltinx{@var{type} __atomic_fetch_or (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
13457 | @defbuiltinx{@var{type} __atomic_fetch_nand (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} | |
d77de738 ML |
13458 | These built-in functions perform the operation suggested by the name, and |
13459 | return the value that had previously been in @code{*@var{ptr}}. Operations | |
13460 | on pointer arguments are performed as if the operands were of | |
13461 | the @code{uintptr_t} type. That is, they are not scaled by the size of | |
13462 | the type to which the pointer points. | |
13463 | ||
13464 | @smallexample | |
13465 | @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} | |
13466 | @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand | |
13467 | @end smallexample | |
13468 | ||
13469 | The same constraints on arguments apply as for the corresponding | |
13470 | @code{__atomic_op_fetch} built-in functions. All memory orders are valid. | |
13471 | ||
f25efe50 | 13472 | @enddefbuiltin |
d77de738 | 13473 | |
23795106 | 13474 | @defbuiltin{bool __atomic_test_and_set (void *@var{ptr}, int @var{memorder})} |
d77de738 ML |
13475 | |
13476 | This built-in function performs an atomic test-and-set operation on | |
13477 | the byte at @code{*@var{ptr}}. The byte is set to some implementation | |
13478 | defined nonzero ``set'' value and the return value is @code{true} if and only | |
13479 | if the previous contents were ``set''. | |
13480 | It should be only used for operands of type @code{bool} or @code{char}. For | |
13481 | other types only part of the value may be set. | |
13482 | ||
13483 | All memory orders are valid. | |
13484 | ||
f25efe50 | 13485 | @enddefbuiltin |
d77de738 | 13486 | |
23795106 | 13487 | @defbuiltin{void __atomic_clear (bool *@var{ptr}, int @var{memorder})} |
d77de738 ML |
13488 | |
13489 | This built-in function performs an atomic clear operation on | |
13490 | @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. | |
13491 | It should be only used for operands of type @code{bool} or @code{char} and | |
13492 | in conjunction with @code{__atomic_test_and_set}. | |
13493 | For other types it may only clear partially. If the type is not @code{bool} | |
13494 | prefer using @code{__atomic_store}. | |
13495 | ||
13496 | The valid memory order variants are | |
13497 | @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and | |
13498 | @code{__ATOMIC_RELEASE}. | |
13499 | ||
f25efe50 | 13500 | @enddefbuiltin |
d77de738 | 13501 | |
23795106 | 13502 | @defbuiltin{void __atomic_thread_fence (int @var{memorder})} |
d77de738 ML |
13503 | |
13504 | This built-in function acts as a synchronization fence between threads | |
13505 | based on the specified memory order. | |
13506 | ||
13507 | All memory orders are valid. | |
13508 | ||
f25efe50 | 13509 | @enddefbuiltin |
d77de738 | 13510 | |
23795106 | 13511 | @defbuiltin{void __atomic_signal_fence (int @var{memorder})} |
d77de738 ML |
13512 | |
13513 | This built-in function acts as a synchronization fence between a thread | |
13514 | and signal handlers based in the same thread. | |
13515 | ||
13516 | All memory orders are valid. | |
13517 | ||
f25efe50 | 13518 | @enddefbuiltin |
d77de738 | 13519 | |
23795106 | 13520 | @defbuiltin{bool __atomic_always_lock_free (size_t @var{size}, void *@var{ptr})} |
d77de738 ML |
13521 | |
13522 | This built-in function returns @code{true} if objects of @var{size} bytes always | |
13523 | generate lock-free atomic instructions for the target architecture. | |
13524 | @var{size} must resolve to a compile-time constant and the result also | |
13525 | resolves to a compile-time constant. | |
13526 | ||
13527 | @var{ptr} is an optional pointer to the object that may be used to determine | |
13528 | alignment. A value of 0 indicates typical alignment should be used. The | |
13529 | compiler may also ignore this parameter. | |
13530 | ||
13531 | @smallexample | |
13532 | if (__atomic_always_lock_free (sizeof (long long), 0)) | |
13533 | @end smallexample | |
13534 | ||
f25efe50 | 13535 | @enddefbuiltin |
d77de738 | 13536 | |
23795106 | 13537 | @defbuiltin{bool __atomic_is_lock_free (size_t @var{size}, void *@var{ptr})} |
d77de738 ML |
13538 | |
13539 | This built-in function returns @code{true} if objects of @var{size} bytes always | |
13540 | generate lock-free atomic instructions for the target architecture. If | |
13541 | the built-in function is not known to be lock-free, a call is made to a | |
13542 | runtime routine named @code{__atomic_is_lock_free}. | |
13543 | ||
13544 | @var{ptr} is an optional pointer to the object that may be used to determine | |
13545 | alignment. A value of 0 indicates typical alignment should be used. The | |
13546 | compiler may also ignore this parameter. | |
f25efe50 | 13547 | @enddefbuiltin |
d77de738 ML |
13548 | |
13549 | @node Integer Overflow Builtins | |
13550 | @section Built-in Functions to Perform Arithmetic with Overflow Checking | |
13551 | ||
13552 | The following built-in functions allow performing simple arithmetic operations | |
13553 | together with checking whether the operations overflowed. | |
13554 | ||
23795106 JJ |
13555 | @defbuiltin{bool __builtin_add_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} |
13556 | @defbuiltinx{bool __builtin_sadd_overflow (int @var{a}, int @var{b}, int *@var{res})} | |
13557 | @defbuiltinx{bool __builtin_saddl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} | |
13558 | @defbuiltinx{bool __builtin_saddll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} | |
13559 | @defbuiltinx{bool __builtin_uadd_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} | |
13560 | @defbuiltinx{bool __builtin_uaddl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} | |
13561 | @defbuiltinx{bool __builtin_uaddll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} | |
d77de738 ML |
13562 | |
13563 | These built-in functions promote the first two operands into infinite precision signed | |
13564 | type and perform addition on those promoted operands. The result is then | |
13565 | cast to the type the third pointer argument points to and stored there. | |
13566 | If the stored result is equal to the infinite precision result, the built-in | |
13567 | functions return @code{false}, otherwise they return @code{true}. As the addition is | |
13568 | performed in infinite signed precision, these built-in functions have fully defined | |
13569 | behavior for all argument values. | |
13570 | ||
13571 | The first built-in function allows arbitrary integral types for operands and | |
13572 | the result type must be pointer to some integral type other than enumerated or | |
13573 | boolean type, the rest of the built-in functions have explicit integer types. | |
13574 | ||
13575 | The compiler will attempt to use hardware instructions to implement | |
13576 | these built-in functions where possible, like conditional jump on overflow | |
13577 | after addition, conditional jump on carry etc. | |
13578 | ||
f25efe50 | 13579 | @enddefbuiltin |
d77de738 | 13580 | |
23795106 JJ |
13581 | @defbuiltin{bool __builtin_sub_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} |
13582 | @defbuiltinx{bool __builtin_ssub_overflow (int @var{a}, int @var{b}, int *@var{res})} | |
13583 | @defbuiltinx{bool __builtin_ssubl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} | |
13584 | @defbuiltinx{bool __builtin_ssubll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} | |
13585 | @defbuiltinx{bool __builtin_usub_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} | |
13586 | @defbuiltinx{bool __builtin_usubl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} | |
13587 | @defbuiltinx{bool __builtin_usubll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} | |
d77de738 ML |
13588 | |
13589 | These built-in functions are similar to the add overflow checking built-in | |
13590 | functions above, except they perform subtraction, subtract the second argument | |
13591 | from the first one, instead of addition. | |
13592 | ||
f25efe50 | 13593 | @enddefbuiltin |
d77de738 | 13594 | |
23795106 JJ |
13595 | @defbuiltin{bool __builtin_mul_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} |
13596 | @defbuiltinx{bool __builtin_smul_overflow (int @var{a}, int @var{b}, int *@var{res})} | |
13597 | @defbuiltinx{bool __builtin_smull_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} | |
13598 | @defbuiltinx{bool __builtin_smulll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} | |
13599 | @defbuiltinx{bool __builtin_umul_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} | |
13600 | @defbuiltinx{bool __builtin_umull_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} | |
13601 | @defbuiltinx{bool __builtin_umulll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} | |
d77de738 ML |
13602 | |
13603 | These built-in functions are similar to the add overflow checking built-in | |
13604 | functions above, except they perform multiplication, instead of addition. | |
13605 | ||
f25efe50 | 13606 | @enddefbuiltin |
d77de738 ML |
13607 | |
13608 | The following built-in functions allow checking if simple arithmetic operation | |
13609 | would overflow. | |
13610 | ||
23795106 JJ |
13611 | @defbuiltin{bool __builtin_add_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} |
13612 | @defbuiltinx{bool __builtin_sub_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} | |
13613 | @defbuiltinx{bool __builtin_mul_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} | |
d77de738 ML |
13614 | |
13615 | These built-in functions are similar to @code{__builtin_add_overflow}, | |
13616 | @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that | |
13617 | they don't store the result of the arithmetic operation anywhere and the | |
13618 | last argument is not a pointer, but some expression with integral type other | |
13619 | than enumerated or boolean type. | |
13620 | ||
13621 | The built-in functions promote the first two operands into infinite precision signed type | |
13622 | and perform addition on those promoted operands. The result is then | |
13623 | cast to the type of the third argument. If the cast result is equal to the infinite | |
13624 | precision result, the built-in functions return @code{false}, otherwise they return @code{true}. | |
13625 | The value of the third argument is ignored, just the side effects in the third argument | |
13626 | are evaluated, and no integral argument promotions are performed on the last argument. | |
13627 | If the third argument is a bit-field, the type used for the result cast has the | |
13628 | precision and signedness of the given bit-field, rather than precision and signedness | |
13629 | of the underlying type. | |
13630 | ||
13631 | For example, the following macro can be used to portably check, at | |
13632 | compile-time, whether or not adding two constant integers will overflow, | |
13633 | and perform the addition only when it is known to be safe and not to trigger | |
13634 | a @option{-Woverflow} warning. | |
13635 | ||
13636 | @smallexample | |
13637 | #define INT_ADD_OVERFLOW_P(a, b) \ | |
13638 | __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) | |
13639 | ||
13640 | enum @{ | |
13641 | A = INT_MAX, B = 3, | |
13642 | C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, | |
13643 | D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) | |
13644 | @}; | |
13645 | @end smallexample | |
13646 | ||
13647 | The compiler will attempt to use hardware instructions to implement | |
13648 | these built-in functions where possible, like conditional jump on overflow | |
13649 | after addition, conditional jump on carry etc. | |
13650 | ||
f25efe50 | 13651 | @enddefbuiltin |
d77de738 | 13652 | |
23795106 JJ |
13653 | @defbuiltin{{unsigned int} __builtin_addc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} |
13654 | @defbuiltinx{{unsigned long int} __builtin_addcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} | |
13655 | @defbuiltinx{{unsigned long long int} __builtin_addcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} | |
2b4e0415 JJ |
13656 | |
13657 | These built-in functions are equivalent to: | |
13658 | @smallexample | |
13659 | (@{ __typeof__ (@var{a}) s; \ | |
13660 | __typeof__ (@var{a}) c1 = __builtin_add_overflow (@var{a}, @var{b}, &s); \ | |
13661 | __typeof__ (@var{a}) c2 = __builtin_add_overflow (s, @var{carry_in}, &s); \ | |
13662 | *(@var{carry_out}) = c1 | c2; \ | |
13663 | s; @}) | |
13664 | @end smallexample | |
13665 | ||
13666 | i.e.@: they add 3 unsigned values, set what the last argument | |
13667 | points to to 1 if any of the two additions overflowed (otherwise 0) | |
13668 | and return the sum of those 3 unsigned values. Note, while all | |
13669 | the first 3 arguments can have arbitrary values, better code will be | |
13670 | emitted if one of them (preferrably the third one) has only values | |
13671 | 0 or 1 (i.e.@: carry-in). | |
13672 | ||
13673 | @enddefbuiltin | |
13674 | ||
23795106 JJ |
13675 | @defbuiltin{{unsigned int} __builtin_subc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} |
13676 | @defbuiltinx{{unsigned long int} __builtin_subcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} | |
13677 | @defbuiltinx{{unsigned long long int} __builtin_subcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} | |
2b4e0415 JJ |
13678 | |
13679 | These built-in functions are equivalent to: | |
13680 | @smallexample | |
13681 | (@{ __typeof__ (@var{a}) s; \ | |
13682 | __typeof__ (@var{a}) c1 = __builtin_sub_overflow (@var{a}, @var{b}, &s); \ | |
13683 | __typeof__ (@var{a}) c2 = __builtin_sub_overflow (s, @var{carry_in}, &s); \ | |
13684 | *(@var{carry_out}) = c1 | c2; \ | |
13685 | s; @}) | |
13686 | @end smallexample | |
13687 | ||
13688 | i.e.@: they subtract 2 unsigned values from the first unsigned value, | |
13689 | set what the last argument points to to 1 if any of the two subtractions | |
13690 | overflowed (otherwise 0) and return the result of the subtractions. | |
13691 | Note, while all the first 3 arguments can have arbitrary values, better code | |
13692 | will be emitted if one of them (preferrably the third one) has only values | |
13693 | 0 or 1 (i.e.@: carry-in). | |
13694 | ||
13695 | @enddefbuiltin | |
13696 | ||
d77de738 ML |
13697 | @node x86 specific memory model extensions for transactional memory |
13698 | @section x86-Specific Memory Model Extensions for Transactional Memory | |
13699 | ||
13700 | The x86 architecture supports additional memory ordering flags | |
13701 | to mark critical sections for hardware lock elision. | |
13702 | These must be specified in addition to an existing memory order to | |
13703 | atomic intrinsics. | |
13704 | ||
13705 | @table @code | |
13706 | @item __ATOMIC_HLE_ACQUIRE | |
13707 | Start lock elision on a lock variable. | |
13708 | Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. | |
13709 | @item __ATOMIC_HLE_RELEASE | |
13710 | End lock elision on a lock variable. | |
13711 | Memory order must be @code{__ATOMIC_RELEASE} or stronger. | |
13712 | @end table | |
13713 | ||
13714 | When a lock acquire fails, it is required for good performance to abort | |
13715 | the transaction quickly. This can be done with a @code{_mm_pause}. | |
13716 | ||
13717 | @smallexample | |
13718 | #include <immintrin.h> // For _mm_pause | |
13719 | ||
13720 | int lockvar; | |
13721 | ||
13722 | /* Acquire lock with lock elision */ | |
13723 | while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) | |
13724 | _mm_pause(); /* Abort failed transaction */ | |
13725 | ... | |
13726 | /* Free lock with lock elision */ | |
13727 | __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); | |
13728 | @end smallexample | |
13729 | ||
13730 | @node Object Size Checking | |
b3009222 SP |
13731 | @section Object Size Checking |
13732 | ||
13733 | @subsection Object Size Checking Built-in Functions | |
d77de738 ML |
13734 | @findex __builtin___memcpy_chk |
13735 | @findex __builtin___mempcpy_chk | |
13736 | @findex __builtin___memmove_chk | |
13737 | @findex __builtin___memset_chk | |
13738 | @findex __builtin___strcpy_chk | |
13739 | @findex __builtin___stpcpy_chk | |
13740 | @findex __builtin___strncpy_chk | |
13741 | @findex __builtin___strcat_chk | |
13742 | @findex __builtin___strncat_chk | |
d77de738 ML |
13743 | |
13744 | GCC implements a limited buffer overflow protection mechanism that can | |
13745 | prevent some buffer overflow attacks by determining the sizes of objects | |
13746 | into which data is about to be written and preventing the writes when | |
13747 | the size isn't sufficient. The built-in functions described below yield | |
13748 | the best results when used together and when optimization is enabled. | |
13749 | For example, to detect object sizes across function boundaries or to | |
13750 | follow pointer assignments through non-trivial control flow they rely | |
13751 | on various optimization passes enabled with @option{-O2}. However, to | |
13752 | a limited extent, they can be used without optimization as well. | |
13753 | ||
f25efe50 | 13754 | @defbuiltin{size_t __builtin_object_size (const void * @var{ptr}, int @var{type})} |
d77de738 ML |
13755 | is a built-in construct that returns a constant number of bytes from |
13756 | @var{ptr} to the end of the object @var{ptr} pointer points to | |
13757 | (if known at compile time). To determine the sizes of dynamically allocated | |
13758 | objects the function relies on the allocation functions called to obtain | |
13759 | the storage to be declared with the @code{alloc_size} attribute (@pxref{Common | |
13760 | Function Attributes}). @code{__builtin_object_size} never evaluates | |
13761 | its arguments for side effects. If there are any side effects in them, it | |
13762 | returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} | |
13763 | for @var{type} 2 or 3. If there are multiple objects @var{ptr} can | |
13764 | point to and all of them are known at compile time, the returned number | |
13765 | is the maximum of remaining byte counts in those objects if @var{type} & 2 is | |
13766 | 0 and minimum if nonzero. If it is not possible to determine which objects | |
13767 | @var{ptr} points to at compile time, @code{__builtin_object_size} should | |
13768 | return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} | |
13769 | for @var{type} 2 or 3. | |
13770 | ||
13771 | @var{type} is an integer constant from 0 to 3. If the least significant | |
13772 | bit is clear, objects are whole variables, if it is set, a closest | |
13773 | surrounding subobject is considered the object a pointer points to. | |
13774 | The second bit determines if maximum or minimum of remaining bytes | |
13775 | is computed. | |
13776 | ||
13777 | @smallexample | |
13778 | struct V @{ char buf1[10]; int b; char buf2[10]; @} var; | |
13779 | char *p = &var.buf1[1], *q = &var.b; | |
13780 | ||
13781 | /* Here the object p points to is var. */ | |
13782 | assert (__builtin_object_size (p, 0) == sizeof (var) - 1); | |
13783 | /* The subobject p points to is var.buf1. */ | |
13784 | assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); | |
13785 | /* The object q points to is var. */ | |
13786 | assert (__builtin_object_size (q, 0) | |
13787 | == (char *) (&var + 1) - (char *) &var.b); | |
13788 | /* The subobject q points to is var.b. */ | |
13789 | assert (__builtin_object_size (q, 1) == sizeof (var.b)); | |
13790 | @end smallexample | |
f25efe50 | 13791 | @enddefbuiltin |
d77de738 | 13792 | |
f25efe50 | 13793 | @defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} |
d77de738 ML |
13794 | is similar to @code{__builtin_object_size} in that it returns a number of bytes |
13795 | from @var{ptr} to the end of the object @var{ptr} pointer points to, except | |
13796 | that the size returned may not be a constant. This results in successful | |
13797 | evaluation of object size estimates in a wider range of use cases and can be | |
13798 | more precise than @code{__builtin_object_size}, but it incurs a performance | |
13799 | penalty since it may add a runtime overhead on size computation. Semantics of | |
13800 | @var{type} as well as return values in case it is not possible to determine | |
13801 | which objects @var{ptr} points to at compile time are the same as in the case | |
13802 | of @code{__builtin_object_size}. | |
f25efe50 | 13803 | @enddefbuiltin |
d77de738 | 13804 | |
b3009222 SP |
13805 | @subsection Object Size Checking and Source Fortification |
13806 | ||
13807 | Hardening of function calls using the @code{_FORTIFY_SOURCE} macro is | |
13808 | one of the key uses of the object size checking built-in functions. To | |
13809 | make implementation of these features more convenient and improve | |
13810 | optimization and diagnostics, there are built-in functions added for | |
13811 | many common string operation functions, e.g., for @code{memcpy} | |
13812 | @code{__builtin___memcpy_chk} built-in is provided. This built-in has | |
13813 | an additional last argument, which is the number of bytes remaining in | |
13814 | the object the @var{dest} argument points to or @code{(size_t) -1} if | |
13815 | the size is not known. | |
d77de738 ML |
13816 | |
13817 | The built-in functions are optimized into the normal string functions | |
13818 | like @code{memcpy} if the last argument is @code{(size_t) -1} or if | |
13819 | it is known at compile time that the destination object will not | |
13820 | be overflowed. If the compiler can determine at compile time that the | |
13821 | object will always be overflowed, it issues a warning. | |
13822 | ||
13823 | The intended use can be e.g.@: | |
13824 | ||
13825 | @smallexample | |
13826 | #undef memcpy | |
13827 | #define bos0(dest) __builtin_object_size (dest, 0) | |
13828 | #define memcpy(dest, src, n) \ | |
13829 | __builtin___memcpy_chk (dest, src, n, bos0 (dest)) | |
13830 | ||
13831 | char *volatile p; | |
13832 | char buf[10]; | |
13833 | /* It is unknown what object p points to, so this is optimized | |
13834 | into plain memcpy - no checking is possible. */ | |
13835 | memcpy (p, "abcde", n); | |
13836 | /* Destination is known and length too. It is known at compile | |
13837 | time there will be no overflow. */ | |
13838 | memcpy (&buf[5], "abcde", 5); | |
13839 | /* Destination is known, but the length is not known at compile time. | |
13840 | This will result in __memcpy_chk call that can check for overflow | |
13841 | at run time. */ | |
13842 | memcpy (&buf[5], "abcde", n); | |
13843 | /* Destination is known and it is known at compile time there will | |
13844 | be overflow. There will be a warning and __memcpy_chk call that | |
13845 | will abort the program at run time. */ | |
13846 | memcpy (&buf[6], "abcde", 5); | |
13847 | @end smallexample | |
13848 | ||
13849 | Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, | |
13850 | @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, | |
13851 | @code{strcat} and @code{strncat}. | |
13852 | ||
e1e5ecb2 | 13853 | @subsubsection Formatted Output Function Checking |
f25efe50 AA |
13854 | @defbuiltin{int __builtin___sprintf_chk @ |
13855 | (char *@var{s}, int @var{flag}, size_t @var{os}, @ | |
13856 | const char *@var{fmt}, ...)} | |
13857 | @defbuiltinx{int __builtin___snprintf_chk @ | |
13858 | (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @ | |
13859 | size_t @var{os}, const char *@var{fmt}, ...)} | |
13860 | @defbuiltinx{int __builtin___vsprintf_chk @ | |
13861 | (char *@var{s}, int @var{flag}, size_t @var{os}, @ | |
13862 | const char *@var{fmt}, va_list @var{ap})} | |
13863 | @defbuiltinx{int __builtin___vsnprintf_chk @ | |
13864 | (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @ | |
13865 | size_t @var{os}, const char *@var{fmt}, @ | |
13866 | va_list @var{ap})} | |
d77de738 ML |
13867 | |
13868 | The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} | |
13869 | etc.@: functions and can contain implementation specific flags on what | |
13870 | additional security measures the checking function might take, such as | |
13871 | handling @code{%n} differently. | |
13872 | ||
13873 | The @var{os} argument is the object size @var{s} points to, like in the | |
13874 | other built-in functions. There is a small difference in the behavior | |
13875 | though, if @var{os} is @code{(size_t) -1}, the built-in functions are | |
13876 | optimized into the non-checking functions only if @var{flag} is 0, otherwise | |
13877 | the checking function is called with @var{os} argument set to | |
13878 | @code{(size_t) -1}. | |
13879 | ||
13880 | In addition to this, there are checking built-in functions | |
13881 | @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, | |
13882 | @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. | |
13883 | These have just one additional argument, @var{flag}, right before | |
13884 | format string @var{fmt}. If the compiler is able to optimize them to | |
13885 | @code{fputc} etc.@: functions, it does, otherwise the checking function | |
13886 | is called and the @var{flag} argument passed to it. | |
f25efe50 | 13887 | @enddefbuiltin |
d77de738 ML |
13888 | |
13889 | @node Other Builtins | |
13890 | @section Other Built-in Functions Provided by GCC | |
13891 | @cindex built-in functions | |
34cf27a6 | 13892 | @findex __builtin_iseqsig |
d77de738 ML |
13893 | @findex __builtin_isfinite |
13894 | @findex __builtin_isnormal | |
13895 | @findex __builtin_isgreater | |
13896 | @findex __builtin_isgreaterequal | |
d77de738 | 13897 | @findex __builtin_isunordered |
d77de738 ML |
13898 | @findex __builtin_speculation_safe_value |
13899 | @findex _Exit | |
13900 | @findex _exit | |
13901 | @findex abort | |
13902 | @findex abs | |
13903 | @findex acos | |
13904 | @findex acosf | |
13905 | @findex acosh | |
13906 | @findex acoshf | |
13907 | @findex acoshl | |
13908 | @findex acosl | |
13909 | @findex alloca | |
13910 | @findex asin | |
13911 | @findex asinf | |
13912 | @findex asinh | |
13913 | @findex asinhf | |
13914 | @findex asinhl | |
13915 | @findex asinl | |
13916 | @findex atan | |
13917 | @findex atan2 | |
13918 | @findex atan2f | |
13919 | @findex atan2l | |
13920 | @findex atanf | |
13921 | @findex atanh | |
13922 | @findex atanhf | |
13923 | @findex atanhl | |
13924 | @findex atanl | |
13925 | @findex bcmp | |
13926 | @findex bzero | |
13927 | @findex cabs | |
13928 | @findex cabsf | |
13929 | @findex cabsl | |
13930 | @findex cacos | |
13931 | @findex cacosf | |
13932 | @findex cacosh | |
13933 | @findex cacoshf | |
13934 | @findex cacoshl | |
13935 | @findex cacosl | |
13936 | @findex calloc | |
13937 | @findex carg | |
13938 | @findex cargf | |
13939 | @findex cargl | |
13940 | @findex casin | |
13941 | @findex casinf | |
13942 | @findex casinh | |
13943 | @findex casinhf | |
13944 | @findex casinhl | |
13945 | @findex casinl | |
13946 | @findex catan | |
13947 | @findex catanf | |
13948 | @findex catanh | |
13949 | @findex catanhf | |
13950 | @findex catanhl | |
13951 | @findex catanl | |
13952 | @findex cbrt | |
13953 | @findex cbrtf | |
13954 | @findex cbrtl | |
13955 | @findex ccos | |
13956 | @findex ccosf | |
13957 | @findex ccosh | |
13958 | @findex ccoshf | |
13959 | @findex ccoshl | |
13960 | @findex ccosl | |
13961 | @findex ceil | |
13962 | @findex ceilf | |
13963 | @findex ceill | |
13964 | @findex cexp | |
13965 | @findex cexpf | |
13966 | @findex cexpl | |
13967 | @findex cimag | |
13968 | @findex cimagf | |
13969 | @findex cimagl | |
13970 | @findex clog | |
13971 | @findex clogf | |
13972 | @findex clogl | |
13973 | @findex clog10 | |
13974 | @findex clog10f | |
13975 | @findex clog10l | |
13976 | @findex conj | |
13977 | @findex conjf | |
13978 | @findex conjl | |
13979 | @findex copysign | |
13980 | @findex copysignf | |
13981 | @findex copysignl | |
13982 | @findex cos | |
13983 | @findex cosf | |
13984 | @findex cosh | |
13985 | @findex coshf | |
13986 | @findex coshl | |
13987 | @findex cosl | |
13988 | @findex cpow | |
13989 | @findex cpowf | |
13990 | @findex cpowl | |
13991 | @findex cproj | |
13992 | @findex cprojf | |
13993 | @findex cprojl | |
13994 | @findex creal | |
13995 | @findex crealf | |
13996 | @findex creall | |
13997 | @findex csin | |
13998 | @findex csinf | |
13999 | @findex csinh | |
14000 | @findex csinhf | |
14001 | @findex csinhl | |
14002 | @findex csinl | |
14003 | @findex csqrt | |
14004 | @findex csqrtf | |
14005 | @findex csqrtl | |
14006 | @findex ctan | |
14007 | @findex ctanf | |
14008 | @findex ctanh | |
14009 | @findex ctanhf | |
14010 | @findex ctanhl | |
14011 | @findex ctanl | |
14012 | @findex dcgettext | |
14013 | @findex dgettext | |
14014 | @findex drem | |
14015 | @findex dremf | |
14016 | @findex dreml | |
14017 | @findex erf | |
14018 | @findex erfc | |
14019 | @findex erfcf | |
14020 | @findex erfcl | |
14021 | @findex erff | |
14022 | @findex erfl | |
14023 | @findex exit | |
14024 | @findex exp | |
14025 | @findex exp10 | |
14026 | @findex exp10f | |
14027 | @findex exp10l | |
14028 | @findex exp2 | |
14029 | @findex exp2f | |
14030 | @findex exp2l | |
14031 | @findex expf | |
14032 | @findex expl | |
14033 | @findex expm1 | |
14034 | @findex expm1f | |
14035 | @findex expm1l | |
14036 | @findex fabs | |
14037 | @findex fabsf | |
14038 | @findex fabsl | |
14039 | @findex fdim | |
14040 | @findex fdimf | |
14041 | @findex fdiml | |
14042 | @findex ffs | |
14043 | @findex floor | |
14044 | @findex floorf | |
14045 | @findex floorl | |
14046 | @findex fma | |
14047 | @findex fmaf | |
14048 | @findex fmal | |
14049 | @findex fmax | |
14050 | @findex fmaxf | |
14051 | @findex fmaxl | |
14052 | @findex fmin | |
14053 | @findex fminf | |
14054 | @findex fminl | |
14055 | @findex fmod | |
14056 | @findex fmodf | |
14057 | @findex fmodl | |
14058 | @findex fprintf | |
14059 | @findex fprintf_unlocked | |
14060 | @findex fputs | |
14061 | @findex fputs_unlocked | |
14062 | @findex free | |
14063 | @findex frexp | |
14064 | @findex frexpf | |
14065 | @findex frexpl | |
14066 | @findex fscanf | |
14067 | @findex gamma | |
14068 | @findex gammaf | |
14069 | @findex gammal | |
14070 | @findex gamma_r | |
14071 | @findex gammaf_r | |
14072 | @findex gammal_r | |
14073 | @findex gettext | |
14074 | @findex hypot | |
14075 | @findex hypotf | |
14076 | @findex hypotl | |
14077 | @findex ilogb | |
14078 | @findex ilogbf | |
14079 | @findex ilogbl | |
14080 | @findex imaxabs | |
14081 | @findex index | |
14082 | @findex isalnum | |
14083 | @findex isalpha | |
14084 | @findex isascii | |
14085 | @findex isblank | |
14086 | @findex iscntrl | |
14087 | @findex isdigit | |
14088 | @findex isgraph | |
14089 | @findex islower | |
14090 | @findex isprint | |
14091 | @findex ispunct | |
14092 | @findex isspace | |
14093 | @findex isupper | |
14094 | @findex iswalnum | |
14095 | @findex iswalpha | |
14096 | @findex iswblank | |
14097 | @findex iswcntrl | |
14098 | @findex iswdigit | |
14099 | @findex iswgraph | |
14100 | @findex iswlower | |
14101 | @findex iswprint | |
14102 | @findex iswpunct | |
14103 | @findex iswspace | |
14104 | @findex iswupper | |
14105 | @findex iswxdigit | |
14106 | @findex isxdigit | |
14107 | @findex j0 | |
14108 | @findex j0f | |
14109 | @findex j0l | |
14110 | @findex j1 | |
14111 | @findex j1f | |
14112 | @findex j1l | |
14113 | @findex jn | |
14114 | @findex jnf | |
14115 | @findex jnl | |
14116 | @findex labs | |
14117 | @findex ldexp | |
14118 | @findex ldexpf | |
14119 | @findex ldexpl | |
14120 | @findex lgamma | |
14121 | @findex lgammaf | |
14122 | @findex lgammal | |
14123 | @findex lgamma_r | |
14124 | @findex lgammaf_r | |
14125 | @findex lgammal_r | |
14126 | @findex llabs | |
14127 | @findex llrint | |
14128 | @findex llrintf | |
14129 | @findex llrintl | |
14130 | @findex llround | |
14131 | @findex llroundf | |
14132 | @findex llroundl | |
14133 | @findex log | |
14134 | @findex log10 | |
14135 | @findex log10f | |
14136 | @findex log10l | |
14137 | @findex log1p | |
14138 | @findex log1pf | |
14139 | @findex log1pl | |
14140 | @findex log2 | |
14141 | @findex log2f | |
14142 | @findex log2l | |
14143 | @findex logb | |
14144 | @findex logbf | |
14145 | @findex logbl | |
14146 | @findex logf | |
14147 | @findex logl | |
14148 | @findex lrint | |
14149 | @findex lrintf | |
14150 | @findex lrintl | |
14151 | @findex lround | |
14152 | @findex lroundf | |
14153 | @findex lroundl | |
14154 | @findex malloc | |
14155 | @findex memchr | |
14156 | @findex memcmp | |
14157 | @findex memcpy | |
14158 | @findex mempcpy | |
14159 | @findex memset | |
14160 | @findex modf | |
14161 | @findex modff | |
14162 | @findex modfl | |
14163 | @findex nearbyint | |
14164 | @findex nearbyintf | |
14165 | @findex nearbyintl | |
14166 | @findex nextafter | |
14167 | @findex nextafterf | |
14168 | @findex nextafterl | |
14169 | @findex nexttoward | |
14170 | @findex nexttowardf | |
14171 | @findex nexttowardl | |
14172 | @findex pow | |
14173 | @findex pow10 | |
14174 | @findex pow10f | |
14175 | @findex pow10l | |
14176 | @findex powf | |
14177 | @findex powl | |
14178 | @findex printf | |
14179 | @findex printf_unlocked | |
14180 | @findex putchar | |
14181 | @findex puts | |
14182 | @findex realloc | |
14183 | @findex remainder | |
14184 | @findex remainderf | |
14185 | @findex remainderl | |
14186 | @findex remquo | |
14187 | @findex remquof | |
14188 | @findex remquol | |
14189 | @findex rindex | |
14190 | @findex rint | |
14191 | @findex rintf | |
14192 | @findex rintl | |
14193 | @findex round | |
14194 | @findex roundf | |
14195 | @findex roundl | |
14196 | @findex scalb | |
14197 | @findex scalbf | |
14198 | @findex scalbl | |
14199 | @findex scalbln | |
14200 | @findex scalblnf | |
14201 | @findex scalblnf | |
14202 | @findex scalbn | |
14203 | @findex scalbnf | |
14204 | @findex scanfnl | |
14205 | @findex signbit | |
14206 | @findex signbitf | |
14207 | @findex signbitl | |
14208 | @findex signbitd32 | |
14209 | @findex signbitd64 | |
14210 | @findex signbitd128 | |
14211 | @findex significand | |
14212 | @findex significandf | |
14213 | @findex significandl | |
14214 | @findex sin | |
14215 | @findex sincos | |
14216 | @findex sincosf | |
14217 | @findex sincosl | |
14218 | @findex sinf | |
14219 | @findex sinh | |
14220 | @findex sinhf | |
14221 | @findex sinhl | |
14222 | @findex sinl | |
14223 | @findex snprintf | |
14224 | @findex sprintf | |
14225 | @findex sqrt | |
14226 | @findex sqrtf | |
14227 | @findex sqrtl | |
14228 | @findex sscanf | |
14229 | @findex stpcpy | |
14230 | @findex stpncpy | |
14231 | @findex strcasecmp | |
14232 | @findex strcat | |
14233 | @findex strchr | |
14234 | @findex strcmp | |
14235 | @findex strcpy | |
14236 | @findex strcspn | |
14237 | @findex strdup | |
14238 | @findex strfmon | |
14239 | @findex strftime | |
14240 | @findex strlen | |
14241 | @findex strncasecmp | |
14242 | @findex strncat | |
14243 | @findex strncmp | |
14244 | @findex strncpy | |
14245 | @findex strndup | |
14246 | @findex strnlen | |
14247 | @findex strpbrk | |
14248 | @findex strrchr | |
14249 | @findex strspn | |
14250 | @findex strstr | |
14251 | @findex tan | |
14252 | @findex tanf | |
14253 | @findex tanh | |
14254 | @findex tanhf | |
14255 | @findex tanhl | |
14256 | @findex tanl | |
14257 | @findex tgamma | |
14258 | @findex tgammaf | |
14259 | @findex tgammal | |
14260 | @findex toascii | |
14261 | @findex tolower | |
14262 | @findex toupper | |
14263 | @findex towlower | |
14264 | @findex towupper | |
14265 | @findex trunc | |
14266 | @findex truncf | |
14267 | @findex truncl | |
14268 | @findex vfprintf | |
14269 | @findex vfscanf | |
14270 | @findex vprintf | |
14271 | @findex vscanf | |
14272 | @findex vsnprintf | |
14273 | @findex vsprintf | |
14274 | @findex vsscanf | |
14275 | @findex y0 | |
14276 | @findex y0f | |
14277 | @findex y0l | |
14278 | @findex y1 | |
14279 | @findex y1f | |
14280 | @findex y1l | |
14281 | @findex yn | |
14282 | @findex ynf | |
14283 | @findex ynl | |
14284 | ||
14285 | GCC provides a large number of built-in functions other than the ones | |
14286 | mentioned above. Some of these are for internal use in the processing | |
14287 | of exceptions or variable-length argument lists and are not | |
14288 | documented here because they may change from time to time; we do not | |
14289 | recommend general use of these functions. | |
14290 | ||
14291 | The remaining functions are provided for optimization purposes. | |
14292 | ||
14293 | With the exception of built-ins that have library equivalents such as | |
14294 | the standard C library functions discussed below, or that expand to | |
14295 | library calls, GCC built-in functions are always expanded inline and | |
14296 | thus do not have corresponding entry points and their address cannot | |
14297 | be obtained. Attempting to use them in an expression other than | |
14298 | a function call results in a compile-time error. | |
14299 | ||
14300 | @opindex fno-builtin | |
14301 | GCC includes built-in versions of many of the functions in the standard | |
14302 | C library. These functions come in two forms: one whose names start with | |
14303 | the @code{__builtin_} prefix, and the other without. Both forms have the | |
14304 | same type (including prototype), the same address (when their address is | |
14305 | taken), and the same meaning as the C library functions even if you specify | |
14306 | the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these | |
14307 | functions are only optimized in certain cases; if they are not optimized in | |
14308 | a particular case, a call to the library function is emitted. | |
14309 | ||
14310 | @opindex ansi | |
14311 | @opindex std | |
14312 | Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, | |
14313 | @option{-std=c99} or @option{-std=c11}), the functions | |
14314 | @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, | |
14315 | @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, | |
14316 | @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, | |
14317 | @code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, | |
14318 | @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, | |
14319 | @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, | |
14320 | @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, | |
14321 | @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, | |
14322 | @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, | |
14323 | @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, | |
14324 | @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl}, | |
14325 | @code{scalbf}, @code{scalbl}, @code{scalb}, | |
14326 | @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, | |
14327 | @code{signbitd64}, @code{signbitd128}, @code{significandf}, | |
14328 | @code{significandl}, @code{significand}, @code{sincosf}, | |
14329 | @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, | |
14330 | @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, | |
14331 | @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, | |
14332 | @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and | |
14333 | @code{yn} | |
14334 | may be handled as built-in functions. | |
14335 | All these functions have corresponding versions | |
14336 | prefixed with @code{__builtin_}, which may be used even in strict C90 | |
14337 | mode. | |
14338 | ||
14339 | The ISO C99 functions | |
14340 | @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, | |
14341 | @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, | |
14342 | @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, | |
14343 | @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, | |
14344 | @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, | |
14345 | @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, | |
14346 | @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, | |
14347 | @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, | |
14348 | @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, | |
14349 | @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, | |
14350 | @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, | |
14351 | @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, | |
14352 | @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, | |
14353 | @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, | |
14354 | @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, | |
14355 | @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, | |
14356 | @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, | |
14357 | @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, | |
14358 | @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, | |
14359 | @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, | |
14360 | @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, | |
14361 | @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, | |
14362 | @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, | |
14363 | @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, | |
14364 | @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, | |
14365 | @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, | |
14366 | @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, | |
14367 | @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, | |
14368 | @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, | |
14369 | @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, | |
14370 | @code{nextafterf}, @code{nextafterl}, @code{nextafter}, | |
14371 | @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, | |
14372 | @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, | |
14373 | @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, | |
14374 | @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, | |
14375 | @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, | |
14376 | @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, | |
14377 | @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, | |
14378 | @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} | |
14379 | are handled as built-in functions | |
14380 | except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). | |
14381 | ||
14382 | There are also built-in versions of the ISO C99 functions | |
14383 | @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, | |
14384 | @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, | |
14385 | @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, | |
14386 | @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, | |
14387 | @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, | |
14388 | @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, | |
14389 | @code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf}, | |
14390 | @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, | |
14391 | @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} | |
14392 | that are recognized in any mode since ISO C90 reserves these names for | |
14393 | the purpose to which ISO C99 puts them. All these functions have | |
14394 | corresponding versions prefixed with @code{__builtin_}. | |
14395 | ||
14396 | There are also built-in functions @code{__builtin_fabsf@var{n}}, | |
14397 | @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and | |
14398 | @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 | |
14399 | functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, | |
14400 | @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported | |
14401 | types @code{_Float@var{n}} and @code{_Float@var{n}x}. | |
14402 | ||
14403 | There are also GNU extension functions @code{clog10}, @code{clog10f} and | |
14404 | @code{clog10l} which names are reserved by ISO C99 for future use. | |
14405 | All these functions have versions prefixed with @code{__builtin_}. | |
14406 | ||
14407 | The ISO C94 functions | |
14408 | @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, | |
14409 | @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, | |
14410 | @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and | |
14411 | @code{towupper} | |
14412 | are handled as built-in functions | |
14413 | except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). | |
14414 | ||
14415 | The ISO C90 functions | |
14416 | @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, | |
14417 | @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, | |
14418 | @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, | |
14419 | @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf}, | |
14420 | @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, | |
14421 | @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, | |
14422 | @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, | |
14423 | @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, | |
14424 | @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, | |
14425 | @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, | |
14426 | @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin}, | |
14427 | @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, | |
14428 | @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, | |
14429 | @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, | |
14430 | @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, | |
14431 | @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} | |
14432 | are all recognized as built-in functions unless | |
14433 | @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} | |
14434 | is specified for an individual function). All of these functions have | |
14435 | corresponding versions prefixed with @code{__builtin_}. | |
14436 | ||
14437 | GCC provides built-in versions of the ISO C99 floating-point comparison | |
14438 | macros that avoid raising exceptions for unordered operands. They have | |
14439 | the same names as the standard macros ( @code{isgreater}, | |
14440 | @code{isgreaterequal}, @code{isless}, @code{islessequal}, | |
14441 | @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} | |
14442 | prefixed. We intend for a library implementor to be able to simply | |
14443 | @code{#define} each standard macro to its built-in equivalent. | |
34cf27a6 FXC |
14444 | In the same fashion, GCC provides @code{fpclassify}, @code{iseqsig}, |
14445 | @code{isfinite}, @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins | |
14446 | used with @code{__builtin_} prefixed. The @code{isinf} and @code{isnan} | |
d77de738 ML |
14447 | built-in functions appear both with and without the @code{__builtin_} prefix. |
14448 | With @code{-ffinite-math-only} option the @code{isinf} and @code{isnan} | |
14449 | built-in functions will always return 0. | |
14450 | ||
14451 | GCC provides built-in versions of the ISO C99 floating-point rounding and | |
14452 | exceptions handling functions @code{fegetround}, @code{feclearexcept} and | |
14453 | @code{feraiseexcept}. They may not be available for all targets, and because | |
14454 | they need close interaction with libc internal values, they may not be available | |
14455 | for all target libcs, but in all cases they will gracefully fallback to libc | |
14456 | calls. These built-in functions appear both with and without the | |
14457 | @code{__builtin_} prefix. | |
14458 | ||
23795106 | 14459 | @defbuiltin{{void *} __builtin_alloca (size_t @var{size})} |
d77de738 ML |
14460 | The @code{__builtin_alloca} function must be called at block scope. |
14461 | The function allocates an object @var{size} bytes large on the stack | |
14462 | of the calling function. The object is aligned on the default stack | |
14463 | alignment boundary for the target determined by the | |
14464 | @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} | |
14465 | function returns a pointer to the first byte of the allocated object. | |
14466 | The lifetime of the allocated object ends just before the calling | |
14467 | function returns to its caller. This is so even when | |
14468 | @code{__builtin_alloca} is called within a nested block. | |
14469 | ||
14470 | For example, the following function allocates eight objects of @code{n} | |
14471 | bytes each on the stack, storing a pointer to each in consecutive elements | |
14472 | of the array @code{a}. It then passes the array to function @code{g} | |
14473 | which can safely use the storage pointed to by each of the array elements. | |
14474 | ||
14475 | @smallexample | |
14476 | void f (unsigned n) | |
14477 | @{ | |
14478 | void *a [8]; | |
14479 | for (int i = 0; i != 8; ++i) | |
14480 | a [i] = __builtin_alloca (n); | |
14481 | ||
14482 | g (a, n); // @r{safe} | |
14483 | @} | |
14484 | @end smallexample | |
14485 | ||
14486 | Since the @code{__builtin_alloca} function doesn't validate its argument | |
14487 | it is the responsibility of its caller to make sure the argument doesn't | |
14488 | cause it to exceed the stack size limit. | |
14489 | The @code{__builtin_alloca} function is provided to make it possible to | |
14490 | allocate on the stack arrays of bytes with an upper bound that may be | |
14491 | computed at run time. Since C99 Variable Length Arrays offer | |
14492 | similar functionality under a portable, more convenient, and safer | |
14493 | interface they are recommended instead, in both C99 and C++ programs | |
14494 | where GCC provides them as an extension. | |
14495 | @xref{Variable Length}, for details. | |
14496 | ||
f25efe50 | 14497 | @enddefbuiltin |
d77de738 | 14498 | |
23795106 | 14499 | @defbuiltin{{void *} __builtin_alloca_with_align (size_t @var{size}, size_t @var{alignment})} |
d77de738 ML |
14500 | The @code{__builtin_alloca_with_align} function must be called at block |
14501 | scope. The function allocates an object @var{size} bytes large on | |
14502 | the stack of the calling function. The allocated object is aligned on | |
14503 | the boundary specified by the argument @var{alignment} whose unit is given | |
14504 | in bits (not bytes). The @var{size} argument must be positive and not | |
14505 | exceed the stack size limit. The @var{alignment} argument must be a constant | |
14506 | integer expression that evaluates to a power of 2 greater than or equal to | |
14507 | @code{CHAR_BIT} and less than some unspecified maximum. Invocations | |
14508 | with other values are rejected with an error indicating the valid bounds. | |
14509 | The function returns a pointer to the first byte of the allocated object. | |
14510 | The lifetime of the allocated object ends at the end of the block in which | |
14511 | the function was called. The allocated storage is released no later than | |
14512 | just before the calling function returns to its caller, but may be released | |
14513 | at the end of the block in which the function was called. | |
14514 | ||
14515 | For example, in the following function the call to @code{g} is unsafe | |
14516 | because when @code{overalign} is non-zero, the space allocated by | |
14517 | @code{__builtin_alloca_with_align} may have been released at the end | |
14518 | of the @code{if} statement in which it was called. | |
14519 | ||
14520 | @smallexample | |
14521 | void f (unsigned n, bool overalign) | |
14522 | @{ | |
14523 | void *p; | |
14524 | if (overalign) | |
14525 | p = __builtin_alloca_with_align (n, 64 /* bits */); | |
14526 | else | |
14527 | p = __builtin_alloc (n); | |
14528 | ||
14529 | g (p, n); // @r{unsafe} | |
14530 | @} | |
14531 | @end smallexample | |
14532 | ||
14533 | Since the @code{__builtin_alloca_with_align} function doesn't validate its | |
14534 | @var{size} argument it is the responsibility of its caller to make sure | |
14535 | the argument doesn't cause it to exceed the stack size limit. | |
14536 | The @code{__builtin_alloca_with_align} function is provided to make | |
14537 | it possible to allocate on the stack overaligned arrays of bytes with | |
14538 | an upper bound that may be computed at run time. Since C99 | |
14539 | Variable Length Arrays offer the same functionality under | |
14540 | a portable, more convenient, and safer interface they are recommended | |
14541 | instead, in both C99 and C++ programs where GCC provides them as | |
14542 | an extension. @xref{Variable Length}, for details. | |
14543 | ||
f25efe50 | 14544 | @enddefbuiltin |
d77de738 | 14545 | |
23795106 | 14546 | @defbuiltin{{void *} __builtin_alloca_with_align_and_max (size_t @var{size}, size_t @var{alignment}, size_t @var{max_size})} |
d77de738 ML |
14547 | Similar to @code{__builtin_alloca_with_align} but takes an extra argument |
14548 | specifying an upper bound for @var{size} in case its value cannot be computed | |
14549 | at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} | |
14550 | and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer | |
14551 | expression, it has no effect on code generation and no attempt is made to | |
14552 | check its compatibility with @var{size}. | |
14553 | ||
f25efe50 | 14554 | @enddefbuiltin |
d77de738 | 14555 | |
f25efe50 | 14556 | @defbuiltin{bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})} |
d77de738 ML |
14557 | The @code{__builtin_has_attribute} function evaluates to an integer constant |
14558 | expression equal to @code{true} if the symbol or type referenced by | |
14559 | the @var{type-or-expression} argument has been declared with | |
14560 | the @var{attribute} referenced by the second argument. For | |
14561 | an @var{type-or-expression} argument that does not reference a symbol, | |
14562 | since attributes do not apply to expressions the built-in consider | |
14563 | the type of the argument. Neither argument is evaluated. | |
14564 | The @var{type-or-expression} argument is subject to the same | |
14565 | restrictions as the argument to @code{typeof} (@pxref{Typeof}). The | |
14566 | @var{attribute} argument is an attribute name optionally followed by | |
14567 | a comma-separated list of arguments enclosed in parentheses. Both forms | |
14568 | of attribute names---with and without double leading and trailing | |
14569 | underscores---are recognized. @xref{Attribute Syntax}, for details. | |
14570 | When no attribute arguments are specified for an attribute that expects | |
14571 | one or more arguments the function returns @code{true} if | |
14572 | @var{type-or-expression} has been declared with the attribute regardless | |
14573 | of the attribute argument values. Arguments provided for an attribute | |
14574 | that expects some are validated and matched up to the provided number. | |
14575 | The function returns @code{true} if all provided arguments match. For | |
14576 | example, the first call to the function below evaluates to @code{true} | |
14577 | because @code{x} is declared with the @code{aligned} attribute but | |
14578 | the second call evaluates to @code{false} because @code{x} is declared | |
14579 | @code{aligned (8)} and not @code{aligned (4)}. | |
14580 | ||
14581 | @smallexample | |
14582 | __attribute__ ((aligned (8))) int x; | |
14583 | _Static_assert (__builtin_has_attribute (x, aligned), "aligned"); | |
14584 | _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)"); | |
14585 | @end smallexample | |
14586 | ||
14587 | Due to a limitation the @code{__builtin_has_attribute} function returns | |
14588 | @code{false} for the @code{mode} attribute even if the type or variable | |
14589 | referenced by the @var{type-or-expression} argument was declared with one. | |
14590 | The function is also not supported with labels, and in C with enumerators. | |
14591 | ||
14592 | Note that unlike the @code{__has_attribute} preprocessor operator which | |
14593 | is suitable for use in @code{#if} preprocessing directives | |
14594 | @code{__builtin_has_attribute} is an intrinsic function that is not | |
14595 | recognized in such contexts. | |
14596 | ||
f25efe50 | 14597 | @enddefbuiltin |
d77de738 | 14598 | |
23795106 | 14599 | @defbuiltin{@var{type} __builtin_speculation_safe_value (@var{type} @var{val}, @var{type} @var{failval})} |
d77de738 ML |
14600 | |
14601 | This built-in function can be used to help mitigate against unsafe | |
14602 | speculative execution. @var{type} may be any integral type or any | |
14603 | pointer type. | |
14604 | ||
14605 | @enumerate | |
14606 | @item | |
14607 | If the CPU is not speculatively executing the code, then @var{val} | |
14608 | is returned. | |
14609 | @item | |
14610 | If the CPU is executing speculatively then either: | |
14611 | @itemize | |
14612 | @item | |
14613 | The function may cause execution to pause until it is known that the | |
14614 | code is no-longer being executed speculatively (in which case | |
14615 | @var{val} can be returned, as above); or | |
14616 | @item | |
14617 | The function may use target-dependent speculation tracking state to cause | |
14618 | @var{failval} to be returned when it is known that speculative | |
14619 | execution has incorrectly predicted a conditional branch operation. | |
14620 | @end itemize | |
14621 | @end enumerate | |
14622 | ||
14623 | The second argument, @var{failval}, is optional and defaults to zero | |
14624 | if omitted. | |
14625 | ||
14626 | GCC defines the preprocessor macro | |
14627 | @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been | |
14628 | updated to support this builtin. | |
14629 | ||
14630 | The built-in function can be used where a variable appears to be used in a | |
14631 | safe way, but the CPU, due to speculative execution may temporarily ignore | |
14632 | the bounds checks. Consider, for example, the following function: | |
14633 | ||
14634 | @smallexample | |
14635 | int array[500]; | |
14636 | int f (unsigned untrusted_index) | |
14637 | @{ | |
14638 | if (untrusted_index < 500) | |
14639 | return array[untrusted_index]; | |
14640 | return 0; | |
14641 | @} | |
14642 | @end smallexample | |
14643 | ||
14644 | If the function is called repeatedly with @code{untrusted_index} less | |
14645 | than the limit of 500, then a branch predictor will learn that the | |
14646 | block of code that returns a value stored in @code{array} will be | |
14647 | executed. If the function is subsequently called with an | |
14648 | out-of-range value it will still try to execute that block of code | |
14649 | first until the CPU determines that the prediction was incorrect | |
14650 | (the CPU will unwind any incorrect operations at that point). | |
14651 | However, depending on how the result of the function is used, it might be | |
14652 | possible to leave traces in the cache that can reveal what was stored | |
14653 | at the out-of-bounds location. The built-in function can be used to | |
14654 | provide some protection against leaking data in this way by changing | |
14655 | the code to: | |
14656 | ||
14657 | @smallexample | |
14658 | int array[500]; | |
14659 | int f (unsigned untrusted_index) | |
14660 | @{ | |
14661 | if (untrusted_index < 500) | |
14662 | return array[__builtin_speculation_safe_value (untrusted_index)]; | |
14663 | return 0; | |
14664 | @} | |
14665 | @end smallexample | |
14666 | ||
14667 | The built-in function will either cause execution to stall until the | |
14668 | conditional branch has been fully resolved, or it may permit | |
14669 | speculative execution to continue, but using 0 instead of | |
14670 | @code{untrusted_value} if that exceeds the limit. | |
14671 | ||
14672 | If accessing any memory location is potentially unsafe when speculative | |
14673 | execution is incorrect, then the code can be rewritten as | |
14674 | ||
14675 | @smallexample | |
14676 | int array[500]; | |
14677 | int f (unsigned untrusted_index) | |
14678 | @{ | |
14679 | if (untrusted_index < 500) | |
14680 | return *__builtin_speculation_safe_value (&array[untrusted_index], NULL); | |
14681 | return 0; | |
14682 | @} | |
14683 | @end smallexample | |
14684 | ||
14685 | which will cause a @code{NULL} pointer to be used for the unsafe case. | |
14686 | ||
f25efe50 | 14687 | @enddefbuiltin |
d77de738 | 14688 | |
f25efe50 | 14689 | @defbuiltin{int __builtin_types_compatible_p (@var{type1}, @var{type2})} |
d77de738 ML |
14690 | |
14691 | You can use the built-in function @code{__builtin_types_compatible_p} to | |
14692 | determine whether two types are the same. | |
14693 | ||
14694 | This built-in function returns 1 if the unqualified versions of the | |
14695 | types @var{type1} and @var{type2} (which are types, not expressions) are | |
14696 | compatible, 0 otherwise. The result of this built-in function can be | |
14697 | used in integer constant expressions. | |
14698 | ||
14699 | This built-in function ignores top level qualifiers (e.g., @code{const}, | |
14700 | @code{volatile}). For example, @code{int} is equivalent to @code{const | |
14701 | int}. | |
14702 | ||
14703 | The type @code{int[]} and @code{int[5]} are compatible. On the other | |
14704 | hand, @code{int} and @code{char *} are not compatible, even if the size | |
14705 | of their types, on the particular architecture are the same. Also, the | |
14706 | amount of pointer indirection is taken into account when determining | |
14707 | similarity. Consequently, @code{short *} is not similar to | |
14708 | @code{short **}. Furthermore, two types that are typedefed are | |
14709 | considered compatible if their underlying types are compatible. | |
14710 | ||
14711 | An @code{enum} type is not considered to be compatible with another | |
14712 | @code{enum} type even if both are compatible with the same integer | |
14713 | type; this is what the C standard specifies. | |
14714 | For example, @code{enum @{foo, bar@}} is not similar to | |
14715 | @code{enum @{hot, dog@}}. | |
14716 | ||
14717 | You typically use this function in code whose execution varies | |
14718 | depending on the arguments' types. For example: | |
14719 | ||
14720 | @smallexample | |
14721 | #define foo(x) \ | |
14722 | (@{ \ | |
14723 | typeof (x) tmp = (x); \ | |
14724 | if (__builtin_types_compatible_p (typeof (x), long double)) \ | |
14725 | tmp = foo_long_double (tmp); \ | |
14726 | else if (__builtin_types_compatible_p (typeof (x), double)) \ | |
14727 | tmp = foo_double (tmp); \ | |
14728 | else if (__builtin_types_compatible_p (typeof (x), float)) \ | |
14729 | tmp = foo_float (tmp); \ | |
14730 | else \ | |
14731 | abort (); \ | |
14732 | tmp; \ | |
14733 | @}) | |
14734 | @end smallexample | |
14735 | ||
14736 | @emph{Note:} This construct is only available for C@. | |
14737 | ||
f25efe50 | 14738 | @enddefbuiltin |
d77de738 | 14739 | |
f25efe50 | 14740 | @defbuiltin{@var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})} |
d77de738 ML |
14741 | |
14742 | The @var{call_exp} expression must be a function call, and the | |
14743 | @var{pointer_exp} expression must be a pointer. The @var{pointer_exp} | |
14744 | is passed to the function call in the target's static chain location. | |
14745 | The result of builtin is the result of the function call. | |
14746 | ||
14747 | @emph{Note:} This builtin is only available for C@. | |
14748 | This builtin can be used to call Go closures from C. | |
14749 | ||
f25efe50 | 14750 | @enddefbuiltin |
d77de738 | 14751 | |
f25efe50 | 14752 | @defbuiltin{@var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})} |
d77de738 ML |
14753 | |
14754 | You can use the built-in function @code{__builtin_choose_expr} to | |
14755 | evaluate code depending on the value of a constant expression. This | |
14756 | built-in function returns @var{exp1} if @var{const_exp}, which is an | |
14757 | integer constant expression, is nonzero. Otherwise it returns @var{exp2}. | |
14758 | ||
14759 | This built-in function is analogous to the @samp{? :} operator in C, | |
14760 | except that the expression returned has its type unaltered by promotion | |
14761 | rules. Also, the built-in function does not evaluate the expression | |
14762 | that is not chosen. For example, if @var{const_exp} evaluates to @code{true}, | |
14763 | @var{exp2} is not evaluated even if it has side effects. | |
14764 | ||
14765 | This built-in function can return an lvalue if the chosen argument is an | |
14766 | lvalue. | |
14767 | ||
14768 | If @var{exp1} is returned, the return type is the same as @var{exp1}'s | |
14769 | type. Similarly, if @var{exp2} is returned, its return type is the same | |
14770 | as @var{exp2}. | |
14771 | ||
14772 | Example: | |
14773 | ||
14774 | @smallexample | |
14775 | #define foo(x) \ | |
14776 | __builtin_choose_expr ( \ | |
14777 | __builtin_types_compatible_p (typeof (x), double), \ | |
14778 | foo_double (x), \ | |
14779 | __builtin_choose_expr ( \ | |
14780 | __builtin_types_compatible_p (typeof (x), float), \ | |
14781 | foo_float (x), \ | |
14782 | /* @r{The void expression results in a compile-time error} \ | |
14783 | @r{when assigning the result to something.} */ \ | |
14784 | (void)0)) | |
14785 | @end smallexample | |
14786 | ||
14787 | @emph{Note:} This construct is only available for C@. Furthermore, the | |
14788 | unused expression (@var{exp1} or @var{exp2} depending on the value of | |
14789 | @var{const_exp}) may still generate syntax errors. This may change in | |
14790 | future revisions. | |
14791 | ||
f25efe50 | 14792 | @enddefbuiltin |
d77de738 | 14793 | |
f25efe50 | 14794 | @defbuiltin{@var{type} __builtin_tgmath (@var{functions}, @var{arguments})} |
d77de738 ML |
14795 | |
14796 | The built-in function @code{__builtin_tgmath}, available only for C | |
14797 | and Objective-C, calls a function determined according to the rules of | |
14798 | @code{<tgmath.h>} macros. It is intended to be used in | |
14799 | implementations of that header, so that expansions of macros from that | |
14800 | header only expand each of their arguments once, to avoid problems | |
14801 | when calls to such macros are nested inside the arguments of other | |
14802 | calls to such macros; in addition, it results in better diagnostics | |
14803 | for invalid calls to @code{<tgmath.h>} macros than implementations | |
14804 | using other GNU C language features. For example, the @code{pow} | |
14805 | type-generic macro might be defined as: | |
14806 | ||
14807 | @smallexample | |
14808 | #define pow(a, b) __builtin_tgmath (powf, pow, powl, \ | |
14809 | cpowf, cpow, cpowl, a, b) | |
14810 | @end smallexample | |
14811 | ||
14812 | The arguments to @code{__builtin_tgmath} are at least two pointers to | |
14813 | functions, followed by the arguments to the type-generic macro (which | |
14814 | will be passed as arguments to the selected function). All the | |
14815 | pointers to functions must be pointers to prototyped functions, none | |
14816 | of which may have variable arguments, and all of which must have the | |
14817 | same number of parameters; the number of parameters of the first | |
14818 | function determines how many arguments to @code{__builtin_tgmath} are | |
14819 | interpreted as function pointers, and how many as the arguments to the | |
14820 | called function. | |
14821 | ||
14822 | The types of the specified functions must all be different, but | |
14823 | related to each other in the same way as a set of functions that may | |
14824 | be selected between by a macro in @code{<tgmath.h>}. This means that | |
14825 | the functions are parameterized by a floating-point type @var{t}, | |
14826 | different for each such function. The function return types may all | |
14827 | be the same type, or they may be @var{t} for each function, or they | |
14828 | may be the real type corresponding to @var{t} for each function (if | |
14829 | some of the types @var{t} are complex). Likewise, for each parameter | |
14830 | position, the type of the parameter in that position may always be the | |
14831 | same type, or may be @var{t} for each function (this case must apply | |
14832 | for at least one parameter position), or may be the real type | |
14833 | corresponding to @var{t} for each function. | |
14834 | ||
14835 | The standard rules for @code{<tgmath.h>} macros are used to find a | |
14836 | common type @var{u} from the types of the arguments for parameters | |
14837 | whose types vary between the functions; complex integer types (a GNU | |
5b68fb47 JM |
14838 | extension) are treated like the complex type corresponding to the real |
14839 | floating type that would be chosen for the corresponding real integer type. | |
d77de738 ML |
14840 | If the function return types vary, or are all the same integer type, |
14841 | the function called is the one for which @var{t} is @var{u}, and it is | |
14842 | an error if there is no such function. If the function return types | |
14843 | are all the same floating-point type, the type-generic macro is taken | |
14844 | to be one of those from TS 18661 that rounds the result to a narrower | |
14845 | type; if there is a function for which @var{t} is @var{u}, it is | |
14846 | called, and otherwise the first function, if any, for which @var{t} | |
14847 | has at least the range and precision of @var{u} is called, and it is | |
14848 | an error if there is no such function. | |
14849 | ||
f25efe50 | 14850 | @enddefbuiltin |
d77de738 | 14851 | |
f25efe50 | 14852 | @defbuiltin{int __builtin_constant_p (@var{exp})} |
d77de738 | 14853 | You can use the built-in function @code{__builtin_constant_p} to |
44271570 RB |
14854 | determine if the expression @var{exp} is known to be constant at |
14855 | compile time and hence that GCC can perform constant-folding on expressions | |
14856 | involving that value. The argument of the function is the expression to test. | |
14857 | The expression is not evaluated, side-effects are discarded. The function | |
d77de738 | 14858 | returns the integer 1 if the argument is known to be a compile-time |
44271570 RB |
14859 | constant and 0 if it is not known to be a compile-time constant. |
14860 | Any expression that has side-effects makes the function return 0. | |
14861 | A return of 0 does not indicate that the expression is @emph{not} a constant, | |
14862 | but merely that GCC cannot prove it is a constant within the constraints | |
14863 | of the active set of optimization options. | |
d77de738 ML |
14864 | |
14865 | You typically use this function in an embedded application where | |
14866 | memory is a critical resource. If you have some complex calculation, | |
14867 | you may want it to be folded if it involves constants, but need to call | |
14868 | a function if it does not. For example: | |
14869 | ||
14870 | @smallexample | |
14871 | #define Scale_Value(X) \ | |
14872 | (__builtin_constant_p (X) \ | |
14873 | ? ((X) * SCALE + OFFSET) : Scale (X)) | |
14874 | @end smallexample | |
14875 | ||
14876 | You may use this built-in function in either a macro or an inline | |
14877 | function. However, if you use it in an inlined function and pass an | |
14878 | argument of the function as the argument to the built-in, GCC | |
14879 | never returns 1 when you call the inline function with a string constant | |
14880 | or compound literal (@pxref{Compound Literals}) and does not return 1 | |
14881 | when you pass a constant numeric value to the inline function unless you | |
14882 | specify the @option{-O} option. | |
14883 | ||
14884 | You may also use @code{__builtin_constant_p} in initializers for static | |
14885 | data. For instance, you can write | |
14886 | ||
14887 | @smallexample | |
14888 | static const int table[] = @{ | |
14889 | __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, | |
14890 | /* @r{@dots{}} */ | |
14891 | @}; | |
14892 | @end smallexample | |
14893 | ||
14894 | @noindent | |
14895 | This is an acceptable initializer even if @var{EXPRESSION} is not a | |
14896 | constant expression, including the case where | |
14897 | @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be | |
14898 | folded to a constant but @var{EXPRESSION} contains operands that are | |
14899 | not otherwise permitted in a static initializer (for example, | |
14900 | @code{0 && foo ()}). GCC must be more conservative about evaluating the | |
14901 | built-in in this case, because it has no opportunity to perform | |
14902 | optimization. | |
f25efe50 | 14903 | @enddefbuiltin |
d77de738 | 14904 | |
f25efe50 | 14905 | @defbuiltin{bool __builtin_is_constant_evaluated (void)} |
d77de738 ML |
14906 | The @code{__builtin_is_constant_evaluated} function is available only |
14907 | in C++. The built-in is intended to be used by implementations of | |
14908 | the @code{std::is_constant_evaluated} C++ function. Programs should make | |
14909 | use of the latter function rather than invoking the built-in directly. | |
14910 | ||
14911 | The main use case of the built-in is to determine whether a @code{constexpr} | |
14912 | function is being called in a @code{constexpr} context. A call to | |
14913 | the function evaluates to a core constant expression with the value | |
14914 | @code{true} if and only if it occurs within the evaluation of an expression | |
14915 | or conversion that is manifestly constant-evaluated as defined in the C++ | |
14916 | standard. Manifestly constant-evaluated contexts include constant-expressions, | |
14917 | the conditions of @code{constexpr if} statements, constraint-expressions, and | |
14918 | initializers of variables usable in constant expressions. For more details | |
14919 | refer to the latest revision of the C++ standard. | |
f25efe50 | 14920 | @enddefbuiltin |
d77de738 | 14921 | |
f25efe50 | 14922 | @defbuiltin{void __builtin_clear_padding (@var{ptr})} |
d77de738 ML |
14923 | The built-in function @code{__builtin_clear_padding} function clears |
14924 | padding bits inside of the object representation of object pointed by | |
14925 | @var{ptr}, which has to be a pointer. The value representation of the | |
14926 | object is not affected. The type of the object is assumed to be the type | |
14927 | the pointer points to. Inside of a union, the only cleared bits are | |
14928 | bits that are padding bits for all the union members. | |
14929 | ||
14930 | This built-in-function is useful if the padding bits of an object might | |
14931 | have intederminate values and the object representation needs to be | |
14932 | bitwise compared to some other object, for example for atomic operations. | |
14933 | ||
14934 | For C++, @var{ptr} argument type should be pointer to trivially-copyable | |
14935 | type, unless the argument is address of a variable or parameter, because | |
14936 | otherwise it isn't known if the type isn't just a base class whose padding | |
14937 | bits are reused or laid out differently in a derived class. | |
f25efe50 | 14938 | @enddefbuiltin |
d77de738 | 14939 | |
f25efe50 | 14940 | @defbuiltin{@var{type} __builtin_bit_cast (@var{type}, @var{arg})} |
d77de738 ML |
14941 | The @code{__builtin_bit_cast} function is available only |
14942 | in C++. The built-in is intended to be used by implementations of | |
14943 | the @code{std::bit_cast} C++ template function. Programs should make | |
14944 | use of the latter function rather than invoking the built-in directly. | |
14945 | ||
14946 | This built-in function allows reinterpreting the bits of the @var{arg} | |
14947 | argument as if it had type @var{type}. @var{type} and the type of the | |
14948 | @var{arg} argument need to be trivially copyable types with the same size. | |
14949 | When manifestly constant-evaluated, it performs extra diagnostics required | |
14950 | for @code{std::bit_cast} and returns a constant expression if @var{arg} | |
14951 | is a constant expression. For more details | |
14952 | refer to the latest revision of the C++ standard. | |
f25efe50 | 14953 | @enddefbuiltin |
d77de738 | 14954 | |
f25efe50 | 14955 | @defbuiltin{long __builtin_expect (long @var{exp}, long @var{c})} |
d77de738 ML |
14956 | @opindex fprofile-arcs |
14957 | You may use @code{__builtin_expect} to provide the compiler with | |
14958 | branch prediction information. In general, you should prefer to | |
14959 | use actual profile feedback for this (@option{-fprofile-arcs}), as | |
14960 | programmers are notoriously bad at predicting how their programs | |
14961 | actually perform. However, there are applications in which this | |
14962 | data is hard to collect. | |
14963 | ||
14964 | The return value is the value of @var{exp}, which should be an integral | |
14965 | expression. The semantics of the built-in are that it is expected that | |
14966 | @var{exp} == @var{c}. For example: | |
14967 | ||
14968 | @smallexample | |
14969 | if (__builtin_expect (x, 0)) | |
14970 | foo (); | |
14971 | @end smallexample | |
14972 | ||
14973 | @noindent | |
14974 | indicates that we do not expect to call @code{foo}, since | |
14975 | we expect @code{x} to be zero. Since you are limited to integral | |
14976 | expressions for @var{exp}, you should use constructions such as | |
14977 | ||
14978 | @smallexample | |
14979 | if (__builtin_expect (ptr != NULL, 1)) | |
14980 | foo (*ptr); | |
14981 | @end smallexample | |
14982 | ||
14983 | @noindent | |
14984 | when testing pointer or floating-point values. | |
14985 | ||
14986 | For the purposes of branch prediction optimizations, the probability that | |
14987 | a @code{__builtin_expect} expression is @code{true} is controlled by GCC's | |
14988 | @code{builtin-expect-probability} parameter, which defaults to 90%. | |
14989 | ||
14990 | You can also use @code{__builtin_expect_with_probability} to explicitly | |
14991 | assign a probability value to individual expressions. If the built-in | |
14992 | is used in a loop construct, the provided probability will influence | |
14993 | the expected number of iterations made by loop optimizations. | |
f25efe50 | 14994 | @enddefbuiltin |
d77de738 | 14995 | |
f25efe50 | 14996 | @defbuiltin{long __builtin_expect_with_probability} |
d77de738 ML |
14997 | (long @var{exp}, long @var{c}, double @var{probability}) |
14998 | ||
14999 | This function has the same semantics as @code{__builtin_expect}, | |
15000 | but the caller provides the expected probability that @var{exp} == @var{c}. | |
15001 | The last argument, @var{probability}, is a floating-point value in the | |
15002 | range 0.0 to 1.0, inclusive. The @var{probability} argument must be | |
15003 | constant floating-point expression. | |
f25efe50 | 15004 | @enddefbuiltin |
d77de738 | 15005 | |
f25efe50 | 15006 | @defbuiltin{void __builtin_trap (void)} |
d77de738 ML |
15007 | This function causes the program to exit abnormally. GCC implements |
15008 | this function by using a target-dependent mechanism (such as | |
15009 | intentionally executing an illegal instruction) or by calling | |
15010 | @code{abort}. The mechanism used may vary from release to release so | |
15011 | you should not rely on any particular implementation. | |
f25efe50 | 15012 | @enddefbuiltin |
d77de738 | 15013 | |
f25efe50 | 15014 | @defbuiltin{void __builtin_unreachable (void)} |
d77de738 ML |
15015 | If control flow reaches the point of the @code{__builtin_unreachable}, |
15016 | the program is undefined. It is useful in situations where the | |
15017 | compiler cannot deduce the unreachability of the code. | |
15018 | ||
15019 | One such case is immediately following an @code{asm} statement that | |
15020 | either never terminates, or one that transfers control elsewhere | |
15021 | and never returns. In this example, without the | |
15022 | @code{__builtin_unreachable}, GCC issues a warning that control | |
15023 | reaches the end of a non-void function. It also generates code | |
15024 | to return after the @code{asm}. | |
15025 | ||
15026 | @smallexample | |
15027 | int f (int c, int v) | |
15028 | @{ | |
15029 | if (c) | |
15030 | @{ | |
15031 | return v; | |
15032 | @} | |
15033 | else | |
15034 | @{ | |
15035 | asm("jmp error_handler"); | |
15036 | __builtin_unreachable (); | |
15037 | @} | |
15038 | @} | |
15039 | @end smallexample | |
15040 | ||
15041 | @noindent | |
15042 | Because the @code{asm} statement unconditionally transfers control out | |
15043 | of the function, control never reaches the end of the function | |
15044 | body. The @code{__builtin_unreachable} is in fact unreachable and | |
15045 | communicates this fact to the compiler. | |
15046 | ||
15047 | Another use for @code{__builtin_unreachable} is following a call a | |
15048 | function that never returns but that is not declared | |
15049 | @code{__attribute__((noreturn))}, as in this example: | |
15050 | ||
15051 | @smallexample | |
15052 | void function_that_never_returns (void); | |
15053 | ||
15054 | int g (int c) | |
15055 | @{ | |
15056 | if (c) | |
15057 | @{ | |
15058 | return 1; | |
15059 | @} | |
15060 | else | |
15061 | @{ | |
15062 | function_that_never_returns (); | |
15063 | __builtin_unreachable (); | |
15064 | @} | |
15065 | @} | |
15066 | @end smallexample | |
15067 | ||
f25efe50 | 15068 | @enddefbuiltin |
d77de738 | 15069 | |
f25efe50 | 15070 | @defbuiltin{@var{type} __builtin_assoc_barrier (@var{type} @var{expr})} |
d77de738 ML |
15071 | This built-in inhibits re-association of the floating-point expression |
15072 | @var{expr} with expressions consuming the return value of the built-in. The | |
15073 | expression @var{expr} itself can be reordered, and the whole expression | |
15074 | @var{expr} can be reordered with operands after the barrier. The barrier is | |
15075 | only relevant when @code{-fassociative-math} is active, since otherwise | |
15076 | floating-point is not treated as associative. | |
15077 | ||
15078 | @smallexample | |
15079 | float x0 = a + b - b; | |
15080 | float x1 = __builtin_assoc_barrier(a + b) - b; | |
15081 | @end smallexample | |
15082 | ||
15083 | @noindent | |
15084 | means that, with @code{-fassociative-math}, @code{x0} can be optimized to | |
15085 | @code{x0 = a} but @code{x1} cannot. | |
f25efe50 | 15086 | @enddefbuiltin |
d77de738 | 15087 | |
f25efe50 | 15088 | @defbuiltin{{void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)} |
d77de738 ML |
15089 | This function returns its first argument, and allows the compiler |
15090 | to assume that the returned pointer is at least @var{align} bytes | |
15091 | aligned. This built-in can have either two or three arguments, | |
15092 | if it has three, the third argument should have integer type, and | |
15093 | if it is nonzero means misalignment offset. For example: | |
15094 | ||
15095 | @smallexample | |
15096 | void *x = __builtin_assume_aligned (arg, 16); | |
15097 | @end smallexample | |
15098 | ||
15099 | @noindent | |
15100 | means that the compiler can assume @code{x}, set to @code{arg}, is at least | |
15101 | 16-byte aligned, while: | |
15102 | ||
15103 | @smallexample | |
15104 | void *x = __builtin_assume_aligned (arg, 32, 8); | |
15105 | @end smallexample | |
15106 | ||
15107 | @noindent | |
15108 | means that the compiler can assume for @code{x}, set to @code{arg}, that | |
15109 | @code{(char *) x - 8} is 32-byte aligned. | |
f25efe50 | 15110 | @enddefbuiltin |
d77de738 | 15111 | |
f25efe50 | 15112 | @defbuiltin{int __builtin_LINE ()} |
d77de738 ML |
15113 | This function is the equivalent of the preprocessor @code{__LINE__} |
15114 | macro and returns a constant integer expression that evaluates to | |
15115 | the line number of the invocation of the built-in. When used as a C++ | |
15116 | default argument for a function @var{F}, it returns the line number | |
15117 | of the call to @var{F}. | |
f25efe50 | 15118 | @enddefbuiltin |
d77de738 | 15119 | |
f25efe50 | 15120 | @defbuiltin{{const char *} __builtin_FUNCTION ()} |
d77de738 ML |
15121 | This function is the equivalent of the @code{__FUNCTION__} symbol |
15122 | and returns an address constant pointing to the name of the function | |
15123 | from which the built-in was invoked, or the empty string if | |
15124 | the invocation is not at function scope. When used as a C++ default | |
15125 | argument for a function @var{F}, it returns the name of @var{F}'s | |
15126 | caller or the empty string if the call was not made at function | |
15127 | scope. | |
f25efe50 | 15128 | @enddefbuiltin |
d77de738 | 15129 | |
f25efe50 | 15130 | @defbuiltin{{const char *} __builtin_FILE ()} |
d77de738 ML |
15131 | This function is the equivalent of the preprocessor @code{__FILE__} |
15132 | macro and returns an address constant pointing to the file name | |
15133 | containing the invocation of the built-in, or the empty string if | |
15134 | the invocation is not at function scope. When used as a C++ default | |
15135 | argument for a function @var{F}, it returns the file name of the call | |
15136 | to @var{F} or the empty string if the call was not made at function | |
15137 | scope. | |
15138 | ||
15139 | For example, in the following, each call to function @code{foo} will | |
15140 | print a line similar to @code{"file.c:123: foo: message"} with the name | |
15141 | of the file and the line number of the @code{printf} call, the name of | |
15142 | the function @code{foo}, followed by the word @code{message}. | |
15143 | ||
15144 | @smallexample | |
15145 | const char* | |
15146 | function (const char *func = __builtin_FUNCTION ()) | |
15147 | @{ | |
15148 | return func; | |
15149 | @} | |
15150 | ||
15151 | void foo (void) | |
15152 | @{ | |
15153 | printf ("%s:%i: %s: message\n", file (), line (), function ()); | |
15154 | @} | |
15155 | @end smallexample | |
15156 | ||
f25efe50 | 15157 | @enddefbuiltin |
d77de738 | 15158 | |
f25efe50 | 15159 | @defbuiltin{void __builtin___clear_cache (void *@var{begin}, void *@var{end})} |
d77de738 ML |
15160 | This function is used to flush the processor's instruction cache for |
15161 | the region of memory between @var{begin} inclusive and @var{end} | |
15162 | exclusive. Some targets require that the instruction cache be | |
15163 | flushed, after modifying memory containing code, in order to obtain | |
15164 | deterministic behavior. | |
15165 | ||
15166 | If the target does not require instruction cache flushes, | |
15167 | @code{__builtin___clear_cache} has no effect. Otherwise either | |
15168 | instructions are emitted in-line to clear the instruction cache or a | |
15169 | call to the @code{__clear_cache} function in libgcc is made. | |
f25efe50 | 15170 | @enddefbuiltin |
d77de738 | 15171 | |
f25efe50 | 15172 | @defbuiltin{void __builtin_prefetch (const void *@var{addr}, ...)} |
d77de738 ML |
15173 | This function is used to minimize cache-miss latency by moving data into |
15174 | a cache before it is accessed. | |
15175 | You can insert calls to @code{__builtin_prefetch} into code for which | |
15176 | you know addresses of data in memory that is likely to be accessed soon. | |
15177 | If the target supports them, data prefetch instructions are generated. | |
15178 | If the prefetch is done early enough before the access then the data will | |
15179 | be in the cache by the time it is accessed. | |
15180 | ||
15181 | The value of @var{addr} is the address of the memory to prefetch. | |
15182 | There are two optional arguments, @var{rw} and @var{locality}. | |
15183 | The value of @var{rw} is a compile-time constant one or zero; one | |
15184 | means that the prefetch is preparing for a write to the memory address | |
15185 | and zero, the default, means that the prefetch is preparing for a read. | |
15186 | The value @var{locality} must be a compile-time constant integer between | |
15187 | zero and three. A value of zero means that the data has no temporal | |
15188 | locality, so it need not be left in the cache after the access. A value | |
15189 | of three means that the data has a high degree of temporal locality and | |
15190 | should be left in all levels of cache possible. Values of one and two | |
15191 | mean, respectively, a low or moderate degree of temporal locality. The | |
15192 | default is three. | |
15193 | ||
15194 | @smallexample | |
15195 | for (i = 0; i < n; i++) | |
15196 | @{ | |
15197 | a[i] = a[i] + b[i]; | |
15198 | __builtin_prefetch (&a[i+j], 1, 1); | |
15199 | __builtin_prefetch (&b[i+j], 0, 1); | |
15200 | /* @r{@dots{}} */ | |
15201 | @} | |
15202 | @end smallexample | |
15203 | ||
15204 | Data prefetch does not generate faults if @var{addr} is invalid, but | |
15205 | the address expression itself must be valid. For example, a prefetch | |
15206 | of @code{p->next} does not fault if @code{p->next} is not a valid | |
15207 | address, but evaluation faults if @code{p} is not a valid address. | |
15208 | ||
15209 | If the target does not support data prefetch, the address expression | |
15210 | is evaluated if it includes side effects but no other code is generated | |
15211 | and GCC does not issue a warning. | |
f25efe50 | 15212 | @enddefbuiltin |
d77de738 | 15213 | |
f25efe50 | 15214 | @defbuiltin{{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})} |
f5300d28 SP |
15215 | Returns a constant size estimate of an object pointed to by @var{ptr}. |
15216 | @xref{Object Size Checking}, for a detailed description of the function. | |
f25efe50 | 15217 | @enddefbuiltin |
f5300d28 | 15218 | |
f25efe50 | 15219 | @defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} |
f5300d28 SP |
15220 | Similar to @code{__builtin_object_size} except that the return value |
15221 | need not be a constant. @xref{Object Size Checking}, for a detailed | |
15222 | description of the function. | |
f25efe50 | 15223 | @enddefbuiltin |
d77de738 | 15224 | |
53d834a7 JJ |
15225 | @defbuiltin{int __builtin_classify_type (@var{arg})} |
15226 | @defbuiltinx{int __builtin_classify_type (@var{type})} | |
15227 | The @code{__builtin_classify_type} returns a small integer with a category | |
15228 | of @var{arg} argument's type, like void type, integer type, enumeral type, | |
15229 | boolean type, pointer type, reference type, offset type, real type, complex | |
15230 | type, function type, method type, record type, union type, array type, | |
509b470d JJ |
15231 | string type, bit-precise integer type, vector type, etc. When the argument |
15232 | is an expression, for backwards compatibility reason the argument is promoted | |
15233 | like arguments passed to @code{...} in varargs function, so some classes are | |
15234 | never returned in certain languages. Alternatively, the argument of the | |
15235 | built-in function can be a typename, such as the @code{typeof} specifier. | |
53d834a7 JJ |
15236 | |
15237 | @smallexample | |
15238 | int a[2]; | |
15239 | __builtin_classify_type (a) == __builtin_classify_type (int[5]); | |
15240 | __builtin_classify_type (a) == __builtin_classify_type (void*); | |
15241 | __builtin_classify_type (typeof (a)) == __builtin_classify_type (int[5]); | |
15242 | @end smallexample | |
15243 | ||
15244 | The first comparison will never be true, as @var{a} is implicitly converted | |
15245 | to pointer. The last two comparisons will be true as they classify | |
15246 | pointers in the second case and arrays in the last case. | |
15247 | @enddefbuiltin | |
15248 | ||
f25efe50 | 15249 | @defbuiltin{double __builtin_huge_val (void)} |
d77de738 ML |
15250 | Returns a positive infinity, if supported by the floating-point format, |
15251 | else @code{DBL_MAX}. This function is suitable for implementing the | |
15252 | ISO C macro @code{HUGE_VAL}. | |
f25efe50 | 15253 | @enddefbuiltin |
d77de738 | 15254 | |
f25efe50 | 15255 | @defbuiltin{float __builtin_huge_valf (void)} |
d77de738 | 15256 | Similar to @code{__builtin_huge_val}, except the return type is @code{float}. |
f25efe50 | 15257 | @enddefbuiltin |
d77de738 | 15258 | |
f25efe50 | 15259 | @defbuiltin{{long double} __builtin_huge_vall (void)} |
d77de738 ML |
15260 | Similar to @code{__builtin_huge_val}, except the return |
15261 | type is @code{long double}. | |
f25efe50 | 15262 | @enddefbuiltin |
d77de738 | 15263 | |
f25efe50 | 15264 | @defbuiltin{_Float@var{n} __builtin_huge_valf@var{n} (void)} |
d77de738 ML |
15265 | Similar to @code{__builtin_huge_val}, except the return type is |
15266 | @code{_Float@var{n}}. | |
f25efe50 | 15267 | @enddefbuiltin |
d77de738 | 15268 | |
f25efe50 | 15269 | @defbuiltin{_Float@var{n}x __builtin_huge_valf@var{n}x (void)} |
d77de738 ML |
15270 | Similar to @code{__builtin_huge_val}, except the return type is |
15271 | @code{_Float@var{n}x}. | |
f25efe50 | 15272 | @enddefbuiltin |
d77de738 | 15273 | |
f25efe50 | 15274 | @defbuiltin{int __builtin_fpclassify (int, int, int, int, int, ...)} |
d77de738 ML |
15275 | This built-in implements the C99 fpclassify functionality. The first |
15276 | five int arguments should be the target library's notion of the | |
15277 | possible FP classes and are used for return values. They must be | |
15278 | constant values and they must appear in this order: @code{FP_NAN}, | |
15279 | @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and | |
15280 | @code{FP_ZERO}. The ellipsis is for exactly one floating-point value | |
15281 | to classify. GCC treats the last argument as type-generic, which | |
15282 | means it does not do default promotion from float to double. | |
f25efe50 | 15283 | @enddefbuiltin |
d77de738 | 15284 | |
f25efe50 | 15285 | @defbuiltin{double __builtin_inf (void)} |
d77de738 ML |
15286 | Similar to @code{__builtin_huge_val}, except a warning is generated |
15287 | if the target floating-point format does not support infinities. | |
f25efe50 | 15288 | @enddefbuiltin |
d77de738 | 15289 | |
f25efe50 | 15290 | @defbuiltin{_Decimal32 __builtin_infd32 (void)} |
d77de738 | 15291 | Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. |
f25efe50 | 15292 | @enddefbuiltin |
d77de738 | 15293 | |
f25efe50 | 15294 | @defbuiltin{_Decimal64 __builtin_infd64 (void)} |
d77de738 | 15295 | Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. |
f25efe50 | 15296 | @enddefbuiltin |
d77de738 | 15297 | |
f25efe50 | 15298 | @defbuiltin{_Decimal128 __builtin_infd128 (void)} |
d77de738 | 15299 | Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. |
f25efe50 | 15300 | @enddefbuiltin |
d77de738 | 15301 | |
f25efe50 | 15302 | @defbuiltin{float __builtin_inff (void)} |
d77de738 ML |
15303 | Similar to @code{__builtin_inf}, except the return type is @code{float}. |
15304 | This function is suitable for implementing the ISO C99 macro @code{INFINITY}. | |
f25efe50 | 15305 | @enddefbuiltin |
d77de738 | 15306 | |
f25efe50 | 15307 | @defbuiltin{{long double} __builtin_infl (void)} |
d77de738 ML |
15308 | Similar to @code{__builtin_inf}, except the return |
15309 | type is @code{long double}. | |
f25efe50 | 15310 | @enddefbuiltin |
d77de738 | 15311 | |
f25efe50 | 15312 | @defbuiltin{_Float@var{n} __builtin_inff@var{n} (void)} |
d77de738 ML |
15313 | Similar to @code{__builtin_inf}, except the return |
15314 | type is @code{_Float@var{n}}. | |
f25efe50 | 15315 | @enddefbuiltin |
d77de738 | 15316 | |
f25efe50 | 15317 | @defbuiltin{_Float@var{n} __builtin_inff@var{n}x (void)} |
d77de738 ML |
15318 | Similar to @code{__builtin_inf}, except the return |
15319 | type is @code{_Float@var{n}x}. | |
f25efe50 | 15320 | @enddefbuiltin |
d77de738 | 15321 | |
f25efe50 | 15322 | @defbuiltin{int __builtin_isinf_sign (...)} |
d77de738 ML |
15323 | Similar to @code{isinf}, except the return value is -1 for |
15324 | an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. | |
15325 | Note while the parameter list is an | |
15326 | ellipsis, this function only accepts exactly one floating-point | |
15327 | argument. GCC treats this parameter as type-generic, which means it | |
15328 | does not do default promotion from float to double. | |
f25efe50 | 15329 | @enddefbuiltin |
d77de738 | 15330 | |
23795106 | 15331 | @defbuiltin{double __builtin_nan (const char *@var{str})} |
d77de738 ML |
15332 | This is an implementation of the ISO C99 function @code{nan}. |
15333 | ||
15334 | Since ISO C99 defines this function in terms of @code{strtod}, which we | |
15335 | do not implement, a description of the parsing is in order. The string | |
15336 | is parsed as by @code{strtol}; that is, the base is recognized by | |
15337 | leading @samp{0} or @samp{0x} prefixes. The number parsed is placed | |
15338 | in the significand such that the least significant bit of the number | |
15339 | is at the least significant bit of the significand. The number is | |
15340 | truncated to fit the significand field provided. The significand is | |
15341 | forced to be a quiet NaN@. | |
15342 | ||
15343 | This function, if given a string literal all of which would have been | |
15344 | consumed by @code{strtol}, is evaluated early enough that it is considered a | |
15345 | compile-time constant. | |
f25efe50 | 15346 | @enddefbuiltin |
d77de738 | 15347 | |
23795106 | 15348 | @defbuiltin{_Decimal32 __builtin_nand32 (const char *@var{str})} |
d77de738 | 15349 | Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. |
f25efe50 | 15350 | @enddefbuiltin |
d77de738 | 15351 | |
23795106 | 15352 | @defbuiltin{_Decimal64 __builtin_nand64 (const char *@var{str})} |
d77de738 | 15353 | Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. |
f25efe50 | 15354 | @enddefbuiltin |
d77de738 | 15355 | |
23795106 | 15356 | @defbuiltin{_Decimal128 __builtin_nand128 (const char *@var{str})} |
d77de738 | 15357 | Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. |
f25efe50 | 15358 | @enddefbuiltin |
d77de738 | 15359 | |
23795106 | 15360 | @defbuiltin{float __builtin_nanf (const char *@var{str})} |
d77de738 | 15361 | Similar to @code{__builtin_nan}, except the return type is @code{float}. |
f25efe50 | 15362 | @enddefbuiltin |
d77de738 | 15363 | |
23795106 | 15364 | @defbuiltin{{long double} __builtin_nanl (const char *@var{str})} |
d77de738 | 15365 | Similar to @code{__builtin_nan}, except the return type is @code{long double}. |
f25efe50 | 15366 | @enddefbuiltin |
d77de738 | 15367 | |
23795106 | 15368 | @defbuiltin{_Float@var{n} __builtin_nanf@var{n} (const char *@var{str})} |
d77de738 ML |
15369 | Similar to @code{__builtin_nan}, except the return type is |
15370 | @code{_Float@var{n}}. | |
f25efe50 | 15371 | @enddefbuiltin |
d77de738 | 15372 | |
23795106 | 15373 | @defbuiltin{_Float@var{n}x __builtin_nanf@var{n}x (const char *@var{str})} |
d77de738 ML |
15374 | Similar to @code{__builtin_nan}, except the return type is |
15375 | @code{_Float@var{n}x}. | |
f25efe50 | 15376 | @enddefbuiltin |
d77de738 | 15377 | |
23795106 | 15378 | @defbuiltin{double __builtin_nans (const char *@var{str})} |
d77de738 ML |
15379 | Similar to @code{__builtin_nan}, except the significand is forced |
15380 | to be a signaling NaN@. The @code{nans} function is proposed by | |
d1bf1c97 | 15381 | @uref{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. |
f25efe50 | 15382 | @enddefbuiltin |
d77de738 | 15383 | |
23795106 | 15384 | @defbuiltin{_Decimal32 __builtin_nansd32 (const char *@var{str})} |
d77de738 | 15385 | Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}. |
f25efe50 | 15386 | @enddefbuiltin |
d77de738 | 15387 | |
23795106 | 15388 | @defbuiltin{_Decimal64 __builtin_nansd64 (const char *@var{str})} |
d77de738 | 15389 | Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}. |
f25efe50 | 15390 | @enddefbuiltin |
d77de738 | 15391 | |
23795106 | 15392 | @defbuiltin{_Decimal128 __builtin_nansd128 (const char *@var{str})} |
d77de738 | 15393 | Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}. |
f25efe50 | 15394 | @enddefbuiltin |
d77de738 | 15395 | |
23795106 | 15396 | @defbuiltin{float __builtin_nansf (const char *@var{str})} |
d77de738 | 15397 | Similar to @code{__builtin_nans}, except the return type is @code{float}. |
f25efe50 | 15398 | @enddefbuiltin |
d77de738 | 15399 | |
23795106 | 15400 | @defbuiltin{{long double} __builtin_nansl (const char *@var{str})} |
d77de738 | 15401 | Similar to @code{__builtin_nans}, except the return type is @code{long double}. |
f25efe50 | 15402 | @enddefbuiltin |
d77de738 | 15403 | |
23795106 | 15404 | @defbuiltin{_Float@var{n} __builtin_nansf@var{n} (const char *@var{str})} |
d77de738 ML |
15405 | Similar to @code{__builtin_nans}, except the return type is |
15406 | @code{_Float@var{n}}. | |
f25efe50 | 15407 | @enddefbuiltin |
d77de738 | 15408 | |
23795106 | 15409 | @defbuiltin{_Float@var{n}x __builtin_nansf@var{n}x (const char *@var{str})} |
d77de738 ML |
15410 | Similar to @code{__builtin_nans}, except the return type is |
15411 | @code{_Float@var{n}x}. | |
f25efe50 | 15412 | @enddefbuiltin |
d77de738 | 15413 | |
f25efe50 | 15414 | @defbuiltin{int __builtin_issignaling (...)} |
d77de738 ML |
15415 | Return non-zero if the argument is a signaling NaN and zero otherwise. |
15416 | Note while the parameter list is an | |
15417 | ellipsis, this function only accepts exactly one floating-point | |
15418 | argument. GCC treats this parameter as type-generic, which means it | |
15419 | does not do default promotion from float to double. | |
15420 | This built-in function can work even without the non-default | |
15421 | @code{-fsignaling-nans} option, although if a signaling NaN is computed, | |
15422 | stored or passed as argument to some function other than this built-in | |
15423 | in the current translation unit, it is safer to use @code{-fsignaling-nans}. | |
15424 | With @code{-ffinite-math-only} option this built-in function will always | |
15425 | return 0. | |
f25efe50 | 15426 | @enddefbuiltin |
d77de738 | 15427 | |
23795106 | 15428 | @defbuiltin{int __builtin_ffs (int @var{x})} |
d77de738 ML |
15429 | Returns one plus the index of the least significant 1-bit of @var{x}, or |
15430 | if @var{x} is zero, returns zero. | |
f25efe50 | 15431 | @enddefbuiltin |
d77de738 | 15432 | |
23795106 | 15433 | @defbuiltin{int __builtin_clz (unsigned int @var{x})} |
d77de738 ML |
15434 | Returns the number of leading 0-bits in @var{x}, starting at the most |
15435 | significant bit position. If @var{x} is 0, the result is undefined. | |
f25efe50 | 15436 | @enddefbuiltin |
d77de738 | 15437 | |
23795106 | 15438 | @defbuiltin{int __builtin_ctz (unsigned int @var{x})} |
d77de738 ML |
15439 | Returns the number of trailing 0-bits in @var{x}, starting at the least |
15440 | significant bit position. If @var{x} is 0, the result is undefined. | |
f25efe50 | 15441 | @enddefbuiltin |
d77de738 | 15442 | |
23795106 | 15443 | @defbuiltin{int __builtin_clrsb (int @var{x})} |
d77de738 ML |
15444 | Returns the number of leading redundant sign bits in @var{x}, i.e.@: the |
15445 | number of bits following the most significant bit that are identical | |
15446 | to it. There are no special cases for 0 or other values. | |
f25efe50 | 15447 | @enddefbuiltin |
d77de738 | 15448 | |
23795106 | 15449 | @defbuiltin{int __builtin_popcount (unsigned int @var{x})} |
d77de738 | 15450 | Returns the number of 1-bits in @var{x}. |
f25efe50 | 15451 | @enddefbuiltin |
d77de738 | 15452 | |
23795106 | 15453 | @defbuiltin{int __builtin_parity (unsigned int @var{x})} |
d77de738 ML |
15454 | Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} |
15455 | modulo 2. | |
f25efe50 | 15456 | @enddefbuiltin |
d77de738 | 15457 | |
f25efe50 | 15458 | @defbuiltin{int __builtin_ffsl (long)} |
d77de738 ML |
15459 | Similar to @code{__builtin_ffs}, except the argument type is |
15460 | @code{long}. | |
f25efe50 | 15461 | @enddefbuiltin |
d77de738 | 15462 | |
f25efe50 | 15463 | @defbuiltin{int __builtin_clzl (unsigned long)} |
d77de738 ML |
15464 | Similar to @code{__builtin_clz}, except the argument type is |
15465 | @code{unsigned long}. | |
f25efe50 | 15466 | @enddefbuiltin |
d77de738 | 15467 | |
f25efe50 | 15468 | @defbuiltin{int __builtin_ctzl (unsigned long)} |
d77de738 ML |
15469 | Similar to @code{__builtin_ctz}, except the argument type is |
15470 | @code{unsigned long}. | |
f25efe50 | 15471 | @enddefbuiltin |
d77de738 | 15472 | |
f25efe50 | 15473 | @defbuiltin{int __builtin_clrsbl (long)} |
d77de738 ML |
15474 | Similar to @code{__builtin_clrsb}, except the argument type is |
15475 | @code{long}. | |
f25efe50 | 15476 | @enddefbuiltin |
d77de738 | 15477 | |
f25efe50 | 15478 | @defbuiltin{int __builtin_popcountl (unsigned long)} |
d77de738 ML |
15479 | Similar to @code{__builtin_popcount}, except the argument type is |
15480 | @code{unsigned long}. | |
f25efe50 | 15481 | @enddefbuiltin |
d77de738 | 15482 | |
f25efe50 | 15483 | @defbuiltin{int __builtin_parityl (unsigned long)} |
d77de738 ML |
15484 | Similar to @code{__builtin_parity}, except the argument type is |
15485 | @code{unsigned long}. | |
f25efe50 | 15486 | @enddefbuiltin |
d77de738 | 15487 | |
f25efe50 | 15488 | @defbuiltin{int __builtin_ffsll (long long)} |
d77de738 ML |
15489 | Similar to @code{__builtin_ffs}, except the argument type is |
15490 | @code{long long}. | |
f25efe50 | 15491 | @enddefbuiltin |
d77de738 | 15492 | |
f25efe50 | 15493 | @defbuiltin{int __builtin_clzll (unsigned long long)} |
d77de738 ML |
15494 | Similar to @code{__builtin_clz}, except the argument type is |
15495 | @code{unsigned long long}. | |
f25efe50 | 15496 | @enddefbuiltin |
d77de738 | 15497 | |
f25efe50 | 15498 | @defbuiltin{int __builtin_ctzll (unsigned long long)} |
d77de738 ML |
15499 | Similar to @code{__builtin_ctz}, except the argument type is |
15500 | @code{unsigned long long}. | |
f25efe50 | 15501 | @enddefbuiltin |
d77de738 | 15502 | |
f25efe50 | 15503 | @defbuiltin{int __builtin_clrsbll (long long)} |
d77de738 ML |
15504 | Similar to @code{__builtin_clrsb}, except the argument type is |
15505 | @code{long long}. | |
f25efe50 | 15506 | @enddefbuiltin |
d77de738 | 15507 | |
f25efe50 | 15508 | @defbuiltin{int __builtin_popcountll (unsigned long long)} |
d77de738 ML |
15509 | Similar to @code{__builtin_popcount}, except the argument type is |
15510 | @code{unsigned long long}. | |
f25efe50 | 15511 | @enddefbuiltin |
d77de738 | 15512 | |
f25efe50 | 15513 | @defbuiltin{int __builtin_parityll (unsigned long long)} |
d77de738 ML |
15514 | Similar to @code{__builtin_parity}, except the argument type is |
15515 | @code{unsigned long long}. | |
f25efe50 | 15516 | @enddefbuiltin |
d77de738 | 15517 | |
7383cb56 JJ |
15518 | @defbuiltin{int __builtin_ffsg (...)} |
15519 | Similar to @code{__builtin_ffs}, except the argument is type-generic | |
15520 | signed integer (standard, extended or bit-precise). No integral argument | |
15521 | promotions are performed on the argument. | |
15522 | @enddefbuiltin | |
15523 | ||
15524 | @defbuiltin{int __builtin_clzg (...)} | |
15525 | Similar to @code{__builtin_clz}, except the argument is type-generic | |
15526 | unsigned integer (standard, extended or bit-precise) and there is | |
15527 | optional second argument with int type. No integral argument promotions | |
15528 | are performed on the first argument. If two arguments are specified, | |
15529 | and first argument is 0, the result is the second argument. If only | |
15530 | one argument is specified and it is 0, the result is undefined. | |
15531 | @enddefbuiltin | |
15532 | ||
15533 | @defbuiltin{int __builtin_ctzg (...)} | |
15534 | Similar to @code{__builtin_ctz}, except the argument is type-generic | |
15535 | unsigned integer (standard, extended or bit-precise) and there is | |
15536 | optional second argument with int type. No integral argument promotions | |
15537 | are performed on the first argument. If two arguments are specified, | |
15538 | and first argument is 0, the result is the second argument. If only | |
15539 | one argument is specified and it is 0, the result is undefined. | |
15540 | @enddefbuiltin | |
15541 | ||
15542 | @defbuiltin{int __builtin_clrsbg (...)} | |
15543 | Similar to @code{__builtin_clrsb}, except the argument is type-generic | |
15544 | signed integer (standard, extended or bit-precise). No integral argument | |
15545 | promotions are performed on the argument. | |
15546 | @enddefbuiltin | |
15547 | ||
15548 | @defbuiltin{int __builtin_popcountg (...)} | |
15549 | Similar to @code{__builtin_popcount}, except the argument is type-generic | |
15550 | unsigned integer (standard, extended or bit-precise). No integral argument | |
15551 | promotions are performed on the argument. | |
15552 | @enddefbuiltin | |
15553 | ||
15554 | @defbuiltin{int __builtin_parityg (...)} | |
15555 | Similar to @code{__builtin_parity}, except the argument is type-generic | |
15556 | unsigned integer (standard, extended or bit-precise). No integral argument | |
15557 | promotions are performed on the argument. | |
15558 | @enddefbuiltin | |
15559 | ||
03c7149d JJ |
15560 | @defbuiltin{@var{type} __builtin_stdc_bit_ceil (@var{type} @var{arg})} |
15561 | The @code{__builtin_stdc_bit_ceil} function is available only | |
15562 | in C. It is type-generic, the argument can be any unsigned integer | |
15563 | (standard, extended or bit-precise). No integral argument promotions are | |
15564 | performed on the argument. It is equivalent to | |
15565 | @code{@var{arg} <= 1 ? (@var{type}) 1 | |
15566 | : (@var{type}) 2 << (@var{prec} - 1 - __builtin_clzg ((@var{type}) (@var{arg} - 1)))} | |
15567 | where @var{prec} is bit width of @var{type}, except that side-effects | |
15568 | in @var{arg} are evaluated just once. | |
15569 | @enddefbuiltin | |
15570 | ||
15571 | @defbuiltin{@var{type} __builtin_stdc_bit_floor (@var{type} @var{arg})} | |
15572 | The @code{__builtin_stdc_bit_floor} function is available only | |
15573 | in C. It is type-generic, the argument can be any unsigned integer | |
15574 | (standard, extended or bit-precise). No integral argument promotions are | |
15575 | performed on the argument. It is equivalent to | |
15576 | @code{@var{arg} == 0 ? (@var{type}) 0 | |
15577 | : (@var{type}) 1 << (@var{prec} - 1 - __builtin_clzg (@var{arg}))} | |
15578 | where @var{prec} is bit width of @var{type}, except that side-effects | |
15579 | in @var{arg} are evaluated just once. | |
15580 | @enddefbuiltin | |
15581 | ||
ff99671a | 15582 | @defbuiltin{{unsigned int} __builtin_stdc_bit_width (@var{type} @var{arg})} |
03c7149d JJ |
15583 | The @code{__builtin_stdc_bit_width} function is available only |
15584 | in C. It is type-generic, the argument can be any unsigned integer | |
15585 | (standard, extended or bit-precise). No integral argument promotions are | |
15586 | performed on the argument. It is equivalent to | |
15587 | @code{(unsigned int) (@var{prec} - __builtin_clzg (@var{arg}, @var{prec}))} | |
15588 | where @var{prec} is bit width of @var{type}. | |
15589 | @enddefbuiltin | |
15590 | ||
ff99671a | 15591 | @defbuiltin{{unsigned int} __builtin_stdc_count_ones (@var{type} @var{arg})} |
03c7149d JJ |
15592 | The @code{__builtin_stdc_count_ones} function is available only |
15593 | in C. It is type-generic, the argument can be any unsigned integer | |
15594 | (standard, extended or bit-precise). No integral argument promotions are | |
15595 | performed on the argument. It is equivalent to | |
15596 | @code{(unsigned int) __builtin_popcountg (@var{arg})} | |
15597 | @enddefbuiltin | |
15598 | ||
ff99671a | 15599 | @defbuiltin{{unsigned int} __builtin_stdc_count_zeros (@var{type} @var{arg})} |
03c7149d JJ |
15600 | The @code{__builtin_stdc_count_zeros} function is available only |
15601 | in C. It is type-generic, the argument can be any unsigned integer | |
15602 | (standard, extended or bit-precise). No integral argument promotions are | |
15603 | performed on the argument. It is equivalent to | |
15604 | @code{(unsigned int) __builtin_popcountg ((@var{type}) ~@var{arg})} | |
15605 | @enddefbuiltin | |
15606 | ||
ff99671a | 15607 | @defbuiltin{{unsigned int} __builtin_stdc_first_leading_one (@var{type} @var{arg})} |
03c7149d JJ |
15608 | The @code{__builtin_stdc_first_leading_one} function is available only |
15609 | in C. It is type-generic, the argument can be any unsigned integer | |
15610 | (standard, extended or bit-precise). No integral argument promotions are | |
15611 | performed on the argument. It is equivalent to | |
15612 | @code{__builtin_clzg (@var{arg}, -1) + 1U} | |
15613 | @enddefbuiltin | |
15614 | ||
ff99671a | 15615 | @defbuiltin{{unsigned int} __builtin_stdc_first_leading_zero (@var{type} @var{arg})} |
03c7149d JJ |
15616 | The @code{__builtin_stdc_first_leading_zero} function is available only |
15617 | in C. It is type-generic, the argument can be any unsigned integer | |
15618 | (standard, extended or bit-precise). No integral argument promotions are | |
15619 | performed on the argument. It is equivalent to | |
15620 | @code{__builtin_clzg ((@var{type}) ~@var{arg}, -1) + 1U} | |
15621 | @enddefbuiltin | |
15622 | ||
ff99671a | 15623 | @defbuiltin{{unsigned int} __builtin_stdc_first_trailing_one (@var{type} @var{arg})} |
03c7149d JJ |
15624 | The @code{__builtin_stdc_first_trailing_one} function is available only |
15625 | in C. It is type-generic, the argument can be any unsigned integer | |
15626 | (standard, extended or bit-precise). No integral argument promotions are | |
15627 | performed on the argument. It is equivalent to | |
15628 | @code{__builtin_ctzg (@var{arg}, -1) + 1U} | |
15629 | @enddefbuiltin | |
15630 | ||
ff99671a | 15631 | @defbuiltin{{unsigned int} __builtin_stdc_first_trailing_zero (@var{type} @var{arg})} |
03c7149d JJ |
15632 | The @code{__builtin_stdc_first_trailing_zero} function is available only |
15633 | in C. It is type-generic, the argument can be any unsigned integer | |
15634 | (standard, extended or bit-precise). No integral argument promotions are | |
15635 | performed on the argument. It is equivalent to | |
15636 | @code{__builtin_ctzg ((@var{type}) ~@var{arg}, -1) + 1U} | |
15637 | @enddefbuiltin | |
15638 | ||
ff99671a | 15639 | @defbuiltin{{unsigned int} __builtin_stdc_has_single_bit (@var{type} @var{arg})} |
03c7149d JJ |
15640 | The @code{__builtin_stdc_has_single_bit} function is available only |
15641 | in C. It is type-generic, the argument can be any unsigned integer | |
15642 | (standard, extended or bit-precise). No integral argument promotions are | |
15643 | performed on the argument. It is equivalent to | |
15644 | @code{(_Bool) (__builtin_popcountg (@var{arg}) == 1)} | |
15645 | @enddefbuiltin | |
15646 | ||
ff99671a | 15647 | @defbuiltin{{unsigned int} __builtin_stdc_leading_ones (@var{type} @var{arg})} |
03c7149d JJ |
15648 | The @code{__builtin_stdc_leading_ones} function is available only |
15649 | in C. It is type-generic, the argument can be any unsigned integer | |
15650 | (standard, extended or bit-precise). No integral argument promotions are | |
15651 | performed on the argument. It is equivalent to | |
15652 | @code{(unsigned int) __builtin_clzg ((@var{type}) ~@var{arg}, @var{prec})} | |
15653 | @enddefbuiltin | |
15654 | ||
ff99671a | 15655 | @defbuiltin{{unsigned int} __builtin_stdc_leading_zeros (@var{type} @var{arg})} |
03c7149d JJ |
15656 | The @code{__builtin_stdc_leading_zeros} function is available only |
15657 | in C. It is type-generic, the argument can be any unsigned integer | |
15658 | (standard, extended or bit-precise). No integral argument promotions are | |
15659 | performed on the argument. It is equivalent to | |
15660 | @code{(unsigned int) __builtin_clzg (@var{arg}, @var{prec})} | |
15661 | @enddefbuiltin | |
15662 | ||
ff99671a | 15663 | @defbuiltin{{unsigned int} __builtin_stdc_trailing_ones (@var{type} @var{arg})} |
03c7149d JJ |
15664 | The @code{__builtin_stdc_trailing_ones} function is available only |
15665 | in C. It is type-generic, the argument can be any unsigned integer | |
15666 | (standard, extended or bit-precise). No integral argument promotions are | |
15667 | performed on the argument. It is equivalent to | |
15668 | @code{(unsigned int) __builtin_ctzg ((@var{type}) ~@var{arg}, @var{prec})} | |
15669 | @enddefbuiltin | |
15670 | ||
ff99671a | 15671 | @defbuiltin{{unsigned int} __builtin_stdc_trailing_zeros (@var{type} @var{arg})} |
03c7149d JJ |
15672 | The @code{__builtin_stdc_trailing_zeros} function is available only |
15673 | in C. It is type-generic, the argument can be any unsigned integer | |
15674 | (standard, extended or bit-precise). No integral argument promotions are | |
15675 | performed on the argument. It is equivalent to | |
15676 | @code{(unsigned int) __builtin_ctzg (@var{arg}, @var{prec})} | |
15677 | @enddefbuiltin | |
15678 | ||
f25efe50 AA |
15679 | @defbuiltin{double __builtin_powi (double, int)} |
15680 | @defbuiltinx{float __builtin_powif (float, int)} | |
15681 | @defbuiltinx{{long double} __builtin_powil (long double, int)} | |
d77de738 ML |
15682 | Returns the first argument raised to the power of the second. Unlike the |
15683 | @code{pow} function no guarantees about precision and rounding are made. | |
f25efe50 | 15684 | @enddefbuiltin |
d77de738 | 15685 | |
23795106 | 15686 | @defbuiltin{uint16_t __builtin_bswap16 (uint16_t @var{x})} |
d77de738 ML |
15687 | Returns @var{x} with the order of the bytes reversed; for example, |
15688 | @code{0xaabb} becomes @code{0xbbaa}. Byte here always means | |
15689 | exactly 8 bits. | |
f25efe50 | 15690 | @enddefbuiltin |
d77de738 | 15691 | |
23795106 | 15692 | @defbuiltin{uint32_t __builtin_bswap32 (uint32_t @var{x})} |
d77de738 ML |
15693 | Similar to @code{__builtin_bswap16}, except the argument and return types |
15694 | are 32-bit. | |
f25efe50 | 15695 | @enddefbuiltin |
d77de738 | 15696 | |
23795106 | 15697 | @defbuiltin{uint64_t __builtin_bswap64 (uint64_t @var{x})} |
d77de738 ML |
15698 | Similar to @code{__builtin_bswap32}, except the argument and return types |
15699 | are 64-bit. | |
f25efe50 | 15700 | @enddefbuiltin |
d77de738 | 15701 | |
23795106 | 15702 | @defbuiltin{uint128_t __builtin_bswap128 (uint128_t @var{x})} |
d77de738 ML |
15703 | Similar to @code{__builtin_bswap64}, except the argument and return types |
15704 | are 128-bit. Only supported on targets when 128-bit types are supported. | |
f25efe50 | 15705 | @enddefbuiltin |
d77de738 ML |
15706 | |
15707 | ||
23795106 | 15708 | @defbuiltin{Pmode __builtin_extend_pointer (void * @var{x})} |
d77de738 ML |
15709 | On targets where the user visible pointer size is smaller than the size |
15710 | of an actual hardware address this function returns the extended user | |
15711 | pointer. Targets where this is true included ILP32 mode on x86_64 or | |
15712 | Aarch64. This function is mainly useful when writing inline assembly | |
15713 | code. | |
f25efe50 | 15714 | @enddefbuiltin |
d77de738 | 15715 | |
23795106 | 15716 | @defbuiltin{int __builtin_goacc_parlevel_id (int @var{x})} |
d77de738 ML |
15717 | Returns the openacc gang, worker or vector id depending on whether @var{x} is |
15718 | 0, 1 or 2. | |
f25efe50 | 15719 | @enddefbuiltin |
d77de738 | 15720 | |
23795106 | 15721 | @defbuiltin{int __builtin_goacc_parlevel_size (int @var{x})} |
d77de738 ML |
15722 | Returns the openacc gang, worker or vector size depending on whether @var{x} is |
15723 | 0, 1 or 2. | |
f25efe50 | 15724 | @enddefbuiltin |
d77de738 ML |
15725 | |
15726 | @node Target Builtins | |
15727 | @section Built-in Functions Specific to Particular Target Machines | |
15728 | ||
15729 | On some target machines, GCC supports many built-in functions specific | |
15730 | to those machines. Generally these generate calls to specific machine | |
15731 | instructions, but allow the compiler to schedule those calls. | |
15732 | ||
15733 | @menu | |
15734 | * AArch64 Built-in Functions:: | |
15735 | * Alpha Built-in Functions:: | |
15736 | * Altera Nios II Built-in Functions:: | |
15737 | * ARC Built-in Functions:: | |
15738 | * ARC SIMD Built-in Functions:: | |
15739 | * ARM iWMMXt Built-in Functions:: | |
15740 | * ARM C Language Extensions (ACLE):: | |
15741 | * ARM Floating Point Status and Control Intrinsics:: | |
15742 | * ARM ARMv8-M Security Extensions:: | |
15743 | * AVR Built-in Functions:: | |
15744 | * Blackfin Built-in Functions:: | |
15745 | * BPF Built-in Functions:: | |
15746 | * FR-V Built-in Functions:: | |
5015cdf3 | 15747 | * LoongArch Base Built-in Functions:: |
1f48786d | 15748 | * LoongArch SX Vector Intrinsics:: |
15749 | * LoongArch ASX Vector Intrinsics:: | |
d77de738 ML |
15750 | * MIPS DSP Built-in Functions:: |
15751 | * MIPS Paired-Single Support:: | |
15752 | * MIPS Loongson Built-in Functions:: | |
15753 | * MIPS SIMD Architecture (MSA) Support:: | |
15754 | * Other MIPS Built-in Functions:: | |
15755 | * MSP430 Built-in Functions:: | |
15756 | * NDS32 Built-in Functions:: | |
c09471fb | 15757 | * Nvidia PTX Built-in Functions:: |
d77de738 ML |
15758 | * Basic PowerPC Built-in Functions:: |
15759 | * PowerPC AltiVec/VSX Built-in Functions:: | |
15760 | * PowerPC Hardware Transactional Memory Built-in Functions:: | |
15761 | * PowerPC Atomic Memory Operation Functions:: | |
15762 | * PowerPC Matrix-Multiply Assist Built-in Functions:: | |
15763 | * PRU Built-in Functions:: | |
15764 | * RISC-V Built-in Functions:: | |
14c1a8df | 15765 | * RISC-V Vector Intrinsics:: |
400efddd | 15766 | * CORE-V Built-in Functions:: |
d77de738 ML |
15767 | * RX Built-in Functions:: |
15768 | * S/390 System z Built-in Functions:: | |
15769 | * SH Built-in Functions:: | |
15770 | * SPARC VIS Built-in Functions:: | |
15771 | * TI C6X Built-in Functions:: | |
15772 | * x86 Built-in Functions:: | |
15773 | * x86 transactional memory intrinsics:: | |
15774 | * x86 control-flow protection intrinsics:: | |
15775 | @end menu | |
15776 | ||
15777 | @node AArch64 Built-in Functions | |
15778 | @subsection AArch64 Built-in Functions | |
15779 | ||
15780 | These built-in functions are available for the AArch64 family of | |
15781 | processors. | |
15782 | @smallexample | |
15783 | unsigned int __builtin_aarch64_get_fpcr (); | |
15784 | void __builtin_aarch64_set_fpcr (unsigned int); | |
15785 | unsigned int __builtin_aarch64_get_fpsr (); | |
15786 | void __builtin_aarch64_set_fpsr (unsigned int); | |
15787 | ||
15788 | unsigned long long __builtin_aarch64_get_fpcr64 (); | |
15789 | void __builtin_aarch64_set_fpcr64 (unsigned long long); | |
15790 | unsigned long long __builtin_aarch64_get_fpsr64 (); | |
15791 | void __builtin_aarch64_set_fpsr64 (unsigned long long); | |
15792 | @end smallexample | |
15793 | ||
15794 | @node Alpha Built-in Functions | |
15795 | @subsection Alpha Built-in Functions | |
15796 | ||
15797 | These built-in functions are available for the Alpha family of | |
15798 | processors, depending on the command-line switches used. | |
15799 | ||
15800 | The following built-in functions are always available. They | |
15801 | all generate the machine instruction that is part of the name. | |
15802 | ||
15803 | @smallexample | |
15804 | long __builtin_alpha_implver (void); | |
15805 | long __builtin_alpha_rpcc (void); | |
15806 | long __builtin_alpha_amask (long); | |
15807 | long __builtin_alpha_cmpbge (long, long); | |
15808 | long __builtin_alpha_extbl (long, long); | |
15809 | long __builtin_alpha_extwl (long, long); | |
15810 | long __builtin_alpha_extll (long, long); | |
15811 | long __builtin_alpha_extql (long, long); | |
15812 | long __builtin_alpha_extwh (long, long); | |
15813 | long __builtin_alpha_extlh (long, long); | |
15814 | long __builtin_alpha_extqh (long, long); | |
15815 | long __builtin_alpha_insbl (long, long); | |
15816 | long __builtin_alpha_inswl (long, long); | |
15817 | long __builtin_alpha_insll (long, long); | |
15818 | long __builtin_alpha_insql (long, long); | |
15819 | long __builtin_alpha_inswh (long, long); | |
15820 | long __builtin_alpha_inslh (long, long); | |
15821 | long __builtin_alpha_insqh (long, long); | |
15822 | long __builtin_alpha_mskbl (long, long); | |
15823 | long __builtin_alpha_mskwl (long, long); | |
15824 | long __builtin_alpha_mskll (long, long); | |
15825 | long __builtin_alpha_mskql (long, long); | |
15826 | long __builtin_alpha_mskwh (long, long); | |
15827 | long __builtin_alpha_msklh (long, long); | |
15828 | long __builtin_alpha_mskqh (long, long); | |
15829 | long __builtin_alpha_umulh (long, long); | |
15830 | long __builtin_alpha_zap (long, long); | |
15831 | long __builtin_alpha_zapnot (long, long); | |
15832 | @end smallexample | |
15833 | ||
15834 | The following built-in functions are always with @option{-mmax} | |
15835 | or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or | |
15836 | later. They all generate the machine instruction that is part | |
15837 | of the name. | |
15838 | ||
15839 | @smallexample | |
15840 | long __builtin_alpha_pklb (long); | |
15841 | long __builtin_alpha_pkwb (long); | |
15842 | long __builtin_alpha_unpkbl (long); | |
15843 | long __builtin_alpha_unpkbw (long); | |
15844 | long __builtin_alpha_minub8 (long, long); | |
15845 | long __builtin_alpha_minsb8 (long, long); | |
15846 | long __builtin_alpha_minuw4 (long, long); | |
15847 | long __builtin_alpha_minsw4 (long, long); | |
15848 | long __builtin_alpha_maxub8 (long, long); | |
15849 | long __builtin_alpha_maxsb8 (long, long); | |
15850 | long __builtin_alpha_maxuw4 (long, long); | |
15851 | long __builtin_alpha_maxsw4 (long, long); | |
15852 | long __builtin_alpha_perr (long, long); | |
15853 | @end smallexample | |
15854 | ||
15855 | The following built-in functions are always with @option{-mcix} | |
15856 | or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or | |
15857 | later. They all generate the machine instruction that is part | |
15858 | of the name. | |
15859 | ||
15860 | @smallexample | |
15861 | long __builtin_alpha_cttz (long); | |
15862 | long __builtin_alpha_ctlz (long); | |
15863 | long __builtin_alpha_ctpop (long); | |
15864 | @end smallexample | |
15865 | ||
15866 | The following built-in functions are available on systems that use the OSF/1 | |
15867 | PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} | |
15868 | PAL calls, but when invoked with @option{-mtls-kernel}, they invoke | |
15869 | @code{rdval} and @code{wrval}. | |
15870 | ||
15871 | @smallexample | |
15872 | void *__builtin_thread_pointer (void); | |
15873 | void __builtin_set_thread_pointer (void *); | |
15874 | @end smallexample | |
15875 | ||
15876 | @node Altera Nios II Built-in Functions | |
15877 | @subsection Altera Nios II Built-in Functions | |
15878 | ||
15879 | These built-in functions are available for the Altera Nios II | |
15880 | family of processors. | |
15881 | ||
15882 | The following built-in functions are always available. They | |
15883 | all generate the machine instruction that is part of the name. | |
15884 | ||
15885 | @example | |
15886 | int __builtin_ldbio (volatile const void *); | |
15887 | int __builtin_ldbuio (volatile const void *); | |
15888 | int __builtin_ldhio (volatile const void *); | |
15889 | int __builtin_ldhuio (volatile const void *); | |
15890 | int __builtin_ldwio (volatile const void *); | |
15891 | void __builtin_stbio (volatile void *, int); | |
15892 | void __builtin_sthio (volatile void *, int); | |
15893 | void __builtin_stwio (volatile void *, int); | |
15894 | void __builtin_sync (void); | |
15895 | int __builtin_rdctl (int); | |
15896 | int __builtin_rdprs (int, int); | |
15897 | void __builtin_wrctl (int, int); | |
15898 | void __builtin_flushd (volatile void *); | |
15899 | void __builtin_flushda (volatile void *); | |
15900 | int __builtin_wrpie (int); | |
15901 | void __builtin_eni (int); | |
15902 | int __builtin_ldex (volatile const void *); | |
15903 | int __builtin_stex (volatile void *, int); | |
15904 | int __builtin_ldsex (volatile const void *); | |
15905 | int __builtin_stsex (volatile void *, int); | |
15906 | @end example | |
15907 | ||
15908 | The following built-in functions are always available. They | |
15909 | all generate a Nios II Custom Instruction. The name of the | |
15910 | function represents the types that the function takes and | |
15911 | returns. The letter before the @code{n} is the return type | |
15912 | or void if absent. The @code{n} represents the first parameter | |
15913 | to all the custom instructions, the custom instruction number. | |
15914 | The two letters after the @code{n} represent the up to two | |
15915 | parameters to the function. | |
15916 | ||
15917 | The letters represent the following data types: | |
15918 | @table @code | |
15919 | @item <no letter> | |
15920 | @code{void} for return type and no parameter for parameter types. | |
15921 | ||
15922 | @item i | |
15923 | @code{int} for return type and parameter type | |
15924 | ||
15925 | @item f | |
15926 | @code{float} for return type and parameter type | |
15927 | ||
15928 | @item p | |
15929 | @code{void *} for return type and parameter type | |
15930 | ||
15931 | @end table | |
15932 | ||
15933 | And the function names are: | |
15934 | @example | |
15935 | void __builtin_custom_n (void); | |
15936 | void __builtin_custom_ni (int); | |
15937 | void __builtin_custom_nf (float); | |
15938 | void __builtin_custom_np (void *); | |
15939 | void __builtin_custom_nii (int, int); | |
15940 | void __builtin_custom_nif (int, float); | |
15941 | void __builtin_custom_nip (int, void *); | |
15942 | void __builtin_custom_nfi (float, int); | |
15943 | void __builtin_custom_nff (float, float); | |
15944 | void __builtin_custom_nfp (float, void *); | |
15945 | void __builtin_custom_npi (void *, int); | |
15946 | void __builtin_custom_npf (void *, float); | |
15947 | void __builtin_custom_npp (void *, void *); | |
15948 | int __builtin_custom_in (void); | |
15949 | int __builtin_custom_ini (int); | |
15950 | int __builtin_custom_inf (float); | |
15951 | int __builtin_custom_inp (void *); | |
15952 | int __builtin_custom_inii (int, int); | |
15953 | int __builtin_custom_inif (int, float); | |
15954 | int __builtin_custom_inip (int, void *); | |
15955 | int __builtin_custom_infi (float, int); | |
15956 | int __builtin_custom_inff (float, float); | |
15957 | int __builtin_custom_infp (float, void *); | |
15958 | int __builtin_custom_inpi (void *, int); | |
15959 | int __builtin_custom_inpf (void *, float); | |
15960 | int __builtin_custom_inpp (void *, void *); | |
15961 | float __builtin_custom_fn (void); | |
15962 | float __builtin_custom_fni (int); | |
15963 | float __builtin_custom_fnf (float); | |
15964 | float __builtin_custom_fnp (void *); | |
15965 | float __builtin_custom_fnii (int, int); | |
15966 | float __builtin_custom_fnif (int, float); | |
15967 | float __builtin_custom_fnip (int, void *); | |
15968 | float __builtin_custom_fnfi (float, int); | |
15969 | float __builtin_custom_fnff (float, float); | |
15970 | float __builtin_custom_fnfp (float, void *); | |
15971 | float __builtin_custom_fnpi (void *, int); | |
15972 | float __builtin_custom_fnpf (void *, float); | |
15973 | float __builtin_custom_fnpp (void *, void *); | |
15974 | void * __builtin_custom_pn (void); | |
15975 | void * __builtin_custom_pni (int); | |
15976 | void * __builtin_custom_pnf (float); | |
15977 | void * __builtin_custom_pnp (void *); | |
15978 | void * __builtin_custom_pnii (int, int); | |
15979 | void * __builtin_custom_pnif (int, float); | |
15980 | void * __builtin_custom_pnip (int, void *); | |
15981 | void * __builtin_custom_pnfi (float, int); | |
15982 | void * __builtin_custom_pnff (float, float); | |
15983 | void * __builtin_custom_pnfp (float, void *); | |
15984 | void * __builtin_custom_pnpi (void *, int); | |
15985 | void * __builtin_custom_pnpf (void *, float); | |
15986 | void * __builtin_custom_pnpp (void *, void *); | |
15987 | @end example | |
15988 | ||
15989 | @node ARC Built-in Functions | |
15990 | @subsection ARC Built-in Functions | |
15991 | ||
15992 | The following built-in functions are provided for ARC targets. The | |
15993 | built-ins generate the corresponding assembly instructions. In the | |
15994 | examples given below, the generated code often requires an operand or | |
15995 | result to be in a register. Where necessary further code will be | |
15996 | generated to ensure this is true, but for brevity this is not | |
15997 | described in each case. | |
15998 | ||
15999 | @emph{Note:} Using a built-in to generate an instruction not supported | |
16000 | by a target may cause problems. At present the compiler is not | |
16001 | guaranteed to detect such misuse, and as a result an internal compiler | |
16002 | error may be generated. | |
16003 | ||
f25efe50 | 16004 | @defbuiltin{int __builtin_arc_aligned (void *@var{val}, int @var{alignval})} |
d77de738 ML |
16005 | Return 1 if @var{val} is known to have the byte alignment given |
16006 | by @var{alignval}, otherwise return 0. | |
16007 | Note that this is different from | |
16008 | @smallexample | |
16009 | __alignof__(*(char *)@var{val}) >= alignval | |
16010 | @end smallexample | |
16011 | because __alignof__ sees only the type of the dereference, whereas | |
16012 | __builtin_arc_align uses alignment information from the pointer | |
16013 | as well as from the pointed-to type. | |
16014 | The information available will depend on optimization level. | |
f25efe50 | 16015 | @enddefbuiltin |
d77de738 | 16016 | |
f25efe50 | 16017 | @defbuiltin{void __builtin_arc_brk (void)} |
d77de738 ML |
16018 | Generates |
16019 | @example | |
16020 | brk | |
16021 | @end example | |
f25efe50 | 16022 | @enddefbuiltin |
d77de738 | 16023 | |
f25efe50 | 16024 | @defbuiltin{{unsigned int} __builtin_arc_core_read (unsigned int @var{regno})} |
d77de738 ML |
16025 | The operand is the number of a register to be read. Generates: |
16026 | @example | |
16027 | mov @var{dest}, r@var{regno} | |
16028 | @end example | |
16029 | where the value in @var{dest} will be the result returned from the | |
16030 | built-in. | |
f25efe50 | 16031 | @enddefbuiltin |
d77de738 | 16032 | |
f25efe50 | 16033 | @defbuiltin{void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})} |
d77de738 ML |
16034 | The first operand is the number of a register to be written, the |
16035 | second operand is a compile time constant to write into that | |
16036 | register. Generates: | |
16037 | @example | |
16038 | mov r@var{regno}, @var{val} | |
16039 | @end example | |
f25efe50 | 16040 | @enddefbuiltin |
d77de738 | 16041 | |
f25efe50 | 16042 | @defbuiltin{int __builtin_arc_divaw (int @var{a}, int @var{b})} |
d77de738 ML |
16043 | Only available if either @option{-mcpu=ARC700} or @option{-meA} is set. |
16044 | Generates: | |
16045 | @example | |
16046 | divaw @var{dest}, @var{a}, @var{b} | |
16047 | @end example | |
16048 | where the value in @var{dest} will be the result returned from the | |
16049 | built-in. | |
f25efe50 | 16050 | @enddefbuiltin |
d77de738 | 16051 | |
f25efe50 | 16052 | @defbuiltin{void __builtin_arc_flag (unsigned int @var{a})} |
d77de738 ML |
16053 | Generates |
16054 | @example | |
16055 | flag @var{a} | |
16056 | @end example | |
f25efe50 | 16057 | @enddefbuiltin |
d77de738 | 16058 | |
f25efe50 | 16059 | @defbuiltin{{unsigned int} __builtin_arc_lr (unsigned int @var{auxr})} |
d77de738 ML |
16060 | The operand, @var{auxv}, is the address of an auxiliary register and |
16061 | must be a compile time constant. Generates: | |
16062 | @example | |
16063 | lr @var{dest}, [@var{auxr}] | |
16064 | @end example | |
16065 | Where the value in @var{dest} will be the result returned from the | |
16066 | built-in. | |
f25efe50 | 16067 | @enddefbuiltin |
d77de738 | 16068 | |
f25efe50 | 16069 | @defbuiltin{void __builtin_arc_mul64 (int @var{a}, int @var{b})} |
d77de738 ML |
16070 | Only available with @option{-mmul64}. Generates: |
16071 | @example | |
16072 | mul64 @var{a}, @var{b} | |
16073 | @end example | |
f25efe50 | 16074 | @enddefbuiltin |
d77de738 | 16075 | |
f25efe50 | 16076 | @defbuiltin{void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})} |
d77de738 ML |
16077 | Only available with @option{-mmul64}. Generates: |
16078 | @example | |
16079 | mulu64 @var{a}, @var{b} | |
16080 | @end example | |
f25efe50 | 16081 | @enddefbuiltin |
d77de738 | 16082 | |
f25efe50 | 16083 | @defbuiltin{void __builtin_arc_nop (void)} |
d77de738 ML |
16084 | Generates: |
16085 | @example | |
16086 | nop | |
16087 | @end example | |
f25efe50 | 16088 | @enddefbuiltin |
d77de738 | 16089 | |
f25efe50 | 16090 | @defbuiltin{int __builtin_arc_norm (int @var{src})} |
d77de738 ML |
16091 | Only valid if the @samp{norm} instruction is available through the |
16092 | @option{-mnorm} option or by default with @option{-mcpu=ARC700}. | |
16093 | Generates: | |
16094 | @example | |
16095 | norm @var{dest}, @var{src} | |
16096 | @end example | |
16097 | Where the value in @var{dest} will be the result returned from the | |
16098 | built-in. | |
f25efe50 | 16099 | @enddefbuiltin |
d77de738 | 16100 | |
f25efe50 | 16101 | @defbuiltin{{short int} __builtin_arc_normw (short int @var{src})} |
d77de738 ML |
16102 | Only valid if the @samp{normw} instruction is available through the |
16103 | @option{-mnorm} option or by default with @option{-mcpu=ARC700}. | |
16104 | Generates: | |
16105 | @example | |
16106 | normw @var{dest}, @var{src} | |
16107 | @end example | |
16108 | Where the value in @var{dest} will be the result returned from the | |
16109 | built-in. | |
f25efe50 | 16110 | @enddefbuiltin |
d77de738 | 16111 | |
f25efe50 | 16112 | @defbuiltin{void __builtin_arc_rtie (void)} |
d77de738 ML |
16113 | Generates: |
16114 | @example | |
16115 | rtie | |
16116 | @end example | |
f25efe50 | 16117 | @enddefbuiltin |
d77de738 | 16118 | |
f25efe50 | 16119 | @defbuiltin{void __builtin_arc_sleep (int @var{a}} |
d77de738 ML |
16120 | Generates: |
16121 | @example | |
16122 | sleep @var{a} | |
16123 | @end example | |
f25efe50 | 16124 | @enddefbuiltin |
d77de738 | 16125 | |
f25efe50 | 16126 | @defbuiltin{void __builtin_arc_sr (unsigned int @var{val}, unsigned int @var{auxr})} |
d77de738 ML |
16127 | The first argument, @var{val}, is a compile time constant to be |
16128 | written to the register, the second argument, @var{auxr}, is the | |
16129 | address of an auxiliary register. Generates: | |
16130 | @example | |
16131 | sr @var{val}, [@var{auxr}] | |
16132 | @end example | |
f25efe50 | 16133 | @enddefbuiltin |
d77de738 | 16134 | |
f25efe50 | 16135 | @defbuiltin{int __builtin_arc_swap (int @var{src})} |
d77de738 ML |
16136 | Only valid with @option{-mswap}. Generates: |
16137 | @example | |
16138 | swap @var{dest}, @var{src} | |
16139 | @end example | |
16140 | Where the value in @var{dest} will be the result returned from the | |
16141 | built-in. | |
f25efe50 | 16142 | @enddefbuiltin |
d77de738 | 16143 | |
f25efe50 | 16144 | @defbuiltin{void __builtin_arc_swi (void)} |
d77de738 ML |
16145 | Generates: |
16146 | @example | |
16147 | swi | |
16148 | @end example | |
f25efe50 | 16149 | @enddefbuiltin |
d77de738 | 16150 | |
f25efe50 | 16151 | @defbuiltin{void __builtin_arc_sync (void)} |
d77de738 ML |
16152 | Only available with @option{-mcpu=ARC700}. Generates: |
16153 | @example | |
16154 | sync | |
16155 | @end example | |
f25efe50 | 16156 | @enddefbuiltin |
d77de738 | 16157 | |
f25efe50 | 16158 | @defbuiltin{void __builtin_arc_trap_s (unsigned int @var{c})} |
d77de738 ML |
16159 | Only available with @option{-mcpu=ARC700}. Generates: |
16160 | @example | |
16161 | trap_s @var{c} | |
16162 | @end example | |
f25efe50 | 16163 | @enddefbuiltin |
d77de738 | 16164 | |
f25efe50 | 16165 | @defbuiltin{void __builtin_arc_unimp_s (void)} |
d77de738 ML |
16166 | Only available with @option{-mcpu=ARC700}. Generates: |
16167 | @example | |
16168 | unimp_s | |
16169 | @end example | |
f25efe50 | 16170 | @enddefbuiltin |
d77de738 ML |
16171 | |
16172 | The instructions generated by the following builtins are not | |
16173 | considered as candidates for scheduling. They are not moved around by | |
16174 | the compiler during scheduling, and thus can be expected to appear | |
16175 | where they are put in the C code: | |
16176 | @example | |
16177 | __builtin_arc_brk() | |
16178 | __builtin_arc_core_read() | |
16179 | __builtin_arc_core_write() | |
16180 | __builtin_arc_flag() | |
16181 | __builtin_arc_lr() | |
16182 | __builtin_arc_sleep() | |
16183 | __builtin_arc_sr() | |
16184 | __builtin_arc_swi() | |
16185 | @end example | |
16186 | ||
b74e4cab CZ |
16187 | The following built-in functions are available for the ARCv2 family of |
16188 | processors. | |
16189 | ||
16190 | @example | |
16191 | int __builtin_arc_clri (); | |
16192 | void __builtin_arc_kflag (unsigned); | |
16193 | void __builtin_arc_seti (int); | |
16194 | @end example | |
16195 | ||
16196 | The following built-in functions are available for the ARCv2 family | |
16197 | and uses @option{-mnorm}. | |
16198 | ||
16199 | @example | |
16200 | int __builtin_arc_ffs (int); | |
16201 | int __builtin_arc_fls (int); | |
16202 | @end example | |
16203 | ||
d77de738 ML |
16204 | @node ARC SIMD Built-in Functions |
16205 | @subsection ARC SIMD Built-in Functions | |
16206 | ||
16207 | SIMD builtins provided by the compiler can be used to generate the | |
16208 | vector instructions. This section describes the available builtins | |
16209 | and their usage in programs. With the @option{-msimd} option, the | |
16210 | compiler provides 128-bit vector types, which can be specified using | |
16211 | the @code{vector_size} attribute. The header file @file{arc-simd.h} | |
16212 | can be included to use the following predefined types: | |
16213 | @example | |
16214 | typedef int __v4si __attribute__((vector_size(16))); | |
16215 | typedef short __v8hi __attribute__((vector_size(16))); | |
16216 | @end example | |
16217 | ||
16218 | These types can be used to define 128-bit variables. The built-in | |
16219 | functions listed in the following section can be used on these | |
16220 | variables to generate the vector operations. | |
16221 | ||
16222 | For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file | |
16223 | @file{arc-simd.h} also provides equivalent macros called | |
16224 | @code{_@var{someinsn}} that can be used for programming ease and | |
16225 | improved readability. The following macros for DMA control are also | |
16226 | provided: | |
16227 | @example | |
16228 | #define _setup_dma_in_channel_reg _vdiwr | |
16229 | #define _setup_dma_out_channel_reg _vdowr | |
16230 | @end example | |
16231 | ||
16232 | The following is a complete list of all the SIMD built-ins provided | |
16233 | for ARC, grouped by calling signature. | |
16234 | ||
16235 | The following take two @code{__v8hi} arguments and return a | |
16236 | @code{__v8hi} result: | |
16237 | @example | |
16238 | __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi); | |
16239 | __v8hi __builtin_arc_vaddw (__v8hi, __v8hi); | |
16240 | __v8hi __builtin_arc_vand (__v8hi, __v8hi); | |
16241 | __v8hi __builtin_arc_vandaw (__v8hi, __v8hi); | |
16242 | __v8hi __builtin_arc_vavb (__v8hi, __v8hi); | |
16243 | __v8hi __builtin_arc_vavrb (__v8hi, __v8hi); | |
16244 | __v8hi __builtin_arc_vbic (__v8hi, __v8hi); | |
16245 | __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi); | |
16246 | __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi); | |
16247 | __v8hi __builtin_arc_vdifw (__v8hi, __v8hi); | |
16248 | __v8hi __builtin_arc_veqw (__v8hi, __v8hi); | |
16249 | __v8hi __builtin_arc_vh264f (__v8hi, __v8hi); | |
16250 | __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi); | |
16251 | __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi); | |
16252 | __v8hi __builtin_arc_vlew (__v8hi, __v8hi); | |
16253 | __v8hi __builtin_arc_vltw (__v8hi, __v8hi); | |
16254 | __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi); | |
16255 | __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi); | |
16256 | __v8hi __builtin_arc_vminaw (__v8hi, __v8hi); | |
16257 | __v8hi __builtin_arc_vminw (__v8hi, __v8hi); | |
16258 | __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi); | |
16259 | __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi); | |
16260 | __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi); | |
16261 | __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi); | |
16262 | __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi); | |
16263 | __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi); | |
16264 | __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi); | |
16265 | __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi); | |
16266 | __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi); | |
16267 | __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi); | |
16268 | __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi); | |
16269 | __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi); | |
16270 | __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi); | |
16271 | __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi); | |
16272 | __v8hi __builtin_arc_vmrb (__v8hi, __v8hi); | |
16273 | __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi); | |
16274 | __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi); | |
16275 | __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi); | |
16276 | __v8hi __builtin_arc_vmulw (__v8hi, __v8hi); | |
16277 | __v8hi __builtin_arc_vnew (__v8hi, __v8hi); | |
16278 | __v8hi __builtin_arc_vor (__v8hi, __v8hi); | |
16279 | __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi); | |
16280 | __v8hi __builtin_arc_vsubw (__v8hi, __v8hi); | |
16281 | __v8hi __builtin_arc_vsummw (__v8hi, __v8hi); | |
16282 | __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi); | |
16283 | __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi); | |
16284 | __v8hi __builtin_arc_vxor (__v8hi, __v8hi); | |
16285 | __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi); | |
16286 | @end example | |
16287 | ||
16288 | The following take one @code{__v8hi} and one @code{int} argument and return a | |
16289 | @code{__v8hi} result: | |
16290 | ||
16291 | @example | |
16292 | __v8hi __builtin_arc_vbaddw (__v8hi, int); | |
16293 | __v8hi __builtin_arc_vbmaxw (__v8hi, int); | |
16294 | __v8hi __builtin_arc_vbminw (__v8hi, int); | |
16295 | __v8hi __builtin_arc_vbmulaw (__v8hi, int); | |
16296 | __v8hi __builtin_arc_vbmulfw (__v8hi, int); | |
16297 | __v8hi __builtin_arc_vbmulw (__v8hi, int); | |
16298 | __v8hi __builtin_arc_vbrsubw (__v8hi, int); | |
16299 | __v8hi __builtin_arc_vbsubw (__v8hi, int); | |
16300 | @end example | |
16301 | ||
16302 | The following take one @code{__v8hi} argument and one @code{int} argument which | |
16303 | must be a 3-bit compile time constant indicating a register number | |
16304 | I0-I7. They return a @code{__v8hi} result. | |
16305 | @example | |
16306 | __v8hi __builtin_arc_vasrw (__v8hi, const int); | |
16307 | __v8hi __builtin_arc_vsr8 (__v8hi, const int); | |
16308 | __v8hi __builtin_arc_vsr8aw (__v8hi, const int); | |
16309 | @end example | |
16310 | ||
16311 | The following take one @code{__v8hi} argument and one @code{int} | |
16312 | argument which must be a 6-bit compile time constant. They return a | |
16313 | @code{__v8hi} result. | |
16314 | @example | |
16315 | __v8hi __builtin_arc_vasrpwbi (__v8hi, const int); | |
16316 | __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int); | |
16317 | __v8hi __builtin_arc_vasrrwi (__v8hi, const int); | |
16318 | __v8hi __builtin_arc_vasrsrwi (__v8hi, const int); | |
16319 | __v8hi __builtin_arc_vasrwi (__v8hi, const int); | |
16320 | __v8hi __builtin_arc_vsr8awi (__v8hi, const int); | |
16321 | __v8hi __builtin_arc_vsr8i (__v8hi, const int); | |
16322 | @end example | |
16323 | ||
16324 | The following take one @code{__v8hi} argument and one @code{int} argument which | |
16325 | must be a 8-bit compile time constant. They return a @code{__v8hi} | |
16326 | result. | |
16327 | @example | |
16328 | __v8hi __builtin_arc_vd6tapf (__v8hi, const int); | |
16329 | __v8hi __builtin_arc_vmvaw (__v8hi, const int); | |
16330 | __v8hi __builtin_arc_vmvw (__v8hi, const int); | |
16331 | __v8hi __builtin_arc_vmvzw (__v8hi, const int); | |
16332 | @end example | |
16333 | ||
16334 | The following take two @code{int} arguments, the second of which which | |
16335 | must be a 8-bit compile time constant. They return a @code{__v8hi} | |
16336 | result: | |
16337 | @example | |
16338 | __v8hi __builtin_arc_vmovaw (int, const int); | |
16339 | __v8hi __builtin_arc_vmovw (int, const int); | |
16340 | __v8hi __builtin_arc_vmovzw (int, const int); | |
16341 | @end example | |
16342 | ||
16343 | The following take a single @code{__v8hi} argument and return a | |
16344 | @code{__v8hi} result: | |
16345 | @example | |
16346 | __v8hi __builtin_arc_vabsaw (__v8hi); | |
16347 | __v8hi __builtin_arc_vabsw (__v8hi); | |
16348 | __v8hi __builtin_arc_vaddsuw (__v8hi); | |
16349 | __v8hi __builtin_arc_vexch1 (__v8hi); | |
16350 | __v8hi __builtin_arc_vexch2 (__v8hi); | |
16351 | __v8hi __builtin_arc_vexch4 (__v8hi); | |
16352 | __v8hi __builtin_arc_vsignw (__v8hi); | |
16353 | __v8hi __builtin_arc_vupbaw (__v8hi); | |
16354 | __v8hi __builtin_arc_vupbw (__v8hi); | |
16355 | __v8hi __builtin_arc_vupsbaw (__v8hi); | |
16356 | __v8hi __builtin_arc_vupsbw (__v8hi); | |
16357 | @end example | |
16358 | ||
16359 | The following take two @code{int} arguments and return no result: | |
16360 | @example | |
16361 | void __builtin_arc_vdirun (int, int); | |
16362 | void __builtin_arc_vdorun (int, int); | |
16363 | @end example | |
16364 | ||
16365 | The following take two @code{int} arguments and return no result. The | |
16366 | first argument must a 3-bit compile time constant indicating one of | |
16367 | the DR0-DR7 DMA setup channels: | |
16368 | @example | |
16369 | void __builtin_arc_vdiwr (const int, int); | |
16370 | void __builtin_arc_vdowr (const int, int); | |
16371 | @end example | |
16372 | ||
16373 | The following take an @code{int} argument and return no result: | |
16374 | @example | |
16375 | void __builtin_arc_vendrec (int); | |
16376 | void __builtin_arc_vrec (int); | |
16377 | void __builtin_arc_vrecrun (int); | |
16378 | void __builtin_arc_vrun (int); | |
16379 | @end example | |
16380 | ||
16381 | The following take a @code{__v8hi} argument and two @code{int} | |
16382 | arguments and return a @code{__v8hi} result. The second argument must | |
16383 | be a 3-bit compile time constants, indicating one the registers I0-I7, | |
16384 | and the third argument must be an 8-bit compile time constant. | |
16385 | ||
16386 | @emph{Note:} Although the equivalent hardware instructions do not take | |
16387 | an SIMD register as an operand, these builtins overwrite the relevant | |
16388 | bits of the @code{__v8hi} register provided as the first argument with | |
16389 | the value loaded from the @code{[Ib, u8]} location in the SDM. | |
16390 | ||
16391 | @example | |
16392 | __v8hi __builtin_arc_vld32 (__v8hi, const int, const int); | |
16393 | __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int); | |
16394 | __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int); | |
16395 | __v8hi __builtin_arc_vld64 (__v8hi, const int, const int); | |
16396 | @end example | |
16397 | ||
16398 | The following take two @code{int} arguments and return a @code{__v8hi} | |
16399 | result. The first argument must be a 3-bit compile time constants, | |
16400 | indicating one the registers I0-I7, and the second argument must be an | |
16401 | 8-bit compile time constant. | |
16402 | ||
16403 | @example | |
16404 | __v8hi __builtin_arc_vld128 (const int, const int); | |
16405 | __v8hi __builtin_arc_vld64w (const int, const int); | |
16406 | @end example | |
16407 | ||
16408 | The following take a @code{__v8hi} argument and two @code{int} | |
16409 | arguments and return no result. The second argument must be a 3-bit | |
16410 | compile time constants, indicating one the registers I0-I7, and the | |
16411 | third argument must be an 8-bit compile time constant. | |
16412 | ||
16413 | @example | |
16414 | void __builtin_arc_vst128 (__v8hi, const int, const int); | |
16415 | void __builtin_arc_vst64 (__v8hi, const int, const int); | |
16416 | @end example | |
16417 | ||
16418 | The following take a @code{__v8hi} argument and three @code{int} | |
16419 | arguments and return no result. The second argument must be a 3-bit | |
16420 | compile-time constant, identifying the 16-bit sub-register to be | |
16421 | stored, the third argument must be a 3-bit compile time constants, | |
16422 | indicating one the registers I0-I7, and the fourth argument must be an | |
16423 | 8-bit compile time constant. | |
16424 | ||
16425 | @example | |
16426 | void __builtin_arc_vst16_n (__v8hi, const int, const int, const int); | |
16427 | void __builtin_arc_vst32_n (__v8hi, const int, const int, const int); | |
16428 | @end example | |
16429 | ||
b74e4cab CZ |
16430 | The following built-in functions are available on systems that uses |
16431 | @option{-mmpy-option=6} or higher. | |
16432 | ||
16433 | @example | |
16434 | __v2hi __builtin_arc_dmach (__v2hi, __v2hi); | |
16435 | __v2hi __builtin_arc_dmachu (__v2hi, __v2hi); | |
16436 | __v2hi __builtin_arc_dmpyh (__v2hi, __v2hi); | |
16437 | __v2hi __builtin_arc_dmpyhu (__v2hi, __v2hi); | |
16438 | __v2hi __builtin_arc_vaddsub2h (__v2hi, __v2hi); | |
16439 | __v2hi __builtin_arc_vsubadd2h (__v2hi, __v2hi); | |
16440 | @end example | |
16441 | ||
16442 | The following built-in functions are available on systems that uses | |
16443 | @option{-mmpy-option=7} or higher. | |
16444 | ||
16445 | @example | |
16446 | __v2si __builtin_arc_vmac2h (__v2hi, __v2hi); | |
16447 | __v2si __builtin_arc_vmac2hu (__v2hi, __v2hi); | |
16448 | __v2si __builtin_arc_vmpy2h (__v2hi, __v2hi); | |
16449 | __v2si __builtin_arc_vmpy2hu (__v2hi, __v2hi); | |
16450 | @end example | |
16451 | ||
16452 | The following built-in functions are available on systems that uses | |
16453 | @option{-mmpy-option=8} or higher. | |
16454 | ||
16455 | @example | |
16456 | long long __builtin_arc_qmach (__v4hi, __v4hi); | |
16457 | long long __builtin_arc_qmachu (__v4hi, __v4hi); | |
16458 | long long __builtin_arc_qmpyh (__v4hi, __v4hi); | |
16459 | long long __builtin_arc_qmpyhu (__v4hi, __v4hi); | |
16460 | long long __builtin_arc_dmacwh (__v2si, __v2hi); | |
16461 | long long __builtin_arc_dmacwhu (__v2si, __v2hi); | |
16462 | _v2si __builtin_arc_vaddsub (__v2si, __v2si); | |
16463 | _v2si __builtin_arc_vsubadd (__v2si, __v2si); | |
16464 | _v4hi __builtin_arc_vaddsub4h (__v4hi, __v4hi); | |
16465 | _v4hi __builtin_arc_vsubadd4h (__v4hi, __v4hi); | |
16466 | @end example | |
16467 | ||
d77de738 ML |
16468 | @node ARM iWMMXt Built-in Functions |
16469 | @subsection ARM iWMMXt Built-in Functions | |
16470 | ||
16471 | These built-in functions are available for the ARM family of | |
16472 | processors when the @option{-mcpu=iwmmxt} switch is used: | |
16473 | ||
16474 | @smallexample | |
16475 | typedef int v2si __attribute__ ((vector_size (8))); | |
16476 | typedef short v4hi __attribute__ ((vector_size (8))); | |
16477 | typedef char v8qi __attribute__ ((vector_size (8))); | |
16478 | ||
16479 | int __builtin_arm_getwcgr0 (void); | |
16480 | void __builtin_arm_setwcgr0 (int); | |
16481 | int __builtin_arm_getwcgr1 (void); | |
16482 | void __builtin_arm_setwcgr1 (int); | |
16483 | int __builtin_arm_getwcgr2 (void); | |
16484 | void __builtin_arm_setwcgr2 (int); | |
16485 | int __builtin_arm_getwcgr3 (void); | |
16486 | void __builtin_arm_setwcgr3 (int); | |
16487 | int __builtin_arm_textrmsb (v8qi, int); | |
16488 | int __builtin_arm_textrmsh (v4hi, int); | |
16489 | int __builtin_arm_textrmsw (v2si, int); | |
16490 | int __builtin_arm_textrmub (v8qi, int); | |
16491 | int __builtin_arm_textrmuh (v4hi, int); | |
16492 | int __builtin_arm_textrmuw (v2si, int); | |
16493 | v8qi __builtin_arm_tinsrb (v8qi, int, int); | |
16494 | v4hi __builtin_arm_tinsrh (v4hi, int, int); | |
16495 | v2si __builtin_arm_tinsrw (v2si, int, int); | |
16496 | long long __builtin_arm_tmia (long long, int, int); | |
16497 | long long __builtin_arm_tmiabb (long long, int, int); | |
16498 | long long __builtin_arm_tmiabt (long long, int, int); | |
16499 | long long __builtin_arm_tmiaph (long long, int, int); | |
16500 | long long __builtin_arm_tmiatb (long long, int, int); | |
16501 | long long __builtin_arm_tmiatt (long long, int, int); | |
16502 | int __builtin_arm_tmovmskb (v8qi); | |
16503 | int __builtin_arm_tmovmskh (v4hi); | |
16504 | int __builtin_arm_tmovmskw (v2si); | |
16505 | long long __builtin_arm_waccb (v8qi); | |
16506 | long long __builtin_arm_wacch (v4hi); | |
16507 | long long __builtin_arm_waccw (v2si); | |
16508 | v8qi __builtin_arm_waddb (v8qi, v8qi); | |
16509 | v8qi __builtin_arm_waddbss (v8qi, v8qi); | |
16510 | v8qi __builtin_arm_waddbus (v8qi, v8qi); | |
16511 | v4hi __builtin_arm_waddh (v4hi, v4hi); | |
16512 | v4hi __builtin_arm_waddhss (v4hi, v4hi); | |
16513 | v4hi __builtin_arm_waddhus (v4hi, v4hi); | |
16514 | v2si __builtin_arm_waddw (v2si, v2si); | |
16515 | v2si __builtin_arm_waddwss (v2si, v2si); | |
16516 | v2si __builtin_arm_waddwus (v2si, v2si); | |
16517 | v8qi __builtin_arm_walign (v8qi, v8qi, int); | |
16518 | long long __builtin_arm_wand(long long, long long); | |
16519 | long long __builtin_arm_wandn (long long, long long); | |
16520 | v8qi __builtin_arm_wavg2b (v8qi, v8qi); | |
16521 | v8qi __builtin_arm_wavg2br (v8qi, v8qi); | |
16522 | v4hi __builtin_arm_wavg2h (v4hi, v4hi); | |
16523 | v4hi __builtin_arm_wavg2hr (v4hi, v4hi); | |
16524 | v8qi __builtin_arm_wcmpeqb (v8qi, v8qi); | |
16525 | v4hi __builtin_arm_wcmpeqh (v4hi, v4hi); | |
16526 | v2si __builtin_arm_wcmpeqw (v2si, v2si); | |
16527 | v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi); | |
16528 | v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi); | |
16529 | v2si __builtin_arm_wcmpgtsw (v2si, v2si); | |
16530 | v8qi __builtin_arm_wcmpgtub (v8qi, v8qi); | |
16531 | v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi); | |
16532 | v2si __builtin_arm_wcmpgtuw (v2si, v2si); | |
16533 | long long __builtin_arm_wmacs (long long, v4hi, v4hi); | |
16534 | long long __builtin_arm_wmacsz (v4hi, v4hi); | |
16535 | long long __builtin_arm_wmacu (long long, v4hi, v4hi); | |
16536 | long long __builtin_arm_wmacuz (v4hi, v4hi); | |
16537 | v4hi __builtin_arm_wmadds (v4hi, v4hi); | |
16538 | v4hi __builtin_arm_wmaddu (v4hi, v4hi); | |
16539 | v8qi __builtin_arm_wmaxsb (v8qi, v8qi); | |
16540 | v4hi __builtin_arm_wmaxsh (v4hi, v4hi); | |
16541 | v2si __builtin_arm_wmaxsw (v2si, v2si); | |
16542 | v8qi __builtin_arm_wmaxub (v8qi, v8qi); | |
16543 | v4hi __builtin_arm_wmaxuh (v4hi, v4hi); | |
16544 | v2si __builtin_arm_wmaxuw (v2si, v2si); | |
16545 | v8qi __builtin_arm_wminsb (v8qi, v8qi); | |
16546 | v4hi __builtin_arm_wminsh (v4hi, v4hi); | |
16547 | v2si __builtin_arm_wminsw (v2si, v2si); | |
16548 | v8qi __builtin_arm_wminub (v8qi, v8qi); | |
16549 | v4hi __builtin_arm_wminuh (v4hi, v4hi); | |
16550 | v2si __builtin_arm_wminuw (v2si, v2si); | |
16551 | v4hi __builtin_arm_wmulsm (v4hi, v4hi); | |
16552 | v4hi __builtin_arm_wmulul (v4hi, v4hi); | |
16553 | v4hi __builtin_arm_wmulum (v4hi, v4hi); | |
16554 | long long __builtin_arm_wor (long long, long long); | |
16555 | v2si __builtin_arm_wpackdss (long long, long long); | |
16556 | v2si __builtin_arm_wpackdus (long long, long long); | |
16557 | v8qi __builtin_arm_wpackhss (v4hi, v4hi); | |
16558 | v8qi __builtin_arm_wpackhus (v4hi, v4hi); | |
16559 | v4hi __builtin_arm_wpackwss (v2si, v2si); | |
16560 | v4hi __builtin_arm_wpackwus (v2si, v2si); | |
16561 | long long __builtin_arm_wrord (long long, long long); | |
16562 | long long __builtin_arm_wrordi (long long, int); | |
16563 | v4hi __builtin_arm_wrorh (v4hi, long long); | |
16564 | v4hi __builtin_arm_wrorhi (v4hi, int); | |
16565 | v2si __builtin_arm_wrorw (v2si, long long); | |
16566 | v2si __builtin_arm_wrorwi (v2si, int); | |
16567 | v2si __builtin_arm_wsadb (v2si, v8qi, v8qi); | |
16568 | v2si __builtin_arm_wsadbz (v8qi, v8qi); | |
16569 | v2si __builtin_arm_wsadh (v2si, v4hi, v4hi); | |
16570 | v2si __builtin_arm_wsadhz (v4hi, v4hi); | |
16571 | v4hi __builtin_arm_wshufh (v4hi, int); | |
16572 | long long __builtin_arm_wslld (long long, long long); | |
16573 | long long __builtin_arm_wslldi (long long, int); | |
16574 | v4hi __builtin_arm_wsllh (v4hi, long long); | |
16575 | v4hi __builtin_arm_wsllhi (v4hi, int); | |
16576 | v2si __builtin_arm_wsllw (v2si, long long); | |
16577 | v2si __builtin_arm_wsllwi (v2si, int); | |
16578 | long long __builtin_arm_wsrad (long long, long long); | |
16579 | long long __builtin_arm_wsradi (long long, int); | |
16580 | v4hi __builtin_arm_wsrah (v4hi, long long); | |
16581 | v4hi __builtin_arm_wsrahi (v4hi, int); | |
16582 | v2si __builtin_arm_wsraw (v2si, long long); | |
16583 | v2si __builtin_arm_wsrawi (v2si, int); | |
16584 | long long __builtin_arm_wsrld (long long, long long); | |
16585 | long long __builtin_arm_wsrldi (long long, int); | |
16586 | v4hi __builtin_arm_wsrlh (v4hi, long long); | |
16587 | v4hi __builtin_arm_wsrlhi (v4hi, int); | |
16588 | v2si __builtin_arm_wsrlw (v2si, long long); | |
16589 | v2si __builtin_arm_wsrlwi (v2si, int); | |
16590 | v8qi __builtin_arm_wsubb (v8qi, v8qi); | |
16591 | v8qi __builtin_arm_wsubbss (v8qi, v8qi); | |
16592 | v8qi __builtin_arm_wsubbus (v8qi, v8qi); | |
16593 | v4hi __builtin_arm_wsubh (v4hi, v4hi); | |
16594 | v4hi __builtin_arm_wsubhss (v4hi, v4hi); | |
16595 | v4hi __builtin_arm_wsubhus (v4hi, v4hi); | |
16596 | v2si __builtin_arm_wsubw (v2si, v2si); | |
16597 | v2si __builtin_arm_wsubwss (v2si, v2si); | |
16598 | v2si __builtin_arm_wsubwus (v2si, v2si); | |
16599 | v4hi __builtin_arm_wunpckehsb (v8qi); | |
16600 | v2si __builtin_arm_wunpckehsh (v4hi); | |
16601 | long long __builtin_arm_wunpckehsw (v2si); | |
16602 | v4hi __builtin_arm_wunpckehub (v8qi); | |
16603 | v2si __builtin_arm_wunpckehuh (v4hi); | |
16604 | long long __builtin_arm_wunpckehuw (v2si); | |
16605 | v4hi __builtin_arm_wunpckelsb (v8qi); | |
16606 | v2si __builtin_arm_wunpckelsh (v4hi); | |
16607 | long long __builtin_arm_wunpckelsw (v2si); | |
16608 | v4hi __builtin_arm_wunpckelub (v8qi); | |
16609 | v2si __builtin_arm_wunpckeluh (v4hi); | |
16610 | long long __builtin_arm_wunpckeluw (v2si); | |
16611 | v8qi __builtin_arm_wunpckihb (v8qi, v8qi); | |
16612 | v4hi __builtin_arm_wunpckihh (v4hi, v4hi); | |
16613 | v2si __builtin_arm_wunpckihw (v2si, v2si); | |
16614 | v8qi __builtin_arm_wunpckilb (v8qi, v8qi); | |
16615 | v4hi __builtin_arm_wunpckilh (v4hi, v4hi); | |
16616 | v2si __builtin_arm_wunpckilw (v2si, v2si); | |
16617 | long long __builtin_arm_wxor (long long, long long); | |
16618 | long long __builtin_arm_wzero (); | |
16619 | @end smallexample | |
16620 | ||
16621 | ||
16622 | @node ARM C Language Extensions (ACLE) | |
16623 | @subsection ARM C Language Extensions (ACLE) | |
16624 | ||
16625 | GCC implements extensions for C as described in the ARM C Language | |
16626 | Extensions (ACLE) specification, which can be found at | |
16627 | @uref{https://developer.arm.com/documentation/ihi0053/latest/}. | |
16628 | ||
16629 | As a part of ACLE, GCC implements extensions for Advanced SIMD as described in | |
16630 | the ARM C Language Extensions Specification. The complete list of Advanced SIMD | |
16631 | intrinsics can be found at | |
16632 | @uref{https://developer.arm.com/documentation/ihi0073/latest/}. | |
16633 | The built-in intrinsics for the Advanced SIMD extension are available when | |
16634 | NEON is enabled. | |
16635 | ||
16636 | Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both | |
16637 | back ends support CRC32 intrinsics and the ARM back end supports the | |
16638 | Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit | |
16639 | floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1. | |
16640 | AArch64's back end does not have support for 16-bit floating point Advanced SIMD | |
16641 | intrinsics yet. | |
16642 | ||
16643 | See @ref{ARM Options} and @ref{AArch64 Options} for more information on the | |
16644 | availability of extensions. | |
16645 | ||
16646 | @node ARM Floating Point Status and Control Intrinsics | |
16647 | @subsection ARM Floating Point Status and Control Intrinsics | |
16648 | ||
16649 | These built-in functions are available for the ARM family of | |
16650 | processors with floating-point unit. | |
16651 | ||
16652 | @smallexample | |
16653 | unsigned int __builtin_arm_get_fpscr (); | |
16654 | void __builtin_arm_set_fpscr (unsigned int); | |
16655 | @end smallexample | |
16656 | ||
16657 | @node ARM ARMv8-M Security Extensions | |
16658 | @subsection ARM ARMv8-M Security Extensions | |
16659 | ||
16660 | GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M | |
16661 | Security Extensions: Requirements on Development Tools Engineering | |
16662 | Specification, which can be found at | |
16663 | @uref{https://developer.arm.com/documentation/ecm0359818/latest/}. | |
16664 | ||
16665 | As part of the Security Extensions GCC implements two new function attributes: | |
16666 | @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}. | |
16667 | ||
16668 | As part of the Security Extensions GCC implements the intrinsics below. FPTR | |
16669 | is used here to mean any function pointer type. | |
16670 | ||
16671 | @smallexample | |
16672 | cmse_address_info_t cmse_TT (void *); | |
16673 | cmse_address_info_t cmse_TT_fptr (FPTR); | |
16674 | cmse_address_info_t cmse_TTT (void *); | |
16675 | cmse_address_info_t cmse_TTT_fptr (FPTR); | |
16676 | cmse_address_info_t cmse_TTA (void *); | |
16677 | cmse_address_info_t cmse_TTA_fptr (FPTR); | |
16678 | cmse_address_info_t cmse_TTAT (void *); | |
16679 | cmse_address_info_t cmse_TTAT_fptr (FPTR); | |
16680 | void * cmse_check_address_range (void *, size_t, int); | |
16681 | typeof(p) cmse_nsfptr_create (FPTR p); | |
16682 | intptr_t cmse_is_nsfptr (FPTR); | |
16683 | int cmse_nonsecure_caller (void); | |
16684 | @end smallexample | |
16685 | ||
16686 | @node AVR Built-in Functions | |
16687 | @subsection AVR Built-in Functions | |
16688 | ||
16689 | For each built-in function for AVR, there is an equally named, | |
16690 | uppercase built-in macro defined. That way users can easily query if | |
16691 | or if not a specific built-in is implemented or not. For example, if | |
16692 | @code{__builtin_avr_nop} is available the macro | |
16693 | @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. | |
16694 | ||
16695 | @table @code | |
16696 | ||
16697 | @item void __builtin_avr_nop (void) | |
16698 | @itemx void __builtin_avr_sei (void) | |
16699 | @itemx void __builtin_avr_cli (void) | |
16700 | @itemx void __builtin_avr_sleep (void) | |
16701 | @itemx void __builtin_avr_wdr (void) | |
16702 | @itemx unsigned char __builtin_avr_swap (unsigned char) | |
16703 | @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char) | |
16704 | @itemx int __builtin_avr_fmuls (char, char) | |
16705 | @itemx int __builtin_avr_fmulsu (char, unsigned char) | |
16706 | These built-in functions map to the respective machine | |
16707 | instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, | |
16708 | @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} | |
16709 | resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented | |
16710 | as library call if no hardware multiplier is available. | |
16711 | ||
16712 | @item void __builtin_avr_delay_cycles (unsigned long ticks) | |
16713 | Delay execution for @var{ticks} cycles. Note that this | |
16714 | built-in does not take into account the effect of interrupts that | |
16715 | might increase delay time. @var{ticks} must be a compile-time | |
16716 | integer constant; delays with a variable number of cycles are not supported. | |
16717 | ||
16718 | @item char __builtin_avr_flash_segment (const __memx void*) | |
16719 | This built-in takes a byte address to the 24-bit | |
16720 | @ref{AVR Named Address Spaces,address space} @code{__memx} and returns | |
16721 | the number of the flash segment (the 64 KiB chunk) where the address | |
16722 | points to. Counting starts at @code{0}. | |
16723 | If the address does not point to flash memory, return @code{-1}. | |
16724 | ||
16725 | @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val) | |
16726 | Insert bits from @var{bits} into @var{val} and return the resulting | |
16727 | value. The nibbles of @var{map} determine how the insertion is | |
16728 | performed: Let @var{X} be the @var{n}-th nibble of @var{map} | |
16729 | @enumerate | |
16730 | @item If @var{X} is @code{0xf}, | |
16731 | then the @var{n}-th bit of @var{val} is returned unaltered. | |
16732 | ||
16733 | @item If X is in the range 0@dots{}7, | |
16734 | then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} | |
16735 | ||
16736 | @item If X is in the range 8@dots{}@code{0xe}, | |
16737 | then the @var{n}-th result bit is undefined. | |
16738 | @end enumerate | |
16739 | ||
16740 | @noindent | |
16741 | One typical use case for this built-in is adjusting input and | |
16742 | output values to non-contiguous port layouts. Some examples: | |
16743 | ||
16744 | @smallexample | |
16745 | // same as val, bits is unused | |
16746 | __builtin_avr_insert_bits (0xffffffff, bits, val); | |
16747 | @end smallexample | |
16748 | ||
16749 | @smallexample | |
16750 | // same as bits, val is unused | |
16751 | __builtin_avr_insert_bits (0x76543210, bits, val); | |
16752 | @end smallexample | |
16753 | ||
16754 | @smallexample | |
16755 | // same as rotating bits by 4 | |
16756 | __builtin_avr_insert_bits (0x32107654, bits, 0); | |
16757 | @end smallexample | |
16758 | ||
16759 | @smallexample | |
16760 | // high nibble of result is the high nibble of val | |
16761 | // low nibble of result is the low nibble of bits | |
16762 | __builtin_avr_insert_bits (0xffff3210, bits, val); | |
16763 | @end smallexample | |
16764 | ||
16765 | @smallexample | |
16766 | // reverse the bit order of bits | |
16767 | __builtin_avr_insert_bits (0x01234567, bits, 0); | |
16768 | @end smallexample | |
16769 | ||
16770 | @item void __builtin_avr_nops (unsigned count) | |
16771 | Insert @var{count} @code{NOP} instructions. | |
16772 | The number of instructions must be a compile-time integer constant. | |
16773 | ||
16774 | @end table | |
16775 | ||
16776 | @noindent | |
16777 | There are many more AVR-specific built-in functions that are used to | |
16778 | implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of | |
16779 | section 7.18a.6. You don't need to use these built-ins directly. | |
16780 | Instead, use the declarations as supplied by the @code{stdfix.h} header | |
16781 | with GNU-C99: | |
16782 | ||
16783 | @smallexample | |
16784 | #include <stdfix.h> | |
16785 | ||
16786 | // Re-interpret the bit representation of unsigned 16-bit | |
16787 | // integer @var{uval} as Q-format 0.16 value. | |
16788 | unsigned fract get_bits (uint_ur_t uval) | |
16789 | @{ | |
16790 | return urbits (uval); | |
16791 | @} | |
16792 | @end smallexample | |
16793 | ||
16794 | @node Blackfin Built-in Functions | |
16795 | @subsection Blackfin Built-in Functions | |
16796 | ||
16797 | Currently, there are two Blackfin-specific built-in functions. These are | |
16798 | used for generating @code{CSYNC} and @code{SSYNC} machine insns without | |
16799 | using inline assembly; by using these built-in functions the compiler can | |
16800 | automatically add workarounds for hardware errata involving these | |
16801 | instructions. These functions are named as follows: | |
16802 | ||
16803 | @smallexample | |
16804 | void __builtin_bfin_csync (void); | |
16805 | void __builtin_bfin_ssync (void); | |
16806 | @end smallexample | |
16807 | ||
16808 | @node BPF Built-in Functions | |
16809 | @subsection BPF Built-in Functions | |
16810 | ||
16811 | The following built-in functions are available for eBPF targets. | |
16812 | ||
f25efe50 | 16813 | @defbuiltin{{unsigned long long} __builtin_bpf_load_byte (unsigned long long @var{offset})} |
d77de738 | 16814 | Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. |
f25efe50 | 16815 | @enddefbuiltin |
d77de738 | 16816 | |
f25efe50 | 16817 | @defbuiltin{{unsigned long long} __builtin_bpf_load_half (unsigned long long @var{offset})} |
7ffbc74c | 16818 | Load 16 bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. |
f25efe50 | 16819 | @enddefbuiltin |
d77de738 | 16820 | |
f25efe50 | 16821 | @defbuiltin{{unsigned long long} __builtin_bpf_load_word (unsigned long long @var{offset})} |
7ffbc74c | 16822 | Load 32 bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. |
f25efe50 | 16823 | @enddefbuiltin |
d77de738 | 16824 | |
f25efe50 | 16825 | @defbuiltin{{void *} __builtin_preserve_access_index (@var{expr})} |
d77de738 | 16826 | 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 | 16827 | @enddefbuiltin |
d77de738 | 16828 | |
f25efe50 | 16829 | @defbuiltin{{unsigned int} __builtin_preserve_field_info (@var{expr}, unsigned int @var{kind})} |
d77de738 ML |
16830 | BPF Compile Once-Run Everywhere (CO-RE) support. This builtin is used to |
16831 | extract information to aid in struct/union relocations. @var{expr} is | |
16832 | an access to a field of a struct or union. Depending on @var{kind}, different | |
16833 | information is returned to the program. A CO-RE relocation for the access in | |
16834 | @var{expr} with kind @var{kind} is recorded if @code{-mco-re} is in effect. | |
16835 | ||
16836 | The following values are supported for @var{kind}: | |
7ffbc74c | 16837 | @table @code |
d77de738 ML |
16838 | @item FIELD_BYTE_OFFSET = 0 |
16839 | The returned value is the offset, in bytes, of the field from the | |
7ffbc74c | 16840 | beginning of the containing structure. For bit-fields, this is the byte offset |
d77de738 ML |
16841 | of the containing word. |
16842 | ||
16843 | @item FIELD_BYTE_SIZE = 1 | |
7ffbc74c SL |
16844 | The returned value is the size, in bytes, of the field. For bit-fields, |
16845 | this is the size in bytes of the containing word. | |
d77de738 ML |
16846 | |
16847 | @item FIELD_EXISTENCE = 2 | |
16848 | The returned value is 1 if the field exists, 0 otherwise. Always 1 at | |
16849 | compile time. | |
16850 | ||
16851 | @item FIELD_SIGNEDNESS = 3 | |
16852 | The returned value is 1 if the field is signed, 0 otherwise. | |
16853 | ||
16854 | @item FIELD_LSHIFT_U64 = 4 | |
16855 | @itemx FIELD_RSHIFT_U64 = 5 | |
16856 | The returned value is the number of bits of left- or right-shifting | |
7ffbc74c SL |
16857 | (respectively) needed in order to recover the original value of the field, |
16858 | after it has been loaded by a read of @code{FIELD_BYTE_SIZE} bytes into an | |
16859 | unsigned 64-bit value. Primarily useful for reading bit-field values | |
16860 | from structures that may change between kernel versions. | |
d77de738 ML |
16861 | |
16862 | @end table | |
16863 | ||
16864 | Note that the return value is a constant which is known at | |
7ffbc74c SL |
16865 | compile time. If the field has a variable offset then |
16866 | @code{FIELD_BYTE_OFFSET}, @code{FIELD_LSHIFT_U64}, | |
16867 | and @code{FIELD_RSHIFT_U64} are not supported. | |
16868 | Similarly, if the field has a variable size then | |
16869 | @code{FIELD_BYTE_SIZE}, @code{FIELD_LSHIFT_U64}, | |
16870 | and @code{FIELD_RSHIFT_U64} are not supported. | |
16871 | ||
16872 | For example, @code{__builtin_preserve_field_info} can be used to reliably | |
16873 | extract bit-field values from a structure that may change between | |
d77de738 ML |
16874 | kernel versions: |
16875 | ||
7ffbc74c | 16876 | @smallexample |
d77de738 ML |
16877 | struct S |
16878 | @{ | |
16879 | short a; | |
16880 | int x:7; | |
16881 | int y:5; | |
16882 | @}; | |
16883 | ||
16884 | int | |
16885 | read_y (struct S *arg) | |
16886 | @{ | |
16887 | unsigned long long val; | |
7ffbc74c SL |
16888 | unsigned int offset |
16889 | = __builtin_preserve_field_info (arg->y, FIELD_BYTE_OFFSET); | |
16890 | unsigned int size | |
16891 | = __builtin_preserve_field_info (arg->y, FIELD_BYTE_SIZE); | |
d77de738 ML |
16892 | |
16893 | /* Read size bytes from arg + offset into val. */ | |
16894 | bpf_probe_read (&val, size, arg + offset); | |
16895 | ||
16896 | val <<= __builtin_preserve_field_info (arg->y, FIELD_LSHIFT_U64); | |
16897 | ||
16898 | if (__builtin_preserve_field_info (arg->y, FIELD_SIGNEDNESS)) | |
7ffbc74c SL |
16899 | val = ((long long) val |
16900 | >> __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64)); | |
d77de738 ML |
16901 | else |
16902 | val >>= __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64); | |
16903 | ||
16904 | return val; | |
16905 | @} | |
16906 | ||
7ffbc74c | 16907 | @end smallexample |
f25efe50 | 16908 | @enddefbuiltin |
d77de738 | 16909 | |
e0a81559 CM |
16910 | @defbuiltin{{unsigned int} __builtin_preserve_enum_value (@var{type}, @var{enum}, unsigned int @var{kind})} |
16911 | BPF Compile Once-Run Everywhere (CO-RE) support. This builtin collects enum | |
16912 | information and creates a CO-RE relocation relative to @var{enum} that should | |
16913 | be of @var{type}. The @var{kind} specifies the action performed. | |
16914 | ||
16915 | The following values are supported for @var{kind}: | |
16916 | @table @code | |
16917 | @item ENUM_VALUE_EXISTS = 0 | |
16918 | The return value is either 0 or 1 depending if the enum value exists in the | |
16919 | target. | |
16920 | ||
16921 | @item ENUM_VALUE = 1 | |
16922 | The return value is the enum value in the target kernel. | |
16923 | @end table | |
16924 | @enddefbuiltin | |
16925 | ||
16926 | @defbuiltin{{unsigned int} __builtin_btf_type_id (@var{type}, unsigned int @var{kind})} | |
16927 | BPF Compile Once-Run Everywhere (CO-RE) support. This builtin is used to get | |
16928 | the BTF type ID of a specified type. Depending on the @var{kind} argument, it | |
16929 | will either return the ID of the local BTF information, or the BTF type ID in | |
16930 | the target kernel. | |
16931 | ||
16932 | The following values are supported for @var{kind}: | |
16933 | @table @code | |
16934 | @item BTF_TYPE_ID_LOCAL = 0 | |
16935 | Return the local BTF type ID. Always succeeds. | |
16936 | ||
16937 | @item BTF_TYPE_ID_TARGET = 1 | |
16938 | Return the target BTF type ID. If type does not exist in the target, returns 0. | |
16939 | @end table | |
16940 | @enddefbuiltin | |
16941 | ||
16942 | @defbuiltin{{unsigned int} __builtin_preserve_type_info (@var{type}, unsigned int @var{kind})} | |
16943 | BPF Compile Once-Run Everywhere (CO-RE) support. This builtin performs named | |
16944 | type (struct/union/enum/typedef) verifications. The type of verification | |
16945 | dependents on the @var{kind} argument provided. This builtin will always | |
16946 | return 0 if type does not exists in the target kernel. | |
16947 | ||
16948 | The following values are supported for @var{kind}: | |
16949 | @table @code | |
16950 | @item BTF_TYPE_EXISTS = 0 | |
16951 | Checks if type exists in the target. | |
16952 | ||
16953 | @item BTF_TYPE_MATCHES = 1 | |
16954 | Checks if type matches the local definition in the target kernel. | |
16955 | ||
16956 | @item BTF_TYPE_SIZE = 2 | |
16957 | Returns the size of the type within the target. | |
16958 | @end table | |
16959 | @enddefbuiltin | |
16960 | ||
d77de738 ML |
16961 | @node FR-V Built-in Functions |
16962 | @subsection FR-V Built-in Functions | |
16963 | ||
16964 | GCC provides many FR-V-specific built-in functions. In general, | |
16965 | these functions are intended to be compatible with those described | |
16966 | by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu | |
16967 | Semiconductor}. The two exceptions are @code{__MDUNPACKH} and | |
16968 | @code{__MBTOHE}, the GCC forms of which pass 128-bit values by | |
16969 | pointer rather than by value. | |
16970 | ||
16971 | Most of the functions are named after specific FR-V instructions. | |
16972 | Such functions are said to be ``directly mapped'' and are summarized | |
16973 | here in tabular form. | |
16974 | ||
16975 | @menu | |
16976 | * Argument Types:: | |
16977 | * Directly-mapped Integer Functions:: | |
16978 | * Directly-mapped Media Functions:: | |
16979 | * Raw read/write Functions:: | |
16980 | * Other Built-in Functions:: | |
16981 | @end menu | |
16982 | ||
16983 | @node Argument Types | |
16984 | @subsubsection Argument Types | |
16985 | ||
16986 | The arguments to the built-in functions can be divided into three groups: | |
16987 | register numbers, compile-time constants and run-time values. In order | |
16988 | to make this classification clear at a glance, the arguments and return | |
16989 | values are given the following pseudo types: | |
16990 | ||
16991 | @multitable @columnfractions .20 .30 .15 .35 | |
16992 | @headitem Pseudo type @tab Real C type @tab Constant? @tab Description | |
16993 | @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword | |
16994 | @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word | |
16995 | @item @code{sw1} @tab @code{int} @tab No @tab a signed word | |
16996 | @item @code{uw2} @tab @code{unsigned long long} @tab No | |
16997 | @tab an unsigned doubleword | |
16998 | @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword | |
16999 | @item @code{const} @tab @code{int} @tab Yes @tab an integer constant | |
17000 | @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number | |
17001 | @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number | |
17002 | @end multitable | |
17003 | ||
17004 | These pseudo types are not defined by GCC, they are simply a notational | |
17005 | convenience used in this manual. | |
17006 | ||
17007 | Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} | |
17008 | and @code{sw2} are evaluated at run time. They correspond to | |
17009 | register operands in the underlying FR-V instructions. | |
17010 | ||
17011 | @code{const} arguments represent immediate operands in the underlying | |
17012 | FR-V instructions. They must be compile-time constants. | |
17013 | ||
17014 | @code{acc} arguments are evaluated at compile time and specify the number | |
17015 | of an accumulator register. For example, an @code{acc} argument of 2 | |
17016 | selects the ACC2 register. | |
17017 | ||
17018 | @code{iacc} arguments are similar to @code{acc} arguments but specify the | |
17019 | number of an IACC register. See @pxref{Other Built-in Functions} | |
17020 | for more details. | |
17021 | ||
17022 | @node Directly-mapped Integer Functions | |
17023 | @subsubsection Directly-Mapped Integer Functions | |
17024 | ||
17025 | The functions listed below map directly to FR-V I-type instructions. | |
17026 | ||
17027 | @multitable @columnfractions .45 .32 .23 | |
17028 | @headitem Function prototype @tab Example usage @tab Assembly output | |
17029 | @item @code{sw1 __ADDSS (sw1, sw1)} | |
17030 | @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} | |
17031 | @tab @code{ADDSS @var{a},@var{b},@var{c}} | |
17032 | @item @code{sw1 __SCAN (sw1, sw1)} | |
17033 | @tab @code{@var{c} = __SCAN (@var{a}, @var{b})} | |
17034 | @tab @code{SCAN @var{a},@var{b},@var{c}} | |
17035 | @item @code{sw1 __SCUTSS (sw1)} | |
17036 | @tab @code{@var{b} = __SCUTSS (@var{a})} | |
17037 | @tab @code{SCUTSS @var{a},@var{b}} | |
17038 | @item @code{sw1 __SLASS (sw1, sw1)} | |
17039 | @tab @code{@var{c} = __SLASS (@var{a}, @var{b})} | |
17040 | @tab @code{SLASS @var{a},@var{b},@var{c}} | |
17041 | @item @code{void __SMASS (sw1, sw1)} | |
17042 | @tab @code{__SMASS (@var{a}, @var{b})} | |
17043 | @tab @code{SMASS @var{a},@var{b}} | |
17044 | @item @code{void __SMSSS (sw1, sw1)} | |
17045 | @tab @code{__SMSSS (@var{a}, @var{b})} | |
17046 | @tab @code{SMSSS @var{a},@var{b}} | |
17047 | @item @code{void __SMU (sw1, sw1)} | |
17048 | @tab @code{__SMU (@var{a}, @var{b})} | |
17049 | @tab @code{SMU @var{a},@var{b}} | |
17050 | @item @code{sw2 __SMUL (sw1, sw1)} | |
17051 | @tab @code{@var{c} = __SMUL (@var{a}, @var{b})} | |
17052 | @tab @code{SMUL @var{a},@var{b},@var{c}} | |
17053 | @item @code{sw1 __SUBSS (sw1, sw1)} | |
17054 | @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} | |
17055 | @tab @code{SUBSS @var{a},@var{b},@var{c}} | |
17056 | @item @code{uw2 __UMUL (uw1, uw1)} | |
17057 | @tab @code{@var{c} = __UMUL (@var{a}, @var{b})} | |
17058 | @tab @code{UMUL @var{a},@var{b},@var{c}} | |
17059 | @end multitable | |
17060 | ||
17061 | @node Directly-mapped Media Functions | |
17062 | @subsubsection Directly-Mapped Media Functions | |
17063 | ||
17064 | The functions listed below map directly to FR-V M-type instructions. | |
17065 | ||
17066 | @multitable @columnfractions .45 .32 .23 | |
17067 | @headitem Function prototype @tab Example usage @tab Assembly output | |
17068 | @item @code{uw1 __MABSHS (sw1)} | |
17069 | @tab @code{@var{b} = __MABSHS (@var{a})} | |
17070 | @tab @code{MABSHS @var{a},@var{b}} | |
17071 | @item @code{void __MADDACCS (acc, acc)} | |
17072 | @tab @code{__MADDACCS (@var{b}, @var{a})} | |
17073 | @tab @code{MADDACCS @var{a},@var{b}} | |
17074 | @item @code{sw1 __MADDHSS (sw1, sw1)} | |
17075 | @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} | |
17076 | @tab @code{MADDHSS @var{a},@var{b},@var{c}} | |
17077 | @item @code{uw1 __MADDHUS (uw1, uw1)} | |
17078 | @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} | |
17079 | @tab @code{MADDHUS @var{a},@var{b},@var{c}} | |
17080 | @item @code{uw1 __MAND (uw1, uw1)} | |
17081 | @tab @code{@var{c} = __MAND (@var{a}, @var{b})} | |
17082 | @tab @code{MAND @var{a},@var{b},@var{c}} | |
17083 | @item @code{void __MASACCS (acc, acc)} | |
17084 | @tab @code{__MASACCS (@var{b}, @var{a})} | |
17085 | @tab @code{MASACCS @var{a},@var{b}} | |
17086 | @item @code{uw1 __MAVEH (uw1, uw1)} | |
17087 | @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} | |
17088 | @tab @code{MAVEH @var{a},@var{b},@var{c}} | |
17089 | @item @code{uw2 __MBTOH (uw1)} | |
17090 | @tab @code{@var{b} = __MBTOH (@var{a})} | |
17091 | @tab @code{MBTOH @var{a},@var{b}} | |
17092 | @item @code{void __MBTOHE (uw1 *, uw1)} | |
17093 | @tab @code{__MBTOHE (&@var{b}, @var{a})} | |
17094 | @tab @code{MBTOHE @var{a},@var{b}} | |
17095 | @item @code{void __MCLRACC (acc)} | |
17096 | @tab @code{__MCLRACC (@var{a})} | |
17097 | @tab @code{MCLRACC @var{a}} | |
17098 | @item @code{void __MCLRACCA (void)} | |
17099 | @tab @code{__MCLRACCA ()} | |
17100 | @tab @code{MCLRACCA} | |
17101 | @item @code{uw1 __Mcop1 (uw1, uw1)} | |
17102 | @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} | |
17103 | @tab @code{Mcop1 @var{a},@var{b},@var{c}} | |
17104 | @item @code{uw1 __Mcop2 (uw1, uw1)} | |
17105 | @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} | |
17106 | @tab @code{Mcop2 @var{a},@var{b},@var{c}} | |
17107 | @item @code{uw1 __MCPLHI (uw2, const)} | |
17108 | @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} | |
17109 | @tab @code{MCPLHI @var{a},#@var{b},@var{c}} | |
17110 | @item @code{uw1 __MCPLI (uw2, const)} | |
17111 | @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} | |
17112 | @tab @code{MCPLI @var{a},#@var{b},@var{c}} | |
17113 | @item @code{void __MCPXIS (acc, sw1, sw1)} | |
17114 | @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} | |
17115 | @tab @code{MCPXIS @var{a},@var{b},@var{c}} | |
17116 | @item @code{void __MCPXIU (acc, uw1, uw1)} | |
17117 | @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} | |
17118 | @tab @code{MCPXIU @var{a},@var{b},@var{c}} | |
17119 | @item @code{void __MCPXRS (acc, sw1, sw1)} | |
17120 | @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} | |
17121 | @tab @code{MCPXRS @var{a},@var{b},@var{c}} | |
17122 | @item @code{void __MCPXRU (acc, uw1, uw1)} | |
17123 | @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} | |
17124 | @tab @code{MCPXRU @var{a},@var{b},@var{c}} | |
17125 | @item @code{uw1 __MCUT (acc, uw1)} | |
17126 | @tab @code{@var{c} = __MCUT (@var{a}, @var{b})} | |
17127 | @tab @code{MCUT @var{a},@var{b},@var{c}} | |
17128 | @item @code{uw1 __MCUTSS (acc, sw1)} | |
17129 | @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} | |
17130 | @tab @code{MCUTSS @var{a},@var{b},@var{c}} | |
17131 | @item @code{void __MDADDACCS (acc, acc)} | |
17132 | @tab @code{__MDADDACCS (@var{b}, @var{a})} | |
17133 | @tab @code{MDADDACCS @var{a},@var{b}} | |
17134 | @item @code{void __MDASACCS (acc, acc)} | |
17135 | @tab @code{__MDASACCS (@var{b}, @var{a})} | |
17136 | @tab @code{MDASACCS @var{a},@var{b}} | |
17137 | @item @code{uw2 __MDCUTSSI (acc, const)} | |
17138 | @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} | |
17139 | @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} | |
17140 | @item @code{uw2 __MDPACKH (uw2, uw2)} | |
17141 | @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} | |
17142 | @tab @code{MDPACKH @var{a},@var{b},@var{c}} | |
17143 | @item @code{uw2 __MDROTLI (uw2, const)} | |
17144 | @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} | |
17145 | @tab @code{MDROTLI @var{a},#@var{b},@var{c}} | |
17146 | @item @code{void __MDSUBACCS (acc, acc)} | |
17147 | @tab @code{__MDSUBACCS (@var{b}, @var{a})} | |
17148 | @tab @code{MDSUBACCS @var{a},@var{b}} | |
17149 | @item @code{void __MDUNPACKH (uw1 *, uw2)} | |
17150 | @tab @code{__MDUNPACKH (&@var{b}, @var{a})} | |
17151 | @tab @code{MDUNPACKH @var{a},@var{b}} | |
17152 | @item @code{uw2 __MEXPDHD (uw1, const)} | |
17153 | @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} | |
17154 | @tab @code{MEXPDHD @var{a},#@var{b},@var{c}} | |
17155 | @item @code{uw1 __MEXPDHW (uw1, const)} | |
17156 | @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} | |
17157 | @tab @code{MEXPDHW @var{a},#@var{b},@var{c}} | |
17158 | @item @code{uw1 __MHDSETH (uw1, const)} | |
17159 | @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} | |
17160 | @tab @code{MHDSETH @var{a},#@var{b},@var{c}} | |
17161 | @item @code{sw1 __MHDSETS (const)} | |
17162 | @tab @code{@var{b} = __MHDSETS (@var{a})} | |
17163 | @tab @code{MHDSETS #@var{a},@var{b}} | |
17164 | @item @code{uw1 __MHSETHIH (uw1, const)} | |
17165 | @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} | |
17166 | @tab @code{MHSETHIH #@var{a},@var{b}} | |
17167 | @item @code{sw1 __MHSETHIS (sw1, const)} | |
17168 | @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} | |
17169 | @tab @code{MHSETHIS #@var{a},@var{b}} | |
17170 | @item @code{uw1 __MHSETLOH (uw1, const)} | |
17171 | @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} | |
17172 | @tab @code{MHSETLOH #@var{a},@var{b}} | |
17173 | @item @code{sw1 __MHSETLOS (sw1, const)} | |
17174 | @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} | |
17175 | @tab @code{MHSETLOS #@var{a},@var{b}} | |
17176 | @item @code{uw1 __MHTOB (uw2)} | |
17177 | @tab @code{@var{b} = __MHTOB (@var{a})} | |
17178 | @tab @code{MHTOB @var{a},@var{b}} | |
17179 | @item @code{void __MMACHS (acc, sw1, sw1)} | |
17180 | @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} | |
17181 | @tab @code{MMACHS @var{a},@var{b},@var{c}} | |
17182 | @item @code{void __MMACHU (acc, uw1, uw1)} | |
17183 | @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} | |
17184 | @tab @code{MMACHU @var{a},@var{b},@var{c}} | |
17185 | @item @code{void __MMRDHS (acc, sw1, sw1)} | |
17186 | @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} | |
17187 | @tab @code{MMRDHS @var{a},@var{b},@var{c}} | |
17188 | @item @code{void __MMRDHU (acc, uw1, uw1)} | |
17189 | @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} | |
17190 | @tab @code{MMRDHU @var{a},@var{b},@var{c}} | |
17191 | @item @code{void __MMULHS (acc, sw1, sw1)} | |
17192 | @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} | |
17193 | @tab @code{MMULHS @var{a},@var{b},@var{c}} | |
17194 | @item @code{void __MMULHU (acc, uw1, uw1)} | |
17195 | @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} | |
17196 | @tab @code{MMULHU @var{a},@var{b},@var{c}} | |
17197 | @item @code{void __MMULXHS (acc, sw1, sw1)} | |
17198 | @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} | |
17199 | @tab @code{MMULXHS @var{a},@var{b},@var{c}} | |
17200 | @item @code{void __MMULXHU (acc, uw1, uw1)} | |
17201 | @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} | |
17202 | @tab @code{MMULXHU @var{a},@var{b},@var{c}} | |
17203 | @item @code{uw1 __MNOT (uw1)} | |
17204 | @tab @code{@var{b} = __MNOT (@var{a})} | |
17205 | @tab @code{MNOT @var{a},@var{b}} | |
17206 | @item @code{uw1 __MOR (uw1, uw1)} | |
17207 | @tab @code{@var{c} = __MOR (@var{a}, @var{b})} | |
17208 | @tab @code{MOR @var{a},@var{b},@var{c}} | |
17209 | @item @code{uw1 __MPACKH (uh, uh)} | |
17210 | @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} | |
17211 | @tab @code{MPACKH @var{a},@var{b},@var{c}} | |
17212 | @item @code{sw2 __MQADDHSS (sw2, sw2)} | |
17213 | @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} | |
17214 | @tab @code{MQADDHSS @var{a},@var{b},@var{c}} | |
17215 | @item @code{uw2 __MQADDHUS (uw2, uw2)} | |
17216 | @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} | |
17217 | @tab @code{MQADDHUS @var{a},@var{b},@var{c}} | |
17218 | @item @code{void __MQCPXIS (acc, sw2, sw2)} | |
17219 | @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} | |
17220 | @tab @code{MQCPXIS @var{a},@var{b},@var{c}} | |
17221 | @item @code{void __MQCPXIU (acc, uw2, uw2)} | |
17222 | @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} | |
17223 | @tab @code{MQCPXIU @var{a},@var{b},@var{c}} | |
17224 | @item @code{void __MQCPXRS (acc, sw2, sw2)} | |
17225 | @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} | |
17226 | @tab @code{MQCPXRS @var{a},@var{b},@var{c}} | |
17227 | @item @code{void __MQCPXRU (acc, uw2, uw2)} | |
17228 | @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} | |
17229 | @tab @code{MQCPXRU @var{a},@var{b},@var{c}} | |
17230 | @item @code{sw2 __MQLCLRHS (sw2, sw2)} | |
17231 | @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} | |
17232 | @tab @code{MQLCLRHS @var{a},@var{b},@var{c}} | |
17233 | @item @code{sw2 __MQLMTHS (sw2, sw2)} | |
17234 | @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} | |
17235 | @tab @code{MQLMTHS @var{a},@var{b},@var{c}} | |
17236 | @item @code{void __MQMACHS (acc, sw2, sw2)} | |
17237 | @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} | |
17238 | @tab @code{MQMACHS @var{a},@var{b},@var{c}} | |
17239 | @item @code{void __MQMACHU (acc, uw2, uw2)} | |
17240 | @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} | |
17241 | @tab @code{MQMACHU @var{a},@var{b},@var{c}} | |
17242 | @item @code{void __MQMACXHS (acc, sw2, sw2)} | |
17243 | @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} | |
17244 | @tab @code{MQMACXHS @var{a},@var{b},@var{c}} | |
17245 | @item @code{void __MQMULHS (acc, sw2, sw2)} | |
17246 | @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} | |
17247 | @tab @code{MQMULHS @var{a},@var{b},@var{c}} | |
17248 | @item @code{void __MQMULHU (acc, uw2, uw2)} | |
17249 | @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} | |
17250 | @tab @code{MQMULHU @var{a},@var{b},@var{c}} | |
17251 | @item @code{void __MQMULXHS (acc, sw2, sw2)} | |
17252 | @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} | |
17253 | @tab @code{MQMULXHS @var{a},@var{b},@var{c}} | |
17254 | @item @code{void __MQMULXHU (acc, uw2, uw2)} | |
17255 | @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} | |
17256 | @tab @code{MQMULXHU @var{a},@var{b},@var{c}} | |
17257 | @item @code{sw2 __MQSATHS (sw2, sw2)} | |
17258 | @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} | |
17259 | @tab @code{MQSATHS @var{a},@var{b},@var{c}} | |
17260 | @item @code{uw2 __MQSLLHI (uw2, int)} | |
17261 | @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} | |
17262 | @tab @code{MQSLLHI @var{a},@var{b},@var{c}} | |
17263 | @item @code{sw2 __MQSRAHI (sw2, int)} | |
17264 | @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} | |
17265 | @tab @code{MQSRAHI @var{a},@var{b},@var{c}} | |
17266 | @item @code{sw2 __MQSUBHSS (sw2, sw2)} | |
17267 | @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} | |
17268 | @tab @code{MQSUBHSS @var{a},@var{b},@var{c}} | |
17269 | @item @code{uw2 __MQSUBHUS (uw2, uw2)} | |
17270 | @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} | |
17271 | @tab @code{MQSUBHUS @var{a},@var{b},@var{c}} | |
17272 | @item @code{void __MQXMACHS (acc, sw2, sw2)} | |
17273 | @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} | |
17274 | @tab @code{MQXMACHS @var{a},@var{b},@var{c}} | |
17275 | @item @code{void __MQXMACXHS (acc, sw2, sw2)} | |
17276 | @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} | |
17277 | @tab @code{MQXMACXHS @var{a},@var{b},@var{c}} | |
17278 | @item @code{uw1 __MRDACC (acc)} | |
17279 | @tab @code{@var{b} = __MRDACC (@var{a})} | |
17280 | @tab @code{MRDACC @var{a},@var{b}} | |
17281 | @item @code{uw1 __MRDACCG (acc)} | |
17282 | @tab @code{@var{b} = __MRDACCG (@var{a})} | |
17283 | @tab @code{MRDACCG @var{a},@var{b}} | |
17284 | @item @code{uw1 __MROTLI (uw1, const)} | |
17285 | @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} | |
17286 | @tab @code{MROTLI @var{a},#@var{b},@var{c}} | |
17287 | @item @code{uw1 __MROTRI (uw1, const)} | |
17288 | @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} | |
17289 | @tab @code{MROTRI @var{a},#@var{b},@var{c}} | |
17290 | @item @code{sw1 __MSATHS (sw1, sw1)} | |
17291 | @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} | |
17292 | @tab @code{MSATHS @var{a},@var{b},@var{c}} | |
17293 | @item @code{uw1 __MSATHU (uw1, uw1)} | |
17294 | @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} | |
17295 | @tab @code{MSATHU @var{a},@var{b},@var{c}} | |
17296 | @item @code{uw1 __MSLLHI (uw1, const)} | |
17297 | @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} | |
17298 | @tab @code{MSLLHI @var{a},#@var{b},@var{c}} | |
17299 | @item @code{sw1 __MSRAHI (sw1, const)} | |
17300 | @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} | |
17301 | @tab @code{MSRAHI @var{a},#@var{b},@var{c}} | |
17302 | @item @code{uw1 __MSRLHI (uw1, const)} | |
17303 | @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} | |
17304 | @tab @code{MSRLHI @var{a},#@var{b},@var{c}} | |
17305 | @item @code{void __MSUBACCS (acc, acc)} | |
17306 | @tab @code{__MSUBACCS (@var{b}, @var{a})} | |
17307 | @tab @code{MSUBACCS @var{a},@var{b}} | |
17308 | @item @code{sw1 __MSUBHSS (sw1, sw1)} | |
17309 | @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} | |
17310 | @tab @code{MSUBHSS @var{a},@var{b},@var{c}} | |
17311 | @item @code{uw1 __MSUBHUS (uw1, uw1)} | |
17312 | @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} | |
17313 | @tab @code{MSUBHUS @var{a},@var{b},@var{c}} | |
17314 | @item @code{void __MTRAP (void)} | |
17315 | @tab @code{__MTRAP ()} | |
17316 | @tab @code{MTRAP} | |
17317 | @item @code{uw2 __MUNPACKH (uw1)} | |
17318 | @tab @code{@var{b} = __MUNPACKH (@var{a})} | |
17319 | @tab @code{MUNPACKH @var{a},@var{b}} | |
17320 | @item @code{uw1 __MWCUT (uw2, uw1)} | |
17321 | @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} | |
17322 | @tab @code{MWCUT @var{a},@var{b},@var{c}} | |
17323 | @item @code{void __MWTACC (acc, uw1)} | |
17324 | @tab @code{__MWTACC (@var{b}, @var{a})} | |
17325 | @tab @code{MWTACC @var{a},@var{b}} | |
17326 | @item @code{void __MWTACCG (acc, uw1)} | |
17327 | @tab @code{__MWTACCG (@var{b}, @var{a})} | |
17328 | @tab @code{MWTACCG @var{a},@var{b}} | |
17329 | @item @code{uw1 __MXOR (uw1, uw1)} | |
17330 | @tab @code{@var{c} = __MXOR (@var{a}, @var{b})} | |
17331 | @tab @code{MXOR @var{a},@var{b},@var{c}} | |
17332 | @end multitable | |
17333 | ||
17334 | @node Raw read/write Functions | |
17335 | @subsubsection Raw Read/Write Functions | |
17336 | ||
17337 | This sections describes built-in functions related to read and write | |
17338 | instructions to access memory. These functions generate | |
17339 | @code{membar} instructions to flush the I/O load and stores where | |
17340 | appropriate, as described in Fujitsu's manual described above. | |
17341 | ||
17342 | @table @code | |
17343 | ||
17344 | @item unsigned char __builtin_read8 (void *@var{data}) | |
17345 | @item unsigned short __builtin_read16 (void *@var{data}) | |
17346 | @item unsigned long __builtin_read32 (void *@var{data}) | |
17347 | @item unsigned long long __builtin_read64 (void *@var{data}) | |
17348 | ||
17349 | @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) | |
17350 | @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) | |
17351 | @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) | |
17352 | @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) | |
17353 | @end table | |
17354 | ||
17355 | @node Other Built-in Functions | |
17356 | @subsubsection Other Built-in Functions | |
17357 | ||
17358 | This section describes built-in functions that are not named after | |
17359 | a specific FR-V instruction. | |
17360 | ||
17361 | @table @code | |
17362 | @item sw2 __IACCreadll (iacc @var{reg}) | |
17363 | Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved | |
17364 | for future expansion and must be 0. | |
17365 | ||
17366 | @item sw1 __IACCreadl (iacc @var{reg}) | |
17367 | Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. | |
17368 | Other values of @var{reg} are rejected as invalid. | |
17369 | ||
17370 | @item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) | |
17371 | Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument | |
17372 | is reserved for future expansion and must be 0. | |
17373 | ||
17374 | @item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) | |
17375 | Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} | |
17376 | is 1. Other values of @var{reg} are rejected as invalid. | |
17377 | ||
17378 | @item void __data_prefetch0 (const void *@var{x}) | |
17379 | Use the @code{dcpl} instruction to load the contents of address @var{x} | |
17380 | into the data cache. | |
17381 | ||
17382 | @item void __data_prefetch (const void *@var{x}) | |
17383 | Use the @code{nldub} instruction to load the contents of address @var{x} | |
17384 | into the data cache. The instruction is issued in slot I1@. | |
17385 | @end table | |
17386 | ||
5015cdf3 LC |
17387 | @node LoongArch Base Built-in Functions |
17388 | @subsection LoongArch Base Built-in Functions | |
17389 | ||
17390 | These built-in functions are available for LoongArch. | |
17391 | ||
17392 | Data Type Description: | |
17393 | @itemize | |
17394 | @item @code{imm0_31}, a compile-time constant in range 0 to 31; | |
17395 | @item @code{imm0_16383}, a compile-time constant in range 0 to 16383; | |
17396 | @item @code{imm0_32767}, a compile-time constant in range 0 to 32767; | |
17397 | @item @code{imm_n2048_2047}, a compile-time constant in range -2048 to 2047; | |
17398 | @end itemize | |
17399 | ||
17400 | The intrinsics provided are listed below: | |
17401 | @smallexample | |
17402 | unsigned int __builtin_loongarch_movfcsr2gr (imm0_31) | |
17403 | void __builtin_loongarch_movgr2fcsr (imm0_31, unsigned int) | |
17404 | void __builtin_loongarch_cacop_d (imm0_31, unsigned long int, imm_n2048_2047) | |
17405 | unsigned int __builtin_loongarch_cpucfg (unsigned int) | |
17406 | void __builtin_loongarch_asrtle_d (long int, long int) | |
17407 | void __builtin_loongarch_asrtgt_d (long int, long int) | |
17408 | long int __builtin_loongarch_lddir_d (long int, imm0_31) | |
17409 | void __builtin_loongarch_ldpte_d (long int, imm0_31) | |
17410 | ||
17411 | int __builtin_loongarch_crc_w_b_w (char, int) | |
17412 | int __builtin_loongarch_crc_w_h_w (short, int) | |
17413 | int __builtin_loongarch_crc_w_w_w (int, int) | |
17414 | int __builtin_loongarch_crc_w_d_w (long int, int) | |
17415 | int __builtin_loongarch_crcc_w_b_w (char, int) | |
17416 | int __builtin_loongarch_crcc_w_h_w (short, int) | |
17417 | int __builtin_loongarch_crcc_w_w_w (int, int) | |
17418 | int __builtin_loongarch_crcc_w_d_w (long int, int) | |
17419 | ||
17420 | unsigned int __builtin_loongarch_csrrd_w (imm0_16383) | |
17421 | unsigned int __builtin_loongarch_csrwr_w (unsigned int, imm0_16383) | |
17422 | unsigned int __builtin_loongarch_csrxchg_w (unsigned int, unsigned int, imm0_16383) | |
17423 | unsigned long int __builtin_loongarch_csrrd_d (imm0_16383) | |
17424 | unsigned long int __builtin_loongarch_csrwr_d (unsigned long int, imm0_16383) | |
17425 | unsigned long int __builtin_loongarch_csrxchg_d (unsigned long int, unsigned long int, imm0_16383) | |
17426 | ||
17427 | unsigned char __builtin_loongarch_iocsrrd_b (unsigned int) | |
17428 | unsigned short __builtin_loongarch_iocsrrd_h (unsigned int) | |
17429 | unsigned int __builtin_loongarch_iocsrrd_w (unsigned int) | |
17430 | unsigned long int __builtin_loongarch_iocsrrd_d (unsigned int) | |
17431 | void __builtin_loongarch_iocsrwr_b (unsigned char, unsigned int) | |
17432 | void __builtin_loongarch_iocsrwr_h (unsigned short, unsigned int) | |
17433 | void __builtin_loongarch_iocsrwr_w (unsigned int, unsigned int) | |
17434 | void __builtin_loongarch_iocsrwr_d (unsigned long int, unsigned int) | |
17435 | ||
17436 | void __builtin_loongarch_dbar (imm0_32767) | |
17437 | void __builtin_loongarch_ibar (imm0_32767) | |
17438 | ||
17439 | void __builtin_loongarch_syscall (imm0_32767) | |
17440 | void __builtin_loongarch_break (imm0_32767) | |
17441 | @end smallexample | |
17442 | ||
61f1001f JX |
17443 | These instrisic functions are available by using @option{-mfrecipe}. |
17444 | @smallexample | |
17445 | float __builtin_loongarch_frecipe_s (float); | |
17446 | double __builtin_loongarch_frecipe_d (double); | |
17447 | float __builtin_loongarch_frsqrte_s (float); | |
17448 | double __builtin_loongarch_frsqrte_d (double); | |
17449 | @end smallexample | |
17450 | ||
5015cdf3 LC |
17451 | @emph{Note:}Since the control register is divided into 32-bit and 64-bit, |
17452 | but the access instruction is not distinguished. So GCC renames the control | |
17453 | instructions when implementing intrinsics. | |
17454 | ||
17455 | Take the csrrd instruction as an example, built-in functions are implemented as follows: | |
17456 | @smallexample | |
17457 | __builtin_loongarch_csrrd_w // When reading the 32-bit control register use. | |
17458 | __builtin_loongarch_csrrd_d // When reading the 64-bit control register use. | |
17459 | @end smallexample | |
17460 | ||
17461 | For the convenience of use, the built-in functions are encapsulated, | |
17462 | the encapsulated functions and @code{__drdtime_t, __rdtime_t} are | |
17463 | defined in the @code{larchintrin.h}. So if you call the following | |
17464 | function you need to include @code{larchintrin.h}. | |
17465 | ||
17466 | @smallexample | |
17467 | typedef struct drdtime@{ | |
17468 | unsigned long dvalue; | |
17469 | unsigned long dtimeid; | |
17470 | @} __drdtime_t; | |
17471 | ||
17472 | typedef struct rdtime@{ | |
17473 | unsigned int value; | |
17474 | unsigned int timeid; | |
17475 | @} __rdtime_t; | |
17476 | @end smallexample | |
17477 | ||
17478 | @smallexample | |
17479 | __drdtime_t __rdtime_d (void) | |
17480 | __rdtime_t __rdtimel_w (void) | |
17481 | __rdtime_t __rdtimeh_w (void) | |
17482 | unsigned int __movfcsr2gr (imm0_31) | |
17483 | void __movgr2fcsr (imm0_31, unsigned int) | |
17484 | void __cacop_d (imm0_31, unsigned long, imm_n2048_2047) | |
17485 | unsigned int __cpucfg (unsigned int) | |
17486 | void __asrtle_d (long int, long int) | |
17487 | void __asrtgt_d (long int, long int) | |
17488 | long int __lddir_d (long int, imm0_31) | |
17489 | void __ldpte_d (long int, imm0_31) | |
17490 | ||
17491 | int __crc_w_b_w (char, int) | |
17492 | int __crc_w_h_w (short, int) | |
17493 | int __crc_w_w_w (int, int) | |
17494 | int __crc_w_d_w (long int, int) | |
17495 | int __crcc_w_b_w (char, int) | |
17496 | int __crcc_w_h_w (short, int) | |
17497 | int __crcc_w_w_w (int, int) | |
17498 | int __crcc_w_d_w (long int, int) | |
17499 | ||
17500 | unsigned int __csrrd_w (imm0_16383) | |
17501 | unsigned int __csrwr_w (unsigned int, imm0_16383) | |
17502 | unsigned int __csrxchg_w (unsigned int, unsigned int, imm0_16383) | |
17503 | unsigned long __csrrd_d (imm0_16383) | |
17504 | unsigned long __csrwr_d (unsigned long, imm0_16383) | |
17505 | unsigned long __csrxchg_d (unsigned long, unsigned long, imm0_16383) | |
17506 | ||
17507 | unsigned char __iocsrrd_b (unsigned int) | |
17508 | unsigned short __iocsrrd_h (unsigned int) | |
17509 | unsigned int __iocsrrd_w (unsigned int) | |
17510 | unsigned long __iocsrrd_d (unsigned int) | |
17511 | void __iocsrwr_b (unsigned char, unsigned int) | |
17512 | void __iocsrwr_h (unsigned short, unsigned int) | |
17513 | void __iocsrwr_w (unsigned int, unsigned int) | |
17514 | void __iocsrwr_d (unsigned long, unsigned int) | |
17515 | ||
17516 | void __dbar (imm0_32767) | |
17517 | void __ibar (imm0_32767) | |
17518 | ||
17519 | void __syscall (imm0_32767) | |
17520 | void __break (imm0_32767) | |
17521 | @end smallexample | |
17522 | ||
61f1001f JX |
17523 | These instrisic functions are available by including @code{larchintrin.h} and |
17524 | using @option{-mfrecipe}. | |
17525 | @smallexample | |
17526 | float __frecipe_s (float); | |
17527 | double __frecipe_d (double); | |
17528 | float __frsqrte_s (float); | |
17529 | double __frsqrte_d (double); | |
17530 | @end smallexample | |
17531 | ||
4e2d53c9 | 17532 | Additional built-in functions are available for LoongArch family |
17533 | processors to efficiently use 128-bit floating-point (__float128) | |
17534 | values. | |
17535 | ||
17536 | The following are the basic built-in functions supported. | |
17537 | @smallexample | |
17538 | __float128 __builtin_fabsq (__float128); | |
17539 | __float128 __builtin_copysignq (__float128, __float128); | |
17540 | __float128 __builtin_infq (void); | |
17541 | __float128 __builtin_huge_valq (void); | |
17542 | __float128 __builtin_nanq (void); | |
17543 | __float128 __builtin_nansq (void); | |
17544 | @end smallexample | |
17545 | ||
1b30ef7c | 17546 | Returns the value that is currently set in the @samp{tp} register. |
17547 | @smallexample | |
17548 | void * __builtin_thread_pointer (void) | |
17549 | @end smallexample | |
17550 | ||
1f48786d | 17551 | @node LoongArch SX Vector Intrinsics |
17552 | @subsection LoongArch SX Vector Intrinsics | |
17553 | ||
17554 | GCC provides intrinsics to access the LSX (Loongson SIMD Extension) instructions. | |
17555 | The interface is made available by including @code{<lsxintrin.h>} and using | |
17556 | @option{-mlsx}. | |
17557 | ||
17558 | The following vectors typedefs are included in @code{lsxintrin.h}: | |
17559 | ||
17560 | @itemize | |
17561 | @item @code{__m128i}, a 128-bit vector of fixed point; | |
17562 | @item @code{__m128}, a 128-bit vector of single precision floating point; | |
17563 | @item @code{__m128d}, a 128-bit vector of double precision floating point. | |
17564 | @end itemize | |
17565 | ||
17566 | Instructions and corresponding built-ins may have additional restrictions and/or | |
17567 | input/output values manipulated: | |
17568 | @itemize | |
17569 | @item @code{imm0_1}, an integer literal in range 0 to 1; | |
17570 | @item @code{imm0_3}, an integer literal in range 0 to 3; | |
17571 | @item @code{imm0_7}, an integer literal in range 0 to 7; | |
17572 | @item @code{imm0_15}, an integer literal in range 0 to 15; | |
17573 | @item @code{imm0_31}, an integer literal in range 0 to 31; | |
17574 | @item @code{imm0_63}, an integer literal in range 0 to 63; | |
17575 | @item @code{imm0_127}, an integer literal in range 0 to 127; | |
17576 | @item @code{imm0_255}, an integer literal in range 0 to 255; | |
17577 | @item @code{imm_n16_15}, an integer literal in range -16 to 15; | |
17578 | @item @code{imm_n128_127}, an integer literal in range -128 to 127; | |
17579 | @item @code{imm_n256_255}, an integer literal in range -256 to 255; | |
17580 | @item @code{imm_n512_511}, an integer literal in range -512 to 511; | |
17581 | @item @code{imm_n1024_1023}, an integer literal in range -1024 to 1023; | |
17582 | @item @code{imm_n2048_2047}, an integer literal in range -2048 to 2047. | |
17583 | @end itemize | |
17584 | ||
17585 | For convenience, GCC defines functions @code{__lsx_vrepli_@{b/h/w/d@}} and | |
17586 | @code{__lsx_b[n]z_@{v/b/h/w/d@}}, which are implemented as follows: | |
17587 | ||
17588 | @smallexample | |
17589 | a. @code{__lsx_vrepli_@{b/h/w/d@}}: Implemented the case where the highest | |
17590 | bit of @code{vldi} instruction @code{i13} is 1. | |
17591 | ||
17592 | i13[12] == 1'b0 | |
17593 | case i13[11:10] of : | |
17594 | 2'b00: __lsx_vrepli_b (imm_n512_511) | |
17595 | 2'b01: __lsx_vrepli_h (imm_n512_511) | |
17596 | 2'b10: __lsx_vrepli_w (imm_n512_511) | |
17597 | 2'b11: __lsx_vrepli_d (imm_n512_511) | |
17598 | ||
17599 | b. @code{__lsx_b[n]z_@{v/b/h/w/d@}}: Since the @code{vseteqz} class directive | |
17600 | cannot be used on its own, this function is defined. | |
17601 | ||
17602 | _lsx_bz_v => vseteqz.v + bcnez | |
17603 | _lsx_bnz_v => vsetnez.v + bcnez | |
17604 | _lsx_bz_b => vsetanyeqz.b + bcnez | |
17605 | _lsx_bz_h => vsetanyeqz.h + bcnez | |
17606 | _lsx_bz_w => vsetanyeqz.w + bcnez | |
17607 | _lsx_bz_d => vsetanyeqz.d + bcnez | |
17608 | _lsx_bnz_b => vsetallnez.b + bcnez | |
17609 | _lsx_bnz_h => vsetallnez.h + bcnez | |
17610 | _lsx_bnz_w => vsetallnez.w + bcnez | |
17611 | _lsx_bnz_d => vsetallnez.d + bcnez | |
17612 | @end smallexample | |
17613 | ||
17614 | @smallexample | |
17615 | eg: | |
17616 | #include <lsxintrin.h> | |
17617 | ||
17618 | extern __m128i @var{a}; | |
17619 | ||
17620 | void | |
17621 | test (void) | |
17622 | @{ | |
17623 | if (__lsx_bz_v (@var{a})) | |
17624 | printf ("1\n"); | |
17625 | else | |
17626 | printf ("2\n"); | |
17627 | @} | |
17628 | @end smallexample | |
17629 | ||
17630 | @emph{Note:} For directives where the intent operand is also the source operand | |
17631 | (modifying only part of the bitfield of the intent register), the first parameter | |
17632 | in the builtin call function is used as the intent operand. | |
17633 | ||
17634 | @smallexample | |
17635 | eg: | |
17636 | #include <lsxintrin.h> | |
17637 | ||
17638 | extern __m128i @var{dst}; | |
17639 | extern int @var{src}; | |
17640 | ||
17641 | void | |
17642 | test (void) | |
17643 | @{ | |
17644 | @var{dst} = __lsx_vinsgr2vr_b (@var{dst}, @var{src}, 3); | |
17645 | @} | |
17646 | @end smallexample | |
17647 | ||
17648 | The intrinsics provided are listed below: | |
17649 | @smallexample | |
17650 | int __lsx_bnz_b (__m128i); | |
17651 | int __lsx_bnz_d (__m128i); | |
17652 | int __lsx_bnz_h (__m128i); | |
17653 | int __lsx_bnz_v (__m128i); | |
17654 | int __lsx_bnz_w (__m128i); | |
17655 | int __lsx_bz_b (__m128i); | |
17656 | int __lsx_bz_d (__m128i); | |
17657 | int __lsx_bz_h (__m128i); | |
17658 | int __lsx_bz_v (__m128i); | |
17659 | int __lsx_bz_w (__m128i); | |
17660 | __m128i __lsx_vabsd_b (__m128i, __m128i); | |
17661 | __m128i __lsx_vabsd_bu (__m128i, __m128i); | |
84ad1b53 | 17662 | __m128i __lsx_vabsd_d (__m128i, __m128i); |
1f48786d | 17663 | __m128i __lsx_vabsd_du (__m128i, __m128i); |
17664 | __m128i __lsx_vabsd_h (__m128i, __m128i); | |
17665 | __m128i __lsx_vabsd_hu (__m128i, __m128i); | |
17666 | __m128i __lsx_vabsd_w (__m128i, __m128i); | |
17667 | __m128i __lsx_vabsd_wu (__m128i, __m128i); | |
17668 | __m128i __lsx_vadda_b (__m128i, __m128i); | |
17669 | __m128i __lsx_vadda_d (__m128i, __m128i); | |
17670 | __m128i __lsx_vadda_h (__m128i, __m128i); | |
17671 | __m128i __lsx_vadda_w (__m128i, __m128i); | |
17672 | __m128i __lsx_vadd_b (__m128i, __m128i); | |
17673 | __m128i __lsx_vadd_d (__m128i, __m128i); | |
17674 | __m128i __lsx_vadd_h (__m128i, __m128i); | |
17675 | __m128i __lsx_vaddi_bu (__m128i, imm0_31); | |
17676 | __m128i __lsx_vaddi_du (__m128i, imm0_31); | |
17677 | __m128i __lsx_vaddi_hu (__m128i, imm0_31); | |
17678 | __m128i __lsx_vaddi_wu (__m128i, imm0_31); | |
17679 | __m128i __lsx_vadd_q (__m128i, __m128i); | |
17680 | __m128i __lsx_vadd_w (__m128i, __m128i); | |
17681 | __m128i __lsx_vaddwev_d_w (__m128i, __m128i); | |
17682 | __m128i __lsx_vaddwev_d_wu (__m128i, __m128i); | |
17683 | __m128i __lsx_vaddwev_d_wu_w (__m128i, __m128i); | |
17684 | __m128i __lsx_vaddwev_h_b (__m128i, __m128i); | |
17685 | __m128i __lsx_vaddwev_h_bu (__m128i, __m128i); | |
17686 | __m128i __lsx_vaddwev_h_bu_b (__m128i, __m128i); | |
17687 | __m128i __lsx_vaddwev_q_d (__m128i, __m128i); | |
17688 | __m128i __lsx_vaddwev_q_du (__m128i, __m128i); | |
17689 | __m128i __lsx_vaddwev_q_du_d (__m128i, __m128i); | |
17690 | __m128i __lsx_vaddwev_w_h (__m128i, __m128i); | |
17691 | __m128i __lsx_vaddwev_w_hu (__m128i, __m128i); | |
17692 | __m128i __lsx_vaddwev_w_hu_h (__m128i, __m128i); | |
17693 | __m128i __lsx_vaddwod_d_w (__m128i, __m128i); | |
17694 | __m128i __lsx_vaddwod_d_wu (__m128i, __m128i); | |
17695 | __m128i __lsx_vaddwod_d_wu_w (__m128i, __m128i); | |
17696 | __m128i __lsx_vaddwod_h_b (__m128i, __m128i); | |
17697 | __m128i __lsx_vaddwod_h_bu (__m128i, __m128i); | |
17698 | __m128i __lsx_vaddwod_h_bu_b (__m128i, __m128i); | |
17699 | __m128i __lsx_vaddwod_q_d (__m128i, __m128i); | |
17700 | __m128i __lsx_vaddwod_q_du (__m128i, __m128i); | |
17701 | __m128i __lsx_vaddwod_q_du_d (__m128i, __m128i); | |
17702 | __m128i __lsx_vaddwod_w_h (__m128i, __m128i); | |
17703 | __m128i __lsx_vaddwod_w_hu (__m128i, __m128i); | |
17704 | __m128i __lsx_vaddwod_w_hu_h (__m128i, __m128i); | |
17705 | __m128i __lsx_vandi_b (__m128i, imm0_255); | |
17706 | __m128i __lsx_vandn_v (__m128i, __m128i); | |
17707 | __m128i __lsx_vand_v (__m128i, __m128i); | |
17708 | __m128i __lsx_vavg_b (__m128i, __m128i); | |
17709 | __m128i __lsx_vavg_bu (__m128i, __m128i); | |
17710 | __m128i __lsx_vavg_d (__m128i, __m128i); | |
17711 | __m128i __lsx_vavg_du (__m128i, __m128i); | |
17712 | __m128i __lsx_vavg_h (__m128i, __m128i); | |
17713 | __m128i __lsx_vavg_hu (__m128i, __m128i); | |
17714 | __m128i __lsx_vavgr_b (__m128i, __m128i); | |
17715 | __m128i __lsx_vavgr_bu (__m128i, __m128i); | |
17716 | __m128i __lsx_vavgr_d (__m128i, __m128i); | |
17717 | __m128i __lsx_vavgr_du (__m128i, __m128i); | |
17718 | __m128i __lsx_vavgr_h (__m128i, __m128i); | |
17719 | __m128i __lsx_vavgr_hu (__m128i, __m128i); | |
17720 | __m128i __lsx_vavgr_w (__m128i, __m128i); | |
17721 | __m128i __lsx_vavgr_wu (__m128i, __m128i); | |
17722 | __m128i __lsx_vavg_w (__m128i, __m128i); | |
17723 | __m128i __lsx_vavg_wu (__m128i, __m128i); | |
17724 | __m128i __lsx_vbitclr_b (__m128i, __m128i); | |
17725 | __m128i __lsx_vbitclr_d (__m128i, __m128i); | |
17726 | __m128i __lsx_vbitclr_h (__m128i, __m128i); | |
17727 | __m128i __lsx_vbitclri_b (__m128i, imm0_7); | |
17728 | __m128i __lsx_vbitclri_d (__m128i, imm0_63); | |
17729 | __m128i __lsx_vbitclri_h (__m128i, imm0_15); | |
17730 | __m128i __lsx_vbitclri_w (__m128i, imm0_31); | |
17731 | __m128i __lsx_vbitclr_w (__m128i, __m128i); | |
17732 | __m128i __lsx_vbitrev_b (__m128i, __m128i); | |
17733 | __m128i __lsx_vbitrev_d (__m128i, __m128i); | |
17734 | __m128i __lsx_vbitrev_h (__m128i, __m128i); | |
17735 | __m128i __lsx_vbitrevi_b (__m128i, imm0_7); | |
17736 | __m128i __lsx_vbitrevi_d (__m128i, imm0_63); | |
17737 | __m128i __lsx_vbitrevi_h (__m128i, imm0_15); | |
17738 | __m128i __lsx_vbitrevi_w (__m128i, imm0_31); | |
17739 | __m128i __lsx_vbitrev_w (__m128i, __m128i); | |
17740 | __m128i __lsx_vbitseli_b (__m128i, __m128i, imm0_255); | |
17741 | __m128i __lsx_vbitsel_v (__m128i, __m128i, __m128i); | |
17742 | __m128i __lsx_vbitset_b (__m128i, __m128i); | |
17743 | __m128i __lsx_vbitset_d (__m128i, __m128i); | |
17744 | __m128i __lsx_vbitset_h (__m128i, __m128i); | |
17745 | __m128i __lsx_vbitseti_b (__m128i, imm0_7); | |
17746 | __m128i __lsx_vbitseti_d (__m128i, imm0_63); | |
17747 | __m128i __lsx_vbitseti_h (__m128i, imm0_15); | |
17748 | __m128i __lsx_vbitseti_w (__m128i, imm0_31); | |
17749 | __m128i __lsx_vbitset_w (__m128i, __m128i); | |
17750 | __m128i __lsx_vbsll_v (__m128i, imm0_31); | |
17751 | __m128i __lsx_vbsrl_v (__m128i, imm0_31); | |
17752 | __m128i __lsx_vclo_b (__m128i); | |
17753 | __m128i __lsx_vclo_d (__m128i); | |
17754 | __m128i __lsx_vclo_h (__m128i); | |
17755 | __m128i __lsx_vclo_w (__m128i); | |
17756 | __m128i __lsx_vclz_b (__m128i); | |
17757 | __m128i __lsx_vclz_d (__m128i); | |
17758 | __m128i __lsx_vclz_h (__m128i); | |
17759 | __m128i __lsx_vclz_w (__m128i); | |
17760 | __m128i __lsx_vdiv_b (__m128i, __m128i); | |
17761 | __m128i __lsx_vdiv_bu (__m128i, __m128i); | |
17762 | __m128i __lsx_vdiv_d (__m128i, __m128i); | |
17763 | __m128i __lsx_vdiv_du (__m128i, __m128i); | |
17764 | __m128i __lsx_vdiv_h (__m128i, __m128i); | |
17765 | __m128i __lsx_vdiv_hu (__m128i, __m128i); | |
17766 | __m128i __lsx_vdiv_w (__m128i, __m128i); | |
17767 | __m128i __lsx_vdiv_wu (__m128i, __m128i); | |
17768 | __m128i __lsx_vexth_du_wu (__m128i); | |
17769 | __m128i __lsx_vexth_d_w (__m128i); | |
17770 | __m128i __lsx_vexth_h_b (__m128i); | |
17771 | __m128i __lsx_vexth_hu_bu (__m128i); | |
17772 | __m128i __lsx_vexth_q_d (__m128i); | |
17773 | __m128i __lsx_vexth_qu_du (__m128i); | |
17774 | __m128i __lsx_vexth_w_h (__m128i); | |
17775 | __m128i __lsx_vexth_wu_hu (__m128i); | |
17776 | __m128i __lsx_vextl_q_d (__m128i); | |
17777 | __m128i __lsx_vextl_qu_du (__m128i); | |
17778 | __m128i __lsx_vextrins_b (__m128i, __m128i, imm0_255); | |
17779 | __m128i __lsx_vextrins_d (__m128i, __m128i, imm0_255); | |
17780 | __m128i __lsx_vextrins_h (__m128i, __m128i, imm0_255); | |
17781 | __m128i __lsx_vextrins_w (__m128i, __m128i, imm0_255); | |
17782 | __m128d __lsx_vfadd_d (__m128d, __m128d); | |
17783 | __m128 __lsx_vfadd_s (__m128, __m128); | |
17784 | __m128i __lsx_vfclass_d (__m128d); | |
17785 | __m128i __lsx_vfclass_s (__m128); | |
17786 | __m128i __lsx_vfcmp_caf_d (__m128d, __m128d); | |
17787 | __m128i __lsx_vfcmp_caf_s (__m128, __m128); | |
17788 | __m128i __lsx_vfcmp_ceq_d (__m128d, __m128d); | |
17789 | __m128i __lsx_vfcmp_ceq_s (__m128, __m128); | |
17790 | __m128i __lsx_vfcmp_cle_d (__m128d, __m128d); | |
17791 | __m128i __lsx_vfcmp_cle_s (__m128, __m128); | |
17792 | __m128i __lsx_vfcmp_clt_d (__m128d, __m128d); | |
17793 | __m128i __lsx_vfcmp_clt_s (__m128, __m128); | |
17794 | __m128i __lsx_vfcmp_cne_d (__m128d, __m128d); | |
17795 | __m128i __lsx_vfcmp_cne_s (__m128, __m128); | |
17796 | __m128i __lsx_vfcmp_cor_d (__m128d, __m128d); | |
17797 | __m128i __lsx_vfcmp_cor_s (__m128, __m128); | |
17798 | __m128i __lsx_vfcmp_cueq_d (__m128d, __m128d); | |
17799 | __m128i __lsx_vfcmp_cueq_s (__m128, __m128); | |
17800 | __m128i __lsx_vfcmp_cule_d (__m128d, __m128d); | |
17801 | __m128i __lsx_vfcmp_cule_s (__m128, __m128); | |
17802 | __m128i __lsx_vfcmp_cult_d (__m128d, __m128d); | |
17803 | __m128i __lsx_vfcmp_cult_s (__m128, __m128); | |
17804 | __m128i __lsx_vfcmp_cun_d (__m128d, __m128d); | |
17805 | __m128i __lsx_vfcmp_cune_d (__m128d, __m128d); | |
17806 | __m128i __lsx_vfcmp_cune_s (__m128, __m128); | |
17807 | __m128i __lsx_vfcmp_cun_s (__m128, __m128); | |
17808 | __m128i __lsx_vfcmp_saf_d (__m128d, __m128d); | |
17809 | __m128i __lsx_vfcmp_saf_s (__m128, __m128); | |
17810 | __m128i __lsx_vfcmp_seq_d (__m128d, __m128d); | |
17811 | __m128i __lsx_vfcmp_seq_s (__m128, __m128); | |
17812 | __m128i __lsx_vfcmp_sle_d (__m128d, __m128d); | |
17813 | __m128i __lsx_vfcmp_sle_s (__m128, __m128); | |
17814 | __m128i __lsx_vfcmp_slt_d (__m128d, __m128d); | |
17815 | __m128i __lsx_vfcmp_slt_s (__m128, __m128); | |
17816 | __m128i __lsx_vfcmp_sne_d (__m128d, __m128d); | |
17817 | __m128i __lsx_vfcmp_sne_s (__m128, __m128); | |
17818 | __m128i __lsx_vfcmp_sor_d (__m128d, __m128d); | |
17819 | __m128i __lsx_vfcmp_sor_s (__m128, __m128); | |
17820 | __m128i __lsx_vfcmp_sueq_d (__m128d, __m128d); | |
17821 | __m128i __lsx_vfcmp_sueq_s (__m128, __m128); | |
17822 | __m128i __lsx_vfcmp_sule_d (__m128d, __m128d); | |
17823 | __m128i __lsx_vfcmp_sule_s (__m128, __m128); | |
17824 | __m128i __lsx_vfcmp_sult_d (__m128d, __m128d); | |
17825 | __m128i __lsx_vfcmp_sult_s (__m128, __m128); | |
17826 | __m128i __lsx_vfcmp_sun_d (__m128d, __m128d); | |
17827 | __m128i __lsx_vfcmp_sune_d (__m128d, __m128d); | |
17828 | __m128i __lsx_vfcmp_sune_s (__m128, __m128); | |
17829 | __m128i __lsx_vfcmp_sun_s (__m128, __m128); | |
17830 | __m128d __lsx_vfcvth_d_s (__m128); | |
17831 | __m128i __lsx_vfcvt_h_s (__m128, __m128); | |
17832 | __m128 __lsx_vfcvth_s_h (__m128i); | |
17833 | __m128d __lsx_vfcvtl_d_s (__m128); | |
17834 | __m128 __lsx_vfcvtl_s_h (__m128i); | |
17835 | __m128 __lsx_vfcvt_s_d (__m128d, __m128d); | |
17836 | __m128d __lsx_vfdiv_d (__m128d, __m128d); | |
17837 | __m128 __lsx_vfdiv_s (__m128, __m128); | |
17838 | __m128d __lsx_vffint_d_l (__m128i); | |
17839 | __m128d __lsx_vffint_d_lu (__m128i); | |
17840 | __m128d __lsx_vffinth_d_w (__m128i); | |
17841 | __m128d __lsx_vffintl_d_w (__m128i); | |
17842 | __m128 __lsx_vffint_s_l (__m128i, __m128i); | |
17843 | __m128 __lsx_vffint_s_w (__m128i); | |
17844 | __m128 __lsx_vffint_s_wu (__m128i); | |
17845 | __m128d __lsx_vflogb_d (__m128d); | |
17846 | __m128 __lsx_vflogb_s (__m128); | |
17847 | __m128d __lsx_vfmadd_d (__m128d, __m128d, __m128d); | |
17848 | __m128 __lsx_vfmadd_s (__m128, __m128, __m128); | |
17849 | __m128d __lsx_vfmaxa_d (__m128d, __m128d); | |
17850 | __m128 __lsx_vfmaxa_s (__m128, __m128); | |
17851 | __m128d __lsx_vfmax_d (__m128d, __m128d); | |
17852 | __m128 __lsx_vfmax_s (__m128, __m128); | |
17853 | __m128d __lsx_vfmina_d (__m128d, __m128d); | |
17854 | __m128 __lsx_vfmina_s (__m128, __m128); | |
17855 | __m128d __lsx_vfmin_d (__m128d, __m128d); | |
17856 | __m128 __lsx_vfmin_s (__m128, __m128); | |
17857 | __m128d __lsx_vfmsub_d (__m128d, __m128d, __m128d); | |
17858 | __m128 __lsx_vfmsub_s (__m128, __m128, __m128); | |
17859 | __m128d __lsx_vfmul_d (__m128d, __m128d); | |
17860 | __m128 __lsx_vfmul_s (__m128, __m128); | |
17861 | __m128d __lsx_vfnmadd_d (__m128d, __m128d, __m128d); | |
17862 | __m128 __lsx_vfnmadd_s (__m128, __m128, __m128); | |
17863 | __m128d __lsx_vfnmsub_d (__m128d, __m128d, __m128d); | |
17864 | __m128 __lsx_vfnmsub_s (__m128, __m128, __m128); | |
17865 | __m128d __lsx_vfrecip_d (__m128d); | |
17866 | __m128 __lsx_vfrecip_s (__m128); | |
17867 | __m128d __lsx_vfrint_d (__m128d); | |
84ad1b53 JC |
17868 | __m128d __lsx_vfrintrm_d (__m128d); |
17869 | __m128 __lsx_vfrintrm_s (__m128); | |
17870 | __m128d __lsx_vfrintrne_d (__m128d); | |
17871 | __m128 __lsx_vfrintrne_s (__m128); | |
17872 | __m128d __lsx_vfrintrp_d (__m128d); | |
17873 | __m128 __lsx_vfrintrp_s (__m128); | |
17874 | __m128d __lsx_vfrintrz_d (__m128d); | |
17875 | __m128 __lsx_vfrintrz_s (__m128); | |
1f48786d | 17876 | __m128 __lsx_vfrint_s (__m128); |
17877 | __m128d __lsx_vfrsqrt_d (__m128d); | |
17878 | __m128 __lsx_vfrsqrt_s (__m128); | |
17879 | __m128i __lsx_vfrstp_b (__m128i, __m128i, __m128i); | |
17880 | __m128i __lsx_vfrstp_h (__m128i, __m128i, __m128i); | |
17881 | __m128i __lsx_vfrstpi_b (__m128i, __m128i, imm0_31); | |
17882 | __m128i __lsx_vfrstpi_h (__m128i, __m128i, imm0_31); | |
17883 | __m128d __lsx_vfsqrt_d (__m128d); | |
17884 | __m128 __lsx_vfsqrt_s (__m128); | |
17885 | __m128d __lsx_vfsub_d (__m128d, __m128d); | |
17886 | __m128 __lsx_vfsub_s (__m128, __m128); | |
17887 | __m128i __lsx_vftinth_l_s (__m128); | |
17888 | __m128i __lsx_vftint_l_d (__m128d); | |
17889 | __m128i __lsx_vftintl_l_s (__m128); | |
17890 | __m128i __lsx_vftint_lu_d (__m128d); | |
17891 | __m128i __lsx_vftintrmh_l_s (__m128); | |
17892 | __m128i __lsx_vftintrm_l_d (__m128d); | |
17893 | __m128i __lsx_vftintrml_l_s (__m128); | |
17894 | __m128i __lsx_vftintrm_w_d (__m128d, __m128d); | |
17895 | __m128i __lsx_vftintrm_w_s (__m128); | |
17896 | __m128i __lsx_vftintrneh_l_s (__m128); | |
17897 | __m128i __lsx_vftintrne_l_d (__m128d); | |
17898 | __m128i __lsx_vftintrnel_l_s (__m128); | |
17899 | __m128i __lsx_vftintrne_w_d (__m128d, __m128d); | |
17900 | __m128i __lsx_vftintrne_w_s (__m128); | |
17901 | __m128i __lsx_vftintrph_l_s (__m128); | |
17902 | __m128i __lsx_vftintrp_l_d (__m128d); | |
17903 | __m128i __lsx_vftintrpl_l_s (__m128); | |
17904 | __m128i __lsx_vftintrp_w_d (__m128d, __m128d); | |
17905 | __m128i __lsx_vftintrp_w_s (__m128); | |
17906 | __m128i __lsx_vftintrzh_l_s (__m128); | |
17907 | __m128i __lsx_vftintrz_l_d (__m128d); | |
17908 | __m128i __lsx_vftintrzl_l_s (__m128); | |
17909 | __m128i __lsx_vftintrz_lu_d (__m128d); | |
17910 | __m128i __lsx_vftintrz_w_d (__m128d, __m128d); | |
17911 | __m128i __lsx_vftintrz_w_s (__m128); | |
17912 | __m128i __lsx_vftintrz_wu_s (__m128); | |
17913 | __m128i __lsx_vftint_w_d (__m128d, __m128d); | |
17914 | __m128i __lsx_vftint_w_s (__m128); | |
17915 | __m128i __lsx_vftint_wu_s (__m128); | |
17916 | __m128i __lsx_vhaddw_du_wu (__m128i, __m128i); | |
17917 | __m128i __lsx_vhaddw_d_w (__m128i, __m128i); | |
17918 | __m128i __lsx_vhaddw_h_b (__m128i, __m128i); | |
17919 | __m128i __lsx_vhaddw_hu_bu (__m128i, __m128i); | |
17920 | __m128i __lsx_vhaddw_q_d (__m128i, __m128i); | |
17921 | __m128i __lsx_vhaddw_qu_du (__m128i, __m128i); | |
17922 | __m128i __lsx_vhaddw_w_h (__m128i, __m128i); | |
17923 | __m128i __lsx_vhaddw_wu_hu (__m128i, __m128i); | |
17924 | __m128i __lsx_vhsubw_du_wu (__m128i, __m128i); | |
17925 | __m128i __lsx_vhsubw_d_w (__m128i, __m128i); | |
17926 | __m128i __lsx_vhsubw_h_b (__m128i, __m128i); | |
17927 | __m128i __lsx_vhsubw_hu_bu (__m128i, __m128i); | |
17928 | __m128i __lsx_vhsubw_q_d (__m128i, __m128i); | |
17929 | __m128i __lsx_vhsubw_qu_du (__m128i, __m128i); | |
17930 | __m128i __lsx_vhsubw_w_h (__m128i, __m128i); | |
17931 | __m128i __lsx_vhsubw_wu_hu (__m128i, __m128i); | |
17932 | __m128i __lsx_vilvh_b (__m128i, __m128i); | |
17933 | __m128i __lsx_vilvh_d (__m128i, __m128i); | |
17934 | __m128i __lsx_vilvh_h (__m128i, __m128i); | |
17935 | __m128i __lsx_vilvh_w (__m128i, __m128i); | |
17936 | __m128i __lsx_vilvl_b (__m128i, __m128i); | |
17937 | __m128i __lsx_vilvl_d (__m128i, __m128i); | |
17938 | __m128i __lsx_vilvl_h (__m128i, __m128i); | |
17939 | __m128i __lsx_vilvl_w (__m128i, __m128i); | |
17940 | __m128i __lsx_vinsgr2vr_b (__m128i, int, imm0_15); | |
17941 | __m128i __lsx_vinsgr2vr_d (__m128i, long int, imm0_1); | |
17942 | __m128i __lsx_vinsgr2vr_h (__m128i, int, imm0_7); | |
17943 | __m128i __lsx_vinsgr2vr_w (__m128i, int, imm0_3); | |
84ad1b53 JC |
17944 | __m128i __lsx_vld (void *, imm_n2048_2047); |
17945 | __m128i __lsx_vldi (imm_n1024_1023); | |
17946 | __m128i __lsx_vldrepl_b (void *, imm_n2048_2047); | |
17947 | __m128i __lsx_vldrepl_d (void *, imm_n256_255); | |
17948 | __m128i __lsx_vldrepl_h (void *, imm_n1024_1023); | |
17949 | __m128i __lsx_vldrepl_w (void *, imm_n512_511); | |
1f48786d | 17950 | __m128i __lsx_vldx (void *, long int); |
17951 | __m128i __lsx_vmadd_b (__m128i, __m128i, __m128i); | |
17952 | __m128i __lsx_vmadd_d (__m128i, __m128i, __m128i); | |
17953 | __m128i __lsx_vmadd_h (__m128i, __m128i, __m128i); | |
17954 | __m128i __lsx_vmadd_w (__m128i, __m128i, __m128i); | |
17955 | __m128i __lsx_vmaddwev_d_w (__m128i, __m128i, __m128i); | |
17956 | __m128i __lsx_vmaddwev_d_wu (__m128i, __m128i, __m128i); | |
17957 | __m128i __lsx_vmaddwev_d_wu_w (__m128i, __m128i, __m128i); | |
17958 | __m128i __lsx_vmaddwev_h_b (__m128i, __m128i, __m128i); | |
17959 | __m128i __lsx_vmaddwev_h_bu (__m128i, __m128i, __m128i); | |
17960 | __m128i __lsx_vmaddwev_h_bu_b (__m128i, __m128i, __m128i); | |
17961 | __m128i __lsx_vmaddwev_q_d (__m128i, __m128i, __m128i); | |
17962 | __m128i __lsx_vmaddwev_q_du (__m128i, __m128i, __m128i); | |
17963 | __m128i __lsx_vmaddwev_q_du_d (__m128i, __m128i, __m128i); | |
17964 | __m128i __lsx_vmaddwev_w_h (__m128i, __m128i, __m128i); | |
17965 | __m128i __lsx_vmaddwev_w_hu (__m128i, __m128i, __m128i); | |
17966 | __m128i __lsx_vmaddwev_w_hu_h (__m128i, __m128i, __m128i); | |
17967 | __m128i __lsx_vmaddwod_d_w (__m128i, __m128i, __m128i); | |
17968 | __m128i __lsx_vmaddwod_d_wu (__m128i, __m128i, __m128i); | |
17969 | __m128i __lsx_vmaddwod_d_wu_w (__m128i, __m128i, __m128i); | |
17970 | __m128i __lsx_vmaddwod_h_b (__m128i, __m128i, __m128i); | |
17971 | __m128i __lsx_vmaddwod_h_bu (__m128i, __m128i, __m128i); | |
17972 | __m128i __lsx_vmaddwod_h_bu_b (__m128i, __m128i, __m128i); | |
17973 | __m128i __lsx_vmaddwod_q_d (__m128i, __m128i, __m128i); | |
17974 | __m128i __lsx_vmaddwod_q_du (__m128i, __m128i, __m128i); | |
17975 | __m128i __lsx_vmaddwod_q_du_d (__m128i, __m128i, __m128i); | |
17976 | __m128i __lsx_vmaddwod_w_h (__m128i, __m128i, __m128i); | |
17977 | __m128i __lsx_vmaddwod_w_hu (__m128i, __m128i, __m128i); | |
17978 | __m128i __lsx_vmaddwod_w_hu_h (__m128i, __m128i, __m128i); | |
17979 | __m128i __lsx_vmax_b (__m128i, __m128i); | |
17980 | __m128i __lsx_vmax_bu (__m128i, __m128i); | |
17981 | __m128i __lsx_vmax_d (__m128i, __m128i); | |
17982 | __m128i __lsx_vmax_du (__m128i, __m128i); | |
17983 | __m128i __lsx_vmax_h (__m128i, __m128i); | |
17984 | __m128i __lsx_vmax_hu (__m128i, __m128i); | |
84ad1b53 | 17985 | __m128i __lsx_vmaxi_b (__m128i, imm_n16_15); |
1f48786d | 17986 | __m128i __lsx_vmaxi_bu (__m128i, imm0_31); |
84ad1b53 | 17987 | __m128i __lsx_vmaxi_d (__m128i, imm_n16_15); |
1f48786d | 17988 | __m128i __lsx_vmaxi_du (__m128i, imm0_31); |
84ad1b53 | 17989 | __m128i __lsx_vmaxi_h (__m128i, imm_n16_15); |
1f48786d | 17990 | __m128i __lsx_vmaxi_hu (__m128i, imm0_31); |
84ad1b53 | 17991 | __m128i __lsx_vmaxi_w (__m128i, imm_n16_15); |
1f48786d | 17992 | __m128i __lsx_vmaxi_wu (__m128i, imm0_31); |
17993 | __m128i __lsx_vmax_w (__m128i, __m128i); | |
17994 | __m128i __lsx_vmax_wu (__m128i, __m128i); | |
17995 | __m128i __lsx_vmin_b (__m128i, __m128i); | |
17996 | __m128i __lsx_vmin_bu (__m128i, __m128i); | |
17997 | __m128i __lsx_vmin_d (__m128i, __m128i); | |
17998 | __m128i __lsx_vmin_du (__m128i, __m128i); | |
17999 | __m128i __lsx_vmin_h (__m128i, __m128i); | |
18000 | __m128i __lsx_vmin_hu (__m128i, __m128i); | |
84ad1b53 | 18001 | __m128i __lsx_vmini_b (__m128i, imm_n16_15); |
1f48786d | 18002 | __m128i __lsx_vmini_bu (__m128i, imm0_31); |
84ad1b53 | 18003 | __m128i __lsx_vmini_d (__m128i, imm_n16_15); |
1f48786d | 18004 | __m128i __lsx_vmini_du (__m128i, imm0_31); |
84ad1b53 | 18005 | __m128i __lsx_vmini_h (__m128i, imm_n16_15); |
1f48786d | 18006 | __m128i __lsx_vmini_hu (__m128i, imm0_31); |
84ad1b53 | 18007 | __m128i __lsx_vmini_w (__m128i, imm_n16_15); |
1f48786d | 18008 | __m128i __lsx_vmini_wu (__m128i, imm0_31); |
18009 | __m128i __lsx_vmin_w (__m128i, __m128i); | |
18010 | __m128i __lsx_vmin_wu (__m128i, __m128i); | |
18011 | __m128i __lsx_vmod_b (__m128i, __m128i); | |
18012 | __m128i __lsx_vmod_bu (__m128i, __m128i); | |
18013 | __m128i __lsx_vmod_d (__m128i, __m128i); | |
18014 | __m128i __lsx_vmod_du (__m128i, __m128i); | |
18015 | __m128i __lsx_vmod_h (__m128i, __m128i); | |
18016 | __m128i __lsx_vmod_hu (__m128i, __m128i); | |
18017 | __m128i __lsx_vmod_w (__m128i, __m128i); | |
18018 | __m128i __lsx_vmod_wu (__m128i, __m128i); | |
18019 | __m128i __lsx_vmskgez_b (__m128i); | |
18020 | __m128i __lsx_vmskltz_b (__m128i); | |
18021 | __m128i __lsx_vmskltz_d (__m128i); | |
18022 | __m128i __lsx_vmskltz_h (__m128i); | |
18023 | __m128i __lsx_vmskltz_w (__m128i); | |
18024 | __m128i __lsx_vmsknz_b (__m128i); | |
18025 | __m128i __lsx_vmsub_b (__m128i, __m128i, __m128i); | |
18026 | __m128i __lsx_vmsub_d (__m128i, __m128i, __m128i); | |
18027 | __m128i __lsx_vmsub_h (__m128i, __m128i, __m128i); | |
18028 | __m128i __lsx_vmsub_w (__m128i, __m128i, __m128i); | |
18029 | __m128i __lsx_vmuh_b (__m128i, __m128i); | |
18030 | __m128i __lsx_vmuh_bu (__m128i, __m128i); | |
18031 | __m128i __lsx_vmuh_d (__m128i, __m128i); | |
18032 | __m128i __lsx_vmuh_du (__m128i, __m128i); | |
18033 | __m128i __lsx_vmuh_h (__m128i, __m128i); | |
18034 | __m128i __lsx_vmuh_hu (__m128i, __m128i); | |
18035 | __m128i __lsx_vmuh_w (__m128i, __m128i); | |
18036 | __m128i __lsx_vmuh_wu (__m128i, __m128i); | |
18037 | __m128i __lsx_vmul_b (__m128i, __m128i); | |
18038 | __m128i __lsx_vmul_d (__m128i, __m128i); | |
18039 | __m128i __lsx_vmul_h (__m128i, __m128i); | |
18040 | __m128i __lsx_vmul_w (__m128i, __m128i); | |
18041 | __m128i __lsx_vmulwev_d_w (__m128i, __m128i); | |
18042 | __m128i __lsx_vmulwev_d_wu (__m128i, __m128i); | |
18043 | __m128i __lsx_vmulwev_d_wu_w (__m128i, __m128i); | |
18044 | __m128i __lsx_vmulwev_h_b (__m128i, __m128i); | |
18045 | __m128i __lsx_vmulwev_h_bu (__m128i, __m128i); | |
18046 | __m128i __lsx_vmulwev_h_bu_b (__m128i, __m128i); | |
18047 | __m128i __lsx_vmulwev_q_d (__m128i, __m128i); | |
18048 | __m128i __lsx_vmulwev_q_du (__m128i, __m128i); | |
18049 | __m128i __lsx_vmulwev_q_du_d (__m128i, __m128i); | |
18050 | __m128i __lsx_vmulwev_w_h (__m128i, __m128i); | |
18051 | __m128i __lsx_vmulwev_w_hu (__m128i, __m128i); | |
18052 | __m128i __lsx_vmulwev_w_hu_h (__m128i, __m128i); | |
18053 | __m128i __lsx_vmulwod_d_w (__m128i, __m128i); | |
18054 | __m128i __lsx_vmulwod_d_wu (__m128i, __m128i); | |
18055 | __m128i __lsx_vmulwod_d_wu_w (__m128i, __m128i); | |
18056 | __m128i __lsx_vmulwod_h_b (__m128i, __m128i); | |
18057 | __m128i __lsx_vmulwod_h_bu (__m128i, __m128i); | |
18058 | __m128i __lsx_vmulwod_h_bu_b (__m128i, __m128i); | |
18059 | __m128i __lsx_vmulwod_q_d (__m128i, __m128i); | |
18060 | __m128i __lsx_vmulwod_q_du (__m128i, __m128i); | |
18061 | __m128i __lsx_vmulwod_q_du_d (__m128i, __m128i); | |
18062 | __m128i __lsx_vmulwod_w_h (__m128i, __m128i); | |
18063 | __m128i __lsx_vmulwod_w_hu (__m128i, __m128i); | |
18064 | __m128i __lsx_vmulwod_w_hu_h (__m128i, __m128i); | |
18065 | __m128i __lsx_vneg_b (__m128i); | |
18066 | __m128i __lsx_vneg_d (__m128i); | |
18067 | __m128i __lsx_vneg_h (__m128i); | |
18068 | __m128i __lsx_vneg_w (__m128i); | |
18069 | __m128i __lsx_vnori_b (__m128i, imm0_255); | |
18070 | __m128i __lsx_vnor_v (__m128i, __m128i); | |
18071 | __m128i __lsx_vori_b (__m128i, imm0_255); | |
18072 | __m128i __lsx_vorn_v (__m128i, __m128i); | |
18073 | __m128i __lsx_vor_v (__m128i, __m128i); | |
18074 | __m128i __lsx_vpackev_b (__m128i, __m128i); | |
18075 | __m128i __lsx_vpackev_d (__m128i, __m128i); | |
18076 | __m128i __lsx_vpackev_h (__m128i, __m128i); | |
18077 | __m128i __lsx_vpackev_w (__m128i, __m128i); | |
18078 | __m128i __lsx_vpackod_b (__m128i, __m128i); | |
18079 | __m128i __lsx_vpackod_d (__m128i, __m128i); | |
18080 | __m128i __lsx_vpackod_h (__m128i, __m128i); | |
18081 | __m128i __lsx_vpackod_w (__m128i, __m128i); | |
18082 | __m128i __lsx_vpcnt_b (__m128i); | |
18083 | __m128i __lsx_vpcnt_d (__m128i); | |
18084 | __m128i __lsx_vpcnt_h (__m128i); | |
18085 | __m128i __lsx_vpcnt_w (__m128i); | |
18086 | __m128i __lsx_vpermi_w (__m128i, __m128i, imm0_255); | |
18087 | __m128i __lsx_vpickev_b (__m128i, __m128i); | |
18088 | __m128i __lsx_vpickev_d (__m128i, __m128i); | |
18089 | __m128i __lsx_vpickev_h (__m128i, __m128i); | |
18090 | __m128i __lsx_vpickev_w (__m128i, __m128i); | |
18091 | __m128i __lsx_vpickod_b (__m128i, __m128i); | |
18092 | __m128i __lsx_vpickod_d (__m128i, __m128i); | |
18093 | __m128i __lsx_vpickod_h (__m128i, __m128i); | |
18094 | __m128i __lsx_vpickod_w (__m128i, __m128i); | |
18095 | int __lsx_vpickve2gr_b (__m128i, imm0_15); | |
84ad1b53 | 18096 | unsigned int __lsx_vpickve2gr_bu (__m128i, imm0_15); |
1f48786d | 18097 | long int __lsx_vpickve2gr_d (__m128i, imm0_1); |
18098 | unsigned long int __lsx_vpickve2gr_du (__m128i, imm0_1); | |
18099 | int __lsx_vpickve2gr_h (__m128i, imm0_7); | |
84ad1b53 | 18100 | unsigned int __lsx_vpickve2gr_hu (__m128i, imm0_7); |
1f48786d | 18101 | int __lsx_vpickve2gr_w (__m128i, imm0_3); |
18102 | unsigned int __lsx_vpickve2gr_wu (__m128i, imm0_3); | |
18103 | __m128i __lsx_vreplgr2vr_b (int); | |
18104 | __m128i __lsx_vreplgr2vr_d (long int); | |
18105 | __m128i __lsx_vreplgr2vr_h (int); | |
18106 | __m128i __lsx_vreplgr2vr_w (int); | |
18107 | __m128i __lsx_vrepli_b (imm_n512_511); | |
18108 | __m128i __lsx_vrepli_d (imm_n512_511); | |
18109 | __m128i __lsx_vrepli_h (imm_n512_511); | |
18110 | __m128i __lsx_vrepli_w (imm_n512_511); | |
18111 | __m128i __lsx_vreplve_b (__m128i, int); | |
18112 | __m128i __lsx_vreplve_d (__m128i, int); | |
18113 | __m128i __lsx_vreplve_h (__m128i, int); | |
18114 | __m128i __lsx_vreplvei_b (__m128i, imm0_15); | |
18115 | __m128i __lsx_vreplvei_d (__m128i, imm0_1); | |
18116 | __m128i __lsx_vreplvei_h (__m128i, imm0_7); | |
18117 | __m128i __lsx_vreplvei_w (__m128i, imm0_3); | |
18118 | __m128i __lsx_vreplve_w (__m128i, int); | |
18119 | __m128i __lsx_vrotr_b (__m128i, __m128i); | |
18120 | __m128i __lsx_vrotr_d (__m128i, __m128i); | |
18121 | __m128i __lsx_vrotr_h (__m128i, __m128i); | |
18122 | __m128i __lsx_vrotri_b (__m128i, imm0_7); | |
18123 | __m128i __lsx_vrotri_d (__m128i, imm0_63); | |
18124 | __m128i __lsx_vrotri_h (__m128i, imm0_15); | |
18125 | __m128i __lsx_vrotri_w (__m128i, imm0_31); | |
18126 | __m128i __lsx_vrotr_w (__m128i, __m128i); | |
18127 | __m128i __lsx_vsadd_b (__m128i, __m128i); | |
18128 | __m128i __lsx_vsadd_bu (__m128i, __m128i); | |
18129 | __m128i __lsx_vsadd_d (__m128i, __m128i); | |
18130 | __m128i __lsx_vsadd_du (__m128i, __m128i); | |
18131 | __m128i __lsx_vsadd_h (__m128i, __m128i); | |
18132 | __m128i __lsx_vsadd_hu (__m128i, __m128i); | |
18133 | __m128i __lsx_vsadd_w (__m128i, __m128i); | |
18134 | __m128i __lsx_vsadd_wu (__m128i, __m128i); | |
18135 | __m128i __lsx_vsat_b (__m128i, imm0_7); | |
18136 | __m128i __lsx_vsat_bu (__m128i, imm0_7); | |
18137 | __m128i __lsx_vsat_d (__m128i, imm0_63); | |
18138 | __m128i __lsx_vsat_du (__m128i, imm0_63); | |
18139 | __m128i __lsx_vsat_h (__m128i, imm0_15); | |
18140 | __m128i __lsx_vsat_hu (__m128i, imm0_15); | |
18141 | __m128i __lsx_vsat_w (__m128i, imm0_31); | |
18142 | __m128i __lsx_vsat_wu (__m128i, imm0_31); | |
18143 | __m128i __lsx_vseq_b (__m128i, __m128i); | |
18144 | __m128i __lsx_vseq_d (__m128i, __m128i); | |
18145 | __m128i __lsx_vseq_h (__m128i, __m128i); | |
18146 | __m128i __lsx_vseqi_b (__m128i, imm_n16_15); | |
18147 | __m128i __lsx_vseqi_d (__m128i, imm_n16_15); | |
18148 | __m128i __lsx_vseqi_h (__m128i, imm_n16_15); | |
18149 | __m128i __lsx_vseqi_w (__m128i, imm_n16_15); | |
18150 | __m128i __lsx_vseq_w (__m128i, __m128i); | |
18151 | __m128i __lsx_vshuf4i_b (__m128i, imm0_255); | |
18152 | __m128i __lsx_vshuf4i_d (__m128i, __m128i, imm0_255); | |
18153 | __m128i __lsx_vshuf4i_h (__m128i, imm0_255); | |
18154 | __m128i __lsx_vshuf4i_w (__m128i, imm0_255); | |
18155 | __m128i __lsx_vshuf_b (__m128i, __m128i, __m128i); | |
18156 | __m128i __lsx_vshuf_d (__m128i, __m128i, __m128i); | |
18157 | __m128i __lsx_vshuf_h (__m128i, __m128i, __m128i); | |
18158 | __m128i __lsx_vshuf_w (__m128i, __m128i, __m128i); | |
18159 | __m128i __lsx_vsigncov_b (__m128i, __m128i); | |
18160 | __m128i __lsx_vsigncov_d (__m128i, __m128i); | |
18161 | __m128i __lsx_vsigncov_h (__m128i, __m128i); | |
18162 | __m128i __lsx_vsigncov_w (__m128i, __m128i); | |
1f48786d | 18163 | __m128i __lsx_vsle_b (__m128i, __m128i); |
18164 | __m128i __lsx_vsle_bu (__m128i, __m128i); | |
18165 | __m128i __lsx_vsle_d (__m128i, __m128i); | |
18166 | __m128i __lsx_vsle_du (__m128i, __m128i); | |
18167 | __m128i __lsx_vsle_h (__m128i, __m128i); | |
18168 | __m128i __lsx_vsle_hu (__m128i, __m128i); | |
18169 | __m128i __lsx_vslei_b (__m128i, imm_n16_15); | |
18170 | __m128i __lsx_vslei_bu (__m128i, imm0_31); | |
18171 | __m128i __lsx_vslei_d (__m128i, imm_n16_15); | |
18172 | __m128i __lsx_vslei_du (__m128i, imm0_31); | |
18173 | __m128i __lsx_vslei_h (__m128i, imm_n16_15); | |
18174 | __m128i __lsx_vslei_hu (__m128i, imm0_31); | |
18175 | __m128i __lsx_vslei_w (__m128i, imm_n16_15); | |
18176 | __m128i __lsx_vslei_wu (__m128i, imm0_31); | |
18177 | __m128i __lsx_vsle_w (__m128i, __m128i); | |
18178 | __m128i __lsx_vsle_wu (__m128i, __m128i); | |
18179 | __m128i __lsx_vsll_b (__m128i, __m128i); | |
18180 | __m128i __lsx_vsll_d (__m128i, __m128i); | |
18181 | __m128i __lsx_vsll_h (__m128i, __m128i); | |
18182 | __m128i __lsx_vslli_b (__m128i, imm0_7); | |
18183 | __m128i __lsx_vslli_d (__m128i, imm0_63); | |
18184 | __m128i __lsx_vslli_h (__m128i, imm0_15); | |
18185 | __m128i __lsx_vslli_w (__m128i, imm0_31); | |
18186 | __m128i __lsx_vsll_w (__m128i, __m128i); | |
18187 | __m128i __lsx_vsllwil_du_wu (__m128i, imm0_31); | |
18188 | __m128i __lsx_vsllwil_d_w (__m128i, imm0_31); | |
18189 | __m128i __lsx_vsllwil_h_b (__m128i, imm0_7); | |
18190 | __m128i __lsx_vsllwil_hu_bu (__m128i, imm0_7); | |
18191 | __m128i __lsx_vsllwil_w_h (__m128i, imm0_15); | |
18192 | __m128i __lsx_vsllwil_wu_hu (__m128i, imm0_15); | |
18193 | __m128i __lsx_vslt_b (__m128i, __m128i); | |
18194 | __m128i __lsx_vslt_bu (__m128i, __m128i); | |
18195 | __m128i __lsx_vslt_d (__m128i, __m128i); | |
18196 | __m128i __lsx_vslt_du (__m128i, __m128i); | |
18197 | __m128i __lsx_vslt_h (__m128i, __m128i); | |
18198 | __m128i __lsx_vslt_hu (__m128i, __m128i); | |
18199 | __m128i __lsx_vslti_b (__m128i, imm_n16_15); | |
18200 | __m128i __lsx_vslti_bu (__m128i, imm0_31); | |
18201 | __m128i __lsx_vslti_d (__m128i, imm_n16_15); | |
18202 | __m128i __lsx_vslti_du (__m128i, imm0_31); | |
18203 | __m128i __lsx_vslti_h (__m128i, imm_n16_15); | |
18204 | __m128i __lsx_vslti_hu (__m128i, imm0_31); | |
18205 | __m128i __lsx_vslti_w (__m128i, imm_n16_15); | |
18206 | __m128i __lsx_vslti_wu (__m128i, imm0_31); | |
18207 | __m128i __lsx_vslt_w (__m128i, __m128i); | |
18208 | __m128i __lsx_vslt_wu (__m128i, __m128i); | |
18209 | __m128i __lsx_vsra_b (__m128i, __m128i); | |
18210 | __m128i __lsx_vsra_d (__m128i, __m128i); | |
18211 | __m128i __lsx_vsra_h (__m128i, __m128i); | |
18212 | __m128i __lsx_vsrai_b (__m128i, imm0_7); | |
18213 | __m128i __lsx_vsrai_d (__m128i, imm0_63); | |
18214 | __m128i __lsx_vsrai_h (__m128i, imm0_15); | |
18215 | __m128i __lsx_vsrai_w (__m128i, imm0_31); | |
18216 | __m128i __lsx_vsran_b_h (__m128i, __m128i); | |
18217 | __m128i __lsx_vsran_h_w (__m128i, __m128i); | |
18218 | __m128i __lsx_vsrani_b_h (__m128i, __m128i, imm0_15); | |
84ad1b53 | 18219 | __m128i __lsx_vsrani_d_q (__m128i, __m128i, imm0_127); |
1f48786d | 18220 | __m128i __lsx_vsrani_h_w (__m128i, __m128i, imm0_31); |
18221 | __m128i __lsx_vsrani_w_d (__m128i, __m128i, imm0_63); | |
18222 | __m128i __lsx_vsran_w_d (__m128i, __m128i); | |
18223 | __m128i __lsx_vsrar_b (__m128i, __m128i); | |
18224 | __m128i __lsx_vsrar_d (__m128i, __m128i); | |
18225 | __m128i __lsx_vsrar_h (__m128i, __m128i); | |
18226 | __m128i __lsx_vsrari_b (__m128i, imm0_7); | |
18227 | __m128i __lsx_vsrari_d (__m128i, imm0_63); | |
18228 | __m128i __lsx_vsrari_h (__m128i, imm0_15); | |
18229 | __m128i __lsx_vsrari_w (__m128i, imm0_31); | |
18230 | __m128i __lsx_vsrarn_b_h (__m128i, __m128i); | |
18231 | __m128i __lsx_vsrarn_h_w (__m128i, __m128i); | |
18232 | __m128i __lsx_vsrarni_b_h (__m128i, __m128i, imm0_15); | |
84ad1b53 | 18233 | __m128i __lsx_vsrarni_d_q (__m128i, __m128i, imm0_127); |
1f48786d | 18234 | __m128i __lsx_vsrarni_h_w (__m128i, __m128i, imm0_31); |
18235 | __m128i __lsx_vsrarni_w_d (__m128i, __m128i, imm0_63); | |
18236 | __m128i __lsx_vsrarn_w_d (__m128i, __m128i); | |
18237 | __m128i __lsx_vsrar_w (__m128i, __m128i); | |
18238 | __m128i __lsx_vsra_w (__m128i, __m128i); | |
18239 | __m128i __lsx_vsrl_b (__m128i, __m128i); | |
18240 | __m128i __lsx_vsrl_d (__m128i, __m128i); | |
18241 | __m128i __lsx_vsrl_h (__m128i, __m128i); | |
18242 | __m128i __lsx_vsrli_b (__m128i, imm0_7); | |
18243 | __m128i __lsx_vsrli_d (__m128i, imm0_63); | |
18244 | __m128i __lsx_vsrli_h (__m128i, imm0_15); | |
18245 | __m128i __lsx_vsrli_w (__m128i, imm0_31); | |
18246 | __m128i __lsx_vsrln_b_h (__m128i, __m128i); | |
18247 | __m128i __lsx_vsrln_h_w (__m128i, __m128i); | |
18248 | __m128i __lsx_vsrlni_b_h (__m128i, __m128i, imm0_15); | |
84ad1b53 | 18249 | __m128i __lsx_vsrlni_d_q (__m128i, __m128i, imm0_127); |
1f48786d | 18250 | __m128i __lsx_vsrlni_h_w (__m128i, __m128i, imm0_31); |
18251 | __m128i __lsx_vsrlni_w_d (__m128i, __m128i, imm0_63); | |
18252 | __m128i __lsx_vsrln_w_d (__m128i, __m128i); | |
18253 | __m128i __lsx_vsrlr_b (__m128i, __m128i); | |
18254 | __m128i __lsx_vsrlr_d (__m128i, __m128i); | |
18255 | __m128i __lsx_vsrlr_h (__m128i, __m128i); | |
18256 | __m128i __lsx_vsrlri_b (__m128i, imm0_7); | |
18257 | __m128i __lsx_vsrlri_d (__m128i, imm0_63); | |
18258 | __m128i __lsx_vsrlri_h (__m128i, imm0_15); | |
18259 | __m128i __lsx_vsrlri_w (__m128i, imm0_31); | |
18260 | __m128i __lsx_vsrlrn_b_h (__m128i, __m128i); | |
18261 | __m128i __lsx_vsrlrn_h_w (__m128i, __m128i); | |
18262 | __m128i __lsx_vsrlrni_b_h (__m128i, __m128i, imm0_15); | |
84ad1b53 | 18263 | __m128i __lsx_vsrlrni_d_q (__m128i, __m128i, imm0_127); |
1f48786d | 18264 | __m128i __lsx_vsrlrni_h_w (__m128i, __m128i, imm0_31); |
18265 | __m128i __lsx_vsrlrni_w_d (__m128i, __m128i, imm0_63); | |
18266 | __m128i __lsx_vsrlrn_w_d (__m128i, __m128i); | |
18267 | __m128i __lsx_vsrlr_w (__m128i, __m128i); | |
18268 | __m128i __lsx_vsrl_w (__m128i, __m128i); | |
18269 | __m128i __lsx_vssran_b_h (__m128i, __m128i); | |
18270 | __m128i __lsx_vssran_bu_h (__m128i, __m128i); | |
18271 | __m128i __lsx_vssran_hu_w (__m128i, __m128i); | |
18272 | __m128i __lsx_vssran_h_w (__m128i, __m128i); | |
18273 | __m128i __lsx_vssrani_b_h (__m128i, __m128i, imm0_15); | |
18274 | __m128i __lsx_vssrani_bu_h (__m128i, __m128i, imm0_15); | |
84ad1b53 JC |
18275 | __m128i __lsx_vssrani_d_q (__m128i, __m128i, imm0_127); |
18276 | __m128i __lsx_vssrani_du_q (__m128i, __m128i, imm0_127); | |
1f48786d | 18277 | __m128i __lsx_vssrani_hu_w (__m128i, __m128i, imm0_31); |
18278 | __m128i __lsx_vssrani_h_w (__m128i, __m128i, imm0_31); | |
18279 | __m128i __lsx_vssrani_w_d (__m128i, __m128i, imm0_63); | |
18280 | __m128i __lsx_vssrani_wu_d (__m128i, __m128i, imm0_63); | |
18281 | __m128i __lsx_vssran_w_d (__m128i, __m128i); | |
18282 | __m128i __lsx_vssran_wu_d (__m128i, __m128i); | |
18283 | __m128i __lsx_vssrarn_b_h (__m128i, __m128i); | |
18284 | __m128i __lsx_vssrarn_bu_h (__m128i, __m128i); | |
18285 | __m128i __lsx_vssrarn_hu_w (__m128i, __m128i); | |
18286 | __m128i __lsx_vssrarn_h_w (__m128i, __m128i); | |
18287 | __m128i __lsx_vssrarni_b_h (__m128i, __m128i, imm0_15); | |
18288 | __m128i __lsx_vssrarni_bu_h (__m128i, __m128i, imm0_15); | |
84ad1b53 JC |
18289 | __m128i __lsx_vssrarni_d_q (__m128i, __m128i, imm0_127); |
18290 | __m128i __lsx_vssrarni_du_q (__m128i, __m128i, imm0_127); | |
1f48786d | 18291 | __m128i __lsx_vssrarni_hu_w (__m128i, __m128i, imm0_31); |
18292 | __m128i __lsx_vssrarni_h_w (__m128i, __m128i, imm0_31); | |
18293 | __m128i __lsx_vssrarni_w_d (__m128i, __m128i, imm0_63); | |
18294 | __m128i __lsx_vssrarni_wu_d (__m128i, __m128i, imm0_63); | |
18295 | __m128i __lsx_vssrarn_w_d (__m128i, __m128i); | |
18296 | __m128i __lsx_vssrarn_wu_d (__m128i, __m128i); | |
18297 | __m128i __lsx_vssrln_b_h (__m128i, __m128i); | |
18298 | __m128i __lsx_vssrln_bu_h (__m128i, __m128i); | |
18299 | __m128i __lsx_vssrln_hu_w (__m128i, __m128i); | |
18300 | __m128i __lsx_vssrln_h_w (__m128i, __m128i); | |
18301 | __m128i __lsx_vssrlni_b_h (__m128i, __m128i, imm0_15); | |
18302 | __m128i __lsx_vssrlni_bu_h (__m128i, __m128i, imm0_15); | |
84ad1b53 JC |
18303 | __m128i __lsx_vssrlni_d_q (__m128i, __m128i, imm0_127); |
18304 | __m128i __lsx_vssrlni_du_q (__m128i, __m128i, imm0_127); | |
1f48786d | 18305 | __m128i __lsx_vssrlni_hu_w (__m128i, __m128i, imm0_31); |
18306 | __m128i __lsx_vssrlni_h_w (__m128i, __m128i, imm0_31); | |
18307 | __m128i __lsx_vssrlni_w_d (__m128i, __m128i, imm0_63); | |
18308 | __m128i __lsx_vssrlni_wu_d (__m128i, __m128i, imm0_63); | |
18309 | __m128i __lsx_vssrln_w_d (__m128i, __m128i); | |
18310 | __m128i __lsx_vssrln_wu_d (__m128i, __m128i); | |
18311 | __m128i __lsx_vssrlrn_b_h (__m128i, __m128i); | |
18312 | __m128i __lsx_vssrlrn_bu_h (__m128i, __m128i); | |
18313 | __m128i __lsx_vssrlrn_hu_w (__m128i, __m128i); | |
18314 | __m128i __lsx_vssrlrn_h_w (__m128i, __m128i); | |
18315 | __m128i __lsx_vssrlrni_b_h (__m128i, __m128i, imm0_15); | |
18316 | __m128i __lsx_vssrlrni_bu_h (__m128i, __m128i, imm0_15); | |
84ad1b53 JC |
18317 | __m128i __lsx_vssrlrni_d_q (__m128i, __m128i, imm0_127); |
18318 | __m128i __lsx_vssrlrni_du_q (__m128i, __m128i, imm0_127); | |
1f48786d | 18319 | __m128i __lsx_vssrlrni_hu_w (__m128i, __m128i, imm0_31); |
18320 | __m128i __lsx_vssrlrni_h_w (__m128i, __m128i, imm0_31); | |
18321 | __m128i __lsx_vssrlrni_w_d (__m128i, __m128i, imm0_63); | |
18322 | __m128i __lsx_vssrlrni_wu_d (__m128i, __m128i, imm0_63); | |
18323 | __m128i __lsx_vssrlrn_w_d (__m128i, __m128i); | |
18324 | __m128i __lsx_vssrlrn_wu_d (__m128i, __m128i); | |
18325 | __m128i __lsx_vssub_b (__m128i, __m128i); | |
18326 | __m128i __lsx_vssub_bu (__m128i, __m128i); | |
18327 | __m128i __lsx_vssub_d (__m128i, __m128i); | |
18328 | __m128i __lsx_vssub_du (__m128i, __m128i); | |
18329 | __m128i __lsx_vssub_h (__m128i, __m128i); | |
18330 | __m128i __lsx_vssub_hu (__m128i, __m128i); | |
18331 | __m128i __lsx_vssub_w (__m128i, __m128i); | |
18332 | __m128i __lsx_vssub_wu (__m128i, __m128i); | |
84ad1b53 JC |
18333 | void __lsx_vst (__m128i, void *, imm_n2048_2047); |
18334 | void __lsx_vstelm_b (__m128i, void *, imm_n128_127, imm0_15); | |
18335 | void __lsx_vstelm_d (__m128i, void *, imm_n128_127, imm0_1); | |
18336 | void __lsx_vstelm_h (__m128i, void *, imm_n128_127, imm0_7); | |
18337 | void __lsx_vstelm_w (__m128i, void *, imm_n128_127, imm0_3); | |
18338 | void __lsx_vstx (__m128i, void *, long int); | |
1f48786d | 18339 | __m128i __lsx_vsub_b (__m128i, __m128i); |
18340 | __m128i __lsx_vsub_d (__m128i, __m128i); | |
18341 | __m128i __lsx_vsub_h (__m128i, __m128i); | |
18342 | __m128i __lsx_vsubi_bu (__m128i, imm0_31); | |
18343 | __m128i __lsx_vsubi_du (__m128i, imm0_31); | |
18344 | __m128i __lsx_vsubi_hu (__m128i, imm0_31); | |
18345 | __m128i __lsx_vsubi_wu (__m128i, imm0_31); | |
18346 | __m128i __lsx_vsub_q (__m128i, __m128i); | |
18347 | __m128i __lsx_vsub_w (__m128i, __m128i); | |
18348 | __m128i __lsx_vsubwev_d_w (__m128i, __m128i); | |
18349 | __m128i __lsx_vsubwev_d_wu (__m128i, __m128i); | |
18350 | __m128i __lsx_vsubwev_h_b (__m128i, __m128i); | |
18351 | __m128i __lsx_vsubwev_h_bu (__m128i, __m128i); | |
18352 | __m128i __lsx_vsubwev_q_d (__m128i, __m128i); | |
18353 | __m128i __lsx_vsubwev_q_du (__m128i, __m128i); | |
18354 | __m128i __lsx_vsubwev_w_h (__m128i, __m128i); | |
18355 | __m128i __lsx_vsubwev_w_hu (__m128i, __m128i); | |
18356 | __m128i __lsx_vsubwod_d_w (__m128i, __m128i); | |
18357 | __m128i __lsx_vsubwod_d_wu (__m128i, __m128i); | |
18358 | __m128i __lsx_vsubwod_h_b (__m128i, __m128i); | |
18359 | __m128i __lsx_vsubwod_h_bu (__m128i, __m128i); | |
18360 | __m128i __lsx_vsubwod_q_d (__m128i, __m128i); | |
18361 | __m128i __lsx_vsubwod_q_du (__m128i, __m128i); | |
18362 | __m128i __lsx_vsubwod_w_h (__m128i, __m128i); | |
18363 | __m128i __lsx_vsubwod_w_hu (__m128i, __m128i); | |
18364 | __m128i __lsx_vxori_b (__m128i, imm0_255); | |
18365 | __m128i __lsx_vxor_v (__m128i, __m128i); | |
18366 | @end smallexample | |
18367 | ||
61f1001f JX |
18368 | These instrisic functions are available by including @code{lsxintrin.h} and |
18369 | using @option{-mfrecipe} and @option{-mlsx}. | |
18370 | @smallexample | |
18371 | __m128d __lsx_vfrecipe_d (__m128d); | |
18372 | __m128 __lsx_vfrecipe_s (__m128); | |
18373 | __m128d __lsx_vfrsqrte_d (__m128d); | |
18374 | __m128 __lsx_vfrsqrte_s (__m128); | |
18375 | @end smallexample | |
18376 | ||
1f48786d | 18377 | @node LoongArch ASX Vector Intrinsics |
18378 | @subsection LoongArch ASX Vector Intrinsics | |
18379 | ||
18380 | GCC provides intrinsics to access the LASX (Loongson Advanced SIMD Extension) | |
18381 | instructions. The interface is made available by including @code{<lasxintrin.h>} | |
18382 | and using @option{-mlasx}. | |
18383 | ||
18384 | The following vectors typedefs are included in @code{lasxintrin.h}: | |
18385 | ||
18386 | @itemize | |
18387 | @item @code{__m256i}, a 256-bit vector of fixed point; | |
18388 | @item @code{__m256}, a 256-bit vector of single precision floating point; | |
18389 | @item @code{__m256d}, a 256-bit vector of double precision floating point. | |
18390 | @end itemize | |
18391 | ||
18392 | Instructions and corresponding built-ins may have additional restrictions and/or | |
18393 | input/output values manipulated: | |
18394 | ||
18395 | @itemize | |
18396 | @item @code{imm0_1}, an integer literal in range 0 to 1. | |
18397 | @item @code{imm0_3}, an integer literal in range 0 to 3. | |
18398 | @item @code{imm0_7}, an integer literal in range 0 to 7. | |
18399 | @item @code{imm0_15}, an integer literal in range 0 to 15. | |
18400 | @item @code{imm0_31}, an integer literal in range 0 to 31. | |
18401 | @item @code{imm0_63}, an integer literal in range 0 to 63. | |
18402 | @item @code{imm0_127}, an integer literal in range 0 to 127. | |
18403 | @item @code{imm0_255}, an integer literal in range 0 to 255. | |
18404 | @item @code{imm_n16_15}, an integer literal in range -16 to 15. | |
18405 | @item @code{imm_n128_127}, an integer literal in range -128 to 127. | |
18406 | @item @code{imm_n256_255}, an integer literal in range -256 to 255. | |
18407 | @item @code{imm_n512_511}, an integer literal in range -512 to 511. | |
18408 | @item @code{imm_n1024_1023}, an integer literal in range -1024 to 1023. | |
18409 | @item @code{imm_n2048_2047}, an integer literal in range -2048 to 2047. | |
18410 | @end itemize | |
18411 | ||
18412 | For convenience, GCC defines functions @code{__lasx_xvrepli_@{b/h/w/d@}} and | |
18413 | @code{__lasx_b[n]z_@{v/b/h/w/d@}}, which are implemented as follows: | |
18414 | ||
18415 | @smallexample | |
18416 | a. @code{__lasx_xvrepli_@{b/h/w/d@}}: Implemented the case where the highest | |
18417 | bit of @code{xvldi} instruction @code{i13} is 1. | |
18418 | ||
18419 | i13[12] == 1'b0 | |
18420 | case i13[11:10] of : | |
18421 | 2'b00: __lasx_xvrepli_b (imm_n512_511) | |
18422 | 2'b01: __lasx_xvrepli_h (imm_n512_511) | |
18423 | 2'b10: __lasx_xvrepli_w (imm_n512_511) | |
18424 | 2'b11: __lasx_xvrepli_d (imm_n512_511) | |
18425 | ||
18426 | b. @code{__lasx_b[n]z_@{v/b/h/w/d@}}: Since the @code{xvseteqz} class directive | |
18427 | cannot be used on its own, this function is defined. | |
18428 | ||
18429 | __lasx_xbz_v => xvseteqz.v + bcnez | |
18430 | __lasx_xbnz_v => xvsetnez.v + bcnez | |
18431 | __lasx_xbz_b => xvsetanyeqz.b + bcnez | |
18432 | __lasx_xbz_h => xvsetanyeqz.h + bcnez | |
18433 | __lasx_xbz_w => xvsetanyeqz.w + bcnez | |
18434 | __lasx_xbz_d => xvsetanyeqz.d + bcnez | |
18435 | __lasx_xbnz_b => xvsetallnez.b + bcnez | |
18436 | __lasx_xbnz_h => xvsetallnez.h + bcnez | |
18437 | __lasx_xbnz_w => xvsetallnez.w + bcnez | |
18438 | __lasx_xbnz_d => xvsetallnez.d + bcnez | |
18439 | @end smallexample | |
18440 | ||
18441 | @smallexample | |
18442 | eg: | |
18443 | #include <lasxintrin.h> | |
18444 | ||
18445 | extern __m256i @var{a}; | |
18446 | ||
18447 | void | |
18448 | test (void) | |
18449 | @{ | |
18450 | if (__lasx_xbz_v (@var{a})) | |
18451 | printf ("1\n"); | |
18452 | else | |
18453 | printf ("2\n"); | |
18454 | @} | |
18455 | @end smallexample | |
18456 | ||
18457 | @emph{Note:} For directives where the intent operand is also the source operand | |
18458 | (modifying only part of the bitfield of the intent register), the first parameter | |
18459 | in the builtin call function is used as the intent operand. | |
18460 | ||
18461 | @smallexample | |
18462 | eg: | |
18463 | #include <lasxintrin.h> | |
18464 | extern __m256i @var{dst}; | |
18465 | int @var{src}; | |
18466 | ||
18467 | void | |
18468 | test (void) | |
18469 | @{ | |
18470 | @var{dst} = __lasx_xvinsgr2vr_w (@var{dst}, @var{src}, 3); | |
18471 | @} | |
18472 | @end smallexample | |
18473 | ||
18474 | ||
18475 | The intrinsics provided are listed below: | |
18476 | ||
18477 | @smallexample | |
18478 | __m256i __lasx_vext2xv_d_b (__m256i); | |
18479 | __m256i __lasx_vext2xv_d_h (__m256i); | |
18480 | __m256i __lasx_vext2xv_du_bu (__m256i); | |
18481 | __m256i __lasx_vext2xv_du_hu (__m256i); | |
18482 | __m256i __lasx_vext2xv_du_wu (__m256i); | |
18483 | __m256i __lasx_vext2xv_d_w (__m256i); | |
18484 | __m256i __lasx_vext2xv_h_b (__m256i); | |
18485 | __m256i __lasx_vext2xv_hu_bu (__m256i); | |
18486 | __m256i __lasx_vext2xv_w_b (__m256i); | |
18487 | __m256i __lasx_vext2xv_w_h (__m256i); | |
18488 | __m256i __lasx_vext2xv_wu_bu (__m256i); | |
18489 | __m256i __lasx_vext2xv_wu_hu (__m256i); | |
18490 | int __lasx_xbnz_b (__m256i); | |
18491 | int __lasx_xbnz_d (__m256i); | |
18492 | int __lasx_xbnz_h (__m256i); | |
18493 | int __lasx_xbnz_v (__m256i); | |
18494 | int __lasx_xbnz_w (__m256i); | |
18495 | int __lasx_xbz_b (__m256i); | |
18496 | int __lasx_xbz_d (__m256i); | |
18497 | int __lasx_xbz_h (__m256i); | |
18498 | int __lasx_xbz_v (__m256i); | |
18499 | int __lasx_xbz_w (__m256i); | |
18500 | __m256i __lasx_xvabsd_b (__m256i, __m256i); | |
18501 | __m256i __lasx_xvabsd_bu (__m256i, __m256i); | |
18502 | __m256i __lasx_xvabsd_d (__m256i, __m256i); | |
18503 | __m256i __lasx_xvabsd_du (__m256i, __m256i); | |
18504 | __m256i __lasx_xvabsd_h (__m256i, __m256i); | |
18505 | __m256i __lasx_xvabsd_hu (__m256i, __m256i); | |
18506 | __m256i __lasx_xvabsd_w (__m256i, __m256i); | |
18507 | __m256i __lasx_xvabsd_wu (__m256i, __m256i); | |
18508 | __m256i __lasx_xvadda_b (__m256i, __m256i); | |
18509 | __m256i __lasx_xvadda_d (__m256i, __m256i); | |
18510 | __m256i __lasx_xvadda_h (__m256i, __m256i); | |
18511 | __m256i __lasx_xvadda_w (__m256i, __m256i); | |
18512 | __m256i __lasx_xvadd_b (__m256i, __m256i); | |
18513 | __m256i __lasx_xvadd_d (__m256i, __m256i); | |
18514 | __m256i __lasx_xvadd_h (__m256i, __m256i); | |
18515 | __m256i __lasx_xvaddi_bu (__m256i, imm0_31); | |
18516 | __m256i __lasx_xvaddi_du (__m256i, imm0_31); | |
18517 | __m256i __lasx_xvaddi_hu (__m256i, imm0_31); | |
18518 | __m256i __lasx_xvaddi_wu (__m256i, imm0_31); | |
18519 | __m256i __lasx_xvadd_q (__m256i, __m256i); | |
18520 | __m256i __lasx_xvadd_w (__m256i, __m256i); | |
18521 | __m256i __lasx_xvaddwev_d_w (__m256i, __m256i); | |
18522 | __m256i __lasx_xvaddwev_d_wu (__m256i, __m256i); | |
18523 | __m256i __lasx_xvaddwev_d_wu_w (__m256i, __m256i); | |
18524 | __m256i __lasx_xvaddwev_h_b (__m256i, __m256i); | |
18525 | __m256i __lasx_xvaddwev_h_bu (__m256i, __m256i); | |
18526 | __m256i __lasx_xvaddwev_h_bu_b (__m256i, __m256i); | |
18527 | __m256i __lasx_xvaddwev_q_d (__m256i, __m256i); | |
18528 | __m256i __lasx_xvaddwev_q_du (__m256i, __m256i); | |
18529 | __m256i __lasx_xvaddwev_q_du_d (__m256i, __m256i); | |
18530 | __m256i __lasx_xvaddwev_w_h (__m256i, __m256i); | |
18531 | __m256i __lasx_xvaddwev_w_hu (__m256i, __m256i); | |
18532 | __m256i __lasx_xvaddwev_w_hu_h (__m256i, __m256i); | |
18533 | __m256i __lasx_xvaddwod_d_w (__m256i, __m256i); | |
18534 | __m256i __lasx_xvaddwod_d_wu (__m256i, __m256i); | |
18535 | __m256i __lasx_xvaddwod_d_wu_w (__m256i, __m256i); | |
18536 | __m256i __lasx_xvaddwod_h_b (__m256i, __m256i); | |
18537 | __m256i __lasx_xvaddwod_h_bu (__m256i, __m256i); | |
18538 | __m256i __lasx_xvaddwod_h_bu_b (__m256i, __m256i); | |
18539 | __m256i __lasx_xvaddwod_q_d (__m256i, __m256i); | |
18540 | __m256i __lasx_xvaddwod_q_du (__m256i, __m256i); | |
18541 | __m256i __lasx_xvaddwod_q_du_d (__m256i, __m256i); | |
18542 | __m256i __lasx_xvaddwod_w_h (__m256i, __m256i); | |
18543 | __m256i __lasx_xvaddwod_w_hu (__m256i, __m256i); | |
18544 | __m256i __lasx_xvaddwod_w_hu_h (__m256i, __m256i); | |
18545 | __m256i __lasx_xvandi_b (__m256i, imm0_255); | |
18546 | __m256i __lasx_xvandn_v (__m256i, __m256i); | |
18547 | __m256i __lasx_xvand_v (__m256i, __m256i); | |
18548 | __m256i __lasx_xvavg_b (__m256i, __m256i); | |
18549 | __m256i __lasx_xvavg_bu (__m256i, __m256i); | |
18550 | __m256i __lasx_xvavg_d (__m256i, __m256i); | |
18551 | __m256i __lasx_xvavg_du (__m256i, __m256i); | |
18552 | __m256i __lasx_xvavg_h (__m256i, __m256i); | |
18553 | __m256i __lasx_xvavg_hu (__m256i, __m256i); | |
18554 | __m256i __lasx_xvavgr_b (__m256i, __m256i); | |
18555 | __m256i __lasx_xvavgr_bu (__m256i, __m256i); | |
18556 | __m256i __lasx_xvavgr_d (__m256i, __m256i); | |
18557 | __m256i __lasx_xvavgr_du (__m256i, __m256i); | |
18558 | __m256i __lasx_xvavgr_h (__m256i, __m256i); | |
18559 | __m256i __lasx_xvavgr_hu (__m256i, __m256i); | |
18560 | __m256i __lasx_xvavgr_w (__m256i, __m256i); | |
18561 | __m256i __lasx_xvavgr_wu (__m256i, __m256i); | |
18562 | __m256i __lasx_xvavg_w (__m256i, __m256i); | |
18563 | __m256i __lasx_xvavg_wu (__m256i, __m256i); | |
18564 | __m256i __lasx_xvbitclr_b (__m256i, __m256i); | |
18565 | __m256i __lasx_xvbitclr_d (__m256i, __m256i); | |
18566 | __m256i __lasx_xvbitclr_h (__m256i, __m256i); | |
18567 | __m256i __lasx_xvbitclri_b (__m256i, imm0_7); | |
18568 | __m256i __lasx_xvbitclri_d (__m256i, imm0_63); | |
18569 | __m256i __lasx_xvbitclri_h (__m256i, imm0_15); | |
18570 | __m256i __lasx_xvbitclri_w (__m256i, imm0_31); | |
18571 | __m256i __lasx_xvbitclr_w (__m256i, __m256i); | |
18572 | __m256i __lasx_xvbitrev_b (__m256i, __m256i); | |
18573 | __m256i __lasx_xvbitrev_d (__m256i, __m256i); | |
18574 | __m256i __lasx_xvbitrev_h (__m256i, __m256i); | |
18575 | __m256i __lasx_xvbitrevi_b (__m256i, imm0_7); | |
18576 | __m256i __lasx_xvbitrevi_d (__m256i, imm0_63); | |
18577 | __m256i __lasx_xvbitrevi_h (__m256i, imm0_15); | |
18578 | __m256i __lasx_xvbitrevi_w (__m256i, imm0_31); | |
18579 | __m256i __lasx_xvbitrev_w (__m256i, __m256i); | |
18580 | __m256i __lasx_xvbitseli_b (__m256i, __m256i, imm0_255); | |
18581 | __m256i __lasx_xvbitsel_v (__m256i, __m256i, __m256i); | |
18582 | __m256i __lasx_xvbitset_b (__m256i, __m256i); | |
18583 | __m256i __lasx_xvbitset_d (__m256i, __m256i); | |
18584 | __m256i __lasx_xvbitset_h (__m256i, __m256i); | |
18585 | __m256i __lasx_xvbitseti_b (__m256i, imm0_7); | |
18586 | __m256i __lasx_xvbitseti_d (__m256i, imm0_63); | |
18587 | __m256i __lasx_xvbitseti_h (__m256i, imm0_15); | |
18588 | __m256i __lasx_xvbitseti_w (__m256i, imm0_31); | |
18589 | __m256i __lasx_xvbitset_w (__m256i, __m256i); | |
18590 | __m256i __lasx_xvbsll_v (__m256i, imm0_31); | |
18591 | __m256i __lasx_xvbsrl_v (__m256i, imm0_31); | |
18592 | __m256i __lasx_xvclo_b (__m256i); | |
18593 | __m256i __lasx_xvclo_d (__m256i); | |
18594 | __m256i __lasx_xvclo_h (__m256i); | |
18595 | __m256i __lasx_xvclo_w (__m256i); | |
18596 | __m256i __lasx_xvclz_b (__m256i); | |
18597 | __m256i __lasx_xvclz_d (__m256i); | |
18598 | __m256i __lasx_xvclz_h (__m256i); | |
18599 | __m256i __lasx_xvclz_w (__m256i); | |
18600 | __m256i __lasx_xvdiv_b (__m256i, __m256i); | |
18601 | __m256i __lasx_xvdiv_bu (__m256i, __m256i); | |
18602 | __m256i __lasx_xvdiv_d (__m256i, __m256i); | |
18603 | __m256i __lasx_xvdiv_du (__m256i, __m256i); | |
18604 | __m256i __lasx_xvdiv_h (__m256i, __m256i); | |
18605 | __m256i __lasx_xvdiv_hu (__m256i, __m256i); | |
18606 | __m256i __lasx_xvdiv_w (__m256i, __m256i); | |
18607 | __m256i __lasx_xvdiv_wu (__m256i, __m256i); | |
18608 | __m256i __lasx_xvexth_du_wu (__m256i); | |
18609 | __m256i __lasx_xvexth_d_w (__m256i); | |
18610 | __m256i __lasx_xvexth_h_b (__m256i); | |
18611 | __m256i __lasx_xvexth_hu_bu (__m256i); | |
18612 | __m256i __lasx_xvexth_q_d (__m256i); | |
18613 | __m256i __lasx_xvexth_qu_du (__m256i); | |
18614 | __m256i __lasx_xvexth_w_h (__m256i); | |
18615 | __m256i __lasx_xvexth_wu_hu (__m256i); | |
18616 | __m256i __lasx_xvextl_q_d (__m256i); | |
18617 | __m256i __lasx_xvextl_qu_du (__m256i); | |
18618 | __m256i __lasx_xvextrins_b (__m256i, __m256i, imm0_255); | |
18619 | __m256i __lasx_xvextrins_d (__m256i, __m256i, imm0_255); | |
18620 | __m256i __lasx_xvextrins_h (__m256i, __m256i, imm0_255); | |
18621 | __m256i __lasx_xvextrins_w (__m256i, __m256i, imm0_255); | |
18622 | __m256d __lasx_xvfadd_d (__m256d, __m256d); | |
18623 | __m256 __lasx_xvfadd_s (__m256, __m256); | |
18624 | __m256i __lasx_xvfclass_d (__m256d); | |
18625 | __m256i __lasx_xvfclass_s (__m256); | |
18626 | __m256i __lasx_xvfcmp_caf_d (__m256d, __m256d); | |
18627 | __m256i __lasx_xvfcmp_caf_s (__m256, __m256); | |
18628 | __m256i __lasx_xvfcmp_ceq_d (__m256d, __m256d); | |
18629 | __m256i __lasx_xvfcmp_ceq_s (__m256, __m256); | |
18630 | __m256i __lasx_xvfcmp_cle_d (__m256d, __m256d); | |
18631 | __m256i __lasx_xvfcmp_cle_s (__m256, __m256); | |
18632 | __m256i __lasx_xvfcmp_clt_d (__m256d, __m256d); | |
18633 | __m256i __lasx_xvfcmp_clt_s (__m256, __m256); | |
18634 | __m256i __lasx_xvfcmp_cne_d (__m256d, __m256d); | |
18635 | __m256i __lasx_xvfcmp_cne_s (__m256, __m256); | |
18636 | __m256i __lasx_xvfcmp_cor_d (__m256d, __m256d); | |
18637 | __m256i __lasx_xvfcmp_cor_s (__m256, __m256); | |
18638 | __m256i __lasx_xvfcmp_cueq_d (__m256d, __m256d); | |
18639 | __m256i __lasx_xvfcmp_cueq_s (__m256, __m256); | |
18640 | __m256i __lasx_xvfcmp_cule_d (__m256d, __m256d); | |
18641 | __m256i __lasx_xvfcmp_cule_s (__m256, __m256); | |
18642 | __m256i __lasx_xvfcmp_cult_d (__m256d, __m256d); | |
18643 | __m256i __lasx_xvfcmp_cult_s (__m256, __m256); | |
18644 | __m256i __lasx_xvfcmp_cun_d (__m256d, __m256d); | |
18645 | __m256i __lasx_xvfcmp_cune_d (__m256d, __m256d); | |
18646 | __m256i __lasx_xvfcmp_cune_s (__m256, __m256); | |
18647 | __m256i __lasx_xvfcmp_cun_s (__m256, __m256); | |
18648 | __m256i __lasx_xvfcmp_saf_d (__m256d, __m256d); | |
18649 | __m256i __lasx_xvfcmp_saf_s (__m256, __m256); | |
18650 | __m256i __lasx_xvfcmp_seq_d (__m256d, __m256d); | |
18651 | __m256i __lasx_xvfcmp_seq_s (__m256, __m256); | |
18652 | __m256i __lasx_xvfcmp_sle_d (__m256d, __m256d); | |
18653 | __m256i __lasx_xvfcmp_sle_s (__m256, __m256); | |
18654 | __m256i __lasx_xvfcmp_slt_d (__m256d, __m256d); | |
18655 | __m256i __lasx_xvfcmp_slt_s (__m256, __m256); | |
18656 | __m256i __lasx_xvfcmp_sne_d (__m256d, __m256d); | |
18657 | __m256i __lasx_xvfcmp_sne_s (__m256, __m256); | |
18658 | __m256i __lasx_xvfcmp_sor_d (__m256d, __m256d); | |
18659 | __m256i __lasx_xvfcmp_sor_s (__m256, __m256); | |
18660 | __m256i __lasx_xvfcmp_sueq_d (__m256d, __m256d); | |
18661 | __m256i __lasx_xvfcmp_sueq_s (__m256, __m256); | |
18662 | __m256i __lasx_xvfcmp_sule_d (__m256d, __m256d); | |
18663 | __m256i __lasx_xvfcmp_sule_s (__m256, __m256); | |
18664 | __m256i __lasx_xvfcmp_sult_d (__m256d, __m256d); | |
18665 | __m256i __lasx_xvfcmp_sult_s (__m256, __m256); | |
18666 | __m256i __lasx_xvfcmp_sun_d (__m256d, __m256d); | |
18667 | __m256i __lasx_xvfcmp_sune_d (__m256d, __m256d); | |
18668 | __m256i __lasx_xvfcmp_sune_s (__m256, __m256); | |
18669 | __m256i __lasx_xvfcmp_sun_s (__m256, __m256); | |
18670 | __m256d __lasx_xvfcvth_d_s (__m256); | |
18671 | __m256i __lasx_xvfcvt_h_s (__m256, __m256); | |
18672 | __m256 __lasx_xvfcvth_s_h (__m256i); | |
18673 | __m256d __lasx_xvfcvtl_d_s (__m256); | |
18674 | __m256 __lasx_xvfcvtl_s_h (__m256i); | |
18675 | __m256 __lasx_xvfcvt_s_d (__m256d, __m256d); | |
18676 | __m256d __lasx_xvfdiv_d (__m256d, __m256d); | |
18677 | __m256 __lasx_xvfdiv_s (__m256, __m256); | |
18678 | __m256d __lasx_xvffint_d_l (__m256i); | |
18679 | __m256d __lasx_xvffint_d_lu (__m256i); | |
18680 | __m256d __lasx_xvffinth_d_w (__m256i); | |
18681 | __m256d __lasx_xvffintl_d_w (__m256i); | |
18682 | __m256 __lasx_xvffint_s_l (__m256i, __m256i); | |
18683 | __m256 __lasx_xvffint_s_w (__m256i); | |
18684 | __m256 __lasx_xvffint_s_wu (__m256i); | |
18685 | __m256d __lasx_xvflogb_d (__m256d); | |
18686 | __m256 __lasx_xvflogb_s (__m256); | |
18687 | __m256d __lasx_xvfmadd_d (__m256d, __m256d, __m256d); | |
18688 | __m256 __lasx_xvfmadd_s (__m256, __m256, __m256); | |
18689 | __m256d __lasx_xvfmaxa_d (__m256d, __m256d); | |
18690 | __m256 __lasx_xvfmaxa_s (__m256, __m256); | |
18691 | __m256d __lasx_xvfmax_d (__m256d, __m256d); | |
18692 | __m256 __lasx_xvfmax_s (__m256, __m256); | |
18693 | __m256d __lasx_xvfmina_d (__m256d, __m256d); | |
18694 | __m256 __lasx_xvfmina_s (__m256, __m256); | |
18695 | __m256d __lasx_xvfmin_d (__m256d, __m256d); | |
18696 | __m256 __lasx_xvfmin_s (__m256, __m256); | |
18697 | __m256d __lasx_xvfmsub_d (__m256d, __m256d, __m256d); | |
18698 | __m256 __lasx_xvfmsub_s (__m256, __m256, __m256); | |
18699 | __m256d __lasx_xvfmul_d (__m256d, __m256d); | |
18700 | __m256 __lasx_xvfmul_s (__m256, __m256); | |
18701 | __m256d __lasx_xvfnmadd_d (__m256d, __m256d, __m256d); | |
18702 | __m256 __lasx_xvfnmadd_s (__m256, __m256, __m256); | |
18703 | __m256d __lasx_xvfnmsub_d (__m256d, __m256d, __m256d); | |
18704 | __m256 __lasx_xvfnmsub_s (__m256, __m256, __m256); | |
18705 | __m256d __lasx_xvfrecip_d (__m256d); | |
18706 | __m256 __lasx_xvfrecip_s (__m256); | |
18707 | __m256d __lasx_xvfrint_d (__m256d); | |
297ed1ac | 18708 | __m256d __lasx_xvfrintrm_d (__m256d); |
18709 | __m256 __lasx_xvfrintrm_s (__m256); | |
18710 | __m256d __lasx_xvfrintrne_d (__m256d); | |
18711 | __m256 __lasx_xvfrintrne_s (__m256); | |
18712 | __m256d __lasx_xvfrintrp_d (__m256d); | |
18713 | __m256 __lasx_xvfrintrp_s (__m256); | |
18714 | __m256d __lasx_xvfrintrz_d (__m256d); | |
18715 | __m256 __lasx_xvfrintrz_s (__m256); | |
1f48786d | 18716 | __m256 __lasx_xvfrint_s (__m256); |
18717 | __m256d __lasx_xvfrsqrt_d (__m256d); | |
18718 | __m256 __lasx_xvfrsqrt_s (__m256); | |
18719 | __m256i __lasx_xvfrstp_b (__m256i, __m256i, __m256i); | |
18720 | __m256i __lasx_xvfrstp_h (__m256i, __m256i, __m256i); | |
18721 | __m256i __lasx_xvfrstpi_b (__m256i, __m256i, imm0_31); | |
18722 | __m256i __lasx_xvfrstpi_h (__m256i, __m256i, imm0_31); | |
18723 | __m256d __lasx_xvfsqrt_d (__m256d); | |
18724 | __m256 __lasx_xvfsqrt_s (__m256); | |
18725 | __m256d __lasx_xvfsub_d (__m256d, __m256d); | |
18726 | __m256 __lasx_xvfsub_s (__m256, __m256); | |
18727 | __m256i __lasx_xvftinth_l_s (__m256); | |
18728 | __m256i __lasx_xvftint_l_d (__m256d); | |
18729 | __m256i __lasx_xvftintl_l_s (__m256); | |
18730 | __m256i __lasx_xvftint_lu_d (__m256d); | |
18731 | __m256i __lasx_xvftintrmh_l_s (__m256); | |
18732 | __m256i __lasx_xvftintrm_l_d (__m256d); | |
18733 | __m256i __lasx_xvftintrml_l_s (__m256); | |
18734 | __m256i __lasx_xvftintrm_w_d (__m256d, __m256d); | |
18735 | __m256i __lasx_xvftintrm_w_s (__m256); | |
18736 | __m256i __lasx_xvftintrneh_l_s (__m256); | |
18737 | __m256i __lasx_xvftintrne_l_d (__m256d); | |
18738 | __m256i __lasx_xvftintrnel_l_s (__m256); | |
18739 | __m256i __lasx_xvftintrne_w_d (__m256d, __m256d); | |
18740 | __m256i __lasx_xvftintrne_w_s (__m256); | |
18741 | __m256i __lasx_xvftintrph_l_s (__m256); | |
18742 | __m256i __lasx_xvftintrp_l_d (__m256d); | |
18743 | __m256i __lasx_xvftintrpl_l_s (__m256); | |
18744 | __m256i __lasx_xvftintrp_w_d (__m256d, __m256d); | |
18745 | __m256i __lasx_xvftintrp_w_s (__m256); | |
18746 | __m256i __lasx_xvftintrzh_l_s (__m256); | |
18747 | __m256i __lasx_xvftintrz_l_d (__m256d); | |
18748 | __m256i __lasx_xvftintrzl_l_s (__m256); | |
18749 | __m256i __lasx_xvftintrz_lu_d (__m256d); | |
18750 | __m256i __lasx_xvftintrz_w_d (__m256d, __m256d); | |
18751 | __m256i __lasx_xvftintrz_w_s (__m256); | |
18752 | __m256i __lasx_xvftintrz_wu_s (__m256); | |
18753 | __m256i __lasx_xvftint_w_d (__m256d, __m256d); | |
18754 | __m256i __lasx_xvftint_w_s (__m256); | |
18755 | __m256i __lasx_xvftint_wu_s (__m256); | |
18756 | __m256i __lasx_xvhaddw_du_wu (__m256i, __m256i); | |
18757 | __m256i __lasx_xvhaddw_d_w (__m256i, __m256i); | |
18758 | __m256i __lasx_xvhaddw_h_b (__m256i, __m256i); | |
18759 | __m256i __lasx_xvhaddw_hu_bu (__m256i, __m256i); | |
18760 | __m256i __lasx_xvhaddw_q_d (__m256i, __m256i); | |
18761 | __m256i __lasx_xvhaddw_qu_du (__m256i, __m256i); | |
18762 | __m256i __lasx_xvhaddw_w_h (__m256i, __m256i); | |
18763 | __m256i __lasx_xvhaddw_wu_hu (__m256i, __m256i); | |
18764 | __m256i __lasx_xvhsubw_du_wu (__m256i, __m256i); | |
18765 | __m256i __lasx_xvhsubw_d_w (__m256i, __m256i); | |
18766 | __m256i __lasx_xvhsubw_h_b (__m256i, __m256i); | |
18767 | __m256i __lasx_xvhsubw_hu_bu (__m256i, __m256i); | |
18768 | __m256i __lasx_xvhsubw_q_d (__m256i, __m256i); | |
18769 | __m256i __lasx_xvhsubw_qu_du (__m256i, __m256i); | |
18770 | __m256i __lasx_xvhsubw_w_h (__m256i, __m256i); | |
18771 | __m256i __lasx_xvhsubw_wu_hu (__m256i, __m256i); | |
18772 | __m256i __lasx_xvilvh_b (__m256i, __m256i); | |
18773 | __m256i __lasx_xvilvh_d (__m256i, __m256i); | |
18774 | __m256i __lasx_xvilvh_h (__m256i, __m256i); | |
18775 | __m256i __lasx_xvilvh_w (__m256i, __m256i); | |
18776 | __m256i __lasx_xvilvl_b (__m256i, __m256i); | |
18777 | __m256i __lasx_xvilvl_d (__m256i, __m256i); | |
18778 | __m256i __lasx_xvilvl_h (__m256i, __m256i); | |
18779 | __m256i __lasx_xvilvl_w (__m256i, __m256i); | |
18780 | __m256i __lasx_xvinsgr2vr_d (__m256i, long int, imm0_3); | |
18781 | __m256i __lasx_xvinsgr2vr_w (__m256i, int, imm0_7); | |
18782 | __m256i __lasx_xvinsve0_d (__m256i, __m256i, imm0_3); | |
18783 | __m256i __lasx_xvinsve0_w (__m256i, __m256i, imm0_7); | |
18784 | __m256i __lasx_xvld (void *, imm_n2048_2047); | |
18785 | __m256i __lasx_xvldi (imm_n1024_1023); | |
18786 | __m256i __lasx_xvldrepl_b (void *, imm_n2048_2047); | |
18787 | __m256i __lasx_xvldrepl_d (void *, imm_n256_255); | |
18788 | __m256i __lasx_xvldrepl_h (void *, imm_n1024_1023); | |
18789 | __m256i __lasx_xvldrepl_w (void *, imm_n512_511); | |
18790 | __m256i __lasx_xvldx (void *, long int); | |
18791 | __m256i __lasx_xvmadd_b (__m256i, __m256i, __m256i); | |
18792 | __m256i __lasx_xvmadd_d (__m256i, __m256i, __m256i); | |
18793 | __m256i __lasx_xvmadd_h (__m256i, __m256i, __m256i); | |
18794 | __m256i __lasx_xvmadd_w (__m256i, __m256i, __m256i); | |
18795 | __m256i __lasx_xvmaddwev_d_w (__m256i, __m256i, __m256i); | |
18796 | __m256i __lasx_xvmaddwev_d_wu (__m256i, __m256i, __m256i); | |
18797 | __m256i __lasx_xvmaddwev_d_wu_w (__m256i, __m256i, __m256i); | |
18798 | __m256i __lasx_xvmaddwev_h_b (__m256i, __m256i, __m256i); | |
18799 | __m256i __lasx_xvmaddwev_h_bu (__m256i, __m256i, __m256i); | |
18800 | __m256i __lasx_xvmaddwev_h_bu_b (__m256i, __m256i, __m256i); | |
18801 | __m256i __lasx_xvmaddwev_q_d (__m256i, __m256i, __m256i); | |
18802 | __m256i __lasx_xvmaddwev_q_du (__m256i, __m256i, __m256i); | |
18803 | __m256i __lasx_xvmaddwev_q_du_d (__m256i, __m256i, __m256i); | |
18804 | __m256i __lasx_xvmaddwev_w_h (__m256i, __m256i, __m256i); | |
18805 | __m256i __lasx_xvmaddwev_w_hu (__m256i, __m256i, __m256i); | |
18806 | __m256i __lasx_xvmaddwev_w_hu_h (__m256i, __m256i, __m256i); | |
18807 | __m256i __lasx_xvmaddwod_d_w (__m256i, __m256i, __m256i); | |
18808 | __m256i __lasx_xvmaddwod_d_wu (__m256i, __m256i, __m256i); | |
18809 | __m256i __lasx_xvmaddwod_d_wu_w (__m256i, __m256i, __m256i); | |
18810 | __m256i __lasx_xvmaddwod_h_b (__m256i, __m256i, __m256i); | |
18811 | __m256i __lasx_xvmaddwod_h_bu (__m256i, __m256i, __m256i); | |
18812 | __m256i __lasx_xvmaddwod_h_bu_b (__m256i, __m256i, __m256i); | |
18813 | __m256i __lasx_xvmaddwod_q_d (__m256i, __m256i, __m256i); | |
18814 | __m256i __lasx_xvmaddwod_q_du (__m256i, __m256i, __m256i); | |
18815 | __m256i __lasx_xvmaddwod_q_du_d (__m256i, __m256i, __m256i); | |
18816 | __m256i __lasx_xvmaddwod_w_h (__m256i, __m256i, __m256i); | |
18817 | __m256i __lasx_xvmaddwod_w_hu (__m256i, __m256i, __m256i); | |
18818 | __m256i __lasx_xvmaddwod_w_hu_h (__m256i, __m256i, __m256i); | |
18819 | __m256i __lasx_xvmax_b (__m256i, __m256i); | |
18820 | __m256i __lasx_xvmax_bu (__m256i, __m256i); | |
18821 | __m256i __lasx_xvmax_d (__m256i, __m256i); | |
18822 | __m256i __lasx_xvmax_du (__m256i, __m256i); | |
18823 | __m256i __lasx_xvmax_h (__m256i, __m256i); | |
18824 | __m256i __lasx_xvmax_hu (__m256i, __m256i); | |
18825 | __m256i __lasx_xvmaxi_b (__m256i, imm_n16_15); | |
18826 | __m256i __lasx_xvmaxi_bu (__m256i, imm0_31); | |
18827 | __m256i __lasx_xvmaxi_d (__m256i, imm_n16_15); | |
18828 | __m256i __lasx_xvmaxi_du (__m256i, imm0_31); | |
18829 | __m256i __lasx_xvmaxi_h (__m256i, imm_n16_15); | |
18830 | __m256i __lasx_xvmaxi_hu (__m256i, imm0_31); | |
18831 | __m256i __lasx_xvmaxi_w (__m256i, imm_n16_15); | |
18832 | __m256i __lasx_xvmaxi_wu (__m256i, imm0_31); | |
18833 | __m256i __lasx_xvmax_w (__m256i, __m256i); | |
18834 | __m256i __lasx_xvmax_wu (__m256i, __m256i); | |
18835 | __m256i __lasx_xvmin_b (__m256i, __m256i); | |
18836 | __m256i __lasx_xvmin_bu (__m256i, __m256i); | |
18837 | __m256i __lasx_xvmin_d (__m256i, __m256i); | |
18838 | __m256i __lasx_xvmin_du (__m256i, __m256i); | |
18839 | __m256i __lasx_xvmin_h (__m256i, __m256i); | |
18840 | __m256i __lasx_xvmin_hu (__m256i, __m256i); | |
18841 | __m256i __lasx_xvmini_b (__m256i, imm_n16_15); | |
18842 | __m256i __lasx_xvmini_bu (__m256i, imm0_31); | |
18843 | __m256i __lasx_xvmini_d (__m256i, imm_n16_15); | |
18844 | __m256i __lasx_xvmini_du (__m256i, imm0_31); | |
18845 | __m256i __lasx_xvmini_h (__m256i, imm_n16_15); | |
18846 | __m256i __lasx_xvmini_hu (__m256i, imm0_31); | |
18847 | __m256i __lasx_xvmini_w (__m256i, imm_n16_15); | |
18848 | __m256i __lasx_xvmini_wu (__m256i, imm0_31); | |
18849 | __m256i __lasx_xvmin_w (__m256i, __m256i); | |
18850 | __m256i __lasx_xvmin_wu (__m256i, __m256i); | |
18851 | __m256i __lasx_xvmod_b (__m256i, __m256i); | |
18852 | __m256i __lasx_xvmod_bu (__m256i, __m256i); | |
18853 | __m256i __lasx_xvmod_d (__m256i, __m256i); | |
18854 | __m256i __lasx_xvmod_du (__m256i, __m256i); | |
18855 | __m256i __lasx_xvmod_h (__m256i, __m256i); | |
18856 | __m256i __lasx_xvmod_hu (__m256i, __m256i); | |
18857 | __m256i __lasx_xvmod_w (__m256i, __m256i); | |
18858 | __m256i __lasx_xvmod_wu (__m256i, __m256i); | |
18859 | __m256i __lasx_xvmskgez_b (__m256i); | |
18860 | __m256i __lasx_xvmskltz_b (__m256i); | |
18861 | __m256i __lasx_xvmskltz_d (__m256i); | |
18862 | __m256i __lasx_xvmskltz_h (__m256i); | |
18863 | __m256i __lasx_xvmskltz_w (__m256i); | |
18864 | __m256i __lasx_xvmsknz_b (__m256i); | |
18865 | __m256i __lasx_xvmsub_b (__m256i, __m256i, __m256i); | |
18866 | __m256i __lasx_xvmsub_d (__m256i, __m256i, __m256i); | |
18867 | __m256i __lasx_xvmsub_h (__m256i, __m256i, __m256i); | |
18868 | __m256i __lasx_xvmsub_w (__m256i, __m256i, __m256i); | |
18869 | __m256i __lasx_xvmuh_b (__m256i, __m256i); | |
18870 | __m256i __lasx_xvmuh_bu (__m256i, __m256i); | |
18871 | __m256i __lasx_xvmuh_d (__m256i, __m256i); | |
18872 | __m256i __lasx_xvmuh_du (__m256i, __m256i); | |
18873 | __m256i __lasx_xvmuh_h (__m256i, __m256i); | |
18874 | __m256i __lasx_xvmuh_hu (__m256i, __m256i); | |
18875 | __m256i __lasx_xvmuh_w (__m256i, __m256i); | |
18876 | __m256i __lasx_xvmuh_wu (__m256i, __m256i); | |
18877 | __m256i __lasx_xvmul_b (__m256i, __m256i); | |
18878 | __m256i __lasx_xvmul_d (__m256i, __m256i); | |
18879 | __m256i __lasx_xvmul_h (__m256i, __m256i); | |
18880 | __m256i __lasx_xvmul_w (__m256i, __m256i); | |
18881 | __m256i __lasx_xvmulwev_d_w (__m256i, __m256i); | |
18882 | __m256i __lasx_xvmulwev_d_wu (__m256i, __m256i); | |
18883 | __m256i __lasx_xvmulwev_d_wu_w (__m256i, __m256i); | |
18884 | __m256i __lasx_xvmulwev_h_b (__m256i, __m256i); | |
18885 | __m256i __lasx_xvmulwev_h_bu (__m256i, __m256i); | |
18886 | __m256i __lasx_xvmulwev_h_bu_b (__m256i, __m256i); | |
18887 | __m256i __lasx_xvmulwev_q_d (__m256i, __m256i); | |
18888 | __m256i __lasx_xvmulwev_q_du (__m256i, __m256i); | |
18889 | __m256i __lasx_xvmulwev_q_du_d (__m256i, __m256i); | |
18890 | __m256i __lasx_xvmulwev_w_h (__m256i, __m256i); | |
18891 | __m256i __lasx_xvmulwev_w_hu (__m256i, __m256i); | |
18892 | __m256i __lasx_xvmulwev_w_hu_h (__m256i, __m256i); | |
18893 | __m256i __lasx_xvmulwod_d_w (__m256i, __m256i); | |
18894 | __m256i __lasx_xvmulwod_d_wu (__m256i, __m256i); | |
18895 | __m256i __lasx_xvmulwod_d_wu_w (__m256i, __m256i); | |
18896 | __m256i __lasx_xvmulwod_h_b (__m256i, __m256i); | |
18897 | __m256i __lasx_xvmulwod_h_bu (__m256i, __m256i); | |
18898 | __m256i __lasx_xvmulwod_h_bu_b (__m256i, __m256i); | |
18899 | __m256i __lasx_xvmulwod_q_d (__m256i, __m256i); | |
18900 | __m256i __lasx_xvmulwod_q_du (__m256i, __m256i); | |
18901 | __m256i __lasx_xvmulwod_q_du_d (__m256i, __m256i); | |
18902 | __m256i __lasx_xvmulwod_w_h (__m256i, __m256i); | |
18903 | __m256i __lasx_xvmulwod_w_hu (__m256i, __m256i); | |
18904 | __m256i __lasx_xvmulwod_w_hu_h (__m256i, __m256i); | |
18905 | __m256i __lasx_xvneg_b (__m256i); | |
18906 | __m256i __lasx_xvneg_d (__m256i); | |
18907 | __m256i __lasx_xvneg_h (__m256i); | |
18908 | __m256i __lasx_xvneg_w (__m256i); | |
18909 | __m256i __lasx_xvnori_b (__m256i, imm0_255); | |
18910 | __m256i __lasx_xvnor_v (__m256i, __m256i); | |
18911 | __m256i __lasx_xvori_b (__m256i, imm0_255); | |
18912 | __m256i __lasx_xvorn_v (__m256i, __m256i); | |
18913 | __m256i __lasx_xvor_v (__m256i, __m256i); | |
18914 | __m256i __lasx_xvpackev_b (__m256i, __m256i); | |
18915 | __m256i __lasx_xvpackev_d (__m256i, __m256i); | |
18916 | __m256i __lasx_xvpackev_h (__m256i, __m256i); | |
18917 | __m256i __lasx_xvpackev_w (__m256i, __m256i); | |
18918 | __m256i __lasx_xvpackod_b (__m256i, __m256i); | |
18919 | __m256i __lasx_xvpackod_d (__m256i, __m256i); | |
18920 | __m256i __lasx_xvpackod_h (__m256i, __m256i); | |
18921 | __m256i __lasx_xvpackod_w (__m256i, __m256i); | |
18922 | __m256i __lasx_xvpcnt_b (__m256i); | |
18923 | __m256i __lasx_xvpcnt_d (__m256i); | |
18924 | __m256i __lasx_xvpcnt_h (__m256i); | |
18925 | __m256i __lasx_xvpcnt_w (__m256i); | |
18926 | __m256i __lasx_xvpermi_d (__m256i, imm0_255); | |
18927 | __m256i __lasx_xvpermi_q (__m256i, __m256i, imm0_255); | |
18928 | __m256i __lasx_xvpermi_w (__m256i, __m256i, imm0_255); | |
18929 | __m256i __lasx_xvperm_w (__m256i, __m256i); | |
18930 | __m256i __lasx_xvpickev_b (__m256i, __m256i); | |
18931 | __m256i __lasx_xvpickev_d (__m256i, __m256i); | |
18932 | __m256i __lasx_xvpickev_h (__m256i, __m256i); | |
18933 | __m256i __lasx_xvpickev_w (__m256i, __m256i); | |
18934 | __m256i __lasx_xvpickod_b (__m256i, __m256i); | |
18935 | __m256i __lasx_xvpickod_d (__m256i, __m256i); | |
18936 | __m256i __lasx_xvpickod_h (__m256i, __m256i); | |
18937 | __m256i __lasx_xvpickod_w (__m256i, __m256i); | |
18938 | long int __lasx_xvpickve2gr_d (__m256i, imm0_3); | |
18939 | unsigned long int __lasx_xvpickve2gr_du (__m256i, imm0_3); | |
18940 | int __lasx_xvpickve2gr_w (__m256i, imm0_7); | |
18941 | unsigned int __lasx_xvpickve2gr_wu (__m256i, imm0_7); | |
18942 | __m256i __lasx_xvpickve_d (__m256i, imm0_3); | |
18943 | __m256d __lasx_xvpickve_d_f (__m256d, imm0_3); | |
18944 | __m256i __lasx_xvpickve_w (__m256i, imm0_7); | |
18945 | __m256 __lasx_xvpickve_w_f (__m256, imm0_7); | |
18946 | __m256i __lasx_xvrepl128vei_b (__m256i, imm0_15); | |
18947 | __m256i __lasx_xvrepl128vei_d (__m256i, imm0_1); | |
18948 | __m256i __lasx_xvrepl128vei_h (__m256i, imm0_7); | |
18949 | __m256i __lasx_xvrepl128vei_w (__m256i, imm0_3); | |
18950 | __m256i __lasx_xvreplgr2vr_b (int); | |
18951 | __m256i __lasx_xvreplgr2vr_d (long int); | |
18952 | __m256i __lasx_xvreplgr2vr_h (int); | |
18953 | __m256i __lasx_xvreplgr2vr_w (int); | |
18954 | __m256i __lasx_xvrepli_b (imm_n512_511); | |
18955 | __m256i __lasx_xvrepli_d (imm_n512_511); | |
18956 | __m256i __lasx_xvrepli_h (imm_n512_511); | |
18957 | __m256i __lasx_xvrepli_w (imm_n512_511); | |
18958 | __m256i __lasx_xvreplve0_b (__m256i); | |
18959 | __m256i __lasx_xvreplve0_d (__m256i); | |
18960 | __m256i __lasx_xvreplve0_h (__m256i); | |
18961 | __m256i __lasx_xvreplve0_q (__m256i); | |
18962 | __m256i __lasx_xvreplve0_w (__m256i); | |
18963 | __m256i __lasx_xvreplve_b (__m256i, int); | |
18964 | __m256i __lasx_xvreplve_d (__m256i, int); | |
18965 | __m256i __lasx_xvreplve_h (__m256i, int); | |
18966 | __m256i __lasx_xvreplve_w (__m256i, int); | |
18967 | __m256i __lasx_xvrotr_b (__m256i, __m256i); | |
18968 | __m256i __lasx_xvrotr_d (__m256i, __m256i); | |
18969 | __m256i __lasx_xvrotr_h (__m256i, __m256i); | |
18970 | __m256i __lasx_xvrotri_b (__m256i, imm0_7); | |
18971 | __m256i __lasx_xvrotri_d (__m256i, imm0_63); | |
18972 | __m256i __lasx_xvrotri_h (__m256i, imm0_15); | |
18973 | __m256i __lasx_xvrotri_w (__m256i, imm0_31); | |
18974 | __m256i __lasx_xvrotr_w (__m256i, __m256i); | |
18975 | __m256i __lasx_xvsadd_b (__m256i, __m256i); | |
18976 | __m256i __lasx_xvsadd_bu (__m256i, __m256i); | |
18977 | __m256i __lasx_xvsadd_d (__m256i, __m256i); | |
18978 | __m256i __lasx_xvsadd_du (__m256i, __m256i); | |
18979 | __m256i __lasx_xvsadd_h (__m256i, __m256i); | |
18980 | __m256i __lasx_xvsadd_hu (__m256i, __m256i); | |
18981 | __m256i __lasx_xvsadd_w (__m256i, __m256i); | |
18982 | __m256i __lasx_xvsadd_wu (__m256i, __m256i); | |
18983 | __m256i __lasx_xvsat_b (__m256i, imm0_7); | |
18984 | __m256i __lasx_xvsat_bu (__m256i, imm0_7); | |
18985 | __m256i __lasx_xvsat_d (__m256i, imm0_63); | |
18986 | __m256i __lasx_xvsat_du (__m256i, imm0_63); | |
18987 | __m256i __lasx_xvsat_h (__m256i, imm0_15); | |
18988 | __m256i __lasx_xvsat_hu (__m256i, imm0_15); | |
18989 | __m256i __lasx_xvsat_w (__m256i, imm0_31); | |
18990 | __m256i __lasx_xvsat_wu (__m256i, imm0_31); | |
18991 | __m256i __lasx_xvseq_b (__m256i, __m256i); | |
18992 | __m256i __lasx_xvseq_d (__m256i, __m256i); | |
18993 | __m256i __lasx_xvseq_h (__m256i, __m256i); | |
18994 | __m256i __lasx_xvseqi_b (__m256i, imm_n16_15); | |
18995 | __m256i __lasx_xvseqi_d (__m256i, imm_n16_15); | |
18996 | __m256i __lasx_xvseqi_h (__m256i, imm_n16_15); | |
18997 | __m256i __lasx_xvseqi_w (__m256i, imm_n16_15); | |
18998 | __m256i __lasx_xvseq_w (__m256i, __m256i); | |
18999 | __m256i __lasx_xvshuf4i_b (__m256i, imm0_255); | |
19000 | __m256i __lasx_xvshuf4i_d (__m256i, __m256i, imm0_255); | |
19001 | __m256i __lasx_xvshuf4i_h (__m256i, imm0_255); | |
19002 | __m256i __lasx_xvshuf4i_w (__m256i, imm0_255); | |
19003 | __m256i __lasx_xvshuf_b (__m256i, __m256i, __m256i); | |
19004 | __m256i __lasx_xvshuf_d (__m256i, __m256i, __m256i); | |
19005 | __m256i __lasx_xvshuf_h (__m256i, __m256i, __m256i); | |
19006 | __m256i __lasx_xvshuf_w (__m256i, __m256i, __m256i); | |
19007 | __m256i __lasx_xvsigncov_b (__m256i, __m256i); | |
19008 | __m256i __lasx_xvsigncov_d (__m256i, __m256i); | |
19009 | __m256i __lasx_xvsigncov_h (__m256i, __m256i); | |
19010 | __m256i __lasx_xvsigncov_w (__m256i, __m256i); | |
19011 | __m256i __lasx_xvsle_b (__m256i, __m256i); | |
19012 | __m256i __lasx_xvsle_bu (__m256i, __m256i); | |
19013 | __m256i __lasx_xvsle_d (__m256i, __m256i); | |
19014 | __m256i __lasx_xvsle_du (__m256i, __m256i); | |
19015 | __m256i __lasx_xvsle_h (__m256i, __m256i); | |
19016 | __m256i __lasx_xvsle_hu (__m256i, __m256i); | |
19017 | __m256i __lasx_xvslei_b (__m256i, imm_n16_15); | |
19018 | __m256i __lasx_xvslei_bu (__m256i, imm0_31); | |
19019 | __m256i __lasx_xvslei_d (__m256i, imm_n16_15); | |
19020 | __m256i __lasx_xvslei_du (__m256i, imm0_31); | |
19021 | __m256i __lasx_xvslei_h (__m256i, imm_n16_15); | |
19022 | __m256i __lasx_xvslei_hu (__m256i, imm0_31); | |
19023 | __m256i __lasx_xvslei_w (__m256i, imm_n16_15); | |
19024 | __m256i __lasx_xvslei_wu (__m256i, imm0_31); | |
19025 | __m256i __lasx_xvsle_w (__m256i, __m256i); | |
19026 | __m256i __lasx_xvsle_wu (__m256i, __m256i); | |
19027 | __m256i __lasx_xvsll_b (__m256i, __m256i); | |
19028 | __m256i __lasx_xvsll_d (__m256i, __m256i); | |
19029 | __m256i __lasx_xvsll_h (__m256i, __m256i); | |
19030 | __m256i __lasx_xvslli_b (__m256i, imm0_7); | |
19031 | __m256i __lasx_xvslli_d (__m256i, imm0_63); | |
19032 | __m256i __lasx_xvslli_h (__m256i, imm0_15); | |
19033 | __m256i __lasx_xvslli_w (__m256i, imm0_31); | |
19034 | __m256i __lasx_xvsll_w (__m256i, __m256i); | |
19035 | __m256i __lasx_xvsllwil_du_wu (__m256i, imm0_31); | |
19036 | __m256i __lasx_xvsllwil_d_w (__m256i, imm0_31); | |
19037 | __m256i __lasx_xvsllwil_h_b (__m256i, imm0_7); | |
19038 | __m256i __lasx_xvsllwil_hu_bu (__m256i, imm0_7); | |
19039 | __m256i __lasx_xvsllwil_w_h (__m256i, imm0_15); | |
19040 | __m256i __lasx_xvsllwil_wu_hu (__m256i, imm0_15); | |
19041 | __m256i __lasx_xvslt_b (__m256i, __m256i); | |
19042 | __m256i __lasx_xvslt_bu (__m256i, __m256i); | |
19043 | __m256i __lasx_xvslt_d (__m256i, __m256i); | |
19044 | __m256i __lasx_xvslt_du (__m256i, __m256i); | |
19045 | __m256i __lasx_xvslt_h (__m256i, __m256i); | |
19046 | __m256i __lasx_xvslt_hu (__m256i, __m256i); | |
19047 | __m256i __lasx_xvslti_b (__m256i, imm_n16_15); | |
19048 | __m256i __lasx_xvslti_bu (__m256i, imm0_31); | |
19049 | __m256i __lasx_xvslti_d (__m256i, imm_n16_15); | |
19050 | __m256i __lasx_xvslti_du (__m256i, imm0_31); | |
19051 | __m256i __lasx_xvslti_h (__m256i, imm_n16_15); | |
19052 | __m256i __lasx_xvslti_hu (__m256i, imm0_31); | |
19053 | __m256i __lasx_xvslti_w (__m256i, imm_n16_15); | |
19054 | __m256i __lasx_xvslti_wu (__m256i, imm0_31); | |
19055 | __m256i __lasx_xvslt_w (__m256i, __m256i); | |
19056 | __m256i __lasx_xvslt_wu (__m256i, __m256i); | |
19057 | __m256i __lasx_xvsra_b (__m256i, __m256i); | |
19058 | __m256i __lasx_xvsra_d (__m256i, __m256i); | |
19059 | __m256i __lasx_xvsra_h (__m256i, __m256i); | |
19060 | __m256i __lasx_xvsrai_b (__m256i, imm0_7); | |
19061 | __m256i __lasx_xvsrai_d (__m256i, imm0_63); | |
19062 | __m256i __lasx_xvsrai_h (__m256i, imm0_15); | |
19063 | __m256i __lasx_xvsrai_w (__m256i, imm0_31); | |
19064 | __m256i __lasx_xvsran_b_h (__m256i, __m256i); | |
19065 | __m256i __lasx_xvsran_h_w (__m256i, __m256i); | |
19066 | __m256i __lasx_xvsrani_b_h (__m256i, __m256i, imm0_15); | |
19067 | __m256i __lasx_xvsrani_d_q (__m256i, __m256i, imm0_127); | |
19068 | __m256i __lasx_xvsrani_h_w (__m256i, __m256i, imm0_31); | |
19069 | __m256i __lasx_xvsrani_w_d (__m256i, __m256i, imm0_63); | |
19070 | __m256i __lasx_xvsran_w_d (__m256i, __m256i); | |
19071 | __m256i __lasx_xvsrar_b (__m256i, __m256i); | |
19072 | __m256i __lasx_xvsrar_d (__m256i, __m256i); | |
19073 | __m256i __lasx_xvsrar_h (__m256i, __m256i); | |
19074 | __m256i __lasx_xvsrari_b (__m256i, imm0_7); | |
19075 | __m256i __lasx_xvsrari_d (__m256i, imm0_63); | |
19076 | __m256i __lasx_xvsrari_h (__m256i, imm0_15); | |
19077 | __m256i __lasx_xvsrari_w (__m256i, imm0_31); | |
19078 | __m256i __lasx_xvsrarn_b_h (__m256i, __m256i); | |
19079 | __m256i __lasx_xvsrarn_h_w (__m256i, __m256i); | |
19080 | __m256i __lasx_xvsrarni_b_h (__m256i, __m256i, imm0_15); | |
19081 | __m256i __lasx_xvsrarni_d_q (__m256i, __m256i, imm0_127); | |
19082 | __m256i __lasx_xvsrarni_h_w (__m256i, __m256i, imm0_31); | |
19083 | __m256i __lasx_xvsrarni_w_d (__m256i, __m256i, imm0_63); | |
19084 | __m256i __lasx_xvsrarn_w_d (__m256i, __m256i); | |
19085 | __m256i __lasx_xvsrar_w (__m256i, __m256i); | |
19086 | __m256i __lasx_xvsra_w (__m256i, __m256i); | |
19087 | __m256i __lasx_xvsrl_b (__m256i, __m256i); | |
19088 | __m256i __lasx_xvsrl_d (__m256i, __m256i); | |
19089 | __m256i __lasx_xvsrl_h (__m256i, __m256i); | |
19090 | __m256i __lasx_xvsrli_b (__m256i, imm0_7); | |
19091 | __m256i __lasx_xvsrli_d (__m256i, imm0_63); | |
19092 | __m256i __lasx_xvsrli_h (__m256i, imm0_15); | |
19093 | __m256i __lasx_xvsrli_w (__m256i, imm0_31); | |
19094 | __m256i __lasx_xvsrln_b_h (__m256i, __m256i); | |
19095 | __m256i __lasx_xvsrln_h_w (__m256i, __m256i); | |
19096 | __m256i __lasx_xvsrlni_b_h (__m256i, __m256i, imm0_15); | |
19097 | __m256i __lasx_xvsrlni_d_q (__m256i, __m256i, imm0_127); | |
19098 | __m256i __lasx_xvsrlni_h_w (__m256i, __m256i, imm0_31); | |
19099 | __m256i __lasx_xvsrlni_w_d (__m256i, __m256i, imm0_63); | |
19100 | __m256i __lasx_xvsrln_w_d (__m256i, __m256i); | |
19101 | __m256i __lasx_xvsrlr_b (__m256i, __m256i); | |
19102 | __m256i __lasx_xvsrlr_d (__m256i, __m256i); | |
19103 | __m256i __lasx_xvsrlr_h (__m256i, __m256i); | |
19104 | __m256i __lasx_xvsrlri_b (__m256i, imm0_7); | |
19105 | __m256i __lasx_xvsrlri_d (__m256i, imm0_63); | |
19106 | __m256i __lasx_xvsrlri_h (__m256i, imm0_15); | |
19107 | __m256i __lasx_xvsrlri_w (__m256i, imm0_31); | |
19108 | __m256i __lasx_xvsrlrn_b_h (__m256i, __m256i); | |
19109 | __m256i __lasx_xvsrlrn_h_w (__m256i, __m256i); | |
19110 | __m256i __lasx_xvsrlrni_b_h (__m256i, __m256i, imm0_15); | |
19111 | __m256i __lasx_xvsrlrni_d_q (__m256i, __m256i, imm0_127); | |
19112 | __m256i __lasx_xvsrlrni_h_w (__m256i, __m256i, imm0_31); | |
19113 | __m256i __lasx_xvsrlrni_w_d (__m256i, __m256i, imm0_63); | |
19114 | __m256i __lasx_xvsrlrn_w_d (__m256i, __m256i); | |
19115 | __m256i __lasx_xvsrlr_w (__m256i, __m256i); | |
19116 | __m256i __lasx_xvsrl_w (__m256i, __m256i); | |
19117 | __m256i __lasx_xvssran_b_h (__m256i, __m256i); | |
19118 | __m256i __lasx_xvssran_bu_h (__m256i, __m256i); | |
19119 | __m256i __lasx_xvssran_hu_w (__m256i, __m256i); | |
19120 | __m256i __lasx_xvssran_h_w (__m256i, __m256i); | |
19121 | __m256i __lasx_xvssrani_b_h (__m256i, __m256i, imm0_15); | |
19122 | __m256i __lasx_xvssrani_bu_h (__m256i, __m256i, imm0_15); | |
19123 | __m256i __lasx_xvssrani_d_q (__m256i, __m256i, imm0_127); | |
19124 | __m256i __lasx_xvssrani_du_q (__m256i, __m256i, imm0_127); | |
19125 | __m256i __lasx_xvssrani_hu_w (__m256i, __m256i, imm0_31); | |
19126 | __m256i __lasx_xvssrani_h_w (__m256i, __m256i, imm0_31); | |
19127 | __m256i __lasx_xvssrani_w_d (__m256i, __m256i, imm0_63); | |
19128 | __m256i __lasx_xvssrani_wu_d (__m256i, __m256i, imm0_63); | |
19129 | __m256i __lasx_xvssran_w_d (__m256i, __m256i); | |
19130 | __m256i __lasx_xvssran_wu_d (__m256i, __m256i); | |
19131 | __m256i __lasx_xvssrarn_b_h (__m256i, __m256i); | |
19132 | __m256i __lasx_xvssrarn_bu_h (__m256i, __m256i); | |
19133 | __m256i __lasx_xvssrarn_hu_w (__m256i, __m256i); | |
19134 | __m256i __lasx_xvssrarn_h_w (__m256i, __m256i); | |
19135 | __m256i __lasx_xvssrarni_b_h (__m256i, __m256i, imm0_15); | |
19136 | __m256i __lasx_xvssrarni_bu_h (__m256i, __m256i, imm0_15); | |
19137 | __m256i __lasx_xvssrarni_d_q (__m256i, __m256i, imm0_127); | |
19138 | __m256i __lasx_xvssrarni_du_q (__m256i, __m256i, imm0_127); | |
19139 | __m256i __lasx_xvssrarni_hu_w (__m256i, __m256i, imm0_31); | |
19140 | __m256i __lasx_xvssrarni_h_w (__m256i, __m256i, imm0_31); | |
19141 | __m256i __lasx_xvssrarni_w_d (__m256i, __m256i, imm0_63); | |
19142 | __m256i __lasx_xvssrarni_wu_d (__m256i, __m256i, imm0_63); | |
19143 | __m256i __lasx_xvssrarn_w_d (__m256i, __m256i); | |
19144 | __m256i __lasx_xvssrarn_wu_d (__m256i, __m256i); | |
19145 | __m256i __lasx_xvssrln_b_h (__m256i, __m256i); | |
19146 | __m256i __lasx_xvssrln_bu_h (__m256i, __m256i); | |
19147 | __m256i __lasx_xvssrln_hu_w (__m256i, __m256i); | |
19148 | __m256i __lasx_xvssrln_h_w (__m256i, __m256i); | |
19149 | __m256i __lasx_xvssrlni_b_h (__m256i, __m256i, imm0_15); | |
19150 | __m256i __lasx_xvssrlni_bu_h (__m256i, __m256i, imm0_15); | |
19151 | __m256i __lasx_xvssrlni_d_q (__m256i, __m256i, imm0_127); | |
19152 | __m256i __lasx_xvssrlni_du_q (__m256i, __m256i, imm0_127); | |
19153 | __m256i __lasx_xvssrlni_hu_w (__m256i, __m256i, imm0_31); | |
19154 | __m256i __lasx_xvssrlni_h_w (__m256i, __m256i, imm0_31); | |
19155 | __m256i __lasx_xvssrlni_w_d (__m256i, __m256i, imm0_63); | |
19156 | __m256i __lasx_xvssrlni_wu_d (__m256i, __m256i, imm0_63); | |
19157 | __m256i __lasx_xvssrln_w_d (__m256i, __m256i); | |
19158 | __m256i __lasx_xvssrln_wu_d (__m256i, __m256i); | |
19159 | __m256i __lasx_xvssrlrn_b_h (__m256i, __m256i); | |
19160 | __m256i __lasx_xvssrlrn_bu_h (__m256i, __m256i); | |
19161 | __m256i __lasx_xvssrlrn_hu_w (__m256i, __m256i); | |
19162 | __m256i __lasx_xvssrlrn_h_w (__m256i, __m256i); | |
19163 | __m256i __lasx_xvssrlrni_b_h (__m256i, __m256i, imm0_15); | |
19164 | __m256i __lasx_xvssrlrni_bu_h (__m256i, __m256i, imm0_15); | |
19165 | __m256i __lasx_xvssrlrni_d_q (__m256i, __m256i, imm0_127); | |
19166 | __m256i __lasx_xvssrlrni_du_q (__m256i, __m256i, imm0_127); | |
19167 | __m256i __lasx_xvssrlrni_hu_w (__m256i, __m256i, imm0_31); | |
19168 | __m256i __lasx_xvssrlrni_h_w (__m256i, __m256i, imm0_31); | |
19169 | __m256i __lasx_xvssrlrni_w_d (__m256i, __m256i, imm0_63); | |
19170 | __m256i __lasx_xvssrlrni_wu_d (__m256i, __m256i, imm0_63); | |
19171 | __m256i __lasx_xvssrlrn_w_d (__m256i, __m256i); | |
19172 | __m256i __lasx_xvssrlrn_wu_d (__m256i, __m256i); | |
19173 | __m256i __lasx_xvssub_b (__m256i, __m256i); | |
19174 | __m256i __lasx_xvssub_bu (__m256i, __m256i); | |
19175 | __m256i __lasx_xvssub_d (__m256i, __m256i); | |
19176 | __m256i __lasx_xvssub_du (__m256i, __m256i); | |
19177 | __m256i __lasx_xvssub_h (__m256i, __m256i); | |
19178 | __m256i __lasx_xvssub_hu (__m256i, __m256i); | |
19179 | __m256i __lasx_xvssub_w (__m256i, __m256i); | |
19180 | __m256i __lasx_xvssub_wu (__m256i, __m256i); | |
19181 | void __lasx_xvst (__m256i, void *, imm_n2048_2047); | |
297ed1ac | 19182 | void __lasx_xvstelm_b (__m256i, void *, imm_n128_127, imm0_31); |
19183 | void __lasx_xvstelm_d (__m256i, void *, imm_n128_127, imm0_3); | |
19184 | void __lasx_xvstelm_h (__m256i, void *, imm_n128_127, imm0_15); | |
19185 | void __lasx_xvstelm_w (__m256i, void *, imm_n128_127, imm0_7); | |
1f48786d | 19186 | void __lasx_xvstx (__m256i, void *, long int); |
19187 | __m256i __lasx_xvsub_b (__m256i, __m256i); | |
19188 | __m256i __lasx_xvsub_d (__m256i, __m256i); | |
19189 | __m256i __lasx_xvsub_h (__m256i, __m256i); | |
19190 | __m256i __lasx_xvsubi_bu (__m256i, imm0_31); | |
19191 | __m256i __lasx_xvsubi_du (__m256i, imm0_31); | |
19192 | __m256i __lasx_xvsubi_hu (__m256i, imm0_31); | |
19193 | __m256i __lasx_xvsubi_wu (__m256i, imm0_31); | |
19194 | __m256i __lasx_xvsub_q (__m256i, __m256i); | |
19195 | __m256i __lasx_xvsub_w (__m256i, __m256i); | |
19196 | __m256i __lasx_xvsubwev_d_w (__m256i, __m256i); | |
19197 | __m256i __lasx_xvsubwev_d_wu (__m256i, __m256i); | |
19198 | __m256i __lasx_xvsubwev_h_b (__m256i, __m256i); | |
19199 | __m256i __lasx_xvsubwev_h_bu (__m256i, __m256i); | |
19200 | __m256i __lasx_xvsubwev_q_d (__m256i, __m256i); | |
19201 | __m256i __lasx_xvsubwev_q_du (__m256i, __m256i); | |
19202 | __m256i __lasx_xvsubwev_w_h (__m256i, __m256i); | |
19203 | __m256i __lasx_xvsubwev_w_hu (__m256i, __m256i); | |
19204 | __m256i __lasx_xvsubwod_d_w (__m256i, __m256i); | |
19205 | __m256i __lasx_xvsubwod_d_wu (__m256i, __m256i); | |
19206 | __m256i __lasx_xvsubwod_h_b (__m256i, __m256i); | |
19207 | __m256i __lasx_xvsubwod_h_bu (__m256i, __m256i); | |
19208 | __m256i __lasx_xvsubwod_q_d (__m256i, __m256i); | |
19209 | __m256i __lasx_xvsubwod_q_du (__m256i, __m256i); | |
19210 | __m256i __lasx_xvsubwod_w_h (__m256i, __m256i); | |
19211 | __m256i __lasx_xvsubwod_w_hu (__m256i, __m256i); | |
19212 | __m256i __lasx_xvxori_b (__m256i, imm0_255); | |
19213 | __m256i __lasx_xvxor_v (__m256i, __m256i); | |
19214 | @end smallexample | |
19215 | ||
61f1001f JX |
19216 | These instrisic functions are available by including @code{lasxintrin.h} and |
19217 | using @option{-mfrecipe} and @option{-mlasx}. | |
19218 | @smallexample | |
19219 | __m256d __lasx_xvfrecipe_d (__m256d); | |
19220 | __m256 __lasx_xvfrecipe_s (__m256); | |
19221 | __m256d __lasx_xvfrsqrte_d (__m256d); | |
19222 | __m256 __lasx_xvfrsqrte_s (__m256); | |
19223 | @end smallexample | |
19224 | ||
d77de738 ML |
19225 | @node MIPS DSP Built-in Functions |
19226 | @subsection MIPS DSP Built-in Functions | |
19227 | ||
19228 | The MIPS DSP Application-Specific Extension (ASE) includes new | |
19229 | instructions that are designed to improve the performance of DSP and | |
19230 | media applications. It provides instructions that operate on packed | |
19231 | 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. | |
19232 | ||
19233 | GCC supports MIPS DSP operations using both the generic | |
19234 | vector extensions (@pxref{Vector Extensions}) and a collection of | |
19235 | MIPS-specific built-in functions. Both kinds of support are | |
19236 | enabled by the @option{-mdsp} command-line option. | |
19237 | ||
19238 | Revision 2 of the ASE was introduced in the second half of 2006. | |
19239 | This revision adds extra instructions to the original ASE, but is | |
19240 | otherwise backwards-compatible with it. You can select revision 2 | |
19241 | using the command-line option @option{-mdspr2}; this option implies | |
19242 | @option{-mdsp}. | |
19243 | ||
19244 | The SCOUNT and POS bits of the DSP control register are global. The | |
19245 | WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and | |
19246 | POS bits. During optimization, the compiler does not delete these | |
19247 | instructions and it does not delete calls to functions containing | |
19248 | these instructions. | |
19249 | ||
19250 | At present, GCC only provides support for operations on 32-bit | |
19251 | vectors. The vector type associated with 8-bit integer data is | |
19252 | usually called @code{v4i8}, the vector type associated with Q7 | |
19253 | is usually called @code{v4q7}, the vector type associated with 16-bit | |
19254 | integer data is usually called @code{v2i16}, and the vector type | |
19255 | associated with Q15 is usually called @code{v2q15}. They can be | |
19256 | defined in C as follows: | |
19257 | ||
19258 | @smallexample | |
19259 | typedef signed char v4i8 __attribute__ ((vector_size(4))); | |
19260 | typedef signed char v4q7 __attribute__ ((vector_size(4))); | |
19261 | typedef short v2i16 __attribute__ ((vector_size(4))); | |
19262 | typedef short v2q15 __attribute__ ((vector_size(4))); | |
19263 | @end smallexample | |
19264 | ||
19265 | @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are | |
19266 | initialized in the same way as aggregates. For example: | |
19267 | ||
19268 | @smallexample | |
19269 | v4i8 a = @{1, 2, 3, 4@}; | |
19270 | v4i8 b; | |
19271 | b = (v4i8) @{5, 6, 7, 8@}; | |
19272 | ||
19273 | v2q15 c = @{0x0fcb, 0x3a75@}; | |
19274 | v2q15 d; | |
19275 | d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; | |
19276 | @end smallexample | |
19277 | ||
19278 | @emph{Note:} The CPU's endianness determines the order in which values | |
19279 | are packed. On little-endian targets, the first value is the least | |
19280 | significant and the last value is the most significant. The opposite | |
19281 | order applies to big-endian targets. For example, the code above | |
19282 | sets the lowest byte of @code{a} to @code{1} on little-endian targets | |
19283 | and @code{4} on big-endian targets. | |
19284 | ||
19285 | @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer | |
19286 | representation. As shown in this example, the integer representation | |
19287 | of a Q7 value can be obtained by multiplying the fractional value by | |
19288 | @code{0x1.0p7}. The equivalent for Q15 values is to multiply by | |
19289 | @code{0x1.0p15}. The equivalent for Q31 values is to multiply by | |
19290 | @code{0x1.0p31}. | |
19291 | ||
19292 | The table below lists the @code{v4i8} and @code{v2q15} operations for which | |
19293 | hardware support exists. @code{a} and @code{b} are @code{v4i8} values, | |
19294 | and @code{c} and @code{d} are @code{v2q15} values. | |
19295 | ||
19296 | @multitable @columnfractions .50 .50 | |
19297 | @headitem C code @tab MIPS instruction | |
19298 | @item @code{a + b} @tab @code{addu.qb} | |
19299 | @item @code{c + d} @tab @code{addq.ph} | |
19300 | @item @code{a - b} @tab @code{subu.qb} | |
19301 | @item @code{c - d} @tab @code{subq.ph} | |
19302 | @end multitable | |
19303 | ||
19304 | The table below lists the @code{v2i16} operation for which | |
19305 | hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are | |
19306 | @code{v2i16} values. | |
19307 | ||
19308 | @multitable @columnfractions .50 .50 | |
19309 | @headitem C code @tab MIPS instruction | |
19310 | @item @code{e * f} @tab @code{mul.ph} | |
19311 | @end multitable | |
19312 | ||
19313 | It is easier to describe the DSP built-in functions if we first define | |
19314 | the following types: | |
19315 | ||
19316 | @smallexample | |
19317 | typedef int q31; | |
19318 | typedef int i32; | |
19319 | typedef unsigned int ui32; | |
19320 | typedef long long a64; | |
19321 | @end smallexample | |
19322 | ||
19323 | @code{q31} and @code{i32} are actually the same as @code{int}, but we | |
19324 | use @code{q31} to indicate a Q31 fractional value and @code{i32} to | |
19325 | indicate a 32-bit integer value. Similarly, @code{a64} is the same as | |
19326 | @code{long long}, but we use @code{a64} to indicate values that are | |
19327 | placed in one of the four DSP accumulators (@code{$ac0}, | |
19328 | @code{$ac1}, @code{$ac2} or @code{$ac3}). | |
19329 | ||
19330 | Also, some built-in functions prefer or require immediate numbers as | |
19331 | parameters, because the corresponding DSP instructions accept both immediate | |
19332 | numbers and register operands, or accept immediate numbers only. The | |
19333 | immediate parameters are listed as follows. | |
19334 | ||
19335 | @smallexample | |
19336 | imm0_3: 0 to 3. | |
19337 | imm0_7: 0 to 7. | |
19338 | imm0_15: 0 to 15. | |
19339 | imm0_31: 0 to 31. | |
19340 | imm0_63: 0 to 63. | |
19341 | imm0_255: 0 to 255. | |
19342 | imm_n32_31: -32 to 31. | |
19343 | imm_n512_511: -512 to 511. | |
19344 | @end smallexample | |
19345 | ||
19346 | The following built-in functions map directly to a particular MIPS DSP | |
19347 | instruction. Please refer to the architecture specification | |
19348 | for details on what each instruction does. | |
19349 | ||
19350 | @smallexample | |
19351 | v2q15 __builtin_mips_addq_ph (v2q15, v2q15); | |
19352 | v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15); | |
19353 | q31 __builtin_mips_addq_s_w (q31, q31); | |
19354 | v4i8 __builtin_mips_addu_qb (v4i8, v4i8); | |
19355 | v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8); | |
19356 | v2q15 __builtin_mips_subq_ph (v2q15, v2q15); | |
19357 | v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15); | |
19358 | q31 __builtin_mips_subq_s_w (q31, q31); | |
19359 | v4i8 __builtin_mips_subu_qb (v4i8, v4i8); | |
19360 | v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8); | |
19361 | i32 __builtin_mips_addsc (i32, i32); | |
19362 | i32 __builtin_mips_addwc (i32, i32); | |
19363 | i32 __builtin_mips_modsub (i32, i32); | |
19364 | i32 __builtin_mips_raddu_w_qb (v4i8); | |
19365 | v2q15 __builtin_mips_absq_s_ph (v2q15); | |
19366 | q31 __builtin_mips_absq_s_w (q31); | |
19367 | v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15); | |
19368 | v2q15 __builtin_mips_precrq_ph_w (q31, q31); | |
19369 | v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31); | |
19370 | v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15); | |
19371 | q31 __builtin_mips_preceq_w_phl (v2q15); | |
19372 | q31 __builtin_mips_preceq_w_phr (v2q15); | |
19373 | v2q15 __builtin_mips_precequ_ph_qbl (v4i8); | |
19374 | v2q15 __builtin_mips_precequ_ph_qbr (v4i8); | |
19375 | v2q15 __builtin_mips_precequ_ph_qbla (v4i8); | |
19376 | v2q15 __builtin_mips_precequ_ph_qbra (v4i8); | |
19377 | v2q15 __builtin_mips_preceu_ph_qbl (v4i8); | |
19378 | v2q15 __builtin_mips_preceu_ph_qbr (v4i8); | |
19379 | v2q15 __builtin_mips_preceu_ph_qbla (v4i8); | |
19380 | v2q15 __builtin_mips_preceu_ph_qbra (v4i8); | |
19381 | v4i8 __builtin_mips_shll_qb (v4i8, imm0_7); | |
19382 | v4i8 __builtin_mips_shll_qb (v4i8, i32); | |
19383 | v2q15 __builtin_mips_shll_ph (v2q15, imm0_15); | |
19384 | v2q15 __builtin_mips_shll_ph (v2q15, i32); | |
19385 | v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15); | |
19386 | v2q15 __builtin_mips_shll_s_ph (v2q15, i32); | |
19387 | q31 __builtin_mips_shll_s_w (q31, imm0_31); | |
19388 | q31 __builtin_mips_shll_s_w (q31, i32); | |
19389 | v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7); | |
19390 | v4i8 __builtin_mips_shrl_qb (v4i8, i32); | |
19391 | v2q15 __builtin_mips_shra_ph (v2q15, imm0_15); | |
19392 | v2q15 __builtin_mips_shra_ph (v2q15, i32); | |
19393 | v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15); | |
19394 | v2q15 __builtin_mips_shra_r_ph (v2q15, i32); | |
19395 | q31 __builtin_mips_shra_r_w (q31, imm0_31); | |
19396 | q31 __builtin_mips_shra_r_w (q31, i32); | |
19397 | v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15); | |
19398 | v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15); | |
19399 | v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15); | |
19400 | q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15); | |
19401 | q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15); | |
19402 | a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8); | |
19403 | a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8); | |
19404 | a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8); | |
19405 | a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8); | |
19406 | a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15); | |
19407 | a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31); | |
19408 | a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15); | |
19409 | a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31); | |
19410 | a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15); | |
19411 | a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15); | |
19412 | a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15); | |
19413 | a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15); | |
19414 | a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15); | |
19415 | i32 __builtin_mips_bitrev (i32); | |
19416 | i32 __builtin_mips_insv (i32, i32); | |
19417 | v4i8 __builtin_mips_repl_qb (imm0_255); | |
19418 | v4i8 __builtin_mips_repl_qb (i32); | |
19419 | v2q15 __builtin_mips_repl_ph (imm_n512_511); | |
19420 | v2q15 __builtin_mips_repl_ph (i32); | |
19421 | void __builtin_mips_cmpu_eq_qb (v4i8, v4i8); | |
19422 | void __builtin_mips_cmpu_lt_qb (v4i8, v4i8); | |
19423 | void __builtin_mips_cmpu_le_qb (v4i8, v4i8); | |
19424 | i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8); | |
19425 | i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8); | |
19426 | i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8); | |
19427 | void __builtin_mips_cmp_eq_ph (v2q15, v2q15); | |
19428 | void __builtin_mips_cmp_lt_ph (v2q15, v2q15); | |
19429 | void __builtin_mips_cmp_le_ph (v2q15, v2q15); | |
19430 | v4i8 __builtin_mips_pick_qb (v4i8, v4i8); | |
19431 | v2q15 __builtin_mips_pick_ph (v2q15, v2q15); | |
19432 | v2q15 __builtin_mips_packrl_ph (v2q15, v2q15); | |
19433 | i32 __builtin_mips_extr_w (a64, imm0_31); | |
19434 | i32 __builtin_mips_extr_w (a64, i32); | |
19435 | i32 __builtin_mips_extr_r_w (a64, imm0_31); | |
19436 | i32 __builtin_mips_extr_s_h (a64, i32); | |
19437 | i32 __builtin_mips_extr_rs_w (a64, imm0_31); | |
19438 | i32 __builtin_mips_extr_rs_w (a64, i32); | |
19439 | i32 __builtin_mips_extr_s_h (a64, imm0_31); | |
19440 | i32 __builtin_mips_extr_r_w (a64, i32); | |
19441 | i32 __builtin_mips_extp (a64, imm0_31); | |
19442 | i32 __builtin_mips_extp (a64, i32); | |
19443 | i32 __builtin_mips_extpdp (a64, imm0_31); | |
19444 | i32 __builtin_mips_extpdp (a64, i32); | |
19445 | a64 __builtin_mips_shilo (a64, imm_n32_31); | |
19446 | a64 __builtin_mips_shilo (a64, i32); | |
19447 | a64 __builtin_mips_mthlip (a64, i32); | |
19448 | void __builtin_mips_wrdsp (i32, imm0_63); | |
19449 | i32 __builtin_mips_rddsp (imm0_63); | |
19450 | i32 __builtin_mips_lbux (void *, i32); | |
19451 | i32 __builtin_mips_lhx (void *, i32); | |
19452 | i32 __builtin_mips_lwx (void *, i32); | |
19453 | a64 __builtin_mips_ldx (void *, i32); /* MIPS64 only */ | |
19454 | i32 __builtin_mips_bposge32 (void); | |
19455 | a64 __builtin_mips_madd (a64, i32, i32); | |
19456 | a64 __builtin_mips_maddu (a64, ui32, ui32); | |
19457 | a64 __builtin_mips_msub (a64, i32, i32); | |
19458 | a64 __builtin_mips_msubu (a64, ui32, ui32); | |
19459 | a64 __builtin_mips_mult (i32, i32); | |
19460 | a64 __builtin_mips_multu (ui32, ui32); | |
19461 | @end smallexample | |
19462 | ||
19463 | The following built-in functions map directly to a particular MIPS DSP REV 2 | |
19464 | instruction. Please refer to the architecture specification | |
19465 | for details on what each instruction does. | |
19466 | ||
19467 | @smallexample | |
19468 | v4q7 __builtin_mips_absq_s_qb (v4q7); | |
19469 | v2i16 __builtin_mips_addu_ph (v2i16, v2i16); | |
19470 | v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); | |
19471 | v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); | |
19472 | v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); | |
19473 | i32 __builtin_mips_append (i32, i32, imm0_31); | |
19474 | i32 __builtin_mips_balign (i32, i32, imm0_3); | |
19475 | i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); | |
19476 | i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); | |
19477 | i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); | |
19478 | a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); | |
19479 | a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); | |
19480 | v2i16 __builtin_mips_mul_ph (v2i16, v2i16); | |
19481 | v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); | |
19482 | q31 __builtin_mips_mulq_rs_w (q31, q31); | |
19483 | v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); | |
19484 | q31 __builtin_mips_mulq_s_w (q31, q31); | |
19485 | a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); | |
19486 | v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); | |
19487 | v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); | |
19488 | v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); | |
19489 | i32 __builtin_mips_prepend (i32, i32, imm0_31); | |
19490 | v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); | |
19491 | v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); | |
19492 | v4i8 __builtin_mips_shra_qb (v4i8, i32); | |
19493 | v4i8 __builtin_mips_shra_r_qb (v4i8, i32); | |
19494 | v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); | |
19495 | v2i16 __builtin_mips_shrl_ph (v2i16, i32); | |
19496 | v2i16 __builtin_mips_subu_ph (v2i16, v2i16); | |
19497 | v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); | |
19498 | v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); | |
19499 | v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); | |
19500 | v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); | |
19501 | v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); | |
19502 | q31 __builtin_mips_addqh_w (q31, q31); | |
19503 | q31 __builtin_mips_addqh_r_w (q31, q31); | |
19504 | v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); | |
19505 | v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); | |
19506 | q31 __builtin_mips_subqh_w (q31, q31); | |
19507 | q31 __builtin_mips_subqh_r_w (q31, q31); | |
19508 | a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); | |
19509 | a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); | |
19510 | a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); | |
19511 | a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); | |
19512 | a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); | |
19513 | a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); | |
19514 | @end smallexample | |
19515 | ||
19516 | ||
19517 | @node MIPS Paired-Single Support | |
19518 | @subsection MIPS Paired-Single Support | |
19519 | ||
19520 | The MIPS64 architecture includes a number of instructions that | |
19521 | operate on pairs of single-precision floating-point values. | |
19522 | Each pair is packed into a 64-bit floating-point register, | |
19523 | with one element being designated the ``upper half'' and | |
19524 | the other being designated the ``lower half''. | |
19525 | ||
19526 | GCC supports paired-single operations using both the generic | |
19527 | vector extensions (@pxref{Vector Extensions}) and a collection of | |
19528 | MIPS-specific built-in functions. Both kinds of support are | |
19529 | enabled by the @option{-mpaired-single} command-line option. | |
19530 | ||
19531 | The vector type associated with paired-single values is usually | |
19532 | called @code{v2sf}. It can be defined in C as follows: | |
19533 | ||
19534 | @smallexample | |
19535 | typedef float v2sf __attribute__ ((vector_size (8))); | |
19536 | @end smallexample | |
19537 | ||
19538 | @code{v2sf} values are initialized in the same way as aggregates. | |
19539 | For example: | |
19540 | ||
19541 | @smallexample | |
19542 | v2sf a = @{1.5, 9.1@}; | |
19543 | v2sf b; | |
19544 | float e, f; | |
19545 | b = (v2sf) @{e, f@}; | |
19546 | @end smallexample | |
19547 | ||
19548 | @emph{Note:} The CPU's endianness determines which value is stored in | |
19549 | the upper half of a register and which value is stored in the lower half. | |
19550 | On little-endian targets, the first value is the lower one and the second | |
19551 | value is the upper one. The opposite order applies to big-endian targets. | |
19552 | For example, the code above sets the lower half of @code{a} to | |
19553 | @code{1.5} on little-endian targets and @code{9.1} on big-endian targets. | |
19554 | ||
19555 | @node MIPS Loongson Built-in Functions | |
19556 | @subsection MIPS Loongson Built-in Functions | |
19557 | ||
19558 | GCC provides intrinsics to access the SIMD instructions provided by the | |
19559 | ST Microelectronics Loongson-2E and -2F processors. These intrinsics, | |
19560 | available after inclusion of the @code{loongson.h} header file, | |
19561 | operate on the following 64-bit vector types: | |
19562 | ||
19563 | @itemize | |
19564 | @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; | |
19565 | @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; | |
19566 | @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; | |
19567 | @item @code{int8x8_t}, a vector of eight signed 8-bit integers; | |
19568 | @item @code{int16x4_t}, a vector of four signed 16-bit integers; | |
19569 | @item @code{int32x2_t}, a vector of two signed 32-bit integers. | |
19570 | @end itemize | |
19571 | ||
19572 | The intrinsics provided are listed below; each is named after the | |
19573 | machine instruction to which it corresponds, with suffixes added as | |
19574 | appropriate to distinguish intrinsics that expand to the same machine | |
19575 | instruction yet have different argument types. Refer to the architecture | |
19576 | documentation for a description of the functionality of each | |
19577 | instruction. | |
19578 | ||
19579 | @smallexample | |
19580 | int16x4_t packsswh (int32x2_t s, int32x2_t t); | |
19581 | int8x8_t packsshb (int16x4_t s, int16x4_t t); | |
19582 | uint8x8_t packushb (uint16x4_t s, uint16x4_t t); | |
19583 | uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); | |
19584 | uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); | |
19585 | uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); | |
19586 | int32x2_t paddw_s (int32x2_t s, int32x2_t t); | |
19587 | int16x4_t paddh_s (int16x4_t s, int16x4_t t); | |
19588 | int8x8_t paddb_s (int8x8_t s, int8x8_t t); | |
19589 | uint64_t paddd_u (uint64_t s, uint64_t t); | |
19590 | int64_t paddd_s (int64_t s, int64_t t); | |
19591 | int16x4_t paddsh (int16x4_t s, int16x4_t t); | |
19592 | int8x8_t paddsb (int8x8_t s, int8x8_t t); | |
19593 | uint16x4_t paddush (uint16x4_t s, uint16x4_t t); | |
19594 | uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); | |
19595 | uint64_t pandn_ud (uint64_t s, uint64_t t); | |
19596 | uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); | |
19597 | uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); | |
19598 | uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); | |
19599 | int64_t pandn_sd (int64_t s, int64_t t); | |
19600 | int32x2_t pandn_sw (int32x2_t s, int32x2_t t); | |
19601 | int16x4_t pandn_sh (int16x4_t s, int16x4_t t); | |
19602 | int8x8_t pandn_sb (int8x8_t s, int8x8_t t); | |
19603 | uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); | |
19604 | uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); | |
19605 | uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); | |
19606 | uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); | |
19607 | uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); | |
19608 | int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); | |
19609 | int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); | |
19610 | int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); | |
19611 | uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); | |
19612 | uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); | |
19613 | uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); | |
19614 | int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); | |
19615 | int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); | |
19616 | int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); | |
19617 | uint16x4_t pextrh_u (uint16x4_t s, int field); | |
19618 | int16x4_t pextrh_s (int16x4_t s, int field); | |
19619 | uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); | |
19620 | uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); | |
19621 | uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); | |
19622 | uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); | |
19623 | int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); | |
19624 | int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); | |
19625 | int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); | |
19626 | int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); | |
19627 | int32x2_t pmaddhw (int16x4_t s, int16x4_t t); | |
19628 | int16x4_t pmaxsh (int16x4_t s, int16x4_t t); | |
19629 | uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); | |
19630 | int16x4_t pminsh (int16x4_t s, int16x4_t t); | |
19631 | uint8x8_t pminub (uint8x8_t s, uint8x8_t t); | |
19632 | uint8x8_t pmovmskb_u (uint8x8_t s); | |
19633 | int8x8_t pmovmskb_s (int8x8_t s); | |
19634 | uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); | |
19635 | int16x4_t pmulhh (int16x4_t s, int16x4_t t); | |
19636 | int16x4_t pmullh (int16x4_t s, int16x4_t t); | |
19637 | int64_t pmuluw (uint32x2_t s, uint32x2_t t); | |
19638 | uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); | |
19639 | uint16x4_t biadd (uint8x8_t s); | |
19640 | uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); | |
19641 | uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); | |
19642 | int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); | |
19643 | uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); | |
19644 | int16x4_t psllh_s (int16x4_t s, uint8_t amount); | |
19645 | uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); | |
19646 | int32x2_t psllw_s (int32x2_t s, uint8_t amount); | |
19647 | uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); | |
19648 | int16x4_t psrlh_s (int16x4_t s, uint8_t amount); | |
19649 | uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); | |
19650 | int32x2_t psrlw_s (int32x2_t s, uint8_t amount); | |
19651 | uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); | |
19652 | int16x4_t psrah_s (int16x4_t s, uint8_t amount); | |
19653 | uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); | |
19654 | int32x2_t psraw_s (int32x2_t s, uint8_t amount); | |
19655 | uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); | |
19656 | uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); | |
19657 | uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); | |
19658 | int32x2_t psubw_s (int32x2_t s, int32x2_t t); | |
19659 | int16x4_t psubh_s (int16x4_t s, int16x4_t t); | |
19660 | int8x8_t psubb_s (int8x8_t s, int8x8_t t); | |
19661 | uint64_t psubd_u (uint64_t s, uint64_t t); | |
19662 | int64_t psubd_s (int64_t s, int64_t t); | |
19663 | int16x4_t psubsh (int16x4_t s, int16x4_t t); | |
19664 | int8x8_t psubsb (int8x8_t s, int8x8_t t); | |
19665 | uint16x4_t psubush (uint16x4_t s, uint16x4_t t); | |
19666 | uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); | |
19667 | uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); | |
19668 | uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); | |
19669 | uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); | |
19670 | int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); | |
19671 | int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); | |
19672 | int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); | |
19673 | uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); | |
19674 | uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); | |
19675 | uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); | |
19676 | int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); | |
19677 | int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); | |
19678 | int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); | |
19679 | @end smallexample | |
19680 | ||
19681 | @menu | |
19682 | * Paired-Single Arithmetic:: | |
19683 | * Paired-Single Built-in Functions:: | |
19684 | * MIPS-3D Built-in Functions:: | |
19685 | @end menu | |
19686 | ||
19687 | @node Paired-Single Arithmetic | |
19688 | @subsubsection Paired-Single Arithmetic | |
19689 | ||
19690 | The table below lists the @code{v2sf} operations for which hardware | |
19691 | support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} | |
19692 | values and @code{x} is an integral value. | |
19693 | ||
19694 | @multitable @columnfractions .50 .50 | |
19695 | @headitem C code @tab MIPS instruction | |
19696 | @item @code{a + b} @tab @code{add.ps} | |
19697 | @item @code{a - b} @tab @code{sub.ps} | |
19698 | @item @code{-a} @tab @code{neg.ps} | |
19699 | @item @code{a * b} @tab @code{mul.ps} | |
19700 | @item @code{a * b + c} @tab @code{madd.ps} | |
19701 | @item @code{a * b - c} @tab @code{msub.ps} | |
19702 | @item @code{-(a * b + c)} @tab @code{nmadd.ps} | |
19703 | @item @code{-(a * b - c)} @tab @code{nmsub.ps} | |
19704 | @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} | |
19705 | @end multitable | |
19706 | ||
19707 | Note that the multiply-accumulate instructions can be disabled | |
19708 | using the command-line option @code{-mno-fused-madd}. | |
19709 | ||
19710 | @node Paired-Single Built-in Functions | |
19711 | @subsubsection Paired-Single Built-in Functions | |
19712 | ||
19713 | The following paired-single functions map directly to a particular | |
19714 | MIPS instruction. Please refer to the architecture specification | |
19715 | for details on what each instruction does. | |
19716 | ||
19717 | @table @code | |
19718 | @item v2sf __builtin_mips_pll_ps (v2sf, v2sf) | |
19719 | Pair lower lower (@code{pll.ps}). | |
19720 | ||
19721 | @item v2sf __builtin_mips_pul_ps (v2sf, v2sf) | |
19722 | Pair upper lower (@code{pul.ps}). | |
19723 | ||
19724 | @item v2sf __builtin_mips_plu_ps (v2sf, v2sf) | |
19725 | Pair lower upper (@code{plu.ps}). | |
19726 | ||
19727 | @item v2sf __builtin_mips_puu_ps (v2sf, v2sf) | |
19728 | Pair upper upper (@code{puu.ps}). | |
19729 | ||
19730 | @item v2sf __builtin_mips_cvt_ps_s (float, float) | |
19731 | Convert pair to paired single (@code{cvt.ps.s}). | |
19732 | ||
19733 | @item float __builtin_mips_cvt_s_pl (v2sf) | |
19734 | Convert pair lower to single (@code{cvt.s.pl}). | |
19735 | ||
19736 | @item float __builtin_mips_cvt_s_pu (v2sf) | |
19737 | Convert pair upper to single (@code{cvt.s.pu}). | |
19738 | ||
19739 | @item v2sf __builtin_mips_abs_ps (v2sf) | |
19740 | Absolute value (@code{abs.ps}). | |
19741 | ||
19742 | @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) | |
19743 | Align variable (@code{alnv.ps}). | |
19744 | ||
19745 | @emph{Note:} The value of the third parameter must be 0 or 4 | |
19746 | modulo 8, otherwise the result is unpredictable. Please read the | |
19747 | instruction description for details. | |
19748 | @end table | |
19749 | ||
19750 | The following multi-instruction functions are also available. | |
19751 | In each case, @var{cond} can be any of the 16 floating-point conditions: | |
19752 | @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, | |
19753 | @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, | |
19754 | @code{lt}, @code{nge}, @code{le} or @code{ngt}. | |
19755 | ||
19756 | @table @code | |
19757 | @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
19758 | @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
19759 | Conditional move based on floating-point comparison (@code{c.@var{cond}.ps}, | |
19760 | @code{movt.ps}/@code{movf.ps}). | |
19761 | ||
19762 | The @code{movt} functions return the value @var{x} computed by: | |
19763 | ||
19764 | @smallexample | |
19765 | c.@var{cond}.ps @var{cc},@var{a},@var{b} | |
19766 | mov.ps @var{x},@var{c} | |
19767 | movt.ps @var{x},@var{d},@var{cc} | |
19768 | @end smallexample | |
19769 | ||
19770 | The @code{movf} functions are similar but use @code{movf.ps} instead | |
19771 | of @code{movt.ps}. | |
19772 | ||
19773 | @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
19774 | @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
19775 | Comparison of two paired-single values (@code{c.@var{cond}.ps}, | |
19776 | @code{bc1t}/@code{bc1f}). | |
19777 | ||
19778 | These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} | |
19779 | and return either the upper or lower half of the result. For example: | |
19780 | ||
19781 | @smallexample | |
19782 | v2sf a, b; | |
19783 | if (__builtin_mips_upper_c_eq_ps (a, b)) | |
19784 | upper_halves_are_equal (); | |
19785 | else | |
19786 | upper_halves_are_unequal (); | |
19787 | ||
19788 | if (__builtin_mips_lower_c_eq_ps (a, b)) | |
19789 | lower_halves_are_equal (); | |
19790 | else | |
19791 | lower_halves_are_unequal (); | |
19792 | @end smallexample | |
19793 | @end table | |
19794 | ||
19795 | @node MIPS-3D Built-in Functions | |
19796 | @subsubsection MIPS-3D Built-in Functions | |
19797 | ||
19798 | The MIPS-3D Application-Specific Extension (ASE) includes additional | |
19799 | paired-single instructions that are designed to improve the performance | |
19800 | of 3D graphics operations. Support for these instructions is controlled | |
19801 | by the @option{-mips3d} command-line option. | |
19802 | ||
19803 | The functions listed below map directly to a particular MIPS-3D | |
19804 | instruction. Please refer to the architecture specification for | |
19805 | more details on what each instruction does. | |
19806 | ||
19807 | @table @code | |
19808 | @item v2sf __builtin_mips_addr_ps (v2sf, v2sf) | |
19809 | Reduction add (@code{addr.ps}). | |
19810 | ||
19811 | @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) | |
19812 | Reduction multiply (@code{mulr.ps}). | |
19813 | ||
19814 | @item v2sf __builtin_mips_cvt_pw_ps (v2sf) | |
19815 | Convert paired single to paired word (@code{cvt.pw.ps}). | |
19816 | ||
19817 | @item v2sf __builtin_mips_cvt_ps_pw (v2sf) | |
19818 | Convert paired word to paired single (@code{cvt.ps.pw}). | |
19819 | ||
19820 | @item float __builtin_mips_recip1_s (float) | |
19821 | @itemx double __builtin_mips_recip1_d (double) | |
19822 | @itemx v2sf __builtin_mips_recip1_ps (v2sf) | |
19823 | Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). | |
19824 | ||
19825 | @item float __builtin_mips_recip2_s (float, float) | |
19826 | @itemx double __builtin_mips_recip2_d (double, double) | |
19827 | @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) | |
19828 | Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). | |
19829 | ||
19830 | @item float __builtin_mips_rsqrt1_s (float) | |
19831 | @itemx double __builtin_mips_rsqrt1_d (double) | |
19832 | @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) | |
19833 | Reduced-precision reciprocal square root (sequence step 1) | |
19834 | (@code{rsqrt1.@var{fmt}}). | |
19835 | ||
19836 | @item float __builtin_mips_rsqrt2_s (float, float) | |
19837 | @itemx double __builtin_mips_rsqrt2_d (double, double) | |
19838 | @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) | |
19839 | Reduced-precision reciprocal square root (sequence step 2) | |
19840 | (@code{rsqrt2.@var{fmt}}). | |
19841 | @end table | |
19842 | ||
19843 | The following multi-instruction functions are also available. | |
19844 | In each case, @var{cond} can be any of the 16 floating-point conditions: | |
19845 | @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, | |
19846 | @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, | |
19847 | @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. | |
19848 | ||
19849 | @table @code | |
19850 | @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) | |
19851 | @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) | |
19852 | Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, | |
19853 | @code{bc1t}/@code{bc1f}). | |
19854 | ||
19855 | These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} | |
19856 | or @code{cabs.@var{cond}.d} and return the result as a boolean value. | |
19857 | For example: | |
19858 | ||
19859 | @smallexample | |
19860 | float a, b; | |
19861 | if (__builtin_mips_cabs_eq_s (a, b)) | |
19862 | true (); | |
19863 | else | |
19864 | false (); | |
19865 | @end smallexample | |
19866 | ||
19867 | @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
19868 | @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
19869 | Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, | |
19870 | @code{bc1t}/@code{bc1f}). | |
19871 | ||
19872 | These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} | |
19873 | and return either the upper or lower half of the result. For example: | |
19874 | ||
19875 | @smallexample | |
19876 | v2sf a, b; | |
19877 | if (__builtin_mips_upper_cabs_eq_ps (a, b)) | |
19878 | upper_halves_are_equal (); | |
19879 | else | |
19880 | upper_halves_are_unequal (); | |
19881 | ||
19882 | if (__builtin_mips_lower_cabs_eq_ps (a, b)) | |
19883 | lower_halves_are_equal (); | |
19884 | else | |
19885 | lower_halves_are_unequal (); | |
19886 | @end smallexample | |
19887 | ||
19888 | @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
19889 | @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
19890 | Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, | |
19891 | @code{movt.ps}/@code{movf.ps}). | |
19892 | ||
19893 | The @code{movt} functions return the value @var{x} computed by: | |
19894 | ||
19895 | @smallexample | |
19896 | cabs.@var{cond}.ps @var{cc},@var{a},@var{b} | |
19897 | mov.ps @var{x},@var{c} | |
19898 | movt.ps @var{x},@var{d},@var{cc} | |
19899 | @end smallexample | |
19900 | ||
19901 | The @code{movf} functions are similar but use @code{movf.ps} instead | |
19902 | of @code{movt.ps}. | |
19903 | ||
19904 | @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
19905 | @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
19906 | @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
19907 | @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) | |
19908 | Comparison of two paired-single values | |
19909 | (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, | |
19910 | @code{bc1any2t}/@code{bc1any2f}). | |
19911 | ||
19912 | These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} | |
19913 | or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either | |
19914 | result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}. | |
19915 | For example: | |
19916 | ||
19917 | @smallexample | |
19918 | v2sf a, b; | |
19919 | if (__builtin_mips_any_c_eq_ps (a, b)) | |
19920 | one_is_true (); | |
19921 | else | |
19922 | both_are_false (); | |
19923 | ||
19924 | if (__builtin_mips_all_c_eq_ps (a, b)) | |
19925 | both_are_true (); | |
19926 | else | |
19927 | one_is_false (); | |
19928 | @end smallexample | |
19929 | ||
19930 | @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
19931 | @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
19932 | @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
19933 | @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) | |
19934 | Comparison of four paired-single values | |
19935 | (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, | |
19936 | @code{bc1any4t}/@code{bc1any4f}). | |
19937 | ||
19938 | These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} | |
19939 | to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. | |
19940 | The @code{any} forms return @code{true} if any of the four results are @code{true} | |
19941 | and the @code{all} forms return @code{true} if all four results are @code{true}. | |
19942 | For example: | |
19943 | ||
19944 | @smallexample | |
19945 | v2sf a, b, c, d; | |
19946 | if (__builtin_mips_any_c_eq_4s (a, b, c, d)) | |
19947 | some_are_true (); | |
19948 | else | |
19949 | all_are_false (); | |
19950 | ||
19951 | if (__builtin_mips_all_c_eq_4s (a, b, c, d)) | |
19952 | all_are_true (); | |
19953 | else | |
19954 | some_are_false (); | |
19955 | @end smallexample | |
19956 | @end table | |
19957 | ||
19958 | @node MIPS SIMD Architecture (MSA) Support | |
19959 | @subsection MIPS SIMD Architecture (MSA) Support | |
19960 | ||
19961 | @menu | |
19962 | * MIPS SIMD Architecture Built-in Functions:: | |
19963 | @end menu | |
19964 | ||
19965 | GCC provides intrinsics to access the SIMD instructions provided by the | |
19966 | MSA MIPS SIMD Architecture. The interface is made available by including | |
19967 | @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}. | |
19968 | For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic, | |
19969 | @code{__msa_*}. | |
19970 | ||
19971 | MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and | |
19972 | 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point | |
19973 | data elements. The following vectors typedefs are included in @code{msa.h}: | |
19974 | @itemize | |
19975 | @item @code{v16i8}, a vector of sixteen signed 8-bit integers; | |
19976 | @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers; | |
19977 | @item @code{v8i16}, a vector of eight signed 16-bit integers; | |
19978 | @item @code{v8u16}, a vector of eight unsigned 16-bit integers; | |
19979 | @item @code{v4i32}, a vector of four signed 32-bit integers; | |
19980 | @item @code{v4u32}, a vector of four unsigned 32-bit integers; | |
19981 | @item @code{v2i64}, a vector of two signed 64-bit integers; | |
19982 | @item @code{v2u64}, a vector of two unsigned 64-bit integers; | |
19983 | @item @code{v4f32}, a vector of four 32-bit floats; | |
19984 | @item @code{v2f64}, a vector of two 64-bit doubles. | |
19985 | @end itemize | |
19986 | ||
19987 | Instructions and corresponding built-ins may have additional restrictions and/or | |
19988 | input/output values manipulated: | |
19989 | @itemize | |
19990 | @item @code{imm0_1}, an integer literal in range 0 to 1; | |
19991 | @item @code{imm0_3}, an integer literal in range 0 to 3; | |
19992 | @item @code{imm0_7}, an integer literal in range 0 to 7; | |
19993 | @item @code{imm0_15}, an integer literal in range 0 to 15; | |
19994 | @item @code{imm0_31}, an integer literal in range 0 to 31; | |
19995 | @item @code{imm0_63}, an integer literal in range 0 to 63; | |
19996 | @item @code{imm0_255}, an integer literal in range 0 to 255; | |
19997 | @item @code{imm_n16_15}, an integer literal in range -16 to 15; | |
19998 | @item @code{imm_n512_511}, an integer literal in range -512 to 511; | |
19999 | @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left | |
20000 | shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022; | |
20001 | @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left | |
20002 | shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044; | |
20003 | @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left | |
20004 | shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088; | |
20005 | @item @code{imm1_4}, an integer literal in range 1 to 4; | |
20006 | @item @code{i32, i64, u32, u64, f32, f64}, defined as follows: | |
20007 | @end itemize | |
20008 | ||
20009 | @smallexample | |
20010 | @{ | |
20011 | typedef int i32; | |
20012 | #if __LONG_MAX__ == __LONG_LONG_MAX__ | |
20013 | typedef long i64; | |
20014 | #else | |
20015 | typedef long long i64; | |
20016 | #endif | |
20017 | ||
20018 | typedef unsigned int u32; | |
20019 | #if __LONG_MAX__ == __LONG_LONG_MAX__ | |
20020 | typedef unsigned long u64; | |
20021 | #else | |
20022 | typedef unsigned long long u64; | |
20023 | #endif | |
20024 | ||
20025 | typedef double f64; | |
20026 | typedef float f32; | |
20027 | @} | |
20028 | @end smallexample | |
20029 | ||
20030 | @node MIPS SIMD Architecture Built-in Functions | |
20031 | @subsubsection MIPS SIMD Architecture Built-in Functions | |
20032 | ||
20033 | The intrinsics provided are listed below; each is named after the | |
20034 | machine instruction. | |
20035 | ||
20036 | @smallexample | |
20037 | v16i8 __builtin_msa_add_a_b (v16i8, v16i8); | |
20038 | v8i16 __builtin_msa_add_a_h (v8i16, v8i16); | |
20039 | v4i32 __builtin_msa_add_a_w (v4i32, v4i32); | |
20040 | v2i64 __builtin_msa_add_a_d (v2i64, v2i64); | |
20041 | ||
20042 | v16i8 __builtin_msa_adds_a_b (v16i8, v16i8); | |
20043 | v8i16 __builtin_msa_adds_a_h (v8i16, v8i16); | |
20044 | v4i32 __builtin_msa_adds_a_w (v4i32, v4i32); | |
20045 | v2i64 __builtin_msa_adds_a_d (v2i64, v2i64); | |
20046 | ||
20047 | v16i8 __builtin_msa_adds_s_b (v16i8, v16i8); | |
20048 | v8i16 __builtin_msa_adds_s_h (v8i16, v8i16); | |
20049 | v4i32 __builtin_msa_adds_s_w (v4i32, v4i32); | |
20050 | v2i64 __builtin_msa_adds_s_d (v2i64, v2i64); | |
20051 | ||
20052 | v16u8 __builtin_msa_adds_u_b (v16u8, v16u8); | |
20053 | v8u16 __builtin_msa_adds_u_h (v8u16, v8u16); | |
20054 | v4u32 __builtin_msa_adds_u_w (v4u32, v4u32); | |
20055 | v2u64 __builtin_msa_adds_u_d (v2u64, v2u64); | |
20056 | ||
20057 | v16i8 __builtin_msa_addv_b (v16i8, v16i8); | |
20058 | v8i16 __builtin_msa_addv_h (v8i16, v8i16); | |
20059 | v4i32 __builtin_msa_addv_w (v4i32, v4i32); | |
20060 | v2i64 __builtin_msa_addv_d (v2i64, v2i64); | |
20061 | ||
20062 | v16i8 __builtin_msa_addvi_b (v16i8, imm0_31); | |
20063 | v8i16 __builtin_msa_addvi_h (v8i16, imm0_31); | |
20064 | v4i32 __builtin_msa_addvi_w (v4i32, imm0_31); | |
20065 | v2i64 __builtin_msa_addvi_d (v2i64, imm0_31); | |
20066 | ||
20067 | v16u8 __builtin_msa_and_v (v16u8, v16u8); | |
20068 | ||
20069 | v16u8 __builtin_msa_andi_b (v16u8, imm0_255); | |
20070 | ||
20071 | v16i8 __builtin_msa_asub_s_b (v16i8, v16i8); | |
20072 | v8i16 __builtin_msa_asub_s_h (v8i16, v8i16); | |
20073 | v4i32 __builtin_msa_asub_s_w (v4i32, v4i32); | |
20074 | v2i64 __builtin_msa_asub_s_d (v2i64, v2i64); | |
20075 | ||
20076 | v16u8 __builtin_msa_asub_u_b (v16u8, v16u8); | |
20077 | v8u16 __builtin_msa_asub_u_h (v8u16, v8u16); | |
20078 | v4u32 __builtin_msa_asub_u_w (v4u32, v4u32); | |
20079 | v2u64 __builtin_msa_asub_u_d (v2u64, v2u64); | |
20080 | ||
20081 | v16i8 __builtin_msa_ave_s_b (v16i8, v16i8); | |
20082 | v8i16 __builtin_msa_ave_s_h (v8i16, v8i16); | |
20083 | v4i32 __builtin_msa_ave_s_w (v4i32, v4i32); | |
20084 | v2i64 __builtin_msa_ave_s_d (v2i64, v2i64); | |
20085 | ||
20086 | v16u8 __builtin_msa_ave_u_b (v16u8, v16u8); | |
20087 | v8u16 __builtin_msa_ave_u_h (v8u16, v8u16); | |
20088 | v4u32 __builtin_msa_ave_u_w (v4u32, v4u32); | |
20089 | v2u64 __builtin_msa_ave_u_d (v2u64, v2u64); | |
20090 | ||
20091 | v16i8 __builtin_msa_aver_s_b (v16i8, v16i8); | |
20092 | v8i16 __builtin_msa_aver_s_h (v8i16, v8i16); | |
20093 | v4i32 __builtin_msa_aver_s_w (v4i32, v4i32); | |
20094 | v2i64 __builtin_msa_aver_s_d (v2i64, v2i64); | |
20095 | ||
20096 | v16u8 __builtin_msa_aver_u_b (v16u8, v16u8); | |
20097 | v8u16 __builtin_msa_aver_u_h (v8u16, v8u16); | |
20098 | v4u32 __builtin_msa_aver_u_w (v4u32, v4u32); | |
20099 | v2u64 __builtin_msa_aver_u_d (v2u64, v2u64); | |
20100 | ||
20101 | v16u8 __builtin_msa_bclr_b (v16u8, v16u8); | |
20102 | v8u16 __builtin_msa_bclr_h (v8u16, v8u16); | |
20103 | v4u32 __builtin_msa_bclr_w (v4u32, v4u32); | |
20104 | v2u64 __builtin_msa_bclr_d (v2u64, v2u64); | |
20105 | ||
20106 | v16u8 __builtin_msa_bclri_b (v16u8, imm0_7); | |
20107 | v8u16 __builtin_msa_bclri_h (v8u16, imm0_15); | |
20108 | v4u32 __builtin_msa_bclri_w (v4u32, imm0_31); | |
20109 | v2u64 __builtin_msa_bclri_d (v2u64, imm0_63); | |
20110 | ||
20111 | v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8); | |
20112 | v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16); | |
20113 | v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32); | |
20114 | v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64); | |
20115 | ||
20116 | v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7); | |
20117 | v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15); | |
20118 | v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31); | |
20119 | v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63); | |
20120 | ||
20121 | v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8); | |
20122 | v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16); | |
20123 | v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32); | |
20124 | v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64); | |
20125 | ||
20126 | v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7); | |
20127 | v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15); | |
20128 | v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31); | |
20129 | v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63); | |
20130 | ||
20131 | v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8); | |
20132 | ||
20133 | v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255); | |
20134 | ||
20135 | v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8); | |
20136 | ||
20137 | v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255); | |
20138 | ||
20139 | v16u8 __builtin_msa_bneg_b (v16u8, v16u8); | |
20140 | v8u16 __builtin_msa_bneg_h (v8u16, v8u16); | |
20141 | v4u32 __builtin_msa_bneg_w (v4u32, v4u32); | |
20142 | v2u64 __builtin_msa_bneg_d (v2u64, v2u64); | |
20143 | ||
20144 | v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7); | |
20145 | v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15); | |
20146 | v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31); | |
20147 | v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63); | |
20148 | ||
20149 | i32 __builtin_msa_bnz_b (v16u8); | |
20150 | i32 __builtin_msa_bnz_h (v8u16); | |
20151 | i32 __builtin_msa_bnz_w (v4u32); | |
20152 | i32 __builtin_msa_bnz_d (v2u64); | |
20153 | ||
20154 | i32 __builtin_msa_bnz_v (v16u8); | |
20155 | ||
20156 | v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8); | |
20157 | ||
20158 | v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255); | |
20159 | ||
20160 | v16u8 __builtin_msa_bset_b (v16u8, v16u8); | |
20161 | v8u16 __builtin_msa_bset_h (v8u16, v8u16); | |
20162 | v4u32 __builtin_msa_bset_w (v4u32, v4u32); | |
20163 | v2u64 __builtin_msa_bset_d (v2u64, v2u64); | |
20164 | ||
20165 | v16u8 __builtin_msa_bseti_b (v16u8, imm0_7); | |
20166 | v8u16 __builtin_msa_bseti_h (v8u16, imm0_15); | |
20167 | v4u32 __builtin_msa_bseti_w (v4u32, imm0_31); | |
20168 | v2u64 __builtin_msa_bseti_d (v2u64, imm0_63); | |
20169 | ||
20170 | i32 __builtin_msa_bz_b (v16u8); | |
20171 | i32 __builtin_msa_bz_h (v8u16); | |
20172 | i32 __builtin_msa_bz_w (v4u32); | |
20173 | i32 __builtin_msa_bz_d (v2u64); | |
20174 | ||
20175 | i32 __builtin_msa_bz_v (v16u8); | |
20176 | ||
20177 | v16i8 __builtin_msa_ceq_b (v16i8, v16i8); | |
20178 | v8i16 __builtin_msa_ceq_h (v8i16, v8i16); | |
20179 | v4i32 __builtin_msa_ceq_w (v4i32, v4i32); | |
20180 | v2i64 __builtin_msa_ceq_d (v2i64, v2i64); | |
20181 | ||
20182 | v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15); | |
20183 | v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15); | |
20184 | v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15); | |
20185 | v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15); | |
20186 | ||
20187 | i32 __builtin_msa_cfcmsa (imm0_31); | |
20188 | ||
20189 | v16i8 __builtin_msa_cle_s_b (v16i8, v16i8); | |
20190 | v8i16 __builtin_msa_cle_s_h (v8i16, v8i16); | |
20191 | v4i32 __builtin_msa_cle_s_w (v4i32, v4i32); | |
20192 | v2i64 __builtin_msa_cle_s_d (v2i64, v2i64); | |
20193 | ||
20194 | v16i8 __builtin_msa_cle_u_b (v16u8, v16u8); | |
20195 | v8i16 __builtin_msa_cle_u_h (v8u16, v8u16); | |
20196 | v4i32 __builtin_msa_cle_u_w (v4u32, v4u32); | |
20197 | v2i64 __builtin_msa_cle_u_d (v2u64, v2u64); | |
20198 | ||
20199 | v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15); | |
20200 | v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15); | |
20201 | v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15); | |
20202 | v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15); | |
20203 | ||
20204 | v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31); | |
20205 | v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31); | |
20206 | v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31); | |
20207 | v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31); | |
20208 | ||
20209 | v16i8 __builtin_msa_clt_s_b (v16i8, v16i8); | |
20210 | v8i16 __builtin_msa_clt_s_h (v8i16, v8i16); | |
20211 | v4i32 __builtin_msa_clt_s_w (v4i32, v4i32); | |
20212 | v2i64 __builtin_msa_clt_s_d (v2i64, v2i64); | |
20213 | ||
20214 | v16i8 __builtin_msa_clt_u_b (v16u8, v16u8); | |
20215 | v8i16 __builtin_msa_clt_u_h (v8u16, v8u16); | |
20216 | v4i32 __builtin_msa_clt_u_w (v4u32, v4u32); | |
20217 | v2i64 __builtin_msa_clt_u_d (v2u64, v2u64); | |
20218 | ||
20219 | v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15); | |
20220 | v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15); | |
20221 | v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15); | |
20222 | v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15); | |
20223 | ||
20224 | v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31); | |
20225 | v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31); | |
20226 | v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31); | |
20227 | v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31); | |
20228 | ||
20229 | i32 __builtin_msa_copy_s_b (v16i8, imm0_15); | |
20230 | i32 __builtin_msa_copy_s_h (v8i16, imm0_7); | |
20231 | i32 __builtin_msa_copy_s_w (v4i32, imm0_3); | |
20232 | i64 __builtin_msa_copy_s_d (v2i64, imm0_1); | |
20233 | ||
20234 | u32 __builtin_msa_copy_u_b (v16i8, imm0_15); | |
20235 | u32 __builtin_msa_copy_u_h (v8i16, imm0_7); | |
20236 | u32 __builtin_msa_copy_u_w (v4i32, imm0_3); | |
20237 | u64 __builtin_msa_copy_u_d (v2i64, imm0_1); | |
20238 | ||
20239 | void __builtin_msa_ctcmsa (imm0_31, i32); | |
20240 | ||
20241 | v16i8 __builtin_msa_div_s_b (v16i8, v16i8); | |
20242 | v8i16 __builtin_msa_div_s_h (v8i16, v8i16); | |
20243 | v4i32 __builtin_msa_div_s_w (v4i32, v4i32); | |
20244 | v2i64 __builtin_msa_div_s_d (v2i64, v2i64); | |
20245 | ||
20246 | v16u8 __builtin_msa_div_u_b (v16u8, v16u8); | |
20247 | v8u16 __builtin_msa_div_u_h (v8u16, v8u16); | |
20248 | v4u32 __builtin_msa_div_u_w (v4u32, v4u32); | |
20249 | v2u64 __builtin_msa_div_u_d (v2u64, v2u64); | |
20250 | ||
20251 | v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8); | |
20252 | v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16); | |
20253 | v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32); | |
20254 | ||
20255 | v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8); | |
20256 | v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16); | |
20257 | v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32); | |
20258 | ||
20259 | v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8); | |
20260 | v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16); | |
20261 | v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32); | |
20262 | ||
20263 | v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8); | |
20264 | v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16); | |
20265 | v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32); | |
20266 | ||
20267 | v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8); | |
20268 | v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16); | |
20269 | v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32); | |
20270 | ||
20271 | v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8); | |
20272 | v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16); | |
20273 | v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32); | |
20274 | ||
20275 | v4f32 __builtin_msa_fadd_w (v4f32, v4f32); | |
20276 | v2f64 __builtin_msa_fadd_d (v2f64, v2f64); | |
20277 | ||
20278 | v4i32 __builtin_msa_fcaf_w (v4f32, v4f32); | |
20279 | v2i64 __builtin_msa_fcaf_d (v2f64, v2f64); | |
20280 | ||
20281 | v4i32 __builtin_msa_fceq_w (v4f32, v4f32); | |
20282 | v2i64 __builtin_msa_fceq_d (v2f64, v2f64); | |
20283 | ||
20284 | v4i32 __builtin_msa_fclass_w (v4f32); | |
20285 | v2i64 __builtin_msa_fclass_d (v2f64); | |
20286 | ||
20287 | v4i32 __builtin_msa_fcle_w (v4f32, v4f32); | |
20288 | v2i64 __builtin_msa_fcle_d (v2f64, v2f64); | |
20289 | ||
20290 | v4i32 __builtin_msa_fclt_w (v4f32, v4f32); | |
20291 | v2i64 __builtin_msa_fclt_d (v2f64, v2f64); | |
20292 | ||
20293 | v4i32 __builtin_msa_fcne_w (v4f32, v4f32); | |
20294 | v2i64 __builtin_msa_fcne_d (v2f64, v2f64); | |
20295 | ||
20296 | v4i32 __builtin_msa_fcor_w (v4f32, v4f32); | |
20297 | v2i64 __builtin_msa_fcor_d (v2f64, v2f64); | |
20298 | ||
20299 | v4i32 __builtin_msa_fcueq_w (v4f32, v4f32); | |
20300 | v2i64 __builtin_msa_fcueq_d (v2f64, v2f64); | |
20301 | ||
20302 | v4i32 __builtin_msa_fcule_w (v4f32, v4f32); | |
20303 | v2i64 __builtin_msa_fcule_d (v2f64, v2f64); | |
20304 | ||
20305 | v4i32 __builtin_msa_fcult_w (v4f32, v4f32); | |
20306 | v2i64 __builtin_msa_fcult_d (v2f64, v2f64); | |
20307 | ||
20308 | v4i32 __builtin_msa_fcun_w (v4f32, v4f32); | |
20309 | v2i64 __builtin_msa_fcun_d (v2f64, v2f64); | |
20310 | ||
20311 | v4i32 __builtin_msa_fcune_w (v4f32, v4f32); | |
20312 | v2i64 __builtin_msa_fcune_d (v2f64, v2f64); | |
20313 | ||
20314 | v4f32 __builtin_msa_fdiv_w (v4f32, v4f32); | |
20315 | v2f64 __builtin_msa_fdiv_d (v2f64, v2f64); | |
20316 | ||
20317 | v8i16 __builtin_msa_fexdo_h (v4f32, v4f32); | |
20318 | v4f32 __builtin_msa_fexdo_w (v2f64, v2f64); | |
20319 | ||
20320 | v4f32 __builtin_msa_fexp2_w (v4f32, v4i32); | |
20321 | v2f64 __builtin_msa_fexp2_d (v2f64, v2i64); | |
20322 | ||
20323 | v4f32 __builtin_msa_fexupl_w (v8i16); | |
20324 | v2f64 __builtin_msa_fexupl_d (v4f32); | |
20325 | ||
20326 | v4f32 __builtin_msa_fexupr_w (v8i16); | |
20327 | v2f64 __builtin_msa_fexupr_d (v4f32); | |
20328 | ||
20329 | v4f32 __builtin_msa_ffint_s_w (v4i32); | |
20330 | v2f64 __builtin_msa_ffint_s_d (v2i64); | |
20331 | ||
20332 | v4f32 __builtin_msa_ffint_u_w (v4u32); | |
20333 | v2f64 __builtin_msa_ffint_u_d (v2u64); | |
20334 | ||
20335 | v4f32 __builtin_msa_ffql_w (v8i16); | |
20336 | v2f64 __builtin_msa_ffql_d (v4i32); | |
20337 | ||
20338 | v4f32 __builtin_msa_ffqr_w (v8i16); | |
20339 | v2f64 __builtin_msa_ffqr_d (v4i32); | |
20340 | ||
20341 | v16i8 __builtin_msa_fill_b (i32); | |
20342 | v8i16 __builtin_msa_fill_h (i32); | |
20343 | v4i32 __builtin_msa_fill_w (i32); | |
20344 | v2i64 __builtin_msa_fill_d (i64); | |
20345 | ||
20346 | v4f32 __builtin_msa_flog2_w (v4f32); | |
20347 | v2f64 __builtin_msa_flog2_d (v2f64); | |
20348 | ||
20349 | v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32); | |
20350 | v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64); | |
20351 | ||
20352 | v4f32 __builtin_msa_fmax_w (v4f32, v4f32); | |
20353 | v2f64 __builtin_msa_fmax_d (v2f64, v2f64); | |
20354 | ||
20355 | v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32); | |
20356 | v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64); | |
20357 | ||
20358 | v4f32 __builtin_msa_fmin_w (v4f32, v4f32); | |
20359 | v2f64 __builtin_msa_fmin_d (v2f64, v2f64); | |
20360 | ||
20361 | v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32); | |
20362 | v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64); | |
20363 | ||
20364 | v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32); | |
20365 | v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64); | |
20366 | ||
20367 | v4f32 __builtin_msa_fmul_w (v4f32, v4f32); | |
20368 | v2f64 __builtin_msa_fmul_d (v2f64, v2f64); | |
20369 | ||
20370 | v4f32 __builtin_msa_frint_w (v4f32); | |
20371 | v2f64 __builtin_msa_frint_d (v2f64); | |
20372 | ||
20373 | v4f32 __builtin_msa_frcp_w (v4f32); | |
20374 | v2f64 __builtin_msa_frcp_d (v2f64); | |
20375 | ||
20376 | v4f32 __builtin_msa_frsqrt_w (v4f32); | |
20377 | v2f64 __builtin_msa_frsqrt_d (v2f64); | |
20378 | ||
20379 | v4i32 __builtin_msa_fsaf_w (v4f32, v4f32); | |
20380 | v2i64 __builtin_msa_fsaf_d (v2f64, v2f64); | |
20381 | ||
20382 | v4i32 __builtin_msa_fseq_w (v4f32, v4f32); | |
20383 | v2i64 __builtin_msa_fseq_d (v2f64, v2f64); | |
20384 | ||
20385 | v4i32 __builtin_msa_fsle_w (v4f32, v4f32); | |
20386 | v2i64 __builtin_msa_fsle_d (v2f64, v2f64); | |
20387 | ||
20388 | v4i32 __builtin_msa_fslt_w (v4f32, v4f32); | |
20389 | v2i64 __builtin_msa_fslt_d (v2f64, v2f64); | |
20390 | ||
20391 | v4i32 __builtin_msa_fsne_w (v4f32, v4f32); | |
20392 | v2i64 __builtin_msa_fsne_d (v2f64, v2f64); | |
20393 | ||
20394 | v4i32 __builtin_msa_fsor_w (v4f32, v4f32); | |
20395 | v2i64 __builtin_msa_fsor_d (v2f64, v2f64); | |
20396 | ||
20397 | v4f32 __builtin_msa_fsqrt_w (v4f32); | |
20398 | v2f64 __builtin_msa_fsqrt_d (v2f64); | |
20399 | ||
20400 | v4f32 __builtin_msa_fsub_w (v4f32, v4f32); | |
20401 | v2f64 __builtin_msa_fsub_d (v2f64, v2f64); | |
20402 | ||
20403 | v4i32 __builtin_msa_fsueq_w (v4f32, v4f32); | |
20404 | v2i64 __builtin_msa_fsueq_d (v2f64, v2f64); | |
20405 | ||
20406 | v4i32 __builtin_msa_fsule_w (v4f32, v4f32); | |
20407 | v2i64 __builtin_msa_fsule_d (v2f64, v2f64); | |
20408 | ||
20409 | v4i32 __builtin_msa_fsult_w (v4f32, v4f32); | |
20410 | v2i64 __builtin_msa_fsult_d (v2f64, v2f64); | |
20411 | ||
20412 | v4i32 __builtin_msa_fsun_w (v4f32, v4f32); | |
20413 | v2i64 __builtin_msa_fsun_d (v2f64, v2f64); | |
20414 | ||
20415 | v4i32 __builtin_msa_fsune_w (v4f32, v4f32); | |
20416 | v2i64 __builtin_msa_fsune_d (v2f64, v2f64); | |
20417 | ||
20418 | v4i32 __builtin_msa_ftint_s_w (v4f32); | |
20419 | v2i64 __builtin_msa_ftint_s_d (v2f64); | |
20420 | ||
20421 | v4u32 __builtin_msa_ftint_u_w (v4f32); | |
20422 | v2u64 __builtin_msa_ftint_u_d (v2f64); | |
20423 | ||
20424 | v8i16 __builtin_msa_ftq_h (v4f32, v4f32); | |
20425 | v4i32 __builtin_msa_ftq_w (v2f64, v2f64); | |
20426 | ||
20427 | v4i32 __builtin_msa_ftrunc_s_w (v4f32); | |
20428 | v2i64 __builtin_msa_ftrunc_s_d (v2f64); | |
20429 | ||
20430 | v4u32 __builtin_msa_ftrunc_u_w (v4f32); | |
20431 | v2u64 __builtin_msa_ftrunc_u_d (v2f64); | |
20432 | ||
20433 | v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8); | |
20434 | v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16); | |
20435 | v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32); | |
20436 | ||
20437 | v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8); | |
20438 | v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16); | |
20439 | v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32); | |
20440 | ||
20441 | v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8); | |
20442 | v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16); | |
20443 | v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32); | |
20444 | ||
20445 | v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8); | |
20446 | v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16); | |
20447 | v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32); | |
20448 | ||
20449 | v16i8 __builtin_msa_ilvev_b (v16i8, v16i8); | |
20450 | v8i16 __builtin_msa_ilvev_h (v8i16, v8i16); | |
20451 | v4i32 __builtin_msa_ilvev_w (v4i32, v4i32); | |
20452 | v2i64 __builtin_msa_ilvev_d (v2i64, v2i64); | |
20453 | ||
20454 | v16i8 __builtin_msa_ilvl_b (v16i8, v16i8); | |
20455 | v8i16 __builtin_msa_ilvl_h (v8i16, v8i16); | |
20456 | v4i32 __builtin_msa_ilvl_w (v4i32, v4i32); | |
20457 | v2i64 __builtin_msa_ilvl_d (v2i64, v2i64); | |
20458 | ||
20459 | v16i8 __builtin_msa_ilvod_b (v16i8, v16i8); | |
20460 | v8i16 __builtin_msa_ilvod_h (v8i16, v8i16); | |
20461 | v4i32 __builtin_msa_ilvod_w (v4i32, v4i32); | |
20462 | v2i64 __builtin_msa_ilvod_d (v2i64, v2i64); | |
20463 | ||
20464 | v16i8 __builtin_msa_ilvr_b (v16i8, v16i8); | |
20465 | v8i16 __builtin_msa_ilvr_h (v8i16, v8i16); | |
20466 | v4i32 __builtin_msa_ilvr_w (v4i32, v4i32); | |
20467 | v2i64 __builtin_msa_ilvr_d (v2i64, v2i64); | |
20468 | ||
20469 | v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32); | |
20470 | v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32); | |
20471 | v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32); | |
20472 | v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64); | |
20473 | ||
20474 | v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8); | |
20475 | v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16); | |
20476 | v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32); | |
20477 | v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64); | |
20478 | ||
20479 | v16i8 __builtin_msa_ld_b (const void *, imm_n512_511); | |
20480 | v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022); | |
20481 | v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044); | |
20482 | v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088); | |
20483 | ||
20484 | v16i8 __builtin_msa_ldi_b (imm_n512_511); | |
20485 | v8i16 __builtin_msa_ldi_h (imm_n512_511); | |
20486 | v4i32 __builtin_msa_ldi_w (imm_n512_511); | |
20487 | v2i64 __builtin_msa_ldi_d (imm_n512_511); | |
20488 | ||
20489 | v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16); | |
20490 | v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32); | |
20491 | ||
20492 | v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16); | |
20493 | v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32); | |
20494 | ||
20495 | v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8); | |
20496 | v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16); | |
20497 | v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32); | |
20498 | v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64); | |
20499 | ||
20500 | v16i8 __builtin_msa_max_a_b (v16i8, v16i8); | |
20501 | v8i16 __builtin_msa_max_a_h (v8i16, v8i16); | |
20502 | v4i32 __builtin_msa_max_a_w (v4i32, v4i32); | |
20503 | v2i64 __builtin_msa_max_a_d (v2i64, v2i64); | |
20504 | ||
20505 | v16i8 __builtin_msa_max_s_b (v16i8, v16i8); | |
20506 | v8i16 __builtin_msa_max_s_h (v8i16, v8i16); | |
20507 | v4i32 __builtin_msa_max_s_w (v4i32, v4i32); | |
20508 | v2i64 __builtin_msa_max_s_d (v2i64, v2i64); | |
20509 | ||
20510 | v16u8 __builtin_msa_max_u_b (v16u8, v16u8); | |
20511 | v8u16 __builtin_msa_max_u_h (v8u16, v8u16); | |
20512 | v4u32 __builtin_msa_max_u_w (v4u32, v4u32); | |
20513 | v2u64 __builtin_msa_max_u_d (v2u64, v2u64); | |
20514 | ||
20515 | v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15); | |
20516 | v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15); | |
20517 | v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15); | |
20518 | v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15); | |
20519 | ||
20520 | v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31); | |
20521 | v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31); | |
20522 | v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31); | |
20523 | v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31); | |
20524 | ||
20525 | v16i8 __builtin_msa_min_a_b (v16i8, v16i8); | |
20526 | v8i16 __builtin_msa_min_a_h (v8i16, v8i16); | |
20527 | v4i32 __builtin_msa_min_a_w (v4i32, v4i32); | |
20528 | v2i64 __builtin_msa_min_a_d (v2i64, v2i64); | |
20529 | ||
20530 | v16i8 __builtin_msa_min_s_b (v16i8, v16i8); | |
20531 | v8i16 __builtin_msa_min_s_h (v8i16, v8i16); | |
20532 | v4i32 __builtin_msa_min_s_w (v4i32, v4i32); | |
20533 | v2i64 __builtin_msa_min_s_d (v2i64, v2i64); | |
20534 | ||
20535 | v16u8 __builtin_msa_min_u_b (v16u8, v16u8); | |
20536 | v8u16 __builtin_msa_min_u_h (v8u16, v8u16); | |
20537 | v4u32 __builtin_msa_min_u_w (v4u32, v4u32); | |
20538 | v2u64 __builtin_msa_min_u_d (v2u64, v2u64); | |
20539 | ||
20540 | v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15); | |
20541 | v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15); | |
20542 | v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15); | |
20543 | v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15); | |
20544 | ||
20545 | v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31); | |
20546 | v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31); | |
20547 | v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31); | |
20548 | v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31); | |
20549 | ||
20550 | v16i8 __builtin_msa_mod_s_b (v16i8, v16i8); | |
20551 | v8i16 __builtin_msa_mod_s_h (v8i16, v8i16); | |
20552 | v4i32 __builtin_msa_mod_s_w (v4i32, v4i32); | |
20553 | v2i64 __builtin_msa_mod_s_d (v2i64, v2i64); | |
20554 | ||
20555 | v16u8 __builtin_msa_mod_u_b (v16u8, v16u8); | |
20556 | v8u16 __builtin_msa_mod_u_h (v8u16, v8u16); | |
20557 | v4u32 __builtin_msa_mod_u_w (v4u32, v4u32); | |
20558 | v2u64 __builtin_msa_mod_u_d (v2u64, v2u64); | |
20559 | ||
20560 | v16i8 __builtin_msa_move_v (v16i8); | |
20561 | ||
20562 | v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16); | |
20563 | v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32); | |
20564 | ||
20565 | v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16); | |
20566 | v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32); | |
20567 | ||
20568 | v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8); | |
20569 | v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16); | |
20570 | v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32); | |
20571 | v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64); | |
20572 | ||
20573 | v8i16 __builtin_msa_mul_q_h (v8i16, v8i16); | |
20574 | v4i32 __builtin_msa_mul_q_w (v4i32, v4i32); | |
20575 | ||
20576 | v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16); | |
20577 | v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32); | |
20578 | ||
20579 | v16i8 __builtin_msa_mulv_b (v16i8, v16i8); | |
20580 | v8i16 __builtin_msa_mulv_h (v8i16, v8i16); | |
20581 | v4i32 __builtin_msa_mulv_w (v4i32, v4i32); | |
20582 | v2i64 __builtin_msa_mulv_d (v2i64, v2i64); | |
20583 | ||
20584 | v16i8 __builtin_msa_nloc_b (v16i8); | |
20585 | v8i16 __builtin_msa_nloc_h (v8i16); | |
20586 | v4i32 __builtin_msa_nloc_w (v4i32); | |
20587 | v2i64 __builtin_msa_nloc_d (v2i64); | |
20588 | ||
20589 | v16i8 __builtin_msa_nlzc_b (v16i8); | |
20590 | v8i16 __builtin_msa_nlzc_h (v8i16); | |
20591 | v4i32 __builtin_msa_nlzc_w (v4i32); | |
20592 | v2i64 __builtin_msa_nlzc_d (v2i64); | |
20593 | ||
20594 | v16u8 __builtin_msa_nor_v (v16u8, v16u8); | |
20595 | ||
20596 | v16u8 __builtin_msa_nori_b (v16u8, imm0_255); | |
20597 | ||
20598 | v16u8 __builtin_msa_or_v (v16u8, v16u8); | |
20599 | ||
20600 | v16u8 __builtin_msa_ori_b (v16u8, imm0_255); | |
20601 | ||
20602 | v16i8 __builtin_msa_pckev_b (v16i8, v16i8); | |
20603 | v8i16 __builtin_msa_pckev_h (v8i16, v8i16); | |
20604 | v4i32 __builtin_msa_pckev_w (v4i32, v4i32); | |
20605 | v2i64 __builtin_msa_pckev_d (v2i64, v2i64); | |
20606 | ||
20607 | v16i8 __builtin_msa_pckod_b (v16i8, v16i8); | |
20608 | v8i16 __builtin_msa_pckod_h (v8i16, v8i16); | |
20609 | v4i32 __builtin_msa_pckod_w (v4i32, v4i32); | |
20610 | v2i64 __builtin_msa_pckod_d (v2i64, v2i64); | |
20611 | ||
20612 | v16i8 __builtin_msa_pcnt_b (v16i8); | |
20613 | v8i16 __builtin_msa_pcnt_h (v8i16); | |
20614 | v4i32 __builtin_msa_pcnt_w (v4i32); | |
20615 | v2i64 __builtin_msa_pcnt_d (v2i64); | |
20616 | ||
20617 | v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7); | |
20618 | v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15); | |
20619 | v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31); | |
20620 | v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63); | |
20621 | ||
20622 | v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7); | |
20623 | v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15); | |
20624 | v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31); | |
20625 | v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63); | |
20626 | ||
20627 | v16i8 __builtin_msa_shf_b (v16i8, imm0_255); | |
20628 | v8i16 __builtin_msa_shf_h (v8i16, imm0_255); | |
20629 | v4i32 __builtin_msa_shf_w (v4i32, imm0_255); | |
20630 | ||
20631 | v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32); | |
20632 | v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32); | |
20633 | v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32); | |
20634 | v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32); | |
20635 | ||
20636 | v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15); | |
20637 | v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7); | |
20638 | v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3); | |
20639 | v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1); | |
20640 | ||
20641 | v16i8 __builtin_msa_sll_b (v16i8, v16i8); | |
20642 | v8i16 __builtin_msa_sll_h (v8i16, v8i16); | |
20643 | v4i32 __builtin_msa_sll_w (v4i32, v4i32); | |
20644 | v2i64 __builtin_msa_sll_d (v2i64, v2i64); | |
20645 | ||
20646 | v16i8 __builtin_msa_slli_b (v16i8, imm0_7); | |
20647 | v8i16 __builtin_msa_slli_h (v8i16, imm0_15); | |
20648 | v4i32 __builtin_msa_slli_w (v4i32, imm0_31); | |
20649 | v2i64 __builtin_msa_slli_d (v2i64, imm0_63); | |
20650 | ||
20651 | v16i8 __builtin_msa_splat_b (v16i8, i32); | |
20652 | v8i16 __builtin_msa_splat_h (v8i16, i32); | |
20653 | v4i32 __builtin_msa_splat_w (v4i32, i32); | |
20654 | v2i64 __builtin_msa_splat_d (v2i64, i32); | |
20655 | ||
20656 | v16i8 __builtin_msa_splati_b (v16i8, imm0_15); | |
20657 | v8i16 __builtin_msa_splati_h (v8i16, imm0_7); | |
20658 | v4i32 __builtin_msa_splati_w (v4i32, imm0_3); | |
20659 | v2i64 __builtin_msa_splati_d (v2i64, imm0_1); | |
20660 | ||
20661 | v16i8 __builtin_msa_sra_b (v16i8, v16i8); | |
20662 | v8i16 __builtin_msa_sra_h (v8i16, v8i16); | |
20663 | v4i32 __builtin_msa_sra_w (v4i32, v4i32); | |
20664 | v2i64 __builtin_msa_sra_d (v2i64, v2i64); | |
20665 | ||
20666 | v16i8 __builtin_msa_srai_b (v16i8, imm0_7); | |
20667 | v8i16 __builtin_msa_srai_h (v8i16, imm0_15); | |
20668 | v4i32 __builtin_msa_srai_w (v4i32, imm0_31); | |
20669 | v2i64 __builtin_msa_srai_d (v2i64, imm0_63); | |
20670 | ||
20671 | v16i8 __builtin_msa_srar_b (v16i8, v16i8); | |
20672 | v8i16 __builtin_msa_srar_h (v8i16, v8i16); | |
20673 | v4i32 __builtin_msa_srar_w (v4i32, v4i32); | |
20674 | v2i64 __builtin_msa_srar_d (v2i64, v2i64); | |
20675 | ||
20676 | v16i8 __builtin_msa_srari_b (v16i8, imm0_7); | |
20677 | v8i16 __builtin_msa_srari_h (v8i16, imm0_15); | |
20678 | v4i32 __builtin_msa_srari_w (v4i32, imm0_31); | |
20679 | v2i64 __builtin_msa_srari_d (v2i64, imm0_63); | |
20680 | ||
20681 | v16i8 __builtin_msa_srl_b (v16i8, v16i8); | |
20682 | v8i16 __builtin_msa_srl_h (v8i16, v8i16); | |
20683 | v4i32 __builtin_msa_srl_w (v4i32, v4i32); | |
20684 | v2i64 __builtin_msa_srl_d (v2i64, v2i64); | |
20685 | ||
20686 | v16i8 __builtin_msa_srli_b (v16i8, imm0_7); | |
20687 | v8i16 __builtin_msa_srli_h (v8i16, imm0_15); | |
20688 | v4i32 __builtin_msa_srli_w (v4i32, imm0_31); | |
20689 | v2i64 __builtin_msa_srli_d (v2i64, imm0_63); | |
20690 | ||
20691 | v16i8 __builtin_msa_srlr_b (v16i8, v16i8); | |
20692 | v8i16 __builtin_msa_srlr_h (v8i16, v8i16); | |
20693 | v4i32 __builtin_msa_srlr_w (v4i32, v4i32); | |
20694 | v2i64 __builtin_msa_srlr_d (v2i64, v2i64); | |
20695 | ||
20696 | v16i8 __builtin_msa_srlri_b (v16i8, imm0_7); | |
20697 | v8i16 __builtin_msa_srlri_h (v8i16, imm0_15); | |
20698 | v4i32 __builtin_msa_srlri_w (v4i32, imm0_31); | |
20699 | v2i64 __builtin_msa_srlri_d (v2i64, imm0_63); | |
20700 | ||
20701 | void __builtin_msa_st_b (v16i8, void *, imm_n512_511); | |
20702 | void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022); | |
20703 | void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044); | |
20704 | void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088); | |
20705 | ||
20706 | v16i8 __builtin_msa_subs_s_b (v16i8, v16i8); | |
20707 | v8i16 __builtin_msa_subs_s_h (v8i16, v8i16); | |
20708 | v4i32 __builtin_msa_subs_s_w (v4i32, v4i32); | |
20709 | v2i64 __builtin_msa_subs_s_d (v2i64, v2i64); | |
20710 | ||
20711 | v16u8 __builtin_msa_subs_u_b (v16u8, v16u8); | |
20712 | v8u16 __builtin_msa_subs_u_h (v8u16, v8u16); | |
20713 | v4u32 __builtin_msa_subs_u_w (v4u32, v4u32); | |
20714 | v2u64 __builtin_msa_subs_u_d (v2u64, v2u64); | |
20715 | ||
20716 | v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8); | |
20717 | v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16); | |
20718 | v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32); | |
20719 | v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64); | |
20720 | ||
20721 | v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8); | |
20722 | v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16); | |
20723 | v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32); | |
20724 | v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64); | |
20725 | ||
20726 | v16i8 __builtin_msa_subv_b (v16i8, v16i8); | |
20727 | v8i16 __builtin_msa_subv_h (v8i16, v8i16); | |
20728 | v4i32 __builtin_msa_subv_w (v4i32, v4i32); | |
20729 | v2i64 __builtin_msa_subv_d (v2i64, v2i64); | |
20730 | ||
20731 | v16i8 __builtin_msa_subvi_b (v16i8, imm0_31); | |
20732 | v8i16 __builtin_msa_subvi_h (v8i16, imm0_31); | |
20733 | v4i32 __builtin_msa_subvi_w (v4i32, imm0_31); | |
20734 | v2i64 __builtin_msa_subvi_d (v2i64, imm0_31); | |
20735 | ||
20736 | v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8); | |
20737 | v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16); | |
20738 | v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32); | |
20739 | v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64); | |
20740 | ||
20741 | v16u8 __builtin_msa_xor_v (v16u8, v16u8); | |
20742 | ||
20743 | v16u8 __builtin_msa_xori_b (v16u8, imm0_255); | |
20744 | @end smallexample | |
20745 | ||
20746 | @node Other MIPS Built-in Functions | |
20747 | @subsection Other MIPS Built-in Functions | |
20748 | ||
20749 | GCC provides other MIPS-specific built-in functions: | |
20750 | ||
20751 | @table @code | |
20752 | @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) | |
20753 | Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. | |
20754 | GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} | |
20755 | when this function is available. | |
20756 | ||
20757 | @item unsigned int __builtin_mips_get_fcsr (void) | |
20758 | @itemx void __builtin_mips_set_fcsr (unsigned int @var{value}) | |
20759 | Get and set the contents of the floating-point control and status register | |
20760 | (FPU control register 31). These functions are only available in hard-float | |
20761 | code but can be called in both MIPS16 and non-MIPS16 contexts. | |
20762 | ||
20763 | @code{__builtin_mips_set_fcsr} can be used to change any bit of the | |
20764 | register except the condition codes, which GCC assumes are preserved. | |
20765 | @end table | |
20766 | ||
20767 | @node MSP430 Built-in Functions | |
20768 | @subsection MSP430 Built-in Functions | |
20769 | ||
20770 | GCC provides a couple of special builtin functions to aid in the | |
20771 | writing of interrupt handlers in C. | |
20772 | ||
20773 | @table @code | |
20774 | @item __bic_SR_register_on_exit (int @var{mask}) | |
20775 | This clears the indicated bits in the saved copy of the status register | |
20776 | currently residing on the stack. This only works inside interrupt | |
20777 | handlers and the changes to the status register will only take affect | |
20778 | once the handler returns. | |
20779 | ||
20780 | @item __bis_SR_register_on_exit (int @var{mask}) | |
20781 | This sets the indicated bits in the saved copy of the status register | |
20782 | currently residing on the stack. This only works inside interrupt | |
20783 | handlers and the changes to the status register will only take affect | |
20784 | once the handler returns. | |
20785 | ||
20786 | @item __delay_cycles (long long @var{cycles}) | |
20787 | This inserts an instruction sequence that takes exactly @var{cycles} | |
20788 | cycles (between 0 and about 17E9) to complete. The inserted sequence | |
20789 | may use jumps, loops, or no-ops, and does not interfere with any other | |
20790 | instructions. Note that @var{cycles} must be a compile-time constant | |
20791 | integer - that is, you must pass a number, not a variable that may be | |
20792 | optimized to a constant later. The number of cycles delayed by this | |
20793 | builtin is exact. | |
20794 | @end table | |
20795 | ||
20796 | @node NDS32 Built-in Functions | |
20797 | @subsection NDS32 Built-in Functions | |
20798 | ||
20799 | These built-in functions are available for the NDS32 target: | |
20800 | ||
f25efe50 | 20801 | @defbuiltin{void __builtin_nds32_isync (int *@var{addr})} |
d77de738 ML |
20802 | Insert an ISYNC instruction into the instruction stream where |
20803 | @var{addr} is an instruction address for serialization. | |
f25efe50 | 20804 | @enddefbuiltin |
d77de738 | 20805 | |
f25efe50 | 20806 | @defbuiltin{void __builtin_nds32_isb (void)} |
d77de738 | 20807 | Insert an ISB instruction into the instruction stream. |
f25efe50 | 20808 | @enddefbuiltin |
d77de738 | 20809 | |
f25efe50 | 20810 | @defbuiltin{int __builtin_nds32_mfsr (int @var{sr})} |
d77de738 | 20811 | Return the content of a system register which is mapped by @var{sr}. |
f25efe50 | 20812 | @enddefbuiltin |
d77de738 | 20813 | |
f25efe50 | 20814 | @defbuiltin{int __builtin_nds32_mfusr (int @var{usr})} |
d77de738 | 20815 | Return the content of a user space register which is mapped by @var{usr}. |
f25efe50 | 20816 | @enddefbuiltin |
d77de738 | 20817 | |
f25efe50 | 20818 | @defbuiltin{void __builtin_nds32_mtsr (int @var{value}, int @var{sr})} |
d77de738 | 20819 | Move the @var{value} to a system register which is mapped by @var{sr}. |
f25efe50 | 20820 | @enddefbuiltin |
d77de738 | 20821 | |
f25efe50 | 20822 | @defbuiltin{void __builtin_nds32_mtusr (int @var{value}, int @var{usr})} |
d77de738 | 20823 | Move the @var{value} to a user space register which is mapped by @var{usr}. |
f25efe50 | 20824 | @enddefbuiltin |
d77de738 | 20825 | |
f25efe50 | 20826 | @defbuiltin{void __builtin_nds32_setgie_en (void)} |
d77de738 | 20827 | Enable global interrupt. |
f25efe50 | 20828 | @enddefbuiltin |
d77de738 | 20829 | |
f25efe50 | 20830 | @defbuiltin{void __builtin_nds32_setgie_dis (void)} |
d77de738 | 20831 | Disable global interrupt. |
f25efe50 | 20832 | @enddefbuiltin |
d77de738 | 20833 | |
c09471fb RS |
20834 | @node Nvidia PTX Built-in Functions |
20835 | @subsection Nvidia PTX Built-in Functions | |
20836 | ||
20837 | These built-in functions are available for the Nvidia PTX target: | |
20838 | ||
ff99671a | 20839 | @defbuiltin{{unsigned int} __builtin_nvptx_brev (unsigned int @var{x})} |
c09471fb | 20840 | Reverse the bit order of a 32-bit unsigned integer. |
c09471fb RS |
20841 | @enddefbuiltin |
20842 | ||
ff99671a | 20843 | @defbuiltin{{unsigned long long} __builtin_nvptx_brevll (unsigned long long @var{x})} |
c09471fb RS |
20844 | Reverse the bit order of a 64-bit unsigned integer. |
20845 | @enddefbuiltin | |
20846 | ||
d77de738 ML |
20847 | @node Basic PowerPC Built-in Functions |
20848 | @subsection Basic PowerPC Built-in Functions | |
20849 | ||
20850 | @menu | |
20851 | * Basic PowerPC Built-in Functions Available on all Configurations:: | |
20852 | * Basic PowerPC Built-in Functions Available on ISA 2.05:: | |
20853 | * Basic PowerPC Built-in Functions Available on ISA 2.06:: | |
20854 | * Basic PowerPC Built-in Functions Available on ISA 2.07:: | |
20855 | * Basic PowerPC Built-in Functions Available on ISA 3.0:: | |
20856 | * Basic PowerPC Built-in Functions Available on ISA 3.1:: | |
20857 | @end menu | |
20858 | ||
20859 | This section describes PowerPC built-in functions that do not require | |
20860 | the inclusion of any special header files to declare prototypes or | |
20861 | provide macro definitions. The sections that follow describe | |
20862 | additional PowerPC built-in functions. | |
20863 | ||
20864 | @node Basic PowerPC Built-in Functions Available on all Configurations | |
20865 | @subsubsection Basic PowerPC Built-in Functions Available on all Configurations | |
20866 | ||
f25efe50 | 20867 | @defbuiltin{void __builtin_cpu_init (void)} |
d77de738 ML |
20868 | This function is a @code{nop} on the PowerPC platform and is included solely |
20869 | to maintain API compatibility with the x86 builtins. | |
f25efe50 | 20870 | @enddefbuiltin |
d77de738 | 20871 | |
f25efe50 | 20872 | @defbuiltin{int __builtin_cpu_is (const char *@var{cpuname})} |
d77de738 ML |
20873 | This function returns a value of @code{1} if the run-time CPU is of type |
20874 | @var{cpuname} and returns @code{0} otherwise | |
20875 | ||
20876 | The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer | |
20877 | which exports the hardware capability bits. GCC defines the macro | |
20878 | @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports} | |
20879 | built-in function is fully supported. | |
20880 | ||
20881 | If GCC was configured to use a GLIBC before 2.23, the built-in | |
20882 | function @code{__builtin_cpu_is} always returns a 0 and the compiler | |
20883 | issues a warning. | |
20884 | ||
20885 | The following CPU names can be detected: | |
20886 | ||
20887 | @table @samp | |
20888 | @item power10 | |
20889 | IBM POWER10 Server CPU. | |
20890 | @item power9 | |
20891 | IBM POWER9 Server CPU. | |
20892 | @item power8 | |
20893 | IBM POWER8 Server CPU. | |
20894 | @item power7 | |
20895 | IBM POWER7 Server CPU. | |
20896 | @item power6x | |
20897 | IBM POWER6 Server CPU (RAW mode). | |
20898 | @item power6 | |
20899 | IBM POWER6 Server CPU (Architected mode). | |
20900 | @item power5+ | |
20901 | IBM POWER5+ Server CPU. | |
20902 | @item power5 | |
20903 | IBM POWER5 Server CPU. | |
20904 | @item ppc970 | |
20905 | IBM 970 Server CPU (ie, Apple G5). | |
20906 | @item power4 | |
20907 | IBM POWER4 Server CPU. | |
20908 | @item ppca2 | |
20909 | IBM A2 64-bit Embedded CPU | |
20910 | @item ppc476 | |
20911 | IBM PowerPC 476FP 32-bit Embedded CPU. | |
20912 | @item ppc464 | |
20913 | IBM PowerPC 464 32-bit Embedded CPU. | |
20914 | @item ppc440 | |
20915 | PowerPC 440 32-bit Embedded CPU. | |
20916 | @item ppc405 | |
20917 | PowerPC 405 32-bit Embedded CPU. | |
20918 | @item ppc-cell-be | |
20919 | IBM PowerPC Cell Broadband Engine Architecture CPU. | |
20920 | @end table | |
20921 | ||
20922 | Here is an example: | |
20923 | @smallexample | |
20924 | #ifdef __BUILTIN_CPU_SUPPORTS__ | |
20925 | if (__builtin_cpu_is ("power8")) | |
20926 | @{ | |
20927 | do_power8 (); // POWER8 specific implementation. | |
20928 | @} | |
20929 | else | |
20930 | #endif | |
20931 | @{ | |
20932 | do_generic (); // Generic implementation. | |
20933 | @} | |
20934 | @end smallexample | |
f25efe50 | 20935 | @enddefbuiltin |
d77de738 | 20936 | |
f25efe50 | 20937 | @defbuiltin{int __builtin_cpu_supports (const char *@var{feature})} |
d77de738 ML |
20938 | This function returns a value of @code{1} if the run-time CPU supports the HWCAP |
20939 | feature @var{feature} and returns @code{0} otherwise. | |
20940 | ||
20941 | The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or | |
20942 | newer which exports the hardware capability bits. GCC defines the | |
20943 | macro @code{__BUILTIN_CPU_SUPPORTS__} if the | |
20944 | @code{__builtin_cpu_supports} built-in function is fully supported. | |
20945 | ||
20946 | If GCC was configured to use a GLIBC before 2.23, the built-in | |
20947 | function @code{__builtin_cpu_supports} always returns a 0 and the | |
20948 | compiler issues a warning. | |
20949 | ||
20950 | The following features can be | |
20951 | detected: | |
20952 | ||
20953 | @table @samp | |
20954 | @item 4xxmac | |
20955 | 4xx CPU has a Multiply Accumulator. | |
20956 | @item altivec | |
20957 | CPU has a SIMD/Vector Unit. | |
20958 | @item arch_2_05 | |
20959 | CPU supports ISA 2.05 (eg, POWER6) | |
20960 | @item arch_2_06 | |
20961 | CPU supports ISA 2.06 (eg, POWER7) | |
20962 | @item arch_2_07 | |
20963 | CPU supports ISA 2.07 (eg, POWER8) | |
20964 | @item arch_3_00 | |
20965 | CPU supports ISA 3.0 (eg, POWER9) | |
20966 | @item arch_3_1 | |
20967 | CPU supports ISA 3.1 (eg, POWER10) | |
20968 | @item archpmu | |
20969 | CPU supports the set of compatible performance monitoring events. | |
20970 | @item booke | |
20971 | CPU supports the Embedded ISA category. | |
20972 | @item cellbe | |
20973 | CPU has a CELL broadband engine. | |
20974 | @item darn | |
20975 | CPU supports the @code{darn} (deliver a random number) instruction. | |
20976 | @item dfp | |
20977 | CPU has a decimal floating point unit. | |
20978 | @item dscr | |
20979 | CPU supports the data stream control register. | |
20980 | @item ebb | |
20981 | CPU supports event base branching. | |
20982 | @item efpdouble | |
20983 | CPU has a SPE double precision floating point unit. | |
20984 | @item efpsingle | |
20985 | CPU has a SPE single precision floating point unit. | |
20986 | @item fpu | |
20987 | CPU has a floating point unit. | |
20988 | @item htm | |
20989 | CPU has hardware transaction memory instructions. | |
20990 | @item htm-nosc | |
20991 | Kernel aborts hardware transactions when a syscall is made. | |
20992 | @item htm-no-suspend | |
20993 | CPU supports hardware transaction memory but does not support the | |
20994 | @code{tsuspend.} instruction. | |
20995 | @item ic_snoop | |
20996 | CPU supports icache snooping capabilities. | |
20997 | @item ieee128 | |
20998 | CPU supports 128-bit IEEE binary floating point instructions. | |
20999 | @item isel | |
21000 | CPU supports the integer select instruction. | |
21001 | @item mma | |
21002 | CPU supports the matrix-multiply assist instructions. | |
21003 | @item mmu | |
21004 | CPU has a memory management unit. | |
21005 | @item notb | |
21006 | CPU does not have a timebase (eg, 601 and 403gx). | |
21007 | @item pa6t | |
21008 | CPU supports the PA Semi 6T CORE ISA. | |
21009 | @item power4 | |
21010 | CPU supports ISA 2.00 (eg, POWER4) | |
21011 | @item power5 | |
21012 | CPU supports ISA 2.02 (eg, POWER5) | |
21013 | @item power5+ | |
21014 | CPU supports ISA 2.03 (eg, POWER5+) | |
21015 | @item power6x | |
21016 | CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr. | |
21017 | @item ppc32 | |
21018 | CPU supports 32-bit mode execution. | |
21019 | @item ppc601 | |
21020 | CPU supports the old POWER ISA (eg, 601) | |
21021 | @item ppc64 | |
21022 | CPU supports 64-bit mode execution. | |
21023 | @item ppcle | |
21024 | CPU supports a little-endian mode that uses address swizzling. | |
21025 | @item scv | |
21026 | Kernel supports system call vectored. | |
21027 | @item smt | |
21028 | CPU support simultaneous multi-threading. | |
21029 | @item spe | |
21030 | CPU has a signal processing extension unit. | |
21031 | @item tar | |
21032 | CPU supports the target address register. | |
21033 | @item true_le | |
21034 | CPU supports true little-endian mode. | |
21035 | @item ucache | |
21036 | CPU has unified I/D cache. | |
21037 | @item vcrypto | |
21038 | CPU supports the vector cryptography instructions. | |
21039 | @item vsx | |
21040 | CPU supports the vector-scalar extension. | |
21041 | @end table | |
21042 | ||
21043 | Here is an example: | |
21044 | @smallexample | |
21045 | #ifdef __BUILTIN_CPU_SUPPORTS__ | |
21046 | if (__builtin_cpu_supports ("fpu")) | |
21047 | @{ | |
21048 | asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2)); | |
21049 | @} | |
21050 | else | |
21051 | #endif | |
21052 | @{ | |
21053 | dst = __fadd (src1, src2); // Software FP addition function. | |
21054 | @} | |
21055 | @end smallexample | |
f25efe50 | 21056 | @enddefbuiltin |
d77de738 ML |
21057 | |
21058 | The following built-in functions are also available on all PowerPC | |
21059 | processors: | |
21060 | @smallexample | |
21061 | uint64_t __builtin_ppc_get_timebase (); | |
21062 | unsigned long __builtin_ppc_mftb (); | |
21063 | double __builtin_unpack_ibm128 (__ibm128, int); | |
21064 | __ibm128 __builtin_pack_ibm128 (double, double); | |
21065 | double __builtin_mffs (void); | |
21066 | void __builtin_mtfsf (const int, double); | |
21067 | void __builtin_mtfsb0 (const int); | |
21068 | void __builtin_mtfsb1 (const int); | |
ef3bbc69 | 21069 | double __builtin_set_fpscr_rn (int); |
d77de738 ML |
21070 | @end smallexample |
21071 | ||
21072 | The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb} | |
21073 | functions generate instructions to read the Time Base Register. The | |
21074 | @code{__builtin_ppc_get_timebase} function may generate multiple | |
21075 | instructions and always returns the 64 bits of the Time Base Register. | |
21076 | The @code{__builtin_ppc_mftb} function always generates one instruction and | |
21077 | returns the Time Base Register value as an unsigned long, throwing away | |
21078 | the most significant word on 32-bit environments. The @code{__builtin_mffs} | |
21079 | return the value of the FPSCR register. Note, ISA 3.0 supports the | |
21080 | @code{__builtin_mffsl()} which permits software to read the control and | |
21081 | non-sticky status bits in the FSPCR without the higher latency associated with | |
21082 | accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant | |
21083 | 8-bit integer field mask and a double precision floating point argument | |
21084 | and generates the @code{mtfsf} (extended mnemonic) instruction to write new | |
21085 | values to selected fields of the FPSCR. The | |
21086 | @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change | |
21087 | as an argument. The valid bit range is between 0 and 31. The builtins map to | |
21088 | the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and | |
21089 | add 32. Hence these instructions only modify the FPSCR[32:63] bits by | |
ef3bbc69 CL |
21090 | changing the specified bit to a zero or one respectively. |
21091 | ||
21092 | The @code{__builtin_set_fpscr_rn} built-in allows changing both of the floating | |
21093 | point rounding mode bits and returning the various FPSCR fields before the RN | |
21094 | field is updated. The built-in returns a double consisting of the initial | |
21095 | value of the FPSCR fields DRN, VE, OE, UE, ZE, XE, NI, and RN bit positions | |
21096 | with all other bits set to zero. The built-in argument is a 2-bit value for the | |
21097 | new RN field value. The argument can either be an @code{const int} or stored | |
21098 | in a variable. Earlier versions of @code{__builtin_set_fpscr_rn} returned | |
21099 | void. A @code{__SET_FPSCR_RN_RETURNS_FPSCR__} macro has been added. If | |
21100 | defined, then the @code{__builtin_set_fpscr_rn} built-in returns the FPSCR | |
21101 | fields. If not defined, the @code{__builtin_set_fpscr_rn} does not return a | |
21102 | value. If the @option{-msoft-float} option is used, the | |
21103 | @code{__builtin_set_fpscr_rn} built-in will not return a value. | |
d77de738 ML |
21104 | |
21105 | @node Basic PowerPC Built-in Functions Available on ISA 2.05 | |
21106 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05 | |
21107 | ||
21108 | The basic built-in functions described in this section are | |
21109 | available on the PowerPC family of processors starting with ISA 2.05 | |
21110 | or later. Unless specific options are explicitly disabled on the | |
21111 | command line, specifying option @option{-mcpu=power6} has the effect of | |
21112 | enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt}, | |
21113 | @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb}, | |
21114 | @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and | |
21115 | @option{-mrecip-precision} options. Specify the | |
21116 | @option{-maltivec} option explicitly in | |
21117 | combination with the above options if desired. | |
21118 | ||
21119 | The following functions require option @option{-mcmpb}. | |
21120 | @smallexample | |
21121 | unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int); | |
21122 | unsigned int __builtin_cmpb (unsigned int, unsigned int); | |
21123 | @end smallexample | |
21124 | ||
21125 | The @code{__builtin_cmpb} function | |
21126 | performs a byte-wise compare on the contents of its two arguments, | |
21127 | returning the result of the byte-wise comparison as the returned | |
21128 | value. For each byte comparison, the corresponding byte of the return | |
21129 | value holds 0xff if the input bytes are equal and 0 if the input bytes | |
21130 | are not equal. If either of the arguments to this built-in function | |
21131 | is wider than 32 bits, the function call expands into the form that | |
21132 | expects @code{unsigned long long int} arguments | |
21133 | which is only available on 64-bit targets. | |
21134 | ||
21135 | The following built-in functions are available | |
21136 | when hardware decimal floating point | |
21137 | (@option{-mhard-dfp}) is available: | |
21138 | @smallexample | |
21139 | void __builtin_set_fpscr_drn(int); | |
21140 | _Decimal64 __builtin_ddedpd (int, _Decimal64); | |
21141 | _Decimal128 __builtin_ddedpdq (int, _Decimal128); | |
21142 | _Decimal64 __builtin_denbcd (int, _Decimal64); | |
21143 | _Decimal128 __builtin_denbcdq (int, _Decimal128); | |
21144 | _Decimal64 __builtin_diex (long long, _Decimal64); | |
21145 | _Decimal128 _builtin_diexq (long long, _Decimal128); | |
21146 | _Decimal64 __builtin_dscli (_Decimal64, int); | |
21147 | _Decimal128 __builtin_dscliq (_Decimal128, int); | |
21148 | _Decimal64 __builtin_dscri (_Decimal64, int); | |
21149 | _Decimal128 __builtin_dscriq (_Decimal128, int); | |
21150 | long long __builtin_dxex (_Decimal64); | |
21151 | long long __builtin_dxexq (_Decimal128); | |
21152 | _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long); | |
21153 | unsigned long long __builtin_unpack_dec128 (_Decimal128, int); | |
21154 | ||
21155 | The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal | |
21156 | floating point rounding mode bits. The argument is a 3-bit value. The | |
21157 | argument can either be a @code{const int} or the value can be stored in | |
21158 | a variable. | |
21159 | The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available. | |
21160 | Otherwise the builtin reads the FPSCR, masks the current decimal rounding | |
21161 | mode bits out and OR's in the new value. | |
21162 | ||
14a3839c CL |
21163 | _Decimal64 __builtin_dfp_quantize (_Decimal64, _Decimal64, const int); |
21164 | _Decimal64 __builtin_dfp_quantize (const int, _Decimal64, const int); | |
21165 | _Decimal128 __builtin_dfp_quantize (_Decimal128, _Decimal128, const int); | |
21166 | _Decimal128 __builtin_dfp_quantize (const int, _Decimal128, const int); | |
21167 | ||
21168 | The @code{__builtin_dfp_quantize} built-in, converts and rounds the second | |
21169 | argument to the form with the exponent as specified by the first | |
21170 | argument based on the rounding mode specified by the third argument. | |
21171 | If the first argument is a decimal floating point value, its exponent is used | |
21172 | for converting and rounding of the second argument. If the first argument is a | |
21173 | 5-bit constant integer value, then the value specifies the exponent to be used | |
21174 | when rounding and converting the second argument. The third argument is a | |
21175 | two bit constant integer that specifies the rounding mode. The possible modes | |
21176 | are: 00 Round to nearest, ties to even; 01 Round toward 0; 10 Round to nearest, | |
21177 | ties away from 0; 11 Round according to DRN where DRN is the Decimal Floating | |
21178 | point field of the FPSCR. | |
21179 | ||
d77de738 ML |
21180 | @end smallexample |
21181 | ||
21182 | The following functions require @option{-mhard-float}, | |
21183 | @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options. | |
21184 | ||
21185 | @smallexample | |
21186 | double __builtin_recipdiv (double, double); | |
21187 | float __builtin_recipdivf (float, float); | |
21188 | double __builtin_rsqrt (double); | |
21189 | float __builtin_rsqrtf (float); | |
21190 | @end smallexample | |
21191 | ||
21192 | The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and | |
21193 | @code{__builtin_rsqrtf} functions generate multiple instructions to | |
21194 | implement the reciprocal sqrt functionality using reciprocal sqrt | |
21195 | estimate instructions. | |
21196 | ||
21197 | The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} | |
21198 | functions generate multiple instructions to implement division using | |
21199 | the reciprocal estimate instructions. | |
21200 | ||
21201 | The following functions require @option{-mhard-float} and | |
21202 | @option{-mmultiple} options. | |
21203 | ||
21204 | The @code{__builtin_unpack_longdouble} function takes a | |
21205 | @code{long double} argument and a compile time constant of 0 or 1. If | |
21206 | the constant is 0, the first @code{double} within the | |
21207 | @code{long double} is returned, otherwise the second @code{double} | |
21208 | is returned. The @code{__builtin_unpack_longdouble} function is only | |
21209 | available if @code{long double} uses the IBM extended double | |
21210 | representation. | |
21211 | ||
21212 | The @code{__builtin_pack_longdouble} function takes two @code{double} | |
21213 | arguments and returns a @code{long double} value that combines the two | |
21214 | arguments. The @code{__builtin_pack_longdouble} function is only | |
21215 | available if @code{long double} uses the IBM extended double | |
21216 | representation. | |
21217 | ||
21218 | The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128} | |
21219 | argument and a compile time constant of 0 or 1. If the constant is 0, | |
21220 | the first @code{double} within the @code{__ibm128} is returned, | |
21221 | otherwise the second @code{double} is returned. | |
21222 | ||
21223 | The @code{__builtin_pack_ibm128} function takes two @code{double} | |
21224 | arguments and returns a @code{__ibm128} value that combines the two | |
21225 | arguments. | |
21226 | ||
21227 | Additional built-in functions are available for the 64-bit PowerPC | |
21228 | family of processors, for efficient use of 128-bit floating point | |
21229 | (@code{__float128}) values. | |
21230 | ||
21231 | @node Basic PowerPC Built-in Functions Available on ISA 2.06 | |
21232 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06 | |
21233 | ||
21234 | The basic built-in functions described in this section are | |
21235 | available on the PowerPC family of processors starting with ISA 2.05 | |
21236 | or later. Unless specific options are explicitly disabled on the | |
21237 | command line, specifying option @option{-mcpu=power7} has the effect of | |
21238 | enabling all the same options as for @option{-mcpu=power6} in | |
21239 | addition to the @option{-maltivec}, @option{-mpopcntd}, and | |
21240 | @option{-mvsx} options. | |
21241 | ||
21242 | The following basic built-in functions require @option{-mpopcntd}: | |
21243 | @smallexample | |
21244 | unsigned int __builtin_addg6s (unsigned int, unsigned int); | |
21245 | long long __builtin_bpermd (long long, long long); | |
21246 | unsigned int __builtin_cbcdtd (unsigned int); | |
21247 | unsigned int __builtin_cdtbcd (unsigned int); | |
21248 | long long __builtin_divde (long long, long long); | |
21249 | unsigned long long __builtin_divdeu (unsigned long long, unsigned long long); | |
21250 | int __builtin_divwe (int, int); | |
21251 | unsigned int __builtin_divweu (unsigned int, unsigned int); | |
21252 | vector __int128 __builtin_pack_vector_int128 (long long, long long); | |
21253 | void __builtin_rs6000_speculation_barrier (void); | |
21254 | long long __builtin_unpack_vector_int128 (vector __int128, signed char); | |
21255 | @end smallexample | |
21256 | ||
21257 | Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions | |
21258 | require a 64-bit environment. | |
21259 | ||
21260 | The following basic built-in functions, which are also supported on | |
21261 | x86 targets, require @option{-mfloat128}. | |
21262 | @smallexample | |
21263 | __float128 __builtin_fabsq (__float128); | |
21264 | __float128 __builtin_copysignq (__float128, __float128); | |
21265 | __float128 __builtin_infq (void); | |
21266 | __float128 __builtin_huge_valq (void); | |
21267 | __float128 __builtin_nanq (void); | |
21268 | __float128 __builtin_nansq (void); | |
21269 | ||
21270 | __float128 __builtin_sqrtf128 (__float128); | |
21271 | __float128 __builtin_fmaf128 (__float128, __float128, __float128); | |
21272 | @end smallexample | |
21273 | ||
21274 | @node Basic PowerPC Built-in Functions Available on ISA 2.07 | |
21275 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07 | |
21276 | ||
21277 | The basic built-in functions described in this section are | |
21278 | available on the PowerPC family of processors starting with ISA 2.07 | |
21279 | or later. Unless specific options are explicitly disabled on the | |
21280 | command line, specifying option @option{-mcpu=power8} has the effect of | |
21281 | enabling all the same options as for @option{-mcpu=power7} in | |
21282 | addition to the @option{-mpower8-fusion}, @option{-mpower8-vector}, | |
21283 | @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and | |
21284 | @option{-mquad-memory-atomic} options. | |
21285 | ||
21286 | This section intentionally empty. | |
21287 | ||
21288 | @node Basic PowerPC Built-in Functions Available on ISA 3.0 | |
21289 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0 | |
21290 | ||
21291 | The basic built-in functions described in this section are | |
21292 | available on the PowerPC family of processors starting with ISA 3.0 | |
21293 | or later. Unless specific options are explicitly disabled on the | |
21294 | command line, specifying option @option{-mcpu=power9} has the effect of | |
21295 | enabling all the same options as for @option{-mcpu=power8} in | |
21296 | addition to the @option{-misel} option. | |
21297 | ||
21298 | The following built-in functions are available on Linux 64-bit systems | |
21299 | that use the ISA 3.0 instruction set (@option{-mcpu=power9}): | |
21300 | ||
f25efe50 | 21301 | @defbuiltin{__float128 __builtin_addf128_round_to_odd (__float128, __float128)} |
d77de738 ML |
21302 | Perform a 128-bit IEEE floating point add using round to odd as the |
21303 | rounding mode. | |
f25efe50 | 21304 | @enddefbuiltin |
d77de738 | 21305 | |
f25efe50 | 21306 | @defbuiltin{__float128 __builtin_subf128_round_to_odd (__float128, __float128)} |
d77de738 ML |
21307 | Perform a 128-bit IEEE floating point subtract using round to odd as |
21308 | the rounding mode. | |
f25efe50 | 21309 | @enddefbuiltin |
d77de738 | 21310 | |
f25efe50 | 21311 | @defbuiltin{__float128 __builtin_mulf128_round_to_odd (__float128, __float128)} |
d77de738 ML |
21312 | Perform a 128-bit IEEE floating point multiply using round to odd as |
21313 | the rounding mode. | |
f25efe50 | 21314 | @enddefbuiltin |
d77de738 | 21315 | |
f25efe50 | 21316 | @defbuiltin{__float128 __builtin_divf128_round_to_odd (__float128, __float128)} |
d77de738 ML |
21317 | Perform a 128-bit IEEE floating point divide using round to odd as |
21318 | the rounding mode. | |
f25efe50 | 21319 | @enddefbuiltin |
d77de738 | 21320 | |
f25efe50 | 21321 | @defbuiltin{__float128 __builtin_sqrtf128_round_to_odd (__float128)} |
d77de738 ML |
21322 | Perform a 128-bit IEEE floating point square root using round to odd |
21323 | as the rounding mode. | |
f25efe50 | 21324 | @enddefbuiltin |
d77de738 | 21325 | |
f25efe50 | 21326 | @defbuiltin{__float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)} |
d77de738 ML |
21327 | Perform a 128-bit IEEE floating point fused multiply and add operation |
21328 | using round to odd as the rounding mode. | |
f25efe50 | 21329 | @enddefbuiltin |
d77de738 | 21330 | |
f25efe50 | 21331 | @defbuiltin{double __builtin_truncf128_round_to_odd (__float128)} |
d77de738 ML |
21332 | Convert a 128-bit IEEE floating point value to @code{double} using |
21333 | round to odd as the rounding mode. | |
f25efe50 AA |
21334 | @enddefbuiltin |
21335 | ||
d77de738 ML |
21336 | |
21337 | The following additional built-in functions are also available for the | |
21338 | PowerPC family of processors, starting with ISA 3.0 or later: | |
d77de738 | 21339 | |
ff99671a JJ |
21340 | @defbuiltin{{long long} __builtin_darn (void)} |
21341 | @defbuiltinx{{long long} __builtin_darn_raw (void)} | |
f25efe50 | 21342 | @defbuiltinx{int __builtin_darn_32 (void)} |
d77de738 ML |
21343 | The @code{__builtin_darn} and @code{__builtin_darn_raw} |
21344 | functions require a | |
21345 | 64-bit environment supporting ISA 3.0 or later. | |
21346 | The @code{__builtin_darn} function provides a 64-bit conditioned | |
21347 | random number. The @code{__builtin_darn_raw} function provides a | |
21348 | 64-bit raw random number. The @code{__builtin_darn_32} function | |
21349 | provides a 32-bit conditioned random number. | |
f25efe50 | 21350 | @enddefbuiltin |
d77de738 ML |
21351 | |
21352 | The following additional built-in functions are also available for the | |
21353 | PowerPC family of processors, starting with ISA 3.0 or later: | |
21354 | ||
21355 | @smallexample | |
21356 | int __builtin_byte_in_set (unsigned char u, unsigned long long set); | |
21357 | int __builtin_byte_in_range (unsigned char u, unsigned int range); | |
21358 | int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges); | |
21359 | ||
21360 | int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value); | |
21361 | int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value); | |
21362 | int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value); | |
21363 | int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value); | |
21364 | ||
21365 | int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value); | |
21366 | int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value); | |
21367 | int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value); | |
21368 | int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value); | |
21369 | ||
21370 | int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value); | |
21371 | int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value); | |
21372 | int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value); | |
21373 | int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value); | |
21374 | ||
21375 | int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value); | |
21376 | int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value); | |
21377 | int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value); | |
21378 | int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value); | |
21379 | ||
21380 | double __builtin_mffsl(void); | |
21381 | ||
21382 | @end smallexample | |
21383 | The @code{__builtin_byte_in_set} function requires a | |
21384 | 64-bit environment supporting ISA 3.0 or later. This function returns | |
21385 | a non-zero value if and only if its @code{u} argument exactly equals one of | |
21386 | the eight bytes contained within its 64-bit @code{set} argument. | |
21387 | ||
21388 | The @code{__builtin_byte_in_range} and | |
21389 | @code{__builtin_byte_in_either_range} require an environment | |
21390 | supporting ISA 3.0 or later. For these two functions, the | |
21391 | @code{range} argument is encoded as 4 bytes, organized as | |
21392 | @code{hi_1:lo_1:hi_2:lo_2}. | |
21393 | The @code{__builtin_byte_in_range} function returns a | |
21394 | non-zero value if and only if its @code{u} argument is within the | |
21395 | range bounded between @code{lo_2} and @code{hi_2} inclusive. | |
21396 | The @code{__builtin_byte_in_either_range} function returns non-zero if | |
21397 | and only if its @code{u} argument is within either the range bounded | |
21398 | between @code{lo_1} and @code{hi_1} inclusive or the range bounded | |
21399 | between @code{lo_2} and @code{hi_2} inclusive. | |
21400 | ||
21401 | The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value | |
21402 | if and only if the number of signficant digits of its @code{value} argument | |
21403 | is less than its @code{comparison} argument. The | |
21404 | @code{__builtin_dfp_dtstsfi_lt_dd} and | |
21405 | @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but | |
21406 | require that the type of the @code{value} argument be | |
21407 | @code{__Decimal64} and @code{__Decimal128} respectively. | |
21408 | ||
21409 | The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value | |
21410 | if and only if the number of signficant digits of its @code{value} argument | |
21411 | is greater than its @code{comparison} argument. The | |
21412 | @code{__builtin_dfp_dtstsfi_gt_dd} and | |
21413 | @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but | |
21414 | require that the type of the @code{value} argument be | |
21415 | @code{__Decimal64} and @code{__Decimal128} respectively. | |
21416 | ||
21417 | The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value | |
21418 | if and only if the number of signficant digits of its @code{value} argument | |
21419 | equals its @code{comparison} argument. The | |
21420 | @code{__builtin_dfp_dtstsfi_eq_dd} and | |
21421 | @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but | |
21422 | require that the type of the @code{value} argument be | |
21423 | @code{__Decimal64} and @code{__Decimal128} respectively. | |
21424 | ||
21425 | The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value | |
21426 | if and only if its @code{value} argument has an undefined number of | |
21427 | significant digits, such as when @code{value} is an encoding of @code{NaN}. | |
21428 | The @code{__builtin_dfp_dtstsfi_ov_dd} and | |
21429 | @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but | |
21430 | require that the type of the @code{value} argument be | |
21431 | @code{__Decimal64} and @code{__Decimal128} respectively. | |
21432 | ||
21433 | The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read | |
21434 | the FPSCR. The instruction is a lower latency version of the @code{mffs} | |
21435 | instruction. If the @code{mffsl} instruction is not available, then the | |
21436 | builtin uses the older @code{mffs} instruction to read the FPSCR. | |
21437 | ||
21438 | @node Basic PowerPC Built-in Functions Available on ISA 3.1 | |
21439 | @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1 | |
21440 | ||
21441 | The basic built-in functions described in this section are | |
21442 | available on the PowerPC family of processors starting with ISA 3.1. | |
21443 | Unless specific options are explicitly disabled on the | |
21444 | command line, specifying option @option{-mcpu=power10} has the effect of | |
21445 | enabling all the same options as for @option{-mcpu=power9}. | |
21446 | ||
21447 | The following built-in functions are available on Linux 64-bit systems | |
21448 | that use a future architecture instruction set (@option{-mcpu=power10}): | |
21449 | ||
f25efe50 AA |
21450 | @defbuiltin{{unsigned long long} @ |
21451 | __builtin_cfuged (unsigned long long, unsigned long long)} | |
d77de738 ML |
21452 | Perform a 64-bit centrifuge operation, as if implemented by the |
21453 | @code{cfuged} instruction. | |
f25efe50 | 21454 | @enddefbuiltin |
d77de738 | 21455 | |
f25efe50 AA |
21456 | @defbuiltin{{unsigned long long} @ |
21457 | __builtin_cntlzdm (unsigned long long, unsigned long long)} | |
d77de738 ML |
21458 | Perform a 64-bit count leading zeros operation under mask, as if |
21459 | implemented by the @code{cntlzdm} instruction. | |
f25efe50 | 21460 | @enddefbuiltin |
d77de738 | 21461 | |
f25efe50 AA |
21462 | @defbuiltin{{unsigned long long} @ |
21463 | __builtin_cnttzdm (unsigned long long, unsigned long long)} | |
d77de738 ML |
21464 | Perform a 64-bit count trailing zeros operation under mask, as if |
21465 | implemented by the @code{cnttzdm} instruction. | |
f25efe50 | 21466 | @enddefbuiltin |
d77de738 | 21467 | |
f25efe50 AA |
21468 | @defbuiltin{{unsigned long long} @ |
21469 | __builtin_pdepd (unsigned long long, unsigned long long)} | |
d77de738 ML |
21470 | Perform a 64-bit parallel bits deposit operation, as if implemented by the |
21471 | @code{pdepd} instruction. | |
f25efe50 | 21472 | @enddefbuiltin |
d77de738 | 21473 | |
f25efe50 AA |
21474 | @defbuiltin{{unsigned long long} @ |
21475 | __builtin_pextd (unsigned long long, unsigned long long)} | |
d77de738 ML |
21476 | Perform a 64-bit parallel bits extract operation, as if implemented by the |
21477 | @code{pextd} instruction. | |
f25efe50 | 21478 | @enddefbuiltin |
d77de738 | 21479 | |
f25efe50 AA |
21480 | @defbuiltin{{vector signed __int128} vsx_xl_sext (signed long long, signed char *)} |
21481 | @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed short *)} | |
21482 | @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed int *)} | |
21483 | @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed long long *)} | |
21484 | @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned char *)} | |
21485 | @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned short *)} | |
21486 | @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned int *)} | |
21487 | @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned long long *)} | |
d77de738 ML |
21488 | |
21489 | Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1 | |
f25efe50 AA |
21490 | @code{lxvrbx}, @code{lxvrhx}, @code{lxvrwx}, and @code{lxvrdx} |
21491 | instructions. | |
21492 | @enddefbuiltin | |
d77de738 | 21493 | |
f25efe50 AA |
21494 | @defbuiltin{{void} vec_xst_trunc (vector signed __int128, signed long long, signed char *)} |
21495 | @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed short *)} | |
21496 | @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed int *)} | |
21497 | @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed long long *)} | |
21498 | @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *)} | |
21499 | @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *)} | |
21500 | @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *)} | |
21501 | @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *)} | |
d77de738 ML |
21502 | |
21503 | Truncate and store the rightmost element of a vector, as if implemented by the | |
21504 | ISA 3.1 @code{stxvrbx}, @code{stxvrhx}, @code{stxvrwx}, and @code{stxvrdx} | |
21505 | instructions. | |
f25efe50 | 21506 | @enddefbuiltin |
d77de738 ML |
21507 | |
21508 | @node PowerPC AltiVec/VSX Built-in Functions | |
21509 | @subsection PowerPC AltiVec/VSX Built-in Functions | |
21510 | ||
21511 | GCC provides an interface for the PowerPC family of processors to access | |
21512 | the AltiVec operations described in Motorola's AltiVec Programming | |
21513 | Interface Manual. The interface is made available by including | |
21514 | @code{<altivec.h>} and using @option{-maltivec} and | |
21515 | @option{-mabi=altivec}. The interface supports the following vector | |
21516 | types. | |
21517 | ||
21518 | @smallexample | |
21519 | vector unsigned char | |
21520 | vector signed char | |
21521 | vector bool char | |
21522 | ||
21523 | vector unsigned short | |
21524 | vector signed short | |
21525 | vector bool short | |
21526 | vector pixel | |
21527 | ||
21528 | vector unsigned int | |
21529 | vector signed int | |
21530 | vector bool int | |
21531 | vector float | |
21532 | @end smallexample | |
21533 | ||
21534 | GCC's implementation of the high-level language interface available from | |
21535 | C and C++ code differs from Motorola's documentation in several ways. | |
21536 | ||
21537 | @itemize @bullet | |
21538 | ||
21539 | @item | |
21540 | A vector constant is a list of constant expressions within curly braces. | |
21541 | ||
21542 | @item | |
21543 | A vector initializer requires no cast if the vector constant is of the | |
21544 | same type as the variable it is initializing. | |
21545 | ||
21546 | @item | |
21547 | If @code{signed} or @code{unsigned} is omitted, the signedness of the | |
21548 | vector type is the default signedness of the base type. The default | |
21549 | varies depending on the operating system, so a portable program should | |
21550 | always specify the signedness. | |
21551 | ||
21552 | @item | |
21553 | Compiling with @option{-maltivec} adds keywords @code{__vector}, | |
21554 | @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and | |
21555 | @code{bool}. When compiling ISO C, the context-sensitive substitution | |
21556 | of the keywords @code{vector}, @code{pixel} and @code{bool} is | |
21557 | disabled. To use them, you must include @code{<altivec.h>} instead. | |
21558 | ||
21559 | @item | |
21560 | GCC allows using a @code{typedef} name as the type specifier for a | |
21561 | vector type, but only under the following circumstances: | |
21562 | ||
21563 | @itemize @bullet | |
21564 | ||
21565 | @item | |
21566 | When using @code{__vector} instead of @code{vector}; for example, | |
21567 | ||
21568 | @smallexample | |
21569 | typedef signed short int16; | |
21570 | __vector int16 data; | |
21571 | @end smallexample | |
21572 | ||
21573 | @item | |
21574 | When using @code{vector} in keyword-and-predefine mode; for example, | |
21575 | ||
21576 | @smallexample | |
21577 | typedef signed short int16; | |
21578 | vector int16 data; | |
21579 | @end smallexample | |
21580 | ||
21581 | Note that keyword-and-predefine mode is enabled by disabling GNU | |
21582 | extensions (e.g., by using @code{-std=c11}) and including | |
21583 | @code{<altivec.h>}. | |
21584 | @end itemize | |
21585 | ||
21586 | @item | |
21587 | For C, overloaded functions are implemented with macros so the following | |
21588 | does not work: | |
21589 | ||
21590 | @smallexample | |
21591 | vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); | |
21592 | @end smallexample | |
21593 | ||
21594 | @noindent | |
21595 | Since @code{vec_add} is a macro, the vector constant in the example | |
21596 | is treated as four separate arguments. Wrap the entire argument in | |
21597 | parentheses for this to work. | |
21598 | @end itemize | |
21599 | ||
21600 | @emph{Note:} Only the @code{<altivec.h>} interface is supported. | |
21601 | Internally, GCC uses built-in functions to achieve the functionality in | |
21602 | the aforementioned header file, but they are not supported and are | |
21603 | subject to change without notice. | |
21604 | ||
21605 | GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR), | |
21606 | which may be found at | |
21607 | @uref{https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference}. | |
21608 | Chapter 4 of this document fully documents the vector API interfaces | |
21609 | that must be | |
21610 | provided by compliant compilers. Programmers should preferentially use | |
21611 | the interfaces described therein. However, historically GCC has provided | |
21612 | additional interfaces for access to vector instructions. These are | |
21613 | briefly described below. Where the PVIPR provides a portable interface, | |
21614 | other functions in GCC that provide the same capabilities should be | |
21615 | considered deprecated. | |
21616 | ||
21617 | The PVIPR documents the following overloaded functions: | |
21618 | ||
21619 | @multitable @columnfractions 0.33 0.33 0.33 | |
21620 | ||
21621 | @item @code{vec_abs} | |
21622 | @tab @code{vec_absd} | |
21623 | @tab @code{vec_abss} | |
21624 | @item @code{vec_add} | |
21625 | @tab @code{vec_addc} | |
21626 | @tab @code{vec_adde} | |
21627 | @item @code{vec_addec} | |
21628 | @tab @code{vec_adds} | |
21629 | @tab @code{vec_all_eq} | |
21630 | @item @code{vec_all_ge} | |
21631 | @tab @code{vec_all_gt} | |
21632 | @tab @code{vec_all_in} | |
21633 | @item @code{vec_all_le} | |
21634 | @tab @code{vec_all_lt} | |
21635 | @tab @code{vec_all_nan} | |
21636 | @item @code{vec_all_ne} | |
21637 | @tab @code{vec_all_nge} | |
21638 | @tab @code{vec_all_ngt} | |
21639 | @item @code{vec_all_nle} | |
21640 | @tab @code{vec_all_nlt} | |
21641 | @tab @code{vec_all_numeric} | |
21642 | @item @code{vec_and} | |
21643 | @tab @code{vec_andc} | |
21644 | @tab @code{vec_any_eq} | |
21645 | @item @code{vec_any_ge} | |
21646 | @tab @code{vec_any_gt} | |
21647 | @tab @code{vec_any_le} | |
21648 | @item @code{vec_any_lt} | |
21649 | @tab @code{vec_any_nan} | |
21650 | @tab @code{vec_any_ne} | |
21651 | @item @code{vec_any_nge} | |
21652 | @tab @code{vec_any_ngt} | |
21653 | @tab @code{vec_any_nle} | |
21654 | @item @code{vec_any_nlt} | |
21655 | @tab @code{vec_any_numeric} | |
21656 | @tab @code{vec_any_out} | |
21657 | @item @code{vec_avg} | |
21658 | @tab @code{vec_bperm} | |
21659 | @tab @code{vec_ceil} | |
21660 | @item @code{vec_cipher_be} | |
21661 | @tab @code{vec_cipherlast_be} | |
21662 | @tab @code{vec_cmpb} | |
21663 | @item @code{vec_cmpeq} | |
21664 | @tab @code{vec_cmpge} | |
21665 | @tab @code{vec_cmpgt} | |
21666 | @item @code{vec_cmple} | |
21667 | @tab @code{vec_cmplt} | |
21668 | @tab @code{vec_cmpne} | |
21669 | @item @code{vec_cmpnez} | |
21670 | @tab @code{vec_cntlz} | |
21671 | @tab @code{vec_cntlz_lsbb} | |
21672 | @item @code{vec_cnttz} | |
21673 | @tab @code{vec_cnttz_lsbb} | |
21674 | @tab @code{vec_cpsgn} | |
21675 | @item @code{vec_ctf} | |
21676 | @tab @code{vec_cts} | |
21677 | @tab @code{vec_ctu} | |
21678 | @item @code{vec_div} | |
21679 | @tab @code{vec_double} | |
21680 | @tab @code{vec_doublee} | |
21681 | @item @code{vec_doubleh} | |
21682 | @tab @code{vec_doublel} | |
21683 | @tab @code{vec_doubleo} | |
21684 | @item @code{vec_eqv} | |
21685 | @tab @code{vec_expte} | |
21686 | @tab @code{vec_extract} | |
21687 | @item @code{vec_extract_exp} | |
21688 | @tab @code{vec_extract_fp32_from_shorth} | |
21689 | @tab @code{vec_extract_fp32_from_shortl} | |
21690 | @item @code{vec_extract_sig} | |
21691 | @tab @code{vec_extract_4b} | |
21692 | @tab @code{vec_first_match_index} | |
21693 | @item @code{vec_first_match_or_eos_index} | |
21694 | @tab @code{vec_first_mismatch_index} | |
21695 | @tab @code{vec_first_mismatch_or_eos_index} | |
21696 | @item @code{vec_float} | |
21697 | @tab @code{vec_float2} | |
21698 | @tab @code{vec_floate} | |
21699 | @item @code{vec_floato} | |
21700 | @tab @code{vec_floor} | |
21701 | @tab @code{vec_gb} | |
21702 | @item @code{vec_insert} | |
21703 | @tab @code{vec_insert_exp} | |
21704 | @tab @code{vec_insert4b} | |
21705 | @item @code{vec_ld} | |
21706 | @tab @code{vec_lde} | |
21707 | @tab @code{vec_ldl} | |
21708 | @item @code{vec_loge} | |
21709 | @tab @code{vec_madd} | |
21710 | @tab @code{vec_madds} | |
21711 | @item @code{vec_max} | |
21712 | @tab @code{vec_mergee} | |
21713 | @tab @code{vec_mergeh} | |
21714 | @item @code{vec_mergel} | |
21715 | @tab @code{vec_mergeo} | |
21716 | @tab @code{vec_mfvscr} | |
21717 | @item @code{vec_min} | |
21718 | @tab @code{vec_mradds} | |
21719 | @tab @code{vec_msub} | |
21720 | @item @code{vec_msum} | |
21721 | @tab @code{vec_msums} | |
21722 | @tab @code{vec_mtvscr} | |
21723 | @item @code{vec_mul} | |
21724 | @tab @code{vec_mule} | |
21725 | @tab @code{vec_mulo} | |
21726 | @item @code{vec_nabs} | |
21727 | @tab @code{vec_nand} | |
21728 | @tab @code{vec_ncipher_be} | |
21729 | @item @code{vec_ncipherlast_be} | |
21730 | @tab @code{vec_nearbyint} | |
21731 | @tab @code{vec_neg} | |
21732 | @item @code{vec_nmadd} | |
21733 | @tab @code{vec_nmsub} | |
21734 | @tab @code{vec_nor} | |
21735 | @item @code{vec_or} | |
21736 | @tab @code{vec_orc} | |
21737 | @tab @code{vec_pack} | |
21738 | @item @code{vec_pack_to_short_fp32} | |
21739 | @tab @code{vec_packpx} | |
21740 | @tab @code{vec_packs} | |
21741 | @item @code{vec_packsu} | |
21742 | @tab @code{vec_parity_lsbb} | |
21743 | @tab @code{vec_perm} | |
21744 | @item @code{vec_permxor} | |
21745 | @tab @code{vec_pmsum_be} | |
21746 | @tab @code{vec_popcnt} | |
21747 | @item @code{vec_re} | |
21748 | @tab @code{vec_recipdiv} | |
21749 | @tab @code{vec_revb} | |
21750 | @item @code{vec_reve} | |
21751 | @tab @code{vec_rint} | |
21752 | @tab @code{vec_rl} | |
21753 | @item @code{vec_rlmi} | |
21754 | @tab @code{vec_rlnm} | |
21755 | @tab @code{vec_round} | |
21756 | @item @code{vec_rsqrt} | |
21757 | @tab @code{vec_rsqrte} | |
21758 | @tab @code{vec_sbox_be} | |
21759 | @item @code{vec_sel} | |
21760 | @tab @code{vec_shasigma_be} | |
21761 | @tab @code{vec_signed} | |
21762 | @item @code{vec_signed2} | |
21763 | @tab @code{vec_signede} | |
21764 | @tab @code{vec_signedo} | |
21765 | @item @code{vec_sl} | |
21766 | @tab @code{vec_sld} | |
21767 | @tab @code{vec_sldw} | |
21768 | @item @code{vec_sll} | |
21769 | @tab @code{vec_slo} | |
21770 | @tab @code{vec_slv} | |
21771 | @item @code{vec_splat} | |
21772 | @tab @code{vec_splat_s8} | |
21773 | @tab @code{vec_splat_s16} | |
21774 | @item @code{vec_splat_s32} | |
21775 | @tab @code{vec_splat_u8} | |
21776 | @tab @code{vec_splat_u16} | |
21777 | @item @code{vec_splat_u32} | |
21778 | @tab @code{vec_splats} | |
21779 | @tab @code{vec_sqrt} | |
21780 | @item @code{vec_sr} | |
21781 | @tab @code{vec_sra} | |
21782 | @tab @code{vec_srl} | |
21783 | @item @code{vec_sro} | |
21784 | @tab @code{vec_srv} | |
21785 | @tab @code{vec_st} | |
21786 | @item @code{vec_ste} | |
21787 | @tab @code{vec_stl} | |
21788 | @tab @code{vec_sub} | |
21789 | @item @code{vec_subc} | |
21790 | @tab @code{vec_sube} | |
21791 | @tab @code{vec_subec} | |
21792 | @item @code{vec_subs} | |
21793 | @tab @code{vec_sum2s} | |
21794 | @tab @code{vec_sum4s} | |
21795 | @item @code{vec_sums} | |
21796 | @tab @code{vec_test_data_class} | |
21797 | @tab @code{vec_trunc} | |
21798 | @item @code{vec_unpackh} | |
21799 | @tab @code{vec_unpackl} | |
21800 | @tab @code{vec_unsigned} | |
21801 | @item @code{vec_unsigned2} | |
21802 | @tab @code{vec_unsignede} | |
21803 | @tab @code{vec_unsignedo} | |
21804 | @item @code{vec_xl} | |
21805 | @tab @code{vec_xl_be} | |
21806 | @tab @code{vec_xl_len} | |
21807 | @item @code{vec_xl_len_r} | |
21808 | @tab @code{vec_xor} | |
21809 | @tab @code{vec_xst} | |
21810 | @item @code{vec_xst_be} | |
21811 | @tab @code{vec_xst_len} | |
21812 | @tab @code{vec_xst_len_r} | |
21813 | ||
21814 | @end multitable | |
21815 | ||
21816 | @menu | |
21817 | * PowerPC AltiVec Built-in Functions on ISA 2.05:: | |
21818 | * PowerPC AltiVec Built-in Functions Available on ISA 2.06:: | |
21819 | * PowerPC AltiVec Built-in Functions Available on ISA 2.07:: | |
21820 | * PowerPC AltiVec Built-in Functions Available on ISA 3.0:: | |
21821 | * PowerPC AltiVec Built-in Functions Available on ISA 3.1:: | |
21822 | @end menu | |
21823 | ||
21824 | @node PowerPC AltiVec Built-in Functions on ISA 2.05 | |
21825 | @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05 | |
21826 | ||
21827 | The following interfaces are supported for the generic and specific | |
21828 | AltiVec operations and the AltiVec predicates. In cases where there | |
21829 | is a direct mapping between generic and specific operations, only the | |
21830 | generic names are shown here, although the specific operations can also | |
21831 | be used. | |
21832 | ||
21833 | Arguments that are documented as @code{const int} require literal | |
21834 | integral values within the range required for that operation. | |
21835 | ||
21836 | Only functions excluded from the PVIPR are listed here. | |
21837 | ||
21838 | @smallexample | |
21839 | void vec_dss (const int); | |
21840 | ||
21841 | void vec_dssall (void); | |
21842 | ||
21843 | void vec_dst (const vector unsigned char *, int, const int); | |
21844 | void vec_dst (const vector signed char *, int, const int); | |
21845 | void vec_dst (const vector bool char *, int, const int); | |
21846 | void vec_dst (const vector unsigned short *, int, const int); | |
21847 | void vec_dst (const vector signed short *, int, const int); | |
21848 | void vec_dst (const vector bool short *, int, const int); | |
21849 | void vec_dst (const vector pixel *, int, const int); | |
21850 | void vec_dst (const vector unsigned int *, int, const int); | |
21851 | void vec_dst (const vector signed int *, int, const int); | |
21852 | void vec_dst (const vector bool int *, int, const int); | |
21853 | void vec_dst (const vector float *, int, const int); | |
21854 | void vec_dst (const unsigned char *, int, const int); | |
21855 | void vec_dst (const signed char *, int, const int); | |
21856 | void vec_dst (const unsigned short *, int, const int); | |
21857 | void vec_dst (const short *, int, const int); | |
21858 | void vec_dst (const unsigned int *, int, const int); | |
21859 | void vec_dst (const int *, int, const int); | |
21860 | void vec_dst (const float *, int, const int); | |
21861 | ||
21862 | void vec_dstst (const vector unsigned char *, int, const int); | |
21863 | void vec_dstst (const vector signed char *, int, const int); | |
21864 | void vec_dstst (const vector bool char *, int, const int); | |
21865 | void vec_dstst (const vector unsigned short *, int, const int); | |
21866 | void vec_dstst (const vector signed short *, int, const int); | |
21867 | void vec_dstst (const vector bool short *, int, const int); | |
21868 | void vec_dstst (const vector pixel *, int, const int); | |
21869 | void vec_dstst (const vector unsigned int *, int, const int); | |
21870 | void vec_dstst (const vector signed int *, int, const int); | |
21871 | void vec_dstst (const vector bool int *, int, const int); | |
21872 | void vec_dstst (const vector float *, int, const int); | |
21873 | void vec_dstst (const unsigned char *, int, const int); | |
21874 | void vec_dstst (const signed char *, int, const int); | |
21875 | void vec_dstst (const unsigned short *, int, const int); | |
21876 | void vec_dstst (const short *, int, const int); | |
21877 | void vec_dstst (const unsigned int *, int, const int); | |
21878 | void vec_dstst (const int *, int, const int); | |
21879 | void vec_dstst (const unsigned long *, int, const int); | |
21880 | void vec_dstst (const long *, int, const int); | |
21881 | void vec_dstst (const float *, int, const int); | |
21882 | ||
21883 | void vec_dststt (const vector unsigned char *, int, const int); | |
21884 | void vec_dststt (const vector signed char *, int, const int); | |
21885 | void vec_dststt (const vector bool char *, int, const int); | |
21886 | void vec_dststt (const vector unsigned short *, int, const int); | |
21887 | void vec_dststt (const vector signed short *, int, const int); | |
21888 | void vec_dststt (const vector bool short *, int, const int); | |
21889 | void vec_dststt (const vector pixel *, int, const int); | |
21890 | void vec_dststt (const vector unsigned int *, int, const int); | |
21891 | void vec_dststt (const vector signed int *, int, const int); | |
21892 | void vec_dststt (const vector bool int *, int, const int); | |
21893 | void vec_dststt (const vector float *, int, const int); | |
21894 | void vec_dststt (const unsigned char *, int, const int); | |
21895 | void vec_dststt (const signed char *, int, const int); | |
21896 | void vec_dststt (const unsigned short *, int, const int); | |
21897 | void vec_dststt (const short *, int, const int); | |
21898 | void vec_dststt (const unsigned int *, int, const int); | |
21899 | void vec_dststt (const int *, int, const int); | |
21900 | void vec_dststt (const float *, int, const int); | |
21901 | ||
21902 | void vec_dstt (const vector unsigned char *, int, const int); | |
21903 | void vec_dstt (const vector signed char *, int, const int); | |
21904 | void vec_dstt (const vector bool char *, int, const int); | |
21905 | void vec_dstt (const vector unsigned short *, int, const int); | |
21906 | void vec_dstt (const vector signed short *, int, const int); | |
21907 | void vec_dstt (const vector bool short *, int, const int); | |
21908 | void vec_dstt (const vector pixel *, int, const int); | |
21909 | void vec_dstt (const vector unsigned int *, int, const int); | |
21910 | void vec_dstt (const vector signed int *, int, const int); | |
21911 | void vec_dstt (const vector bool int *, int, const int); | |
21912 | void vec_dstt (const vector float *, int, const int); | |
21913 | void vec_dstt (const unsigned char *, int, const int); | |
21914 | void vec_dstt (const signed char *, int, const int); | |
21915 | void vec_dstt (const unsigned short *, int, const int); | |
21916 | void vec_dstt (const short *, int, const int); | |
21917 | void vec_dstt (const unsigned int *, int, const int); | |
21918 | void vec_dstt (const int *, int, const int); | |
21919 | void vec_dstt (const float *, int, const int); | |
21920 | ||
21921 | vector signed char vec_lvebx (int, char *); | |
21922 | vector unsigned char vec_lvebx (int, unsigned char *); | |
21923 | ||
21924 | vector signed short vec_lvehx (int, short *); | |
21925 | vector unsigned short vec_lvehx (int, unsigned short *); | |
21926 | ||
21927 | vector float vec_lvewx (int, float *); | |
21928 | vector signed int vec_lvewx (int, int *); | |
21929 | vector unsigned int vec_lvewx (int, unsigned int *); | |
21930 | ||
21931 | vector unsigned char vec_lvsl (int, const unsigned char *); | |
21932 | vector unsigned char vec_lvsl (int, const signed char *); | |
21933 | vector unsigned char vec_lvsl (int, const unsigned short *); | |
21934 | vector unsigned char vec_lvsl (int, const short *); | |
21935 | vector unsigned char vec_lvsl (int, const unsigned int *); | |
21936 | vector unsigned char vec_lvsl (int, const int *); | |
21937 | vector unsigned char vec_lvsl (int, const float *); | |
21938 | ||
21939 | vector unsigned char vec_lvsr (int, const unsigned char *); | |
21940 | vector unsigned char vec_lvsr (int, const signed char *); | |
21941 | vector unsigned char vec_lvsr (int, const unsigned short *); | |
21942 | vector unsigned char vec_lvsr (int, const short *); | |
21943 | vector unsigned char vec_lvsr (int, const unsigned int *); | |
21944 | vector unsigned char vec_lvsr (int, const int *); | |
21945 | vector unsigned char vec_lvsr (int, const float *); | |
21946 | ||
21947 | void vec_stvebx (vector signed char, int, signed char *); | |
21948 | void vec_stvebx (vector unsigned char, int, unsigned char *); | |
21949 | void vec_stvebx (vector bool char, int, signed char *); | |
21950 | void vec_stvebx (vector bool char, int, unsigned char *); | |
21951 | ||
21952 | void vec_stvehx (vector signed short, int, short *); | |
21953 | void vec_stvehx (vector unsigned short, int, unsigned short *); | |
21954 | void vec_stvehx (vector bool short, int, short *); | |
21955 | void vec_stvehx (vector bool short, int, unsigned short *); | |
21956 | ||
21957 | void vec_stvewx (vector float, int, float *); | |
21958 | void vec_stvewx (vector signed int, int, int *); | |
21959 | void vec_stvewx (vector unsigned int, int, unsigned int *); | |
21960 | void vec_stvewx (vector bool int, int, int *); | |
21961 | void vec_stvewx (vector bool int, int, unsigned int *); | |
21962 | ||
21963 | vector float vec_vaddfp (vector float, vector float); | |
21964 | ||
21965 | vector signed char vec_vaddsbs (vector bool char, vector signed char); | |
21966 | vector signed char vec_vaddsbs (vector signed char, vector bool char); | |
21967 | vector signed char vec_vaddsbs (vector signed char, vector signed char); | |
21968 | ||
21969 | vector signed short vec_vaddshs (vector bool short, vector signed short); | |
21970 | vector signed short vec_vaddshs (vector signed short, vector bool short); | |
21971 | vector signed short vec_vaddshs (vector signed short, vector signed short); | |
21972 | ||
21973 | vector signed int vec_vaddsws (vector bool int, vector signed int); | |
21974 | vector signed int vec_vaddsws (vector signed int, vector bool int); | |
21975 | vector signed int vec_vaddsws (vector signed int, vector signed int); | |
21976 | ||
21977 | vector signed char vec_vaddubm (vector bool char, vector signed char); | |
21978 | vector signed char vec_vaddubm (vector signed char, vector bool char); | |
21979 | vector signed char vec_vaddubm (vector signed char, vector signed char); | |
21980 | vector unsigned char vec_vaddubm (vector bool char, vector unsigned char); | |
21981 | vector unsigned char vec_vaddubm (vector unsigned char, vector bool char); | |
21982 | vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char); | |
21983 | ||
21984 | vector unsigned char vec_vaddubs (vector bool char, vector unsigned char); | |
21985 | vector unsigned char vec_vaddubs (vector unsigned char, vector bool char); | |
21986 | vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char); | |
21987 | ||
21988 | vector signed short vec_vadduhm (vector bool short, vector signed short); | |
21989 | vector signed short vec_vadduhm (vector signed short, vector bool short); | |
21990 | vector signed short vec_vadduhm (vector signed short, vector signed short); | |
21991 | vector unsigned short vec_vadduhm (vector bool short, vector unsigned short); | |
21992 | vector unsigned short vec_vadduhm (vector unsigned short, vector bool short); | |
21993 | vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short); | |
21994 | ||
21995 | vector unsigned short vec_vadduhs (vector bool short, vector unsigned short); | |
21996 | vector unsigned short vec_vadduhs (vector unsigned short, vector bool short); | |
21997 | vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short); | |
21998 | ||
21999 | vector signed int vec_vadduwm (vector bool int, vector signed int); | |
22000 | vector signed int vec_vadduwm (vector signed int, vector bool int); | |
22001 | vector signed int vec_vadduwm (vector signed int, vector signed int); | |
22002 | vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); | |
22003 | vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); | |
22004 | vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int); | |
22005 | ||
22006 | vector unsigned int vec_vadduws (vector bool int, vector unsigned int); | |
22007 | vector unsigned int vec_vadduws (vector unsigned int, vector bool int); | |
22008 | vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int); | |
22009 | ||
22010 | vector signed char vec_vavgsb (vector signed char, vector signed char); | |
22011 | ||
22012 | vector signed short vec_vavgsh (vector signed short, vector signed short); | |
22013 | ||
22014 | vector signed int vec_vavgsw (vector signed int, vector signed int); | |
22015 | ||
22016 | vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char); | |
22017 | ||
22018 | vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short); | |
22019 | ||
22020 | vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int); | |
22021 | ||
22022 | vector float vec_vcfsx (vector signed int, const int); | |
22023 | ||
22024 | vector float vec_vcfux (vector unsigned int, const int); | |
22025 | ||
22026 | vector bool int vec_vcmpeqfp (vector float, vector float); | |
22027 | ||
22028 | vector bool char vec_vcmpequb (vector signed char, vector signed char); | |
22029 | vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char); | |
22030 | ||
22031 | vector bool short vec_vcmpequh (vector signed short, vector signed short); | |
22032 | vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short); | |
22033 | ||
22034 | vector bool int vec_vcmpequw (vector signed int, vector signed int); | |
22035 | vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); | |
22036 | ||
22037 | vector bool int vec_vcmpgtfp (vector float, vector float); | |
22038 | ||
22039 | vector bool char vec_vcmpgtsb (vector signed char, vector signed char); | |
22040 | ||
22041 | vector bool short vec_vcmpgtsh (vector signed short, vector signed short); | |
22042 | ||
22043 | vector bool int vec_vcmpgtsw (vector signed int, vector signed int); | |
22044 | ||
22045 | vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char); | |
22046 | ||
22047 | vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short); | |
22048 | ||
22049 | vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); | |
22050 | ||
22051 | vector float vec_vmaxfp (vector float, vector float); | |
22052 | ||
22053 | vector signed char vec_vmaxsb (vector bool char, vector signed char); | |
22054 | vector signed char vec_vmaxsb (vector signed char, vector bool char); | |
22055 | vector signed char vec_vmaxsb (vector signed char, vector signed char); | |
22056 | ||
22057 | vector signed short vec_vmaxsh (vector bool short, vector signed short); | |
22058 | vector signed short vec_vmaxsh (vector signed short, vector bool short); | |
22059 | vector signed short vec_vmaxsh (vector signed short, vector signed short); | |
22060 | ||
22061 | vector signed int vec_vmaxsw (vector bool int, vector signed int); | |
22062 | vector signed int vec_vmaxsw (vector signed int, vector bool int); | |
22063 | vector signed int vec_vmaxsw (vector signed int, vector signed int); | |
22064 | ||
22065 | vector unsigned char vec_vmaxub (vector bool char, vector unsigned char); | |
22066 | vector unsigned char vec_vmaxub (vector unsigned char, vector bool char); | |
22067 | vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char); | |
22068 | ||
22069 | vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short); | |
22070 | vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short); | |
22071 | vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short); | |
22072 | ||
22073 | vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); | |
22074 | vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); | |
22075 | vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int); | |
22076 | ||
22077 | vector float vec_vminfp (vector float, vector float); | |
22078 | ||
22079 | vector signed char vec_vminsb (vector bool char, vector signed char); | |
22080 | vector signed char vec_vminsb (vector signed char, vector bool char); | |
22081 | vector signed char vec_vminsb (vector signed char, vector signed char); | |
22082 | ||
22083 | vector signed short vec_vminsh (vector bool short, vector signed short); | |
22084 | vector signed short vec_vminsh (vector signed short, vector bool short); | |
22085 | vector signed short vec_vminsh (vector signed short, vector signed short); | |
22086 | ||
22087 | vector signed int vec_vminsw (vector bool int, vector signed int); | |
22088 | vector signed int vec_vminsw (vector signed int, vector bool int); | |
22089 | vector signed int vec_vminsw (vector signed int, vector signed int); | |
22090 | ||
22091 | vector unsigned char vec_vminub (vector bool char, vector unsigned char); | |
22092 | vector unsigned char vec_vminub (vector unsigned char, vector bool char); | |
22093 | vector unsigned char vec_vminub (vector unsigned char, vector unsigned char); | |
22094 | ||
22095 | vector unsigned short vec_vminuh (vector bool short, vector unsigned short); | |
22096 | vector unsigned short vec_vminuh (vector unsigned short, vector bool short); | |
22097 | vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short); | |
22098 | ||
22099 | vector unsigned int vec_vminuw (vector bool int, vector unsigned int); | |
22100 | vector unsigned int vec_vminuw (vector unsigned int, vector bool int); | |
22101 | vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int); | |
22102 | ||
22103 | vector bool char vec_vmrghb (vector bool char, vector bool char); | |
22104 | vector signed char vec_vmrghb (vector signed char, vector signed char); | |
22105 | vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char); | |
22106 | ||
22107 | vector bool short vec_vmrghh (vector bool short, vector bool short); | |
22108 | vector signed short vec_vmrghh (vector signed short, vector signed short); | |
22109 | vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short); | |
22110 | vector pixel vec_vmrghh (vector pixel, vector pixel); | |
22111 | ||
22112 | vector float vec_vmrghw (vector float, vector float); | |
22113 | vector bool int vec_vmrghw (vector bool int, vector bool int); | |
22114 | vector signed int vec_vmrghw (vector signed int, vector signed int); | |
22115 | vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int); | |
22116 | ||
22117 | vector bool char vec_vmrglb (vector bool char, vector bool char); | |
22118 | vector signed char vec_vmrglb (vector signed char, vector signed char); | |
22119 | vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char); | |
22120 | ||
22121 | vector bool short vec_vmrglh (vector bool short, vector bool short); | |
22122 | vector signed short vec_vmrglh (vector signed short, vector signed short); | |
22123 | vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short); | |
22124 | vector pixel vec_vmrglh (vector pixel, vector pixel); | |
22125 | ||
22126 | vector float vec_vmrglw (vector float, vector float); | |
22127 | vector signed int vec_vmrglw (vector signed int, vector signed int); | |
22128 | vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int); | |
22129 | vector bool int vec_vmrglw (vector bool int, vector bool int); | |
22130 | ||
22131 | vector signed int vec_vmsummbm (vector signed char, vector unsigned char, | |
22132 | vector signed int); | |
22133 | ||
22134 | vector signed int vec_vmsumshm (vector signed short, vector signed short, | |
22135 | vector signed int); | |
22136 | ||
22137 | vector signed int vec_vmsumshs (vector signed short, vector signed short, | |
22138 | vector signed int); | |
22139 | ||
22140 | vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char, | |
22141 | vector unsigned int); | |
22142 | ||
22143 | vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short, | |
22144 | vector unsigned int); | |
22145 | ||
22146 | vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short, | |
22147 | vector unsigned int); | |
22148 | ||
22149 | vector signed short vec_vmulesb (vector signed char, vector signed char); | |
22150 | ||
22151 | vector signed int vec_vmulesh (vector signed short, vector signed short); | |
22152 | ||
22153 | vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char); | |
22154 | ||
22155 | vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short); | |
22156 | ||
22157 | vector signed short vec_vmulosb (vector signed char, vector signed char); | |
22158 | ||
22159 | vector signed int vec_vmulosh (vector signed short, vector signed short); | |
22160 | ||
22161 | vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char); | |
22162 | ||
22163 | vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short); | |
22164 | ||
22165 | vector signed char vec_vpkshss (vector signed short, vector signed short); | |
22166 | ||
22167 | vector unsigned char vec_vpkshus (vector signed short, vector signed short); | |
22168 | ||
22169 | vector signed short vec_vpkswss (vector signed int, vector signed int); | |
22170 | ||
22171 | vector unsigned short vec_vpkswus (vector signed int, vector signed int); | |
22172 | ||
22173 | vector bool char vec_vpkuhum (vector bool short, vector bool short); | |
22174 | vector signed char vec_vpkuhum (vector signed short, vector signed short); | |
22175 | vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short); | |
22176 | ||
22177 | vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short); | |
22178 | ||
22179 | vector bool short vec_vpkuwum (vector bool int, vector bool int); | |
22180 | vector signed short vec_vpkuwum (vector signed int, vector signed int); | |
22181 | vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int); | |
22182 | ||
22183 | vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int); | |
22184 | ||
22185 | vector signed char vec_vrlb (vector signed char, vector unsigned char); | |
22186 | vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char); | |
22187 | ||
22188 | vector signed short vec_vrlh (vector signed short, vector unsigned short); | |
22189 | vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short); | |
22190 | ||
22191 | vector signed int vec_vrlw (vector signed int, vector unsigned int); | |
22192 | vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); | |
22193 | ||
22194 | vector signed char vec_vslb (vector signed char, vector unsigned char); | |
22195 | vector unsigned char vec_vslb (vector unsigned char, vector unsigned char); | |
22196 | ||
22197 | vector signed short vec_vslh (vector signed short, vector unsigned short); | |
22198 | vector unsigned short vec_vslh (vector unsigned short, vector unsigned short); | |
22199 | ||
22200 | vector signed int vec_vslw (vector signed int, vector unsigned int); | |
22201 | vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); | |
22202 | ||
22203 | vector signed char vec_vspltb (vector signed char, const int); | |
22204 | vector unsigned char vec_vspltb (vector unsigned char, const int); | |
22205 | vector bool char vec_vspltb (vector bool char, const int); | |
22206 | ||
22207 | vector bool short vec_vsplth (vector bool short, const int); | |
22208 | vector signed short vec_vsplth (vector signed short, const int); | |
22209 | vector unsigned short vec_vsplth (vector unsigned short, const int); | |
22210 | vector pixel vec_vsplth (vector pixel, const int); | |
22211 | ||
22212 | vector float vec_vspltw (vector float, const int); | |
22213 | vector signed int vec_vspltw (vector signed int, const int); | |
22214 | vector unsigned int vec_vspltw (vector unsigned int, const int); | |
22215 | vector bool int vec_vspltw (vector bool int, const int); | |
22216 | ||
22217 | vector signed char vec_vsrab (vector signed char, vector unsigned char); | |
22218 | vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char); | |
22219 | ||
22220 | vector signed short vec_vsrah (vector signed short, vector unsigned short); | |
22221 | vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short); | |
22222 | ||
22223 | vector signed int vec_vsraw (vector signed int, vector unsigned int); | |
22224 | vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int); | |
22225 | ||
22226 | vector signed char vec_vsrb (vector signed char, vector unsigned char); | |
22227 | vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char); | |
22228 | ||
22229 | vector signed short vec_vsrh (vector signed short, vector unsigned short); | |
22230 | vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short); | |
22231 | ||
22232 | vector signed int vec_vsrw (vector signed int, vector unsigned int); | |
22233 | vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); | |
22234 | ||
22235 | vector float vec_vsubfp (vector float, vector float); | |
22236 | ||
22237 | vector signed char vec_vsubsbs (vector bool char, vector signed char); | |
22238 | vector signed char vec_vsubsbs (vector signed char, vector bool char); | |
22239 | vector signed char vec_vsubsbs (vector signed char, vector signed char); | |
22240 | ||
22241 | vector signed short vec_vsubshs (vector bool short, vector signed short); | |
22242 | vector signed short vec_vsubshs (vector signed short, vector bool short); | |
22243 | vector signed short vec_vsubshs (vector signed short, vector signed short); | |
22244 | ||
22245 | vector signed int vec_vsubsws (vector bool int, vector signed int); | |
22246 | vector signed int vec_vsubsws (vector signed int, vector bool int); | |
22247 | vector signed int vec_vsubsws (vector signed int, vector signed int); | |
22248 | ||
22249 | vector signed char vec_vsububm (vector bool char, vector signed char); | |
22250 | vector signed char vec_vsububm (vector signed char, vector bool char); | |
22251 | vector signed char vec_vsububm (vector signed char, vector signed char); | |
22252 | vector unsigned char vec_vsububm (vector bool char, vector unsigned char); | |
22253 | vector unsigned char vec_vsububm (vector unsigned char, vector bool char); | |
22254 | vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char); | |
22255 | ||
22256 | vector unsigned char vec_vsububs (vector bool char, vector unsigned char); | |
22257 | vector unsigned char vec_vsububs (vector unsigned char, vector bool char); | |
22258 | vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char); | |
22259 | ||
22260 | vector signed short vec_vsubuhm (vector bool short, vector signed short); | |
22261 | vector signed short vec_vsubuhm (vector signed short, vector bool short); | |
22262 | vector signed short vec_vsubuhm (vector signed short, vector signed short); | |
22263 | vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short); | |
22264 | vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short); | |
22265 | vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short); | |
22266 | ||
22267 | vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short); | |
22268 | vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short); | |
22269 | vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short); | |
22270 | ||
22271 | vector signed int vec_vsubuwm (vector bool int, vector signed int); | |
22272 | vector signed int vec_vsubuwm (vector signed int, vector bool int); | |
22273 | vector signed int vec_vsubuwm (vector signed int, vector signed int); | |
22274 | vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); | |
22275 | vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); | |
22276 | vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int); | |
22277 | ||
22278 | vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); | |
22279 | vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); | |
22280 | vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int); | |
22281 | ||
22282 | vector signed int vec_vsum4sbs (vector signed char, vector signed int); | |
22283 | ||
22284 | vector signed int vec_vsum4shs (vector signed short, vector signed int); | |
22285 | ||
22286 | vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int); | |
22287 | ||
22288 | vector unsigned int vec_vupkhpx (vector pixel); | |
22289 | ||
22290 | vector bool short vec_vupkhsb (vector bool char); | |
22291 | vector signed short vec_vupkhsb (vector signed char); | |
22292 | ||
22293 | vector bool int vec_vupkhsh (vector bool short); | |
22294 | vector signed int vec_vupkhsh (vector signed short); | |
22295 | ||
22296 | vector unsigned int vec_vupklpx (vector pixel); | |
22297 | ||
22298 | vector bool short vec_vupklsb (vector bool char); | |
22299 | vector signed short vec_vupklsb (vector signed char); | |
22300 | ||
22301 | vector bool int vec_vupklsh (vector bool short); | |
22302 | vector signed int vec_vupklsh (vector signed short); | |
22303 | @end smallexample | |
22304 | ||
22305 | @node PowerPC AltiVec Built-in Functions Available on ISA 2.06 | |
22306 | @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06 | |
22307 | ||
22308 | The AltiVec built-in functions described in this section are | |
22309 | available on the PowerPC family of processors starting with ISA 2.06 | |
22310 | or later. These are normally enabled by adding @option{-mvsx} to the | |
22311 | command line. | |
22312 | ||
22313 | When @option{-mvsx} is used, the following additional vector types are | |
22314 | implemented. | |
22315 | ||
22316 | @smallexample | |
22317 | vector unsigned __int128 | |
22318 | vector signed __int128 | |
22319 | vector unsigned long long int | |
22320 | vector signed long long int | |
22321 | vector double | |
22322 | @end smallexample | |
22323 | ||
22324 | The long long types are only implemented for 64-bit code generation. | |
22325 | ||
22326 | Only functions excluded from the PVIPR are listed here. | |
22327 | ||
22328 | @smallexample | |
22329 | void vec_dst (const unsigned long *, int, const int); | |
22330 | void vec_dst (const long *, int, const int); | |
22331 | ||
22332 | void vec_dststt (const unsigned long *, int, const int); | |
22333 | void vec_dststt (const long *, int, const int); | |
22334 | ||
22335 | void vec_dstt (const unsigned long *, int, const int); | |
22336 | void vec_dstt (const long *, int, const int); | |
22337 | ||
22338 | vector unsigned char vec_lvsl (int, const unsigned long *); | |
22339 | vector unsigned char vec_lvsl (int, const long *); | |
22340 | ||
22341 | vector unsigned char vec_lvsr (int, const unsigned long *); | |
22342 | vector unsigned char vec_lvsr (int, const long *); | |
22343 | ||
22344 | vector unsigned char vec_lvsl (int, const double *); | |
22345 | vector unsigned char vec_lvsr (int, const double *); | |
22346 | ||
22347 | vector double vec_vsx_ld (int, const vector double *); | |
22348 | vector double vec_vsx_ld (int, const double *); | |
22349 | vector float vec_vsx_ld (int, const vector float *); | |
22350 | vector float vec_vsx_ld (int, const float *); | |
22351 | vector bool int vec_vsx_ld (int, const vector bool int *); | |
22352 | vector signed int vec_vsx_ld (int, const vector signed int *); | |
22353 | vector signed int vec_vsx_ld (int, const int *); | |
22354 | vector signed int vec_vsx_ld (int, const long *); | |
22355 | vector unsigned int vec_vsx_ld (int, const vector unsigned int *); | |
22356 | vector unsigned int vec_vsx_ld (int, const unsigned int *); | |
22357 | vector unsigned int vec_vsx_ld (int, const unsigned long *); | |
22358 | vector bool short vec_vsx_ld (int, const vector bool short *); | |
22359 | vector pixel vec_vsx_ld (int, const vector pixel *); | |
22360 | vector signed short vec_vsx_ld (int, const vector signed short *); | |
22361 | vector signed short vec_vsx_ld (int, const short *); | |
22362 | vector unsigned short vec_vsx_ld (int, const vector unsigned short *); | |
22363 | vector unsigned short vec_vsx_ld (int, const unsigned short *); | |
22364 | vector bool char vec_vsx_ld (int, const vector bool char *); | |
22365 | vector signed char vec_vsx_ld (int, const vector signed char *); | |
22366 | vector signed char vec_vsx_ld (int, const signed char *); | |
22367 | vector unsigned char vec_vsx_ld (int, const vector unsigned char *); | |
22368 | vector unsigned char vec_vsx_ld (int, const unsigned char *); | |
22369 | ||
22370 | void vec_vsx_st (vector double, int, vector double *); | |
22371 | void vec_vsx_st (vector double, int, double *); | |
22372 | void vec_vsx_st (vector float, int, vector float *); | |
22373 | void vec_vsx_st (vector float, int, float *); | |
22374 | void vec_vsx_st (vector signed int, int, vector signed int *); | |
22375 | void vec_vsx_st (vector signed int, int, int *); | |
22376 | void vec_vsx_st (vector unsigned int, int, vector unsigned int *); | |
22377 | void vec_vsx_st (vector unsigned int, int, unsigned int *); | |
22378 | void vec_vsx_st (vector bool int, int, vector bool int *); | |
22379 | void vec_vsx_st (vector bool int, int, unsigned int *); | |
22380 | void vec_vsx_st (vector bool int, int, int *); | |
22381 | void vec_vsx_st (vector signed short, int, vector signed short *); | |
22382 | void vec_vsx_st (vector signed short, int, short *); | |
22383 | void vec_vsx_st (vector unsigned short, int, vector unsigned short *); | |
22384 | void vec_vsx_st (vector unsigned short, int, unsigned short *); | |
22385 | void vec_vsx_st (vector bool short, int, vector bool short *); | |
22386 | void vec_vsx_st (vector bool short, int, unsigned short *); | |
22387 | void vec_vsx_st (vector pixel, int, vector pixel *); | |
22388 | void vec_vsx_st (vector pixel, int, unsigned short *); | |
22389 | void vec_vsx_st (vector pixel, int, short *); | |
22390 | void vec_vsx_st (vector bool short, int, short *); | |
22391 | void vec_vsx_st (vector signed char, int, vector signed char *); | |
22392 | void vec_vsx_st (vector signed char, int, signed char *); | |
22393 | void vec_vsx_st (vector unsigned char, int, vector unsigned char *); | |
22394 | void vec_vsx_st (vector unsigned char, int, unsigned char *); | |
22395 | void vec_vsx_st (vector bool char, int, vector bool char *); | |
22396 | void vec_vsx_st (vector bool char, int, unsigned char *); | |
22397 | void vec_vsx_st (vector bool char, int, signed char *); | |
22398 | ||
22399 | vector double vec_xxpermdi (vector double, vector double, const int); | |
22400 | vector float vec_xxpermdi (vector float, vector float, const int); | |
22401 | vector long long vec_xxpermdi (vector long long, vector long long, const int); | |
22402 | vector unsigned long long vec_xxpermdi (vector unsigned long long, | |
22403 | vector unsigned long long, const int); | |
22404 | vector int vec_xxpermdi (vector int, vector int, const int); | |
22405 | vector unsigned int vec_xxpermdi (vector unsigned int, | |
22406 | vector unsigned int, const int); | |
22407 | vector short vec_xxpermdi (vector short, vector short, const int); | |
22408 | vector unsigned short vec_xxpermdi (vector unsigned short, | |
22409 | vector unsigned short, const int); | |
22410 | vector signed char vec_xxpermdi (vector signed char, vector signed char, | |
22411 | const int); | |
22412 | vector unsigned char vec_xxpermdi (vector unsigned char, | |
22413 | vector unsigned char, const int); | |
22414 | ||
22415 | vector double vec_xxsldi (vector double, vector double, int); | |
22416 | vector float vec_xxsldi (vector float, vector float, int); | |
22417 | vector long long vec_xxsldi (vector long long, vector long long, int); | |
22418 | vector unsigned long long vec_xxsldi (vector unsigned long long, | |
22419 | vector unsigned long long, int); | |
22420 | vector int vec_xxsldi (vector int, vector int, int); | |
22421 | vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int); | |
22422 | vector short vec_xxsldi (vector short, vector short, int); | |
22423 | vector unsigned short vec_xxsldi (vector unsigned short, | |
22424 | vector unsigned short, int); | |
22425 | vector signed char vec_xxsldi (vector signed char, vector signed char, int); | |
22426 | vector unsigned char vec_xxsldi (vector unsigned char, | |
22427 | vector unsigned char, int); | |
22428 | @end smallexample | |
22429 | ||
22430 | Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always | |
22431 | generate the AltiVec @samp{LVX} and @samp{STVX} instructions even | |
22432 | if the VSX instruction set is available. The @samp{vec_vsx_ld} and | |
22433 | @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X}, | |
22434 | @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. | |
22435 | ||
22436 | @node PowerPC AltiVec Built-in Functions Available on ISA 2.07 | |
22437 | @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07 | |
22438 | ||
22439 | If the ISA 2.07 additions to the vector/scalar (power8-vector) | |
22440 | instruction set are available, the following additional functions are | |
22441 | available for both 32-bit and 64-bit targets. For 64-bit targets, you | |
22442 | can use @var{vector long} instead of @var{vector long long}, | |
22443 | @var{vector bool long} instead of @var{vector bool long long}, and | |
22444 | @var{vector unsigned long} instead of @var{vector unsigned long long}. | |
22445 | ||
22446 | Only functions excluded from the PVIPR are listed here. | |
22447 | ||
22448 | @smallexample | |
22449 | vector long long vec_vaddudm (vector long long, vector long long); | |
22450 | vector long long vec_vaddudm (vector bool long long, vector long long); | |
22451 | vector long long vec_vaddudm (vector long long, vector bool long long); | |
22452 | vector unsigned long long vec_vaddudm (vector unsigned long long, | |
22453 | vector unsigned long long); | |
22454 | vector unsigned long long vec_vaddudm (vector bool unsigned long long, | |
22455 | vector unsigned long long); | |
22456 | vector unsigned long long vec_vaddudm (vector unsigned long long, | |
22457 | vector bool unsigned long long); | |
22458 | ||
22459 | vector long long vec_vclz (vector long long); | |
22460 | vector unsigned long long vec_vclz (vector unsigned long long); | |
22461 | vector int vec_vclz (vector int); | |
22462 | vector unsigned int vec_vclz (vector int); | |
22463 | vector short vec_vclz (vector short); | |
22464 | vector unsigned short vec_vclz (vector unsigned short); | |
22465 | vector signed char vec_vclz (vector signed char); | |
22466 | vector unsigned char vec_vclz (vector unsigned char); | |
22467 | ||
22468 | vector signed char vec_vclzb (vector signed char); | |
22469 | vector unsigned char vec_vclzb (vector unsigned char); | |
22470 | ||
22471 | vector long long vec_vclzd (vector long long); | |
22472 | vector unsigned long long vec_vclzd (vector unsigned long long); | |
22473 | ||
22474 | vector short vec_vclzh (vector short); | |
22475 | vector unsigned short vec_vclzh (vector unsigned short); | |
22476 | ||
22477 | vector int vec_vclzw (vector int); | |
22478 | vector unsigned int vec_vclzw (vector int); | |
22479 | ||
22480 | vector signed char vec_vgbbd (vector signed char); | |
22481 | vector unsigned char vec_vgbbd (vector unsigned char); | |
22482 | ||
22483 | vector long long vec_vmaxsd (vector long long, vector long long); | |
22484 | ||
22485 | vector unsigned long long vec_vmaxud (vector unsigned long long, | |
22486 | unsigned vector long long); | |
22487 | ||
22488 | vector long long vec_vminsd (vector long long, vector long long); | |
22489 | ||
22490 | vector unsigned long long vec_vminud (vector long long, vector long long); | |
22491 | ||
22492 | vector int vec_vpksdss (vector long long, vector long long); | |
22493 | vector unsigned int vec_vpksdss (vector long long, vector long long); | |
22494 | ||
22495 | vector unsigned int vec_vpkudus (vector unsigned long long, | |
22496 | vector unsigned long long); | |
22497 | ||
22498 | vector int vec_vpkudum (vector long long, vector long long); | |
22499 | vector unsigned int vec_vpkudum (vector unsigned long long, | |
22500 | vector unsigned long long); | |
22501 | vector bool int vec_vpkudum (vector bool long long, vector bool long long); | |
22502 | ||
22503 | vector long long vec_vpopcnt (vector long long); | |
22504 | vector unsigned long long vec_vpopcnt (vector unsigned long long); | |
22505 | vector int vec_vpopcnt (vector int); | |
22506 | vector unsigned int vec_vpopcnt (vector int); | |
22507 | vector short vec_vpopcnt (vector short); | |
22508 | vector unsigned short vec_vpopcnt (vector unsigned short); | |
22509 | vector signed char vec_vpopcnt (vector signed char); | |
22510 | vector unsigned char vec_vpopcnt (vector unsigned char); | |
22511 | ||
22512 | vector signed char vec_vpopcntb (vector signed char); | |
22513 | vector unsigned char vec_vpopcntb (vector unsigned char); | |
22514 | ||
22515 | vector long long vec_vpopcntd (vector long long); | |
22516 | vector unsigned long long vec_vpopcntd (vector unsigned long long); | |
22517 | ||
22518 | vector short vec_vpopcnth (vector short); | |
22519 | vector unsigned short vec_vpopcnth (vector unsigned short); | |
22520 | ||
22521 | vector int vec_vpopcntw (vector int); | |
22522 | vector unsigned int vec_vpopcntw (vector int); | |
22523 | ||
22524 | vector long long vec_vrld (vector long long, vector unsigned long long); | |
22525 | vector unsigned long long vec_vrld (vector unsigned long long, | |
22526 | vector unsigned long long); | |
22527 | ||
22528 | vector long long vec_vsld (vector long long, vector unsigned long long); | |
22529 | vector long long vec_vsld (vector unsigned long long, | |
22530 | vector unsigned long long); | |
22531 | ||
22532 | vector long long vec_vsrad (vector long long, vector unsigned long long); | |
22533 | vector unsigned long long vec_vsrad (vector unsigned long long, | |
22534 | vector unsigned long long); | |
22535 | ||
22536 | vector long long vec_vsrd (vector long long, vector unsigned long long); | |
22537 | vector unsigned long long char vec_vsrd (vector unsigned long long, | |
22538 | vector unsigned long long); | |
22539 | ||
22540 | vector long long vec_vsubudm (vector long long, vector long long); | |
22541 | vector long long vec_vsubudm (vector bool long long, vector long long); | |
22542 | vector long long vec_vsubudm (vector long long, vector bool long long); | |
22543 | vector unsigned long long vec_vsubudm (vector unsigned long long, | |
22544 | vector unsigned long long); | |
22545 | vector unsigned long long vec_vsubudm (vector bool long long, | |
22546 | vector unsigned long long); | |
22547 | vector unsigned long long vec_vsubudm (vector unsigned long long, | |
22548 | vector bool long long); | |
22549 | ||
22550 | vector long long vec_vupkhsw (vector int); | |
22551 | vector unsigned long long vec_vupkhsw (vector unsigned int); | |
22552 | ||
22553 | vector long long vec_vupklsw (vector int); | |
22554 | vector unsigned long long vec_vupklsw (vector int); | |
22555 | @end smallexample | |
22556 | ||
22557 | If the ISA 2.07 additions to the vector/scalar (power8-vector) | |
22558 | instruction set are available, the following additional functions are | |
22559 | available for 64-bit targets. New vector types | |
22560 | (@var{vector __int128} and @var{vector __uint128}) are available | |
22561 | to hold the @var{__int128} and @var{__uint128} types to use these | |
22562 | builtins. | |
22563 | ||
22564 | The normal vector extract, and set operations work on | |
22565 | @var{vector __int128} and @var{vector __uint128} types, | |
22566 | but the index value must be 0. | |
22567 | ||
22568 | Only functions excluded from the PVIPR are listed here. | |
22569 | ||
22570 | @smallexample | |
22571 | vector __int128 vec_vaddcuq (vector __int128, vector __int128); | |
22572 | vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128); | |
22573 | ||
22574 | vector __int128 vec_vadduqm (vector __int128, vector __int128); | |
22575 | vector __uint128 vec_vadduqm (vector __uint128, vector __uint128); | |
22576 | ||
22577 | vector __int128 vec_vaddecuq (vector __int128, vector __int128, | |
22578 | vector __int128); | |
22579 | vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128, | |
22580 | vector __uint128); | |
22581 | ||
22582 | vector __int128 vec_vaddeuqm (vector __int128, vector __int128, | |
22583 | vector __int128); | |
22584 | vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128, | |
22585 | vector __uint128); | |
22586 | ||
22587 | vector __int128 vec_vsubecuq (vector __int128, vector __int128, | |
22588 | vector __int128); | |
22589 | vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128, | |
22590 | vector __uint128); | |
22591 | ||
22592 | vector __int128 vec_vsubeuqm (vector __int128, vector __int128, | |
22593 | vector __int128); | |
22594 | vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128, | |
22595 | vector __uint128); | |
22596 | ||
22597 | vector __int128 vec_vsubcuq (vector __int128, vector __int128); | |
22598 | vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128); | |
22599 | ||
22600 | __int128 vec_vsubuqm (__int128, __int128); | |
22601 | __uint128 vec_vsubuqm (__uint128, __uint128); | |
22602 | ||
22603 | vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int); | |
22604 | vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char, | |
22605 | const int); | |
22606 | int __builtin_bcdadd_lt (vector __int128, vector __int128, const int); | |
22607 | int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int); | |
22608 | int __builtin_bcdadd_eq (vector __int128, vector __int128, const int); | |
22609 | int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int); | |
22610 | int __builtin_bcdadd_gt (vector __int128, vector __int128, const int); | |
22611 | int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int); | |
22612 | int __builtin_bcdadd_ov (vector __int128, vector __int128, const int); | |
22613 | int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int); | |
22614 | ||
22615 | vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int); | |
22616 | vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char, | |
22617 | const int); | |
c82f123d CL |
22618 | int __builtin_bcdsub_le (vector __int128, vector __int128, const int); |
22619 | int __builtin_bcdsub_le (vector unsigned char, vector unsigned char, const int); | |
d77de738 ML |
22620 | int __builtin_bcdsub_lt (vector __int128, vector __int128, const int); |
22621 | int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int); | |
22622 | int __builtin_bcdsub_eq (vector __int128, vector __int128, const int); | |
22623 | int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int); | |
22624 | int __builtin_bcdsub_gt (vector __int128, vector __int128, const int); | |
22625 | int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int); | |
c82f123d CL |
22626 | int __builtin_bcdsub_ge (vector __int128, vector __int128, const int); |
22627 | int __builtin_bcdsub_ge (vector unsigned char, vector unsigned char, const int); | |
d77de738 ML |
22628 | int __builtin_bcdsub_ov (vector __int128, vector __int128, const int); |
22629 | int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int); | |
22630 | @end smallexample | |
22631 | ||
22632 | @node PowerPC AltiVec Built-in Functions Available on ISA 3.0 | |
22633 | @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0 | |
22634 | ||
22635 | The following additional built-in functions are also available for the | |
22636 | PowerPC family of processors, starting with ISA 3.0 | |
22637 | (@option{-mcpu=power9}) or later. | |
22638 | ||
22639 | Only instructions excluded from the PVIPR are listed here. | |
22640 | ||
22641 | @smallexample | |
22642 | unsigned int scalar_extract_exp (double source); | |
22643 | unsigned long long int scalar_extract_exp (__ieee128 source); | |
22644 | ||
22645 | unsigned long long int scalar_extract_sig (double source); | |
22646 | unsigned __int128 scalar_extract_sig (__ieee128 source); | |
22647 | ||
22648 | double scalar_insert_exp (unsigned long long int significand, | |
22649 | unsigned long long int exponent); | |
22650 | double scalar_insert_exp (double significand, unsigned long long int exponent); | |
22651 | ||
22652 | ieee_128 scalar_insert_exp (unsigned __int128 significand, | |
22653 | unsigned long long int exponent); | |
22654 | ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent); | |
86df278d CL |
22655 | vector ieee_128 scalar_insert_exp (vector unsigned __int128 significand, |
22656 | vector unsigned long long exponent); | |
22657 | vector unsigned long long scalar_extract_exp_to_vec (ieee_128); | |
22658 | vector unsigned __int128 scalar_extract_sig_to_vec (ieee_128); | |
d77de738 ML |
22659 | |
22660 | int scalar_cmp_exp_gt (double arg1, double arg2); | |
22661 | int scalar_cmp_exp_lt (double arg1, double arg2); | |
22662 | int scalar_cmp_exp_eq (double arg1, double arg2); | |
22663 | int scalar_cmp_exp_unordered (double arg1, double arg2); | |
22664 | ||
22665 | bool scalar_test_data_class (float source, const int condition); | |
22666 | bool scalar_test_data_class (double source, const int condition); | |
22667 | bool scalar_test_data_class (__ieee128 source, const int condition); | |
22668 | ||
22669 | bool scalar_test_neg (float source); | |
22670 | bool scalar_test_neg (double source); | |
22671 | bool scalar_test_neg (__ieee128 source); | |
22672 | @end smallexample | |
22673 | ||
e25dc59d HG |
22674 | The @code{scalar_extract_exp} with a 64-bit source argument |
22675 | function requires an environment supporting ISA 3.0 or later. | |
22676 | The @code{scalar_extract_exp} with a 128-bit source argument | |
22677 | and @code{scalar_extract_sig} | |
d77de738 ML |
22678 | functions require a 64-bit environment supporting ISA 3.0 or later. |
22679 | The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in | |
22680 | functions return the significand and the biased exponent value | |
22681 | respectively of their @code{source} arguments. | |
22682 | When supplied with a 64-bit @code{source} argument, the | |
22683 | result returned by @code{scalar_extract_sig} has | |
22684 | the @code{0x0010000000000000} bit set if the | |
22685 | function's @code{source} argument is in normalized form. | |
22686 | Otherwise, this bit is set to 0. | |
22687 | When supplied with a 128-bit @code{source} argument, the | |
22688 | @code{0x00010000000000000000000000000000} bit of the result is | |
22689 | treated similarly. | |
22690 | Note that the sign of the significand is not represented in the result | |
22691 | returned from the @code{scalar_extract_sig} function. Use the | |
22692 | @code{scalar_test_neg} function to test the sign of its @code{double} | |
22693 | argument. | |
22694 | ||
22695 | The @code{scalar_insert_exp} | |
22696 | functions require a 64-bit environment supporting ISA 3.0 or later. | |
22697 | When supplied with a 64-bit first argument, the | |
22698 | @code{scalar_insert_exp} built-in function returns a double-precision | |
22699 | floating point value that is constructed by assembling the values of its | |
22700 | @code{significand} and @code{exponent} arguments. The sign of the | |
22701 | result is copied from the most significant bit of the | |
22702 | @code{significand} argument. The significand and exponent components | |
22703 | of the result are composed of the least significant 11 bits of the | |
22704 | @code{exponent} argument and the least significant 52 bits of the | |
22705 | @code{significand} argument respectively. | |
22706 | ||
22707 | When supplied with a 128-bit first argument, the | |
22708 | @code{scalar_insert_exp} built-in function returns a quad-precision | |
86df278d CL |
22709 | IEEE floating point value if the two arguments were scalar. If the two |
22710 | arguments are vectors, the return value is a vector IEEE floating point value. | |
22711 | The sign bit of the result is copied from the most significant bit of the | |
22712 | @code{significand} argument. The significand and exponent components of the | |
22713 | result are composed of the least significant 15 bits of the @code{exponent} | |
22714 | argument (element 0 on big-endian and element 1 on little-endian) and the | |
22715 | least significant 112 bits of the @code{significand} argument | |
22716 | respectively. Note, the @code{significand} is the scalar argument or in the | |
22717 | case of vector arguments, @code{significand} is element 0 for big-endian and | |
22718 | element 1 for little-endian. | |
22719 | ||
22720 | The @code{scalar_extract_exp_to_vec}, | |
22721 | and @code{scalar_extract_sig_to_vec} are similar to | |
22722 | @code{scalar_extract_exp}, @code{scalar_extract_sig} except they return | |
22723 | a vector result of type unsigned long long and unsigned __int128 respectively. | |
d77de738 ML |
22724 | |
22725 | The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt}, | |
22726 | @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in | |
22727 | functions return a non-zero value if @code{arg1} is greater than, less | |
22728 | than, equal to, or not comparable to @code{arg2} respectively. The | |
22729 | arguments are not comparable if one or the other equals NaN (not a | |
22730 | number). | |
22731 | ||
22732 | The @code{scalar_test_data_class} built-in function returns 1 | |
22733 | if any of the condition tests enabled by the value of the | |
22734 | @code{condition} variable are true, and 0 otherwise. The | |
22735 | @code{condition} argument must be a compile-time constant integer with | |
22736 | value not exceeding 127. The | |
22737 | @code{condition} argument is encoded as a bitmask with each bit | |
22738 | enabling the testing of a different condition, as characterized by the | |
22739 | following: | |
22740 | @smallexample | |
22741 | 0x40 Test for NaN | |
22742 | 0x20 Test for +Infinity | |
22743 | 0x10 Test for -Infinity | |
22744 | 0x08 Test for +Zero | |
22745 | 0x04 Test for -Zero | |
22746 | 0x02 Test for +Denormal | |
22747 | 0x01 Test for -Denormal | |
22748 | @end smallexample | |
22749 | ||
22750 | The @code{scalar_test_neg} built-in function returns 1 if its | |
22751 | @code{source} argument holds a negative value, 0 otherwise. | |
22752 | ||
22753 | The following built-in functions are also available for the PowerPC family | |
22754 | of processors, starting with ISA 3.0 or later | |
22755 | (@option{-mcpu=power9}). These string functions are described | |
22756 | separately in order to group the descriptions closer to the function | |
22757 | prototypes. | |
22758 | ||
22759 | Only functions excluded from the PVIPR are listed here. | |
22760 | ||
22761 | @smallexample | |
22762 | int vec_all_nez (vector signed char, vector signed char); | |
22763 | int vec_all_nez (vector unsigned char, vector unsigned char); | |
22764 | int vec_all_nez (vector signed short, vector signed short); | |
22765 | int vec_all_nez (vector unsigned short, vector unsigned short); | |
22766 | int vec_all_nez (vector signed int, vector signed int); | |
22767 | int vec_all_nez (vector unsigned int, vector unsigned int); | |
22768 | ||
22769 | int vec_any_eqz (vector signed char, vector signed char); | |
22770 | int vec_any_eqz (vector unsigned char, vector unsigned char); | |
22771 | int vec_any_eqz (vector signed short, vector signed short); | |
22772 | int vec_any_eqz (vector unsigned short, vector unsigned short); | |
22773 | int vec_any_eqz (vector signed int, vector signed int); | |
22774 | int vec_any_eqz (vector unsigned int, vector unsigned int); | |
22775 | ||
22776 | signed char vec_xlx (unsigned int index, vector signed char data); | |
22777 | unsigned char vec_xlx (unsigned int index, vector unsigned char data); | |
22778 | signed short vec_xlx (unsigned int index, vector signed short data); | |
22779 | unsigned short vec_xlx (unsigned int index, vector unsigned short data); | |
22780 | signed int vec_xlx (unsigned int index, vector signed int data); | |
22781 | unsigned int vec_xlx (unsigned int index, vector unsigned int data); | |
22782 | float vec_xlx (unsigned int index, vector float data); | |
22783 | ||
22784 | signed char vec_xrx (unsigned int index, vector signed char data); | |
22785 | unsigned char vec_xrx (unsigned int index, vector unsigned char data); | |
22786 | signed short vec_xrx (unsigned int index, vector signed short data); | |
22787 | unsigned short vec_xrx (unsigned int index, vector unsigned short data); | |
22788 | signed int vec_xrx (unsigned int index, vector signed int data); | |
22789 | unsigned int vec_xrx (unsigned int index, vector unsigned int data); | |
22790 | float vec_xrx (unsigned int index, vector float data); | |
22791 | @end smallexample | |
22792 | ||
22793 | The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez} | |
22794 | perform pairwise comparisons between the elements at the same | |
22795 | positions within their two vector arguments. | |
22796 | The @code{vec_all_nez} function returns a | |
22797 | non-zero value if and only if all pairwise comparisons are not | |
22798 | equal and no element of either vector argument contains a zero. | |
22799 | The @code{vec_any_eqz} function returns a | |
22800 | non-zero value if and only if at least one pairwise comparison is equal | |
22801 | or if at least one element of either vector argument contains a zero. | |
22802 | The @code{vec_cmpnez} function returns a vector of the same type as | |
22803 | its two arguments, within which each element consists of all ones to | |
22804 | denote that either the corresponding elements of the incoming arguments are | |
22805 | not equal or that at least one of the corresponding elements contains | |
22806 | zero. Otherwise, the element of the returned vector contains all zeros. | |
22807 | ||
22808 | The @code{vec_xlx} and @code{vec_xrx} functions extract the single | |
22809 | element selected by the @code{index} argument from the vector | |
22810 | represented by the @code{data} argument. The @code{index} argument | |
22811 | always specifies a byte offset, regardless of the size of the vector | |
22812 | element. With @code{vec_xlx}, @code{index} is the offset of the first | |
22813 | byte of the element to be extracted. With @code{vec_xrx}, @code{index} | |
22814 | represents the last byte of the element to be extracted, measured | |
22815 | from the right end of the vector. In other words, the last byte of | |
22816 | the element to be extracted is found at position @code{(15 - index)}. | |
22817 | There is no requirement that @code{index} be a multiple of the vector | |
22818 | element size. However, if the size of the vector element added to | |
22819 | @code{index} is greater than 15, the content of the returned value is | |
22820 | undefined. | |
22821 | ||
22822 | The following functions are also available if the ISA 3.0 instruction | |
22823 | set additions (@option{-mcpu=power9}) are available. | |
22824 | ||
22825 | Only functions excluded from the PVIPR are listed here. | |
22826 | ||
22827 | @smallexample | |
22828 | vector long long vec_vctz (vector long long); | |
22829 | vector unsigned long long vec_vctz (vector unsigned long long); | |
22830 | vector int vec_vctz (vector int); | |
22831 | vector unsigned int vec_vctz (vector int); | |
22832 | vector short vec_vctz (vector short); | |
22833 | vector unsigned short vec_vctz (vector unsigned short); | |
22834 | vector signed char vec_vctz (vector signed char); | |
22835 | vector unsigned char vec_vctz (vector unsigned char); | |
22836 | ||
22837 | vector signed char vec_vctzb (vector signed char); | |
22838 | vector unsigned char vec_vctzb (vector unsigned char); | |
22839 | ||
22840 | vector long long vec_vctzd (vector long long); | |
22841 | vector unsigned long long vec_vctzd (vector unsigned long long); | |
22842 | ||
22843 | vector short vec_vctzh (vector short); | |
22844 | vector unsigned short vec_vctzh (vector unsigned short); | |
22845 | ||
22846 | vector int vec_vctzw (vector int); | |
22847 | vector unsigned int vec_vctzw (vector int); | |
22848 | ||
22849 | vector int vec_vprtyb (vector int); | |
22850 | vector unsigned int vec_vprtyb (vector unsigned int); | |
22851 | vector long long vec_vprtyb (vector long long); | |
22852 | vector unsigned long long vec_vprtyb (vector unsigned long long); | |
22853 | ||
22854 | vector int vec_vprtybw (vector int); | |
22855 | vector unsigned int vec_vprtybw (vector unsigned int); | |
22856 | ||
22857 | vector long long vec_vprtybd (vector long long); | |
22858 | vector unsigned long long vec_vprtybd (vector unsigned long long); | |
22859 | @end smallexample | |
22860 | ||
22861 | On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) | |
22862 | are available: | |
22863 | ||
22864 | @smallexample | |
22865 | vector long vec_vprtyb (vector long); | |
22866 | vector unsigned long vec_vprtyb (vector unsigned long); | |
22867 | vector __int128 vec_vprtyb (vector __int128); | |
22868 | vector __uint128 vec_vprtyb (vector __uint128); | |
22869 | ||
22870 | vector long vec_vprtybd (vector long); | |
22871 | vector unsigned long vec_vprtybd (vector unsigned long); | |
22872 | ||
22873 | vector __int128 vec_vprtybq (vector __int128); | |
22874 | vector __uint128 vec_vprtybd (vector __uint128); | |
22875 | @end smallexample | |
22876 | ||
22877 | The following built-in functions are available for the PowerPC family | |
22878 | of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}). | |
22879 | ||
22880 | Only functions excluded from the PVIPR are listed here. | |
22881 | ||
22882 | @smallexample | |
22883 | __vector unsigned char | |
22884 | vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2); | |
22885 | __vector unsigned short | |
22886 | vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2); | |
22887 | __vector unsigned int | |
22888 | vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2); | |
22889 | @end smallexample | |
22890 | ||
22891 | The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and | |
22892 | @code{vec_absdw} built-in functions each computes the absolute | |
22893 | differences of the pairs of vector elements supplied in its two vector | |
22894 | arguments, placing the absolute differences into the corresponding | |
22895 | elements of the vector result. | |
22896 | ||
22897 | The following built-in functions are available for the PowerPC family | |
22898 | of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): | |
22899 | @smallexample | |
22900 | vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int); | |
22901 | vector unsigned long long vec_vrlnm (vector unsigned long long, | |
22902 | vector unsigned long long); | |
22903 | @end smallexample | |
22904 | ||
22905 | The result of @code{vec_vrlnm} is obtained by rotating each element | |
22906 | of the first argument vector left and ANDing it with a mask. The | |
22907 | second argument vector contains the mask beginning in bits 11:15, | |
22908 | the mask end in bits 19:23, and the shift count in bits 27:31, | |
22909 | of each element. | |
22910 | ||
22911 | If the cryptographic instructions are enabled (@option{-mcrypto} or | |
22912 | @option{-mcpu=power8}), the following builtins are enabled. | |
22913 | ||
22914 | Only functions excluded from the PVIPR are listed here. | |
22915 | ||
22916 | @smallexample | |
22917 | vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long); | |
22918 | ||
22919 | vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long, | |
22920 | vector unsigned long long); | |
22921 | ||
22922 | vector unsigned long long __builtin_crypto_vcipherlast | |
22923 | (vector unsigned long long, | |
22924 | vector unsigned long long); | |
22925 | ||
22926 | vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long, | |
22927 | vector unsigned long long); | |
22928 | ||
22929 | vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long, | |
22930 | vector unsigned long long); | |
22931 | ||
22932 | vector unsigned char __builtin_crypto_vpermxor (vector unsigned char, | |
22933 | vector unsigned char, | |
22934 | vector unsigned char); | |
22935 | ||
22936 | vector unsigned short __builtin_crypto_vpermxor (vector unsigned short, | |
22937 | vector unsigned short, | |
22938 | vector unsigned short); | |
22939 | ||
22940 | vector unsigned int __builtin_crypto_vpermxor (vector unsigned int, | |
22941 | vector unsigned int, | |
22942 | vector unsigned int); | |
22943 | ||
22944 | vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long, | |
22945 | vector unsigned long long, | |
22946 | vector unsigned long long); | |
22947 | ||
22948 | vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char, | |
22949 | vector unsigned char); | |
22950 | ||
22951 | vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short, | |
22952 | vector unsigned short); | |
22953 | ||
22954 | vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int, | |
22955 | vector unsigned int); | |
22956 | ||
22957 | vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long, | |
22958 | vector unsigned long long); | |
22959 | ||
22960 | vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long, | |
22961 | int, int); | |
22962 | ||
22963 | vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int); | |
22964 | @end smallexample | |
22965 | ||
22966 | The second argument to @var{__builtin_crypto_vshasigmad} and | |
22967 | @var{__builtin_crypto_vshasigmaw} must be a constant | |
22968 | integer that is 0 or 1. The third argument to these built-in functions | |
22969 | must be a constant integer in the range of 0 to 15. | |
22970 | ||
22971 | The following sign extension builtins are provided: | |
22972 | ||
22973 | @smallexample | |
22974 | vector signed int vec_signexti (vector signed char a); | |
22975 | vector signed long long vec_signextll (vector signed char a); | |
22976 | vector signed int vec_signexti (vector signed short a); | |
22977 | vector signed long long vec_signextll (vector signed short a); | |
22978 | vector signed long long vec_signextll (vector signed int a); | |
22979 | vector signed long long vec_signextq (vector signed long long a); | |
22980 | @end smallexample | |
22981 | ||
22982 | Each element of the result is produced by sign-extending the element of the | |
22983 | input vector that would fall in the least significant portion of the result | |
22984 | element. For example, a sign-extension of a vector signed char to a vector | |
22985 | signed long long will sign extend the rightmost byte of each doubleword. | |
22986 | ||
22987 | @node PowerPC AltiVec Built-in Functions Available on ISA 3.1 | |
22988 | @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1 | |
22989 | ||
22990 | The following additional built-in functions are also available for the | |
22991 | PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}): | |
22992 | ||
22993 | ||
22994 | @smallexample | |
22995 | @exdent vector unsigned long long int | |
22996 | @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int); | |
22997 | @end smallexample | |
22998 | Perform a vector centrifuge operation, as if implemented by the | |
22999 | @code{vcfuged} instruction. | |
23000 | @findex vec_cfuge | |
23001 | ||
23002 | @smallexample | |
23003 | @exdent vector unsigned long long int | |
23004 | @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int); | |
23005 | @end smallexample | |
23006 | Perform a vector count leading zeros under bit mask operation, as if | |
23007 | implemented by the @code{vclzdm} instruction. | |
23008 | @findex vec_cntlzm | |
23009 | ||
23010 | @smallexample | |
23011 | @exdent vector unsigned long long int | |
23012 | @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int); | |
23013 | @end smallexample | |
23014 | Perform a vector count trailing zeros under bit mask operation, as if | |
23015 | implemented by the @code{vctzdm} instruction. | |
23016 | @findex vec_cnttzm | |
23017 | ||
23018 | @smallexample | |
23019 | @exdent vector signed char | |
23795106 | 23020 | @exdent vec_clrl (vector signed char @var{a}, unsigned int @var{n}); |
d77de738 | 23021 | @exdent vector unsigned char |
23795106 | 23022 | @exdent vec_clrl (vector unsigned char @var{a}, unsigned int @var{n}); |
d77de738 ML |
23023 | @end smallexample |
23024 | Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if | |
23025 | implemented by the @code{vclrlb} instruction on a big-endian target | |
23026 | and by the @code{vclrrb} instruction on a little-endian target. A | |
23027 | value of @code{n} that is greater than 16 is treated as if it equaled 16. | |
23028 | @findex vec_clrl | |
23029 | ||
23030 | @smallexample | |
23031 | @exdent vector signed char | |
23795106 | 23032 | @exdent vec_clrr (vector signed char @var{a}, unsigned int @var{n}); |
d77de738 | 23033 | @exdent vector unsigned char |
23795106 | 23034 | @exdent vec_clrr (vector unsigned char @var{a}, unsigned int @var{n}); |
d77de738 ML |
23035 | @end smallexample |
23036 | Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if | |
23037 | implemented by the @code{vclrrb} instruction on a big-endian target | |
23038 | and by the @code{vclrlb} instruction on a little-endian target. A | |
23039 | value of @code{n} that is greater than 16 is treated as if it equaled 16. | |
23040 | @findex vec_clrr | |
23041 | ||
23042 | @smallexample | |
23043 | @exdent vector unsigned long long int | |
23044 | @exdent vec_gnb (vector unsigned __int128, const unsigned char); | |
23045 | @end smallexample | |
23046 | Perform a 128-bit vector gather operation, as if implemented by the | |
23047 | @code{vgnb} instruction. The second argument must be a literal | |
23048 | integer value between 2 and 7 inclusive. | |
23049 | @findex vec_gnb | |
23050 | ||
23051 | ||
23052 | Vector Extract | |
23053 | ||
23054 | @smallexample | |
23055 | @exdent vector unsigned long long int | |
23056 | @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int); | |
23057 | @exdent vector unsigned long long int | |
23058 | @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int); | |
23059 | @exdent vector unsigned long long int | |
23060 | @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int); | |
23061 | @exdent vector unsigned long long int | |
23062 | @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int); | |
23063 | @end smallexample | |
23064 | Extract an element from two concatenated vectors starting at the given byte index | |
23065 | in natural-endian order, and place it zero-extended in doubleword 1 of the result | |
23066 | according to natural element order. If the byte index is out of range for the | |
23067 | data type, the intrinsic will be rejected. | |
23068 | For little-endian, this output will match the placement by the hardware | |
23069 | instruction, i.e., dword[0] in RTL notation. For big-endian, an additional | |
23070 | instruction is needed to move it from the "left" doubleword to the "right" one. | |
23071 | For little-endian, semantics matching the @code{vextdubvrx}, | |
23072 | @code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for | |
23073 | big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx}, | |
23074 | @code{vextduwvlx} instructions | |
23075 | will be generated. Note that some fairly anomalous results can be generated if | |
23076 | the byte index is not aligned on an element boundary for the element being | |
23077 | extracted. This is a limitation of the bi-endian vector programming model is | |
23078 | consistent with the limitation on @code{vec_perm}. | |
23079 | @findex vec_extractl | |
23080 | ||
23081 | @smallexample | |
23082 | @exdent vector unsigned long long int | |
23083 | @exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int); | |
23084 | @exdent vector unsigned long long int | |
23085 | @exdent vec_extracth (vector unsigned short, vector unsigned short, | |
23086 | unsigned int); | |
23087 | @exdent vector unsigned long long int | |
23088 | @exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int); | |
23089 | @exdent vector unsigned long long int | |
23090 | @exdent vec_extracth (vector unsigned long long, vector unsigned long long, | |
23091 | unsigned int); | |
23092 | @end smallexample | |
23093 | Extract an element from two concatenated vectors starting at the given byte | |
23094 | index. The index is based on big endian order for a little endian system. | |
23095 | Similarly, the index is based on little endian order for a big endian system. | |
23096 | The extraced elements are zero-extended and put in doubleword 1 | |
23097 | according to natural element order. If the byte index is out of range for the | |
23098 | data type, the intrinsic will be rejected. For little-endian, this output | |
23099 | will match the placement by the hardware instruction (vextdubvrx, vextduhvrx, | |
23100 | vextduwvrx, vextddvrx) i.e., dword[0] in RTL | |
23101 | notation. For big-endian, an additional instruction is needed to move it | |
23102 | from the "left" doubleword to the "right" one. For little-endian, semantics | |
23103 | matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx} | |
23104 | instructions will be generated, while for big-endian, semantics matching the | |
23105 | @code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will | |
23106 | be generated. Note that some fairly anomalous | |
23107 | results can be generated if the byte index is not aligned on the | |
23108 | element boundary for the element being extracted. This is a | |
23109 | limitation of the bi-endian vector programming model consistent with the | |
23110 | limitation on @code{vec_perm}. | |
23111 | @findex vec_extracth | |
23112 | @smallexample | |
23113 | @exdent vector unsigned long long int | |
23114 | @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int); | |
23115 | @end smallexample | |
23116 | Perform a vector parallel bits deposit operation, as if implemented by | |
23117 | the @code{vpdepd} instruction. | |
23118 | @findex vec_pdep | |
23119 | ||
23120 | Vector Insert | |
23121 | ||
23122 | @smallexample | |
23123 | @exdent vector unsigned char | |
23124 | @exdent vec_insertl (unsigned char, vector unsigned char, unsigned int); | |
23125 | @exdent vector unsigned short | |
23126 | @exdent vec_insertl (unsigned short, vector unsigned short, unsigned int); | |
23127 | @exdent vector unsigned int | |
23128 | @exdent vec_insertl (unsigned int, vector unsigned int, unsigned int); | |
23129 | @exdent vector unsigned long long | |
23130 | @exdent vec_insertl (unsigned long long, vector unsigned long long, | |
23131 | unsigned int); | |
23132 | @exdent vector unsigned char | |
23133 | @exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int; | |
23134 | @exdent vector unsigned short | |
23135 | @exdent vec_insertl (vector unsigned short, vector unsigned short, | |
23136 | unsigned int); | |
23137 | @exdent vector unsigned int | |
23138 | @exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int); | |
23139 | @end smallexample | |
23140 | ||
23141 | Let src be the first argument, when the first argument is a scalar, or the | |
23142 | rightmost element of the left doubleword of the first argument, when the first | |
23143 | argument is a vector. Insert the source into the destination at the position | |
23144 | given by the third argument, using natural element order in the second | |
23145 | argument. The rest of the second argument is unchanged. If the byte | |
23146 | index is greater than 14 for halfwords, greater than 12 for words, or | |
23147 | greater than 8 for doublewords the result is undefined. For little-endian, | |
23148 | the generated code will be semantically equivalent to @code{vins[bhwd]rx} | |
23149 | instructions. Similarly for big-endian it will be semantically equivalent | |
23150 | to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be | |
23151 | generated if the byte index is not aligned on an element boundary for the | |
23152 | type of element being inserted. | |
23153 | @findex vec_insertl | |
23154 | ||
23155 | @smallexample | |
23156 | @exdent vector unsigned char | |
23157 | @exdent vec_inserth (unsigned char, vector unsigned char, unsigned int); | |
23158 | @exdent vector unsigned short | |
23159 | @exdent vec_inserth (unsigned short, vector unsigned short, unsigned int); | |
23160 | @exdent vector unsigned int | |
23161 | @exdent vec_inserth (unsigned int, vector unsigned int, unsigned int); | |
23162 | @exdent vector unsigned long long | |
23163 | @exdent vec_inserth (unsigned long long, vector unsigned long long, | |
23164 | unsigned int); | |
23165 | @exdent vector unsigned char | |
23166 | @exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int); | |
23167 | @exdent vector unsigned short | |
23168 | @exdent vec_inserth (vector unsigned short, vector unsigned short, | |
23169 | unsigned int); | |
23170 | @exdent vector unsigned int | |
23171 | @exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int); | |
23172 | @end smallexample | |
23173 | ||
23174 | Let src be the first argument, when the first argument is a scalar, or the | |
23175 | rightmost element of the first argument, when the first argument is a vector. | |
23176 | Insert src into the second argument at the position identified by the third | |
23177 | argument, using opposite element order in the second argument, and leaving the | |
23178 | rest of the second argument unchanged. If the byte index is greater than 14 | |
23179 | for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be | |
23180 | rejected. Note that the underlying hardware instruction uses the same register | |
23181 | for the second argument and the result. | |
23182 | For little-endian, the code generation will be semantically equivalent to | |
23183 | @code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to | |
23184 | @code{vins[bhwd]rx}. | |
23185 | Note that some fairly anomalous results can be generated if the byte index is | |
23186 | not aligned on an element boundary for the sort of element being inserted. | |
23187 | @findex vec_inserth | |
23188 | ||
23189 | Vector Replace Element | |
23190 | @smallexample | |
23191 | @exdent vector signed int vec_replace_elt (vector signed int, signed int, | |
23192 | const int); | |
23193 | @exdent vector unsigned int vec_replace_elt (vector unsigned int, | |
23194 | unsigned int, const int); | |
23195 | @exdent vector float vec_replace_elt (vector float, float, const int); | |
23196 | @exdent vector signed long long vec_replace_elt (vector signed long long, | |
23197 | signed long long, const int); | |
23198 | @exdent vector unsigned long long vec_replace_elt (vector unsigned long long, | |
23199 | unsigned long long, const int); | |
23200 | @exdent vector double rec_replace_elt (vector double, double, const int); | |
23201 | @end smallexample | |
23202 | The third argument (constrained to [0,3]) identifies the natural-endian | |
23203 | element number of the first argument that will be replaced by the second | |
23204 | argument to produce the result. The other elements of the first argument will | |
23205 | remain unchanged in the result. | |
23206 | ||
23207 | If it's desirable to insert a word at an unaligned position, use | |
23208 | vec_replace_unaligned instead. | |
23209 | ||
23210 | @findex vec_replace_element | |
23211 | ||
23212 | Vector Replace Unaligned | |
23213 | @smallexample | |
23214 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
23215 | signed int, const int); | |
23216 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
23217 | unsigned int, const int); | |
23218 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
23219 | float, const int); | |
23220 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
23221 | signed long long, const int); | |
23222 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
23223 | unsigned long long, const int); | |
23224 | @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, | |
23225 | double, const int); | |
23226 | @end smallexample | |
23227 | ||
23228 | The second argument replaces a portion of the first argument to produce the | |
23229 | result, with the rest of the first argument unchanged in the result. The | |
23230 | third argument identifies the byte index (using left-to-right, or big-endian | |
23231 | order) where the high-order byte of the second argument will be placed, with | |
23232 | the remaining bytes of the second argument placed naturally "to the right" | |
23233 | of the high-order byte. | |
23234 | ||
23235 | The programmer is responsible for understanding the endianness issues involved | |
23236 | with the first argument and the result. | |
23237 | @findex vec_replace_unaligned | |
23238 | ||
23239 | Vector Shift Left Double Bit Immediate | |
23240 | @smallexample | |
23241 | @exdent vector signed char vec_sldb (vector signed char, vector signed char, | |
23242 | const unsigned int); | |
23243 | @exdent vector unsigned char vec_sldb (vector unsigned char, | |
23244 | vector unsigned char, const unsigned int); | |
23245 | @exdent vector signed short vec_sldb (vector signed short, vector signed short, | |
23246 | const unsigned int); | |
23247 | @exdent vector unsigned short vec_sldb (vector unsigned short, | |
23248 | vector unsigned short, const unsigned int); | |
23249 | @exdent vector signed int vec_sldb (vector signed int, vector signed int, | |
23250 | const unsigned int); | |
23251 | @exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int, | |
23252 | const unsigned int); | |
23253 | @exdent vector signed long long vec_sldb (vector signed long long, | |
23254 | vector signed long long, const unsigned int); | |
23255 | @exdent vector unsigned long long vec_sldb (vector unsigned long long, | |
23256 | vector unsigned long long, const unsigned int); | |
23257 | @end smallexample | |
23258 | ||
23259 | Shift the combined input vectors left by the amount specified by the low-order | |
23260 | three bits of the third argument, and return the leftmost remaining 128 bits. | |
23261 | Code using this instruction must be endian-aware. | |
23262 | ||
23263 | @findex vec_sldb | |
23264 | ||
23265 | Vector Shift Right Double Bit Immediate | |
23266 | ||
23267 | @smallexample | |
23268 | @exdent vector signed char vec_srdb (vector signed char, vector signed char, | |
23269 | const unsigned int); | |
23270 | @exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char, | |
23271 | const unsigned int); | |
23272 | @exdent vector signed short vec_srdb (vector signed short, vector signed short, | |
23273 | const unsigned int); | |
23274 | @exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short, | |
23275 | const unsigned int); | |
23276 | @exdent vector signed int vec_srdb (vector signed int, vector signed int, | |
23277 | const unsigned int); | |
23278 | @exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int, | |
23279 | const unsigned int); | |
23280 | @exdent vector signed long long vec_srdb (vector signed long long, | |
23281 | vector signed long long, const unsigned int); | |
23282 | @exdent vector unsigned long long vec_srdb (vector unsigned long long, | |
23283 | vector unsigned long long, const unsigned int); | |
23284 | @end smallexample | |
23285 | ||
23286 | Shift the combined input vectors right by the amount specified by the low-order | |
23287 | three bits of the third argument, and return the remaining 128 bits. Code | |
23288 | using this built-in must be endian-aware. | |
23289 | ||
23290 | @findex vec_srdb | |
23291 | ||
23292 | Vector Splat | |
23293 | ||
23294 | @smallexample | |
23295 | @exdent vector signed int vec_splati (const signed int); | |
23296 | @exdent vector float vec_splati (const float); | |
23297 | @end smallexample | |
23298 | ||
23299 | Splat a 32-bit immediate into a vector of words. | |
23300 | ||
23301 | @findex vec_splati | |
23302 | ||
23303 | @smallexample | |
23304 | @exdent vector double vec_splatid (const float); | |
23305 | @end smallexample | |
23306 | ||
23307 | Convert a single precision floating-point value to double-precision and splat | |
23308 | the result to a vector of double-precision floats. | |
23309 | ||
23310 | @findex vec_splatid | |
23311 | ||
23312 | @smallexample | |
23313 | @exdent vector signed int vec_splati_ins (vector signed int, | |
23314 | const unsigned int, const signed int); | |
23315 | @exdent vector unsigned int vec_splati_ins (vector unsigned int, | |
23316 | const unsigned int, const unsigned int); | |
23317 | @exdent vector float vec_splati_ins (vector float, const unsigned int, | |
23318 | const float); | |
23319 | @end smallexample | |
23320 | ||
23321 | Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word | |
23322 | identified by argument 2 of each doubleword of argument 1 and return the | |
23323 | result. The other words of argument 1 are unchanged. | |
23324 | ||
23325 | @findex vec_splati_ins | |
23326 | ||
23327 | Vector Blend Variable | |
23328 | ||
23329 | @smallexample | |
23330 | @exdent vector signed char vec_blendv (vector signed char, vector signed char, | |
23331 | vector unsigned char); | |
23332 | @exdent vector unsigned char vec_blendv (vector unsigned char, | |
23333 | vector unsigned char, vector unsigned char); | |
23334 | @exdent vector signed short vec_blendv (vector signed short, | |
23335 | vector signed short, vector unsigned short); | |
23336 | @exdent vector unsigned short vec_blendv (vector unsigned short, | |
23337 | vector unsigned short, vector unsigned short); | |
23338 | @exdent vector signed int vec_blendv (vector signed int, vector signed int, | |
23339 | vector unsigned int); | |
23340 | @exdent vector unsigned int vec_blendv (vector unsigned int, | |
23341 | vector unsigned int, vector unsigned int); | |
23342 | @exdent vector signed long long vec_blendv (vector signed long long, | |
23343 | vector signed long long, vector unsigned long long); | |
23344 | @exdent vector unsigned long long vec_blendv (vector unsigned long long, | |
23345 | vector unsigned long long, vector unsigned long long); | |
23346 | @exdent vector float vec_blendv (vector float, vector float, | |
23347 | vector unsigned int); | |
23348 | @exdent vector double vec_blendv (vector double, vector double, | |
23349 | vector unsigned long long); | |
23350 | @end smallexample | |
23351 | ||
23352 | Blend the first and second argument vectors according to the sign bits of the | |
23353 | corresponding elements of the third argument vector. This is similar to the | |
23354 | @code{vsel} and @code{xxsel} instructions but for bigger elements. | |
23355 | ||
23356 | @findex vec_blendv | |
23357 | ||
23358 | Vector Permute Extended | |
23359 | ||
23360 | @smallexample | |
23361 | @exdent vector signed char vec_permx (vector signed char, vector signed char, | |
23362 | vector unsigned char, const int); | |
23363 | @exdent vector unsigned char vec_permx (vector unsigned char, | |
23364 | vector unsigned char, vector unsigned char, const int); | |
23365 | @exdent vector signed short vec_permx (vector signed short, | |
23366 | vector signed short, vector unsigned char, const int); | |
23367 | @exdent vector unsigned short vec_permx (vector unsigned short, | |
23368 | vector unsigned short, vector unsigned char, const int); | |
23369 | @exdent vector signed int vec_permx (vector signed int, vector signed int, | |
23370 | vector unsigned char, const int); | |
23371 | @exdent vector unsigned int vec_permx (vector unsigned int, | |
23372 | vector unsigned int, vector unsigned char, const int); | |
23373 | @exdent vector signed long long vec_permx (vector signed long long, | |
23374 | vector signed long long, vector unsigned char, const int); | |
23375 | @exdent vector unsigned long long vec_permx (vector unsigned long long, | |
23376 | vector unsigned long long, vector unsigned char, const int); | |
23377 | @exdent vector float (vector float, vector float, vector unsigned char, | |
23378 | const int); | |
23379 | @exdent vector double (vector double, vector double, vector unsigned char, | |
23380 | const int); | |
23381 | @end smallexample | |
23382 | ||
23383 | Perform a partial permute of the first two arguments, which form a 32-byte | |
23384 | section of an emulated vector up to 256 bytes wide, using the partial permute | |
23385 | control vector in the third argument. The fourth argument (constrained to | |
23386 | values of 0-7) identifies which 32-byte section of the emulated vector is | |
23387 | contained in the first two arguments. | |
23388 | @findex vec_permx | |
23389 | ||
23390 | @smallexample | |
23391 | @exdent vector unsigned long long int | |
23392 | @exdent vec_pext (vector unsigned long long int, vector unsigned long long int); | |
23393 | @end smallexample | |
23394 | Perform a vector parallel bit extract operation, as if implemented by | |
23395 | the @code{vpextd} instruction. | |
23396 | @findex vec_pext | |
23397 | ||
23398 | @smallexample | |
23399 | @exdent vector unsigned char vec_stril (vector unsigned char); | |
23400 | @exdent vector signed char vec_stril (vector signed char); | |
23401 | @exdent vector unsigned short vec_stril (vector unsigned short); | |
23402 | @exdent vector signed short vec_stril (vector signed short); | |
23403 | @end smallexample | |
23404 | Isolate the left-most non-zero elements of the incoming vector argument, | |
23405 | replacing all elements to the right of the left-most zero element | |
23406 | found within the argument with zero. The typical implementation uses | |
23407 | the @code{vstribl} or @code{vstrihl} instruction on big-endian targets | |
23408 | and uses the @code{vstribr} or @code{vstrihr} instruction on | |
23409 | little-endian targets. | |
23410 | @findex vec_stril | |
23411 | ||
23412 | @smallexample | |
23413 | @exdent int vec_stril_p (vector unsigned char); | |
23414 | @exdent int vec_stril_p (vector signed char); | |
23415 | @exdent int short vec_stril_p (vector unsigned short); | |
23416 | @exdent int vec_stril_p (vector signed short); | |
23417 | @end smallexample | |
23418 | Return a non-zero value if and only if the argument contains a zero | |
23419 | element. The typical implementation uses | |
23420 | the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets | |
23421 | and uses the @code{vstribr.} or @code{vstrihr.} instruction on | |
23422 | little-endian targets. Choose this built-in to check for presence of | |
23423 | zero element if the same argument is also passed to @code{vec_stril}. | |
23424 | @findex vec_stril_p | |
23425 | ||
23426 | @smallexample | |
23427 | @exdent vector unsigned char vec_strir (vector unsigned char); | |
23428 | @exdent vector signed char vec_strir (vector signed char); | |
23429 | @exdent vector unsigned short vec_strir (vector unsigned short); | |
23430 | @exdent vector signed short vec_strir (vector signed short); | |
23431 | @end smallexample | |
23432 | Isolate the right-most non-zero elements of the incoming vector argument, | |
23433 | replacing all elements to the left of the right-most zero element | |
23434 | found within the argument with zero. The typical implementation uses | |
23435 | the @code{vstribr} or @code{vstrihr} instruction on big-endian targets | |
23436 | and uses the @code{vstribl} or @code{vstrihl} instruction on | |
23437 | little-endian targets. | |
23438 | @findex vec_strir | |
23439 | ||
23440 | @smallexample | |
23441 | @exdent int vec_strir_p (vector unsigned char); | |
23442 | @exdent int vec_strir_p (vector signed char); | |
23443 | @exdent int short vec_strir_p (vector unsigned short); | |
23444 | @exdent int vec_strir_p (vector signed short); | |
23445 | @end smallexample | |
23446 | Return a non-zero value if and only if the argument contains a zero | |
23447 | element. The typical implementation uses | |
23448 | the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets | |
23449 | and uses the @code{vstribl.} or @code{vstrihl.} instruction on | |
23450 | little-endian targets. Choose this built-in to check for presence of | |
23451 | zero element if the same argument is also passed to @code{vec_strir}. | |
23452 | @findex vec_strir_p | |
23453 | ||
23454 | @smallexample | |
23455 | @exdent vector unsigned char | |
23456 | @exdent vec_ternarylogic (vector unsigned char, vector unsigned char, | |
23457 | vector unsigned char, const unsigned int); | |
23458 | @exdent vector unsigned short | |
23459 | @exdent vec_ternarylogic (vector unsigned short, vector unsigned short, | |
23460 | vector unsigned short, const unsigned int); | |
23461 | @exdent vector unsigned int | |
23462 | @exdent vec_ternarylogic (vector unsigned int, vector unsigned int, | |
23463 | vector unsigned int, const unsigned int); | |
23464 | @exdent vector unsigned long long int | |
23465 | @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int, | |
23466 | vector unsigned long long int, const unsigned int); | |
23467 | @exdent vector unsigned __int128 | |
23468 | @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128, | |
23469 | vector unsigned __int128, const unsigned int); | |
23470 | @end smallexample | |
23471 | Perform a 128-bit vector evaluate operation, as if implemented by the | |
23472 | @code{xxeval} instruction. The fourth argument must be a literal | |
23473 | integer value between 0 and 255 inclusive. | |
23474 | @findex vec_ternarylogic | |
23475 | ||
23476 | @smallexample | |
23477 | @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int); | |
23478 | @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int); | |
23479 | @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int); | |
23480 | @exdent vector unsigned int vec_genpcvm (vector unsigned long long int, | |
23481 | const int); | |
23482 | @end smallexample | |
23483 | ||
23484 | Vector Integer Multiply/Divide/Modulo | |
23485 | ||
23486 | @smallexample | |
23487 | @exdent vector signed int | |
23795106 | 23488 | @exdent vec_mulh (vector signed int @var{a}, vector signed int @var{b}); |
d77de738 | 23489 | @exdent vector unsigned int |
23795106 | 23490 | @exdent vec_mulh (vector unsigned int @var{a}, vector unsigned int @var{b}); |
d77de738 ML |
23491 | @end smallexample |
23492 | ||
23493 | For each integer value @code{i} from 0 to 3, do the following. The integer | |
23494 | value in word element @code{i} of a is multiplied by the integer value in word | |
23495 | element @code{i} of b. The high-order 32 bits of the 64-bit product are placed | |
23496 | into word element @code{i} of the vector returned. | |
23497 | ||
23498 | @smallexample | |
23499 | @exdent vector signed long long | |
23795106 | 23500 | @exdent vec_mulh (vector signed long long @var{a}, vector signed long long @var{b}); |
d77de738 | 23501 | @exdent vector unsigned long long |
23795106 | 23502 | @exdent vec_mulh (vector unsigned long long @var{a}, vector unsigned long long @var{b}); |
d77de738 ML |
23503 | @end smallexample |
23504 | ||
23505 | For each integer value @code{i} from 0 to 1, do the following. The integer | |
23506 | value in doubleword element @code{i} of a is multiplied by the integer value in | |
23507 | doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product | |
23508 | are placed into doubleword element @code{i} of the vector returned. | |
23509 | ||
23510 | @smallexample | |
23511 | @exdent vector unsigned long long | |
23795106 | 23512 | @exdent vec_mul (vector unsigned long long @var{a}, vector unsigned long long @var{b}); |
d77de738 | 23513 | @exdent vector signed long long |
23795106 | 23514 | @exdent vec_mul (vector signed long long @var{a}, vector signed long long @var{b}); |
d77de738 ML |
23515 | @end smallexample |
23516 | ||
23517 | For each integer value @code{i} from 0 to 1, do the following. The integer | |
23518 | value in doubleword element @code{i} of a is multiplied by the integer value in | |
23519 | doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product | |
23520 | are placed into doubleword element @code{i} of the vector returned. | |
23521 | ||
23522 | @smallexample | |
23523 | @exdent vector signed int | |
23795106 | 23524 | @exdent vec_div (vector signed int @var{a}, vector signed int @var{b}); |
d77de738 | 23525 | @exdent vector unsigned int |
23795106 | 23526 | @exdent vec_div (vector unsigned int @var{a}, vector unsigned int @var{b}); |
d77de738 ML |
23527 | @end smallexample |
23528 | ||
23529 | For each integer value @code{i} from 0 to 3, do the following. The integer in | |
23530 | word element @code{i} of a is divided by the integer in word element @code{i} | |
23531 | of b. The unique integer quotient is placed into the word element @code{i} of | |
23532 | the vector returned. If an attempt is made to perform any of the divisions | |
23533 | <anything> ÷ 0 then the quotient is undefined. | |
23534 | ||
23535 | @smallexample | |
23536 | @exdent vector signed long long | |
23795106 | 23537 | @exdent vec_div (vector signed long long @var{a}, vector signed long long @var{b}); |
d77de738 | 23538 | @exdent vector unsigned long long |
23795106 | 23539 | @exdent vec_div (vector unsigned long long @var{a}, vector unsigned long long @var{b}); |
d77de738 ML |
23540 | @end smallexample |
23541 | ||
23542 | For each integer value @code{i} from 0 to 1, do the following. The integer in | |
23543 | doubleword element @code{i} of a is divided by the integer in doubleword | |
23544 | element @code{i} of b. The unique integer quotient is placed into the | |
23545 | doubleword element @code{i} of the vector returned. If an attempt is made to | |
23546 | perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then | |
23547 | the quotient is undefined. | |
23548 | ||
23549 | @smallexample | |
23550 | @exdent vector signed int | |
23795106 | 23551 | @exdent vec_dive (vector signed int @var{a}, vector signed int @var{b}); |
d77de738 | 23552 | @exdent vector unsigned int |
23795106 | 23553 | @exdent vec_dive (vector unsigned int @var{a}, vector unsigned int @var{b}); |
d77de738 ML |
23554 | @end smallexample |
23555 | ||
23556 | For each integer value @code{i} from 0 to 3, do the following. The integer in | |
23557 | word element @code{i} of a is shifted left by 32 bits, then divided by the | |
23558 | integer in word element @code{i} of b. The unique integer quotient is placed | |
23559 | into the word element @code{i} of the vector returned. If the quotient cannot | |
23560 | be represented in 32 bits, or if an attempt is made to perform any of the | |
23561 | divisions <anything> ÷ 0 then the quotient is undefined. | |
23562 | ||
23563 | @smallexample | |
23564 | @exdent vector signed long long | |
23795106 | 23565 | @exdent vec_dive (vector signed long long @var{a}, vector signed long long @var{b}); |
d77de738 | 23566 | @exdent vector unsigned long long |
23795106 | 23567 | @exdent vec_dive (vector unsigned long long @var{a}, vector unsigned long long @var{b}); |
d77de738 ML |
23568 | @end smallexample |
23569 | ||
23570 | For each integer value @code{i} from 0 to 1, do the following. The integer in | |
23571 | doubleword element @code{i} of a is shifted left by 64 bits, then divided by | |
23572 | the integer in doubleword element @code{i} of b. The unique integer quotient is | |
23573 | placed into the doubleword element @code{i} of the vector returned. If the | |
23574 | quotient cannot be represented in 64 bits, or if an attempt is made to perform | |
23575 | <anything> ÷ 0 then the quotient is undefined. | |
23576 | ||
23577 | @smallexample | |
23578 | @exdent vector signed int | |
23795106 | 23579 | @exdent vec_mod (vector signed int @var{a}, vector signed int @var{b}); |
d77de738 | 23580 | @exdent vector unsigned int |
23795106 | 23581 | @exdent vec_mod (vector unsigned int @var{a}, vector unsigned int @var{b}); |
d77de738 ML |
23582 | @end smallexample |
23583 | ||
23584 | For each integer value @code{i} from 0 to 3, do the following. The integer in | |
23585 | word element @code{i} of a is divided by the integer in word element @code{i} | |
23586 | of b. The unique integer remainder is placed into the word element @code{i} of | |
23587 | the vector returned. If an attempt is made to perform any of the divisions | |
23588 | 0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined. | |
23589 | ||
23590 | @smallexample | |
23591 | @exdent vector signed long long | |
23795106 | 23592 | @exdent vec_mod (vector signed long long @var{a}, vector signed long long @var{b}); |
d77de738 | 23593 | @exdent vector unsigned long long |
23795106 | 23594 | @exdent vec_mod (vector unsigned long long @var{a}, vector unsigned long long @var{b}); |
d77de738 ML |
23595 | @end smallexample |
23596 | ||
23597 | For each integer value @code{i} from 0 to 1, do the following. The integer in | |
23598 | doubleword element @code{i} of a is divided by the integer in doubleword | |
23599 | element @code{i} of b. The unique integer remainder is placed into the | |
23600 | doubleword element @code{i} of the vector returned. If an attempt is made to | |
23601 | perform <anything> ÷ 0 then the remainder is undefined. | |
23602 | ||
23603 | Generate PCV from specified Mask size, as if implemented by the | |
23604 | @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where | |
23605 | immediate value is either 0, 1, 2 or 3. | |
23606 | @findex vec_genpcvm | |
23607 | ||
23608 | @smallexample | |
23795106 JJ |
23609 | @exdent vector unsigned __int128 vec_rl (vector unsigned __int128 @var{A}, |
23610 | vector unsigned __int128 @var{B}); | |
23611 | @exdent vector signed __int128 vec_rl (vector signed __int128 @var{A}, | |
23612 | vector unsigned __int128 @var{B}); | |
d77de738 ML |
23613 | @end smallexample |
23614 | ||
23795106 JJ |
23615 | Result value: Each element of @var{R} is obtained by rotating the corresponding element |
23616 | of @var{A} left by the number of bits specified by the corresponding element of @var{B}. | |
d77de738 ML |
23617 | |
23618 | ||
23619 | @smallexample | |
23620 | @exdent vector unsigned __int128 vec_rlmi (vector unsigned __int128, | |
23621 | vector unsigned __int128, | |
23622 | vector unsigned __int128); | |
23623 | @exdent vector signed __int128 vec_rlmi (vector signed __int128, | |
23624 | vector signed __int128, | |
23625 | vector unsigned __int128); | |
23626 | @end smallexample | |
23627 | ||
23628 | Returns the result of rotating the first input and inserting it under mask | |
23629 | into the second input. The first bit in the mask, the last bit in the mask are | |
23630 | obtained from the two 7-bit fields bits [108:115] and bits [117:123] | |
23631 | respectively of the second input. The shift is obtained from the third input | |
23632 | in the 7-bit field [125:131] where all bits counted from zero at the left. | |
23633 | ||
23634 | @smallexample | |
23635 | @exdent vector unsigned __int128 vec_rlnm (vector unsigned __int128, | |
23636 | vector unsigned __int128, | |
23637 | vector unsigned __int128); | |
23638 | @exdent vector signed __int128 vec_rlnm (vector signed __int128, | |
23639 | vector unsigned __int128, | |
23640 | vector unsigned __int128); | |
23641 | @end smallexample | |
23642 | ||
23643 | Returns the result of rotating the first input and ANDing it with a mask. The | |
23644 | first bit in the mask and the last bit in the mask are obtained from the two | |
23645 | 7-bit fields bits [117:123] and bits [125:131] respectively of the second | |
23646 | input. The shift is obtained from the third input in the 7-bit field bits | |
23647 | [125:131] where all bits counted from zero at the left. | |
23648 | ||
23649 | @smallexample | |
23795106 JJ |
23650 | @exdent vector unsigned __int128 vec_sl(vector unsigned __int128 @var{A}, vector unsigned __int128 @var{B}); |
23651 | @exdent vector signed __int128 vec_sl(vector signed __int128 @var{A}, vector unsigned __int128 @var{B}); | |
d77de738 ML |
23652 | @end smallexample |
23653 | ||
23795106 JJ |
23654 | Result value: Each element of @var{R} is obtained by shifting the corresponding element of |
23655 | @var{A} left by the number of bits specified by the corresponding element of @var{B}. | |
d77de738 ML |
23656 | |
23657 | @smallexample | |
23795106 JJ |
23658 | @exdent vector unsigned __int128 vec_sr(vector unsigned __int128 @var{A}, vector unsigned __int128 @var{B}); |
23659 | @exdent vector signed __int128 vec_sr(vector signed __int128 @var{A}, vector unsigned __int128 @var{B}); | |
d77de738 ML |
23660 | @end smallexample |
23661 | ||
23795106 JJ |
23662 | Result value: Each element of @var{R} is obtained by shifting the corresponding element of |
23663 | @var{A} right by the number of bits specified by the corresponding element of @var{B}. | |
d77de738 ML |
23664 | |
23665 | @smallexample | |
23795106 JJ |
23666 | @exdent vector unsigned __int128 vec_sra(vector unsigned __int128 @var{A}, vector unsigned __int128 @var{B}); |
23667 | @exdent vector signed __int128 vec_sra(vector signed __int128 @var{A}, vector unsigned __int128 @var{B}); | |
d77de738 ML |
23668 | @end smallexample |
23669 | ||
23795106 JJ |
23670 | Result value: Each element of @var{R} is obtained by arithmetic shifting the corresponding |
23671 | element of @var{A} right by the number of bits specified by the corresponding element of @var{B}. | |
d77de738 ML |
23672 | |
23673 | @smallexample | |
23674 | @exdent vector unsigned __int128 vec_mule (vector unsigned long long, | |
23675 | vector unsigned long long); | |
23676 | @exdent vector signed __int128 vec_mule (vector signed long long, | |
23677 | vector signed long long); | |
23678 | @end smallexample | |
23679 | ||
23680 | Returns a vector containing a 128-bit integer result of multiplying the even | |
23681 | doubleword elements of the two inputs. | |
23682 | ||
23683 | @smallexample | |
23684 | @exdent vector unsigned __int128 vec_mulo (vector unsigned long long, | |
23685 | vector unsigned long long); | |
23686 | @exdent vector signed __int128 vec_mulo (vector signed long long, | |
23687 | vector signed long long); | |
23688 | @end smallexample | |
23689 | ||
23690 | Returns a vector containing a 128-bit integer result of multiplying the odd | |
23691 | doubleword elements of the two inputs. | |
23692 | ||
23693 | @smallexample | |
23694 | @exdent vector unsigned __int128 vec_div (vector unsigned __int128, | |
23695 | vector unsigned __int128); | |
23696 | @exdent vector signed __int128 vec_div (vector signed __int128, | |
23697 | vector signed __int128); | |
23698 | @end smallexample | |
23699 | ||
23700 | Returns the result of dividing the first operand by the second operand. An | |
23701 | attempt to divide any value by zero or to divide the most negative signed | |
23702 | 128-bit integer by negative one results in an undefined value. | |
23703 | ||
23704 | @smallexample | |
23705 | @exdent vector unsigned __int128 vec_dive (vector unsigned __int128, | |
23706 | vector unsigned __int128); | |
23707 | @exdent vector signed __int128 vec_dive (vector signed __int128, | |
23708 | vector signed __int128); | |
23709 | @end smallexample | |
23710 | ||
23711 | The result is produced by shifting the first input left by 128 bits and | |
23712 | dividing by the second. If an attempt is made to divide by zero or the result | |
23713 | is larger than 128 bits, the result is undefined. | |
23714 | ||
23715 | @smallexample | |
23716 | @exdent vector unsigned __int128 vec_mod (vector unsigned __int128, | |
23717 | vector unsigned __int128); | |
23718 | @exdent vector signed __int128 vec_mod (vector signed __int128, | |
23719 | vector signed __int128); | |
23720 | @end smallexample | |
23721 | ||
23722 | The result is the modulo result of dividing the first input by the second | |
23723 | input. | |
23724 | ||
23725 | The following builtins perform 128-bit vector comparisons. The | |
23726 | @code{vec_all_xx}, @code{vec_any_xx}, and @code{vec_cmpxx}, where @code{xx} is | |
23727 | one of the operations @code{eq, ne, gt, lt, ge, le} perform pairwise | |
23728 | comparisons between the elements at the same positions within their two vector | |
23729 | arguments. The @code{vec_all_xx}function returns a non-zero value if and only | |
23730 | if all pairwise comparisons are true. The @code{vec_any_xx} function returns | |
23731 | a non-zero value if and only if at least one pairwise comparison is true. The | |
23732 | @code{vec_cmpxx}function returns a vector of the same type as its two | |
23733 | arguments, within which each element consists of all ones to denote that | |
23734 | specified logical comparison of the corresponding elements was true. | |
23735 | Otherwise, the element of the returned vector contains all zeros. | |
23736 | ||
23737 | @smallexample | |
23738 | vector bool __int128 vec_cmpeq (vector signed __int128, vector signed __int128); | |
23739 | vector bool __int128 vec_cmpeq (vector unsigned __int128, vector unsigned __int128); | |
23740 | vector bool __int128 vec_cmpne (vector signed __int128, vector signed __int128); | |
23741 | vector bool __int128 vec_cmpne (vector unsigned __int128, vector unsigned __int128); | |
23742 | vector bool __int128 vec_cmpgt (vector signed __int128, vector signed __int128); | |
23743 | vector bool __int128 vec_cmpgt (vector unsigned __int128, vector unsigned __int128); | |
23744 | vector bool __int128 vec_cmplt (vector signed __int128, vector signed __int128); | |
23745 | vector bool __int128 vec_cmplt (vector unsigned __int128, vector unsigned __int128); | |
23746 | vector bool __int128 vec_cmpge (vector signed __int128, vector signed __int128); | |
23747 | vector bool __int128 vec_cmpge (vector unsigned __int128, vector unsigned __int128); | |
23748 | vector bool __int128 vec_cmple (vector signed __int128, vector signed __int128); | |
23749 | vector bool __int128 vec_cmple (vector unsigned __int128, vector unsigned __int128); | |
23750 | ||
23751 | int vec_all_eq (vector signed __int128, vector signed __int128); | |
23752 | int vec_all_eq (vector unsigned __int128, vector unsigned __int128); | |
23753 | int vec_all_ne (vector signed __int128, vector signed __int128); | |
23754 | int vec_all_ne (vector unsigned __int128, vector unsigned __int128); | |
23755 | int vec_all_gt (vector signed __int128, vector signed __int128); | |
23756 | int vec_all_gt (vector unsigned __int128, vector unsigned __int128); | |
23757 | int vec_all_lt (vector signed __int128, vector signed __int128); | |
23758 | int vec_all_lt (vector unsigned __int128, vector unsigned __int128); | |
23759 | int vec_all_ge (vector signed __int128, vector signed __int128); | |
23760 | int vec_all_ge (vector unsigned __int128, vector unsigned __int128); | |
23761 | int vec_all_le (vector signed __int128, vector signed __int128); | |
23762 | int vec_all_le (vector unsigned __int128, vector unsigned __int128); | |
23763 | ||
23764 | int vec_any_eq (vector signed __int128, vector signed __int128); | |
23765 | int vec_any_eq (vector unsigned __int128, vector unsigned __int128); | |
23766 | int vec_any_ne (vector signed __int128, vector signed __int128); | |
23767 | int vec_any_ne (vector unsigned __int128, vector unsigned __int128); | |
23768 | int vec_any_gt (vector signed __int128, vector signed __int128); | |
23769 | int vec_any_gt (vector unsigned __int128, vector unsigned __int128); | |
23770 | int vec_any_lt (vector signed __int128, vector signed __int128); | |
23771 | int vec_any_lt (vector unsigned __int128, vector unsigned __int128); | |
23772 | int vec_any_ge (vector signed __int128, vector signed __int128); | |
23773 | int vec_any_ge (vector unsigned __int128, vector unsigned __int128); | |
23774 | int vec_any_le (vector signed __int128, vector signed __int128); | |
23775 | int vec_any_le (vector unsigned __int128, vector unsigned __int128); | |
23776 | @end smallexample | |
23777 | ||
23778 | ||
23779 | @node PowerPC Hardware Transactional Memory Built-in Functions | |
23780 | @subsection PowerPC Hardware Transactional Memory Built-in Functions | |
23781 | GCC provides two interfaces for accessing the Hardware Transactional | |
23782 | Memory (HTM) instructions available on some of the PowerPC family | |
23783 | of processors (eg, POWER8). The two interfaces come in a low level | |
23784 | interface, consisting of built-in functions specific to PowerPC and a | |
23785 | higher level interface consisting of inline functions that are common | |
23786 | between PowerPC and S/390. | |
23787 | ||
23788 | @subsubsection PowerPC HTM Low Level Built-in Functions | |
23789 | ||
23790 | The following low level built-in functions are available with | |
23791 | @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. | |
23792 | They all generate the machine instruction that is part of the name. | |
23793 | ||
23794 | The HTM builtins (with the exception of @code{__builtin_tbegin}) return | |
23795 | the full 4-bit condition register value set by their associated hardware | |
23796 | instruction. The header file @code{htmintrin.h} defines some macros that can | |
23797 | be used to decipher the return value. The @code{__builtin_tbegin} builtin | |
23798 | returns a simple @code{true} or @code{false} value depending on whether a transaction was | |
23799 | successfully started or not. The arguments of the builtins match exactly the | |
23800 | type and order of the associated hardware instruction's operands, except for | |
23801 | the @code{__builtin_tcheck} builtin, which does not take any input arguments. | |
23802 | Refer to the ISA manual for a description of each instruction's operands. | |
23803 | ||
23804 | @smallexample | |
23805 | unsigned int __builtin_tbegin (unsigned int); | |
23806 | unsigned int __builtin_tend (unsigned int); | |
23807 | ||
23808 | unsigned int __builtin_tabort (unsigned int); | |
23809 | unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int); | |
23810 | unsigned int __builtin_tabortdci (unsigned int, unsigned int, int); | |
23811 | unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int); | |
23812 | unsigned int __builtin_tabortwci (unsigned int, unsigned int, int); | |
23813 | ||
23814 | unsigned int __builtin_tcheck (void); | |
23815 | unsigned int __builtin_treclaim (unsigned int); | |
23816 | unsigned int __builtin_trechkpt (void); | |
23817 | unsigned int __builtin_tsr (unsigned int); | |
23818 | @end smallexample | |
23819 | ||
23820 | In addition to the above HTM built-ins, we have added built-ins for | |
23821 | some common extended mnemonics of the HTM instructions: | |
23822 | ||
23823 | @smallexample | |
23824 | unsigned int __builtin_tendall (void); | |
23825 | unsigned int __builtin_tresume (void); | |
23826 | unsigned int __builtin_tsuspend (void); | |
23827 | @end smallexample | |
23828 | ||
23829 | Note that the semantics of the above HTM builtins are required to mimic | |
23830 | the locking semantics used for critical sections. Builtins that are used | |
23831 | to create a new transaction or restart a suspended transaction must have | |
23832 | lock acquisition like semantics while those builtins that end or suspend a | |
23833 | transaction must have lock release like semantics. Specifically, this must | |
23834 | mimic lock semantics as specified by C++11, for example: Lock acquisition is | |
23835 | as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) | |
23836 | that returns 0, and lock release is as-if an execution of | |
23837 | __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an | |
23838 | implicit implementation-defined lock used for all transactions. The HTM | |
23839 | instructions associated with with the builtins inherently provide the | |
23840 | correct acquisition and release hardware barriers required. However, | |
23841 | the compiler must also be prohibited from moving loads and stores across | |
23842 | the builtins in a way that would violate their semantics. This has been | |
23843 | accomplished by adding memory barriers to the associated HTM instructions | |
23844 | (which is a conservative approach to provide acquire and release semantics). | |
23845 | Earlier versions of the compiler did not treat the HTM instructions as | |
23846 | memory barriers. A @code{__TM_FENCE__} macro has been added, which can | |
23847 | be used to determine whether the current compiler treats HTM instructions | |
23848 | as memory barriers or not. This allows the user to explicitly add memory | |
23849 | barriers to their code when using an older version of the compiler. | |
23850 | ||
23851 | The following set of built-in functions are available to gain access | |
23852 | to the HTM specific special purpose registers. | |
23853 | ||
23854 | @smallexample | |
23855 | unsigned long __builtin_get_texasr (void); | |
23856 | unsigned long __builtin_get_texasru (void); | |
23857 | unsigned long __builtin_get_tfhar (void); | |
23858 | unsigned long __builtin_get_tfiar (void); | |
23859 | ||
23860 | void __builtin_set_texasr (unsigned long); | |
23861 | void __builtin_set_texasru (unsigned long); | |
23862 | void __builtin_set_tfhar (unsigned long); | |
23863 | void __builtin_set_tfiar (unsigned long); | |
23864 | @end smallexample | |
23865 | ||
23866 | Example usage of these low level built-in functions may look like: | |
23867 | ||
23868 | @smallexample | |
23869 | #include <htmintrin.h> | |
23870 | ||
23871 | int num_retries = 10; | |
23872 | ||
23873 | while (1) | |
23874 | @{ | |
23875 | if (__builtin_tbegin (0)) | |
23876 | @{ | |
23877 | /* Transaction State Initiated. */ | |
23878 | if (is_locked (lock)) | |
23879 | __builtin_tabort (0); | |
23880 | ... transaction code... | |
23881 | __builtin_tend (0); | |
23882 | break; | |
23883 | @} | |
23884 | else | |
23885 | @{ | |
23886 | /* Transaction State Failed. Use locks if the transaction | |
23887 | failure is "persistent" or we've tried too many times. */ | |
23888 | if (num_retries-- <= 0 | |
23889 | || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) | |
23890 | @{ | |
23891 | acquire_lock (lock); | |
23892 | ... non transactional fallback path... | |
23893 | release_lock (lock); | |
23894 | break; | |
23895 | @} | |
23896 | @} | |
23897 | @} | |
23898 | @end smallexample | |
23899 | ||
23900 | One final built-in function has been added that returns the value of | |
23901 | the 2-bit Transaction State field of the Machine Status Register (MSR) | |
23902 | as stored in @code{CR0}. | |
23903 | ||
23904 | @smallexample | |
23905 | unsigned long __builtin_ttest (void) | |
23906 | @end smallexample | |
23907 | ||
23908 | This built-in can be used to determine the current transaction state | |
23909 | using the following code example: | |
23910 | ||
23911 | @smallexample | |
23912 | #include <htmintrin.h> | |
23913 | ||
23914 | unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); | |
23915 | ||
23916 | if (tx_state == _HTM_TRANSACTIONAL) | |
23917 | @{ | |
23918 | /* Code to use in transactional state. */ | |
23919 | @} | |
23920 | else if (tx_state == _HTM_NONTRANSACTIONAL) | |
23921 | @{ | |
23922 | /* Code to use in non-transactional state. */ | |
23923 | @} | |
23924 | else if (tx_state == _HTM_SUSPENDED) | |
23925 | @{ | |
23926 | /* Code to use in transaction suspended state. */ | |
23927 | @} | |
23928 | @end smallexample | |
23929 | ||
23930 | @subsubsection PowerPC HTM High Level Inline Functions | |
23931 | ||
23932 | The following high level HTM interface is made available by including | |
23933 | @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU} | |
23934 | where CPU is `power8' or later. This interface is common between PowerPC | |
23935 | and S/390, allowing users to write one HTM source implementation that | |
23936 | can be compiled and executed on either system. | |
23937 | ||
23938 | @smallexample | |
23939 | long __TM_simple_begin (void); | |
23940 | long __TM_begin (void* const TM_buff); | |
23941 | long __TM_end (void); | |
23942 | void __TM_abort (void); | |
23943 | void __TM_named_abort (unsigned char const code); | |
23944 | void __TM_resume (void); | |
23945 | void __TM_suspend (void); | |
23946 | ||
23947 | long __TM_is_user_abort (void* const TM_buff); | |
23948 | long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code); | |
23949 | long __TM_is_illegal (void* const TM_buff); | |
23950 | long __TM_is_footprint_exceeded (void* const TM_buff); | |
23951 | long __TM_nesting_depth (void* const TM_buff); | |
23952 | long __TM_is_nested_too_deep(void* const TM_buff); | |
23953 | long __TM_is_conflict(void* const TM_buff); | |
23954 | long __TM_is_failure_persistent(void* const TM_buff); | |
23955 | long __TM_failure_address(void* const TM_buff); | |
23956 | long long __TM_failure_code(void* const TM_buff); | |
23957 | @end smallexample | |
23958 | ||
23959 | Using these common set of HTM inline functions, we can create | |
23960 | a more portable version of the HTM example in the previous | |
23961 | section that will work on either PowerPC or S/390: | |
23962 | ||
23963 | @smallexample | |
23964 | #include <htmxlintrin.h> | |
23965 | ||
23966 | int num_retries = 10; | |
23967 | TM_buff_type TM_buff; | |
23968 | ||
23969 | while (1) | |
23970 | @{ | |
23971 | if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED) | |
23972 | @{ | |
23973 | /* Transaction State Initiated. */ | |
23974 | if (is_locked (lock)) | |
23975 | __TM_abort (); | |
23976 | ... transaction code... | |
23977 | __TM_end (); | |
23978 | break; | |
23979 | @} | |
23980 | else | |
23981 | @{ | |
23982 | /* Transaction State Failed. Use locks if the transaction | |
23983 | failure is "persistent" or we've tried too many times. */ | |
23984 | if (num_retries-- <= 0 | |
23985 | || __TM_is_failure_persistent (TM_buff)) | |
23986 | @{ | |
23987 | acquire_lock (lock); | |
23988 | ... non transactional fallback path... | |
23989 | release_lock (lock); | |
23990 | break; | |
23991 | @} | |
23992 | @} | |
23993 | @} | |
23994 | @end smallexample | |
23995 | ||
23996 | @node PowerPC Atomic Memory Operation Functions | |
23997 | @subsection PowerPC Atomic Memory Operation Functions | |
23998 | ISA 3.0 of the PowerPC added new atomic memory operation (amo) | |
23999 | instructions. GCC provides support for these instructions in 64-bit | |
24000 | environments. All of the functions are declared in the include file | |
24001 | @code{amo.h}. | |
24002 | ||
24003 | The functions supported are: | |
24004 | ||
24005 | @smallexample | |
24006 | #include <amo.h> | |
24007 | ||
24008 | uint32_t amo_lwat_add (uint32_t *, uint32_t); | |
24009 | uint32_t amo_lwat_xor (uint32_t *, uint32_t); | |
24010 | uint32_t amo_lwat_ior (uint32_t *, uint32_t); | |
24011 | uint32_t amo_lwat_and (uint32_t *, uint32_t); | |
24012 | uint32_t amo_lwat_umax (uint32_t *, uint32_t); | |
24013 | uint32_t amo_lwat_umin (uint32_t *, uint32_t); | |
24014 | uint32_t amo_lwat_swap (uint32_t *, uint32_t); | |
24015 | ||
24016 | int32_t amo_lwat_sadd (int32_t *, int32_t); | |
24017 | int32_t amo_lwat_smax (int32_t *, int32_t); | |
24018 | int32_t amo_lwat_smin (int32_t *, int32_t); | |
24019 | int32_t amo_lwat_sswap (int32_t *, int32_t); | |
24020 | ||
24021 | uint64_t amo_ldat_add (uint64_t *, uint64_t); | |
24022 | uint64_t amo_ldat_xor (uint64_t *, uint64_t); | |
24023 | uint64_t amo_ldat_ior (uint64_t *, uint64_t); | |
24024 | uint64_t amo_ldat_and (uint64_t *, uint64_t); | |
24025 | uint64_t amo_ldat_umax (uint64_t *, uint64_t); | |
24026 | uint64_t amo_ldat_umin (uint64_t *, uint64_t); | |
24027 | uint64_t amo_ldat_swap (uint64_t *, uint64_t); | |
24028 | ||
24029 | int64_t amo_ldat_sadd (int64_t *, int64_t); | |
24030 | int64_t amo_ldat_smax (int64_t *, int64_t); | |
24031 | int64_t amo_ldat_smin (int64_t *, int64_t); | |
24032 | int64_t amo_ldat_sswap (int64_t *, int64_t); | |
24033 | ||
24034 | void amo_stwat_add (uint32_t *, uint32_t); | |
24035 | void amo_stwat_xor (uint32_t *, uint32_t); | |
24036 | void amo_stwat_ior (uint32_t *, uint32_t); | |
24037 | void amo_stwat_and (uint32_t *, uint32_t); | |
24038 | void amo_stwat_umax (uint32_t *, uint32_t); | |
24039 | void amo_stwat_umin (uint32_t *, uint32_t); | |
24040 | ||
24041 | void amo_stwat_sadd (int32_t *, int32_t); | |
24042 | void amo_stwat_smax (int32_t *, int32_t); | |
24043 | void amo_stwat_smin (int32_t *, int32_t); | |
24044 | ||
24045 | void amo_stdat_add (uint64_t *, uint64_t); | |
24046 | void amo_stdat_xor (uint64_t *, uint64_t); | |
24047 | void amo_stdat_ior (uint64_t *, uint64_t); | |
24048 | void amo_stdat_and (uint64_t *, uint64_t); | |
24049 | void amo_stdat_umax (uint64_t *, uint64_t); | |
24050 | void amo_stdat_umin (uint64_t *, uint64_t); | |
24051 | ||
24052 | void amo_stdat_sadd (int64_t *, int64_t); | |
24053 | void amo_stdat_smax (int64_t *, int64_t); | |
24054 | void amo_stdat_smin (int64_t *, int64_t); | |
24055 | @end smallexample | |
24056 | ||
24057 | @node PowerPC Matrix-Multiply Assist Built-in Functions | |
24058 | @subsection PowerPC Matrix-Multiply Assist Built-in Functions | |
24059 | ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions. | |
24060 | GCC provides support for these instructions through the following built-in | |
24061 | functions which are enabled with the @code{-mmma} option. The vec_t type | |
24062 | below is defined to be a normal vector unsigned char type. The uint2, uint4 | |
24063 | and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants | |
24064 | respectively. The compiler will verify that they are constants and that | |
24065 | their values are within range. | |
24066 | ||
24067 | The built-in functions supported are: | |
24068 | ||
24069 | @smallexample | |
24070 | void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t); | |
24071 | void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t); | |
24072 | void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t); | |
24073 | void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t); | |
24074 | void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t); | |
24075 | void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t); | |
24076 | void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t); | |
24077 | ||
24078 | void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t); | |
24079 | void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t); | |
24080 | void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t); | |
24081 | void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t); | |
24082 | void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t); | |
24083 | void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t); | |
24084 | void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t); | |
24085 | void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t); | |
24086 | void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t); | |
24087 | void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t); | |
24088 | void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t); | |
24089 | void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t); | |
24090 | void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t); | |
24091 | void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t); | |
24092 | void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t); | |
24093 | void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t); | |
24094 | void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t); | |
24095 | ||
24096 | void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8); | |
24097 | void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8); | |
24098 | ||
24099 | void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); | |
24100 | void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); | |
24101 | void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); | |
24102 | ||
24103 | void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24104 | void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24105 | void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24106 | void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24107 | ||
24108 | void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24109 | void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24110 | void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24111 | void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24112 | void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24113 | void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24114 | void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24115 | void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24116 | void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24117 | void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); | |
24118 | ||
24119 | void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
24120 | void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
24121 | void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
24122 | void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
24123 | void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4); | |
24124 | ||
24125 | void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t); | |
24126 | void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t); | |
24127 | void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t); | |
24128 | void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t); | |
24129 | void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t); | |
24130 | ||
24131 | void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
24132 | void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
24133 | void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
24134 | void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
24135 | void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2); | |
24136 | ||
24137 | void __builtin_mma_xxmtacc (__vector_quad *); | |
24138 | void __builtin_mma_xxmfacc (__vector_quad *); | |
24139 | void __builtin_mma_xxsetaccz (__vector_quad *); | |
24140 | ||
24141 | void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t); | |
24142 | void __builtin_mma_disassemble_acc (void *, __vector_quad *); | |
24143 | ||
24144 | void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t); | |
24145 | void __builtin_vsx_disassemble_pair (void *, __vector_pair *); | |
24146 | ||
24147 | vec_t __builtin_vsx_xvcvspbf16 (vec_t); | |
24148 | vec_t __builtin_vsx_xvcvbf16spn (vec_t); | |
24149 | ||
24150 | __vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *); | |
24151 | void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *); | |
24152 | @end smallexample | |
24153 | ||
24154 | @node PRU Built-in Functions | |
24155 | @subsection PRU Built-in Functions | |
24156 | ||
24157 | GCC provides a couple of special builtin functions to aid in utilizing | |
24158 | special PRU instructions. | |
24159 | ||
24160 | The built-in functions supported are: | |
24161 | ||
f25efe50 | 24162 | @defbuiltin{void __delay_cycles (constant long long @var{cycles})} |
d77de738 ML |
24163 | This inserts an instruction sequence that takes exactly @var{cycles} |
24164 | cycles (between 0 and 0xffffffff) to complete. The inserted sequence | |
24165 | may use jumps, loops, or no-ops, and does not interfere with any other | |
24166 | instructions. Note that @var{cycles} must be a compile-time constant | |
24167 | integer - that is, you must pass a number, not a variable that may be | |
24168 | optimized to a constant later. The number of cycles delayed by this | |
24169 | builtin is exact. | |
f25efe50 | 24170 | @enddefbuiltin |
d77de738 | 24171 | |
f25efe50 | 24172 | @defbuiltin{void __halt (void)} |
d77de738 | 24173 | This inserts a HALT instruction to stop processor execution. |
f25efe50 | 24174 | @enddefbuiltin |
d77de738 | 24175 | |
f25efe50 AA |
24176 | @defbuiltin{{unsigned int} @ |
24177 | __lmbd (unsigned int @var{wordval}, @ | |
24178 | unsigned int @var{bitval})} | |
d77de738 ML |
24179 | This inserts LMBD instruction to calculate the left-most bit with value |
24180 | @var{bitval} in value @var{wordval}. Only the least significant bit | |
24181 | of @var{bitval} is taken into account. | |
f25efe50 | 24182 | @enddefbuiltin |
d77de738 ML |
24183 | |
24184 | @node RISC-V Built-in Functions | |
24185 | @subsection RISC-V Built-in Functions | |
24186 | ||
24187 | These built-in functions are available for the RISC-V family of | |
24188 | processors. | |
24189 | ||
f25efe50 | 24190 | @defbuiltin{{void *} __builtin_thread_pointer (void)} |
d77de738 | 24191 | Returns the value that is currently set in the @samp{tp} register. |
f25efe50 | 24192 | @enddefbuiltin |
d77de738 | 24193 | |
f25efe50 | 24194 | @defbuiltin{void __builtin_riscv_pause (void)} |
cf64ab18 TO |
24195 | Generates the @code{pause} (hint) machine instruction. If the target implements |
24196 | the Zihintpause extension, it indicates that the current hart should be | |
24197 | temporarily paused or slowed down. | |
f25efe50 | 24198 | @enddefbuiltin |
c717a92d | 24199 | |
14c1a8df KC |
24200 | @node RISC-V Vector Intrinsics |
24201 | @subsection RISC-V Vector Intrinsics | |
24202 | ||
24203 | GCC supports vector intrinsics as specified in version 0.11 of the RISC-V | |
24204 | vector intrinsic specification, which is available at the following link: | |
24205 | @uref{https://github.com/riscv-non-isa/rvv-intrinsic-doc/tree/v0.11.x}. | |
24206 | All of these functions are declared in the include file @file{riscv_vector.h}. | |
24207 | ||
400efddd | 24208 | @node CORE-V Built-in Functions |
e99ad401 | 24209 | @subsection CORE-V Built-in Functions |
400efddd MB |
24210 | |
24211 | These built-in functions are available for the CORE-V MAC machine | |
24212 | architecture. For more information on CORE-V built-ins, please see | |
24213 | @uref{https://github.com/openhwgroup/core-v-sw/blob/master/specifications/corev-builtin-spec.md#listing-of-multiply-accumulate-builtins-xcvmac}. | |
24214 | ||
24215 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mac (int32_t, int32_t, int32_t) | |
24216 | Generated assembler @code{cv.mac} | |
24217 | @end deftypefn | |
24218 | ||
24219 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_msu (int32_t, int32_t, int32_t) | |
24220 | Generates the @code{cv.msu} machine instruction. | |
24221 | @end deftypefn | |
24222 | ||
24223 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_muluN (uint32_t, uint32_t, uint8_t) | |
24224 | Generates the @code{cv.muluN} machine instruction. | |
24225 | @end deftypefn | |
24226 | ||
24227 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_mulhhuN (uint32_t, uint32_t, uint8_t) | |
24228 | Generates the @code{cv.mulhhuN} machine instruction. | |
24229 | @end deftypefn | |
24230 | ||
24231 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mulsN (int32_t, int32_t, uint8_t) | |
24232 | Generates the @code{cv.mulsN} machine instruction. | |
24233 | @end deftypefn | |
24234 | ||
24235 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mulhhsN (int32_t, int32_t, uint8_t) | |
24236 | Generates the @code{cv.mulhhsN} machine instruction. | |
24237 | @end deftypefn | |
24238 | ||
24239 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_muluRN (uint32_t, uint32_t, uint8_t) | |
24240 | Generates the @code{cv.muluRN} machine instruction. | |
24241 | @end deftypefn | |
24242 | ||
24243 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_mulhhuRN (uint32_t, uint32_t, uint8_t) | |
24244 | Generates the @code{cv.mulhhuRN} machine instruction. | |
24245 | @end deftypefn | |
24246 | ||
24247 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mulsRN (int32_t, int32_t, uint8_t) | |
24248 | Generates the @code{cv.mulsRN} machine instruction. | |
24249 | @end deftypefn | |
24250 | ||
24251 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mulhhsRN (int32_t, int32_t, uint8_t) | |
24252 | Generates the @code{cv.mulhhsRN} machine instruction. | |
24253 | @end deftypefn | |
24254 | ||
24255 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_macuN (uint32_t, uint32_t, uint8_t) | |
24256 | Generates the @code{cv.macuN} machine instruction. | |
24257 | @end deftypefn | |
24258 | ||
24259 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_machhuN (uint32_t, uint32_t, uint8_t) | |
24260 | Generates the @code{cv.machhuN} machine instruction. | |
24261 | @end deftypefn | |
24262 | ||
24263 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_macsN (int32_t, int32_t, uint8_t) | |
24264 | Generates the @code{cv.macsN} machine instruction. | |
24265 | @end deftypefn | |
24266 | ||
24267 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_machhsN (int32_t, int32_t, uint8_t) | |
24268 | Generates the @code{cv.machhsN} machine instruction. | |
24269 | @end deftypefn | |
24270 | ||
24271 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_macuRN (uint32_t, uint32_t, uint8_t) | |
24272 | Generates the @code{cv.macuRN} machine instruction. | |
24273 | @end deftypefn | |
24274 | ||
24275 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_machhuRN (uint32_t, uint32_t, uint8_t) | |
24276 | Generates the @code{cv.machhuRN} machine instruction. | |
24277 | @end deftypefn | |
24278 | ||
24279 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_macsRN (int32_t, int32_t, uint8_t) | |
24280 | Generates the @code{cv.macsRN} machine instruction. | |
24281 | @end deftypefn | |
24282 | ||
24283 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_machhsRN (int32_t, int32_t, uint8_t) | |
24284 | Generates the @code{cv.machhsRN} machine instruction. | |
24285 | @end deftypefn | |
24286 | ||
5ef248c1 MB |
24287 | These built-in functions are available for the CORE-V ALU machine |
24288 | architecture. For more information on CORE-V built-ins, please see | |
24289 | @uref{https://github.com/openhwgroup/core-v-sw/blob/master/specifications/corev-builtin-spec.md#listing-of-miscellaneous-alu-builtins-xcvalu} | |
24290 | ||
24291 | @deftypefn {Built-in Function} {int} __builtin_riscv_cv_alu_slet (int32_t, int32_t) | |
24292 | Generated assembler @code{cv.slet} | |
24293 | @end deftypefn | |
24294 | ||
24295 | @deftypefn {Built-in Function} {int} __builtin_riscv_cv_alu_sletu (uint32_t, uint32_t) | |
24296 | Generated assembler @code{cv.sletu} | |
24297 | @end deftypefn | |
24298 | ||
24299 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_min (int32_t, int32_t) | |
24300 | Generated assembler @code{cv.min} | |
24301 | @end deftypefn | |
24302 | ||
24303 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_minu (uint32_t, uint32_t) | |
24304 | Generated assembler @code{cv.minu} | |
24305 | @end deftypefn | |
24306 | ||
24307 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_max (int32_t, int32_t) | |
24308 | Generated assembler @code{cv.max} | |
24309 | @end deftypefn | |
24310 | ||
24311 | @deftypefn {Built-in Function} {uint32_tnt} __builtin_riscv_cv_alu_maxu (uint32_t, uint32_t) | |
24312 | Generated assembler @code{cv.maxu} | |
24313 | @end deftypefn | |
24314 | ||
24315 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_exths (int16_t) | |
24316 | Generated assembler @code{cv.exths} | |
24317 | @end deftypefn | |
24318 | ||
24319 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_exthz (uint16_t) | |
24320 | Generated assembler @code{cv.exthz} | |
24321 | @end deftypefn | |
24322 | ||
24323 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_extbs (int8_t) | |
24324 | Generated assembler @code{cv.extbs} | |
24325 | @end deftypefn | |
24326 | ||
24327 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_extbz (uint8_t) | |
24328 | Generated assembler @code{cv.extbz} | |
24329 | @end deftypefn | |
24330 | ||
24331 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_clip (int32_t, uint32_t) | |
24332 | Generated assembler @code{cv.clip} if the uint32_t operand is a constant and an exact power of 2. | |
24333 | Generated assembler @code{cv.clipr} if the it is a register. | |
24334 | @end deftypefn | |
24335 | ||
24336 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_clipu (uint32_t, uint32_t) | |
24337 | Generated assembler @code{cv.clipu} if the uint32_t operand is a constant and an exact power of 2. | |
24338 | Generated assembler @code{cv.clipur} if the it is a register. | |
24339 | @end deftypefn | |
24340 | ||
24341 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_addN (int32_t, int32_t, uint8_t) | |
24342 | Generated assembler @code{cv.addN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31. | |
24343 | Generated assembler @code{cv.addNr} if the it is a register. | |
24344 | @end deftypefn | |
24345 | ||
24346 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_adduN (uint32_t, uint32_t, uint8_t) | |
24347 | Generated assembler @code{cv.adduN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31. | |
24348 | Generated assembler @code{cv.adduNr} if the it is a register. | |
24349 | @end deftypefn | |
24350 | ||
24351 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_addRN (int32_t, int32_t, uint8_t) | |
24352 | Generated assembler @code{cv.addRN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31. | |
24353 | Generated assembler @code{cv.addRNr} if the it is a register. | |
24354 | @end deftypefn | |
24355 | ||
24356 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_adduRN (uint32_t, uint32_t, uint8_t) | |
24357 | Generated assembler @code{cv.adduRN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31. | |
24358 | Generated assembler @code{cv.adduRNr} if the it is a register. | |
24359 | @end deftypefn | |
24360 | ||
24361 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_subN (int32_t, int32_t, uint8_t) | |
24362 | Generated assembler @code{cv.subN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31. | |
24363 | Generated assembler @code{cv.subNr} if the it is a register. | |
24364 | @end deftypefn | |
24365 | ||
24366 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_subuN (uint32_t, uint32_t, uint8_t) | |
24367 | Generated assembler @code{cv.subuN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31. | |
24368 | Generated assembler @code{cv.subuNr} if the it is a register. | |
24369 | @end deftypefn | |
24370 | ||
24371 | @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_subRN (int32_t, int32_t, uint8_t) | |
24372 | Generated assembler @code{cv.subRN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31. | |
24373 | Generated assembler @code{cv.subRNr} if the it is a register. | |
24374 | @end deftypefn | |
24375 | ||
24376 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_subuRN (uint32_t, uint32_t, uint8_t) | |
24377 | Generated assembler @code{cv.subuRN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31. | |
24378 | Generated assembler @code{cv.subuRNr} if the it is a register. | |
24379 | @end deftypefn | |
24380 | ||
14876d6a MB |
24381 | These built-in functions are available for the CORE-V Event Load machine |
24382 | architecture. For more information on CORE-V ELW builtins, please see | |
24383 | @uref{https://github.com/openhwgroup/core-v-sw/blob/master/specifications/corev-builtin-spec.md#listing-of-event-load-word-builtins-xcvelw} | |
24384 | ||
24385 | @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_elw_elw (uint32_t *) | |
24386 | Generated assembler @code{cv.elw} | |
24387 | @end deftypefn | |
24388 | ||
d77de738 ML |
24389 | @node RX Built-in Functions |
24390 | @subsection RX Built-in Functions | |
24391 | GCC supports some of the RX instructions which cannot be expressed in | |
24392 | the C programming language via the use of built-in functions. The | |
24393 | following functions are supported: | |
24394 | ||
f25efe50 | 24395 | @defbuiltin{void __builtin_rx_brk (void)} |
d77de738 | 24396 | Generates the @code{brk} machine instruction. |
f25efe50 | 24397 | @enddefbuiltin |
d77de738 | 24398 | |
f25efe50 | 24399 | @defbuiltin{void __builtin_rx_clrpsw (int)} |
d77de738 ML |
24400 | Generates the @code{clrpsw} machine instruction to clear the specified |
24401 | bit in the processor status word. | |
f25efe50 | 24402 | @enddefbuiltin |
d77de738 | 24403 | |
f25efe50 | 24404 | @defbuiltin{void __builtin_rx_int (int)} |
d77de738 ML |
24405 | Generates the @code{int} machine instruction to generate an interrupt |
24406 | with the specified value. | |
f25efe50 | 24407 | @enddefbuiltin |
d77de738 | 24408 | |
f25efe50 | 24409 | @defbuiltin{void __builtin_rx_machi (int, int)} |
d77de738 ML |
24410 | Generates the @code{machi} machine instruction to add the result of |
24411 | multiplying the top 16 bits of the two arguments into the | |
24412 | accumulator. | |
f25efe50 | 24413 | @enddefbuiltin |
d77de738 | 24414 | |
f25efe50 | 24415 | @defbuiltin{void __builtin_rx_maclo (int, int)} |
d77de738 ML |
24416 | Generates the @code{maclo} machine instruction to add the result of |
24417 | multiplying the bottom 16 bits of the two arguments into the | |
24418 | accumulator. | |
f25efe50 | 24419 | @enddefbuiltin |
d77de738 | 24420 | |
f25efe50 | 24421 | @defbuiltin{void __builtin_rx_mulhi (int, int)} |
d77de738 ML |
24422 | Generates the @code{mulhi} machine instruction to place the result of |
24423 | multiplying the top 16 bits of the two arguments into the | |
24424 | accumulator. | |
f25efe50 | 24425 | @enddefbuiltin |
d77de738 | 24426 | |
f25efe50 | 24427 | @defbuiltin{void __builtin_rx_mullo (int, int)} |
d77de738 ML |
24428 | Generates the @code{mullo} machine instruction to place the result of |
24429 | multiplying the bottom 16 bits of the two arguments into the | |
24430 | accumulator. | |
f25efe50 | 24431 | @enddefbuiltin |
d77de738 | 24432 | |
ff99671a | 24433 | @defbuiltin{int __builtin_rx_mvfachi (void)} |
d77de738 ML |
24434 | Generates the @code{mvfachi} machine instruction to read the top |
24435 | 32 bits of the accumulator. | |
f25efe50 | 24436 | @enddefbuiltin |
d77de738 | 24437 | |
ff99671a | 24438 | @defbuiltin{int __builtin_rx_mvfacmi (void)} |
d77de738 ML |
24439 | Generates the @code{mvfacmi} machine instruction to read the middle |
24440 | 32 bits of the accumulator. | |
f25efe50 | 24441 | @enddefbuiltin |
d77de738 | 24442 | |
f25efe50 | 24443 | @defbuiltin{int __builtin_rx_mvfc (int)} |
d77de738 ML |
24444 | Generates the @code{mvfc} machine instruction which reads the control |
24445 | register specified in its argument and returns its value. | |
f25efe50 | 24446 | @enddefbuiltin |
d77de738 | 24447 | |
f25efe50 | 24448 | @defbuiltin{void __builtin_rx_mvtachi (int)} |
d77de738 ML |
24449 | Generates the @code{mvtachi} machine instruction to set the top |
24450 | 32 bits of the accumulator. | |
f25efe50 | 24451 | @enddefbuiltin |
d77de738 | 24452 | |
f25efe50 | 24453 | @defbuiltin{void __builtin_rx_mvtaclo (int)} |
d77de738 ML |
24454 | Generates the @code{mvtaclo} machine instruction to set the bottom |
24455 | 32 bits of the accumulator. | |
f25efe50 | 24456 | @enddefbuiltin |
d77de738 | 24457 | |
23795106 | 24458 | @defbuiltin{void __builtin_rx_mvtc (int @var{reg}, int @var{val})} |
d77de738 ML |
24459 | Generates the @code{mvtc} machine instruction which sets control |
24460 | register number @code{reg} to @code{val}. | |
f25efe50 | 24461 | @enddefbuiltin |
d77de738 | 24462 | |
f25efe50 | 24463 | @defbuiltin{void __builtin_rx_mvtipl (int)} |
d77de738 ML |
24464 | Generates the @code{mvtipl} machine instruction set the interrupt |
24465 | priority level. | |
f25efe50 | 24466 | @enddefbuiltin |
d77de738 | 24467 | |
f25efe50 | 24468 | @defbuiltin{void __builtin_rx_racw (int)} |
d77de738 ML |
24469 | Generates the @code{racw} machine instruction to round the accumulator |
24470 | according to the specified mode. | |
f25efe50 | 24471 | @enddefbuiltin |
d77de738 | 24472 | |
f25efe50 | 24473 | @defbuiltin{int __builtin_rx_revw (int)} |
d77de738 ML |
24474 | Generates the @code{revw} machine instruction which swaps the bytes in |
24475 | the argument so that bits 0--7 now occupy bits 8--15 and vice versa, | |
24476 | and also bits 16--23 occupy bits 24--31 and vice versa. | |
f25efe50 | 24477 | @enddefbuiltin |
d77de738 | 24478 | |
f25efe50 | 24479 | @defbuiltin{void __builtin_rx_rmpa (void)} |
d77de738 ML |
24480 | Generates the @code{rmpa} machine instruction which initiates a |
24481 | repeated multiply and accumulate sequence. | |
f25efe50 | 24482 | @enddefbuiltin |
d77de738 | 24483 | |
f25efe50 | 24484 | @defbuiltin{void __builtin_rx_round (float)} |
d77de738 ML |
24485 | Generates the @code{round} machine instruction which returns the |
24486 | floating-point argument rounded according to the current rounding mode | |
24487 | set in the floating-point status word register. | |
f25efe50 | 24488 | @enddefbuiltin |
d77de738 | 24489 | |
f25efe50 | 24490 | @defbuiltin{int __builtin_rx_sat (int)} |
d77de738 ML |
24491 | Generates the @code{sat} machine instruction which returns the |
24492 | saturated value of the argument. | |
f25efe50 | 24493 | @enddefbuiltin |
d77de738 | 24494 | |
f25efe50 | 24495 | @defbuiltin{void __builtin_rx_setpsw (int)} |
d77de738 ML |
24496 | Generates the @code{setpsw} machine instruction to set the specified |
24497 | bit in the processor status word. | |
f25efe50 | 24498 | @enddefbuiltin |
d77de738 | 24499 | |
f25efe50 | 24500 | @defbuiltin{void __builtin_rx_wait (void)} |
d77de738 | 24501 | Generates the @code{wait} machine instruction. |
f25efe50 | 24502 | @enddefbuiltin |
d77de738 ML |
24503 | |
24504 | @node S/390 System z Built-in Functions | |
24505 | @subsection S/390 System z Built-in Functions | |
f25efe50 | 24506 | @defbuiltin{int __builtin_tbegin (void*)} |
d77de738 ML |
24507 | Generates the @code{tbegin} machine instruction starting a |
24508 | non-constrained hardware transaction. If the parameter is non-NULL the | |
24509 | memory area is used to store the transaction diagnostic buffer and | |
24510 | will be passed as first operand to @code{tbegin}. This buffer can be | |
24511 | defined using the @code{struct __htm_tdb} C struct defined in | |
24512 | @code{htmintrin.h} and must reside on a double-word boundary. The | |
24513 | second tbegin operand is set to @code{0xff0c}. This enables | |
24514 | save/restore of all GPRs and disables aborts for FPR and AR | |
24515 | manipulations inside the transaction body. The condition code set by | |
24516 | the tbegin instruction is returned as integer value. The tbegin | |
24517 | instruction by definition overwrites the content of all FPRs. The | |
24518 | compiler will generate code which saves and restores the FPRs. For | |
24519 | soft-float code it is recommended to used the @code{*_nofloat} | |
24520 | variant. In order to prevent a TDB from being written it is required | |
24521 | to pass a constant zero value as parameter. Passing a zero value | |
24522 | through a variable is not sufficient. Although modifications of | |
24523 | access registers inside the transaction will not trigger an | |
24524 | transaction abort it is not supported to actually modify them. Access | |
24525 | registers do not get saved when entering a transaction. They will have | |
24526 | undefined state when reaching the abort code. | |
f25efe50 | 24527 | @enddefbuiltin |
d77de738 ML |
24528 | |
24529 | Macros for the possible return codes of tbegin are defined in the | |
24530 | @code{htmintrin.h} header file: | |
24531 | ||
f25efe50 | 24532 | @defmac _HTM_TBEGIN_STARTED |
d77de738 ML |
24533 | @code{tbegin} has been executed as part of normal processing. The |
24534 | transaction body is supposed to be executed. | |
f25efe50 AA |
24535 | @end defmac |
24536 | ||
24537 | @defmac _HTM_TBEGIN_INDETERMINATE | |
d77de738 ML |
24538 | The transaction was aborted due to an indeterminate condition which |
24539 | might be persistent. | |
f25efe50 AA |
24540 | @end defmac |
24541 | ||
24542 | @defmac _HTM_TBEGIN_TRANSIENT | |
d77de738 ML |
24543 | The transaction aborted due to a transient failure. The transaction |
24544 | should be re-executed in that case. | |
f25efe50 AA |
24545 | @end defmac |
24546 | ||
24547 | @defmac _HTM_TBEGIN_PERSISTENT | |
d77de738 ML |
24548 | The transaction aborted due to a persistent failure. Re-execution |
24549 | under same circumstances will not be productive. | |
f25efe50 | 24550 | @end defmac |
d77de738 ML |
24551 | |
24552 | @defmac _HTM_FIRST_USER_ABORT_CODE | |
24553 | The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h} | |
24554 | specifies the first abort code which can be used for | |
24555 | @code{__builtin_tabort}. Values below this threshold are reserved for | |
24556 | machine use. | |
24557 | @end defmac | |
24558 | ||
24559 | @deftp {Data type} {struct __htm_tdb} | |
24560 | The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes | |
24561 | the structure of the transaction diagnostic block as specified in the | |
24562 | Principles of Operation manual chapter 5-91. | |
24563 | @end deftp | |
24564 | ||
f25efe50 | 24565 | @defbuiltin{int __builtin_tbegin_nofloat (void*)} |
d77de738 ML |
24566 | Same as @code{__builtin_tbegin} but without FPR saves and restores. |
24567 | Using this variant in code making use of FPRs will leave the FPRs in | |
24568 | undefined state when entering the transaction abort handler code. | |
f25efe50 | 24569 | @enddefbuiltin |
d77de738 | 24570 | |
f25efe50 | 24571 | @defbuiltin{int __builtin_tbegin_retry (void*, int)} |
d77de738 ML |
24572 | In addition to @code{__builtin_tbegin} a loop for transient failures |
24573 | is generated. If tbegin returns a condition code of 2 the transaction | |
24574 | will be retried as often as specified in the second argument. The | |
24575 | perform processor assist instruction is used to tell the CPU about the | |
24576 | number of fails so far. | |
f25efe50 | 24577 | @enddefbuiltin |
d77de738 | 24578 | |
f25efe50 | 24579 | @defbuiltin{int __builtin_tbegin_retry_nofloat (void*, int)} |
d77de738 ML |
24580 | Same as @code{__builtin_tbegin_retry} but without FPR saves and |
24581 | restores. Using this variant in code making use of FPRs will leave | |
24582 | the FPRs in undefined state when entering the transaction abort | |
24583 | handler code. | |
f25efe50 | 24584 | @enddefbuiltin |
d77de738 | 24585 | |
f25efe50 | 24586 | @defbuiltin{void __builtin_tbeginc (void)} |
d77de738 ML |
24587 | Generates the @code{tbeginc} machine instruction starting a constrained |
24588 | hardware transaction. The second operand is set to @code{0xff08}. | |
f25efe50 | 24589 | @enddefbuiltin |
d77de738 | 24590 | |
f25efe50 | 24591 | @defbuiltin{int __builtin_tend (void)} |
d77de738 ML |
24592 | Generates the @code{tend} machine instruction finishing a transaction |
24593 | and making the changes visible to other threads. The condition code | |
24594 | generated by tend is returned as integer value. | |
f25efe50 | 24595 | @enddefbuiltin |
d77de738 | 24596 | |
f25efe50 | 24597 | @defbuiltin{void __builtin_tabort (int)} |
d77de738 ML |
24598 | Generates the @code{tabort} machine instruction with the specified |
24599 | abort code. Abort codes from 0 through 255 are reserved and will | |
24600 | result in an error message. | |
f25efe50 | 24601 | @enddefbuiltin |
d77de738 | 24602 | |
f25efe50 | 24603 | @defbuiltin{void __builtin_tx_assist (int)} |
d77de738 ML |
24604 | Generates the @code{ppa rX,rY,1} machine instruction. Where the |
24605 | integer parameter is loaded into rX and a value of zero is loaded into | |
24606 | rY. The integer parameter specifies the number of times the | |
24607 | transaction repeatedly aborted. | |
f25efe50 | 24608 | @enddefbuiltin |
d77de738 | 24609 | |
f25efe50 | 24610 | @defbuiltin{int __builtin_tx_nesting_depth (void)} |
d77de738 ML |
24611 | Generates the @code{etnd} machine instruction. The current nesting |
24612 | depth is returned as integer value. For a nesting depth of 0 the code | |
24613 | is not executed as part of an transaction. | |
f25efe50 | 24614 | @enddefbuiltin |
d77de738 | 24615 | |
f25efe50 | 24616 | @defbuiltin{void __builtin_non_tx_store (uint64_t *, uint64_t)} |
d77de738 ML |
24617 | |
24618 | Generates the @code{ntstg} machine instruction. The second argument | |
24619 | is written to the first arguments location. The store operation will | |
24620 | not be rolled-back in case of an transaction abort. | |
f25efe50 | 24621 | @enddefbuiltin |
d77de738 ML |
24622 | |
24623 | @node SH Built-in Functions | |
24624 | @subsection SH Built-in Functions | |
24625 | The following built-in functions are supported on the SH1, SH2, SH3 and SH4 | |
24626 | families of processors: | |
24627 | ||
f25efe50 | 24628 | @defbuiltin{{void} __builtin_set_thread_pointer (void *@var{ptr})} |
d77de738 ML |
24629 | Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually |
24630 | used by system code that manages threads and execution contexts. The compiler | |
24631 | normally does not generate code that modifies the contents of @samp{GBR} and | |
24632 | thus the value is preserved across function calls. Changing the @samp{GBR} | |
24633 | value in user code must be done with caution, since the compiler might use | |
24634 | @samp{GBR} in order to access thread local variables. | |
24635 | ||
f25efe50 | 24636 | @enddefbuiltin |
d77de738 | 24637 | |
f25efe50 | 24638 | @defbuiltin{{void *} __builtin_thread_pointer (void)} |
d77de738 ML |
24639 | Returns the value that is currently set in the @samp{GBR} register. |
24640 | Memory loads and stores that use the thread pointer as a base address are | |
24641 | turned into @samp{GBR} based displacement loads and stores, if possible. | |
24642 | For example: | |
24643 | @smallexample | |
24644 | struct my_tcb | |
24645 | @{ | |
24646 | int a, b, c, d, e; | |
24647 | @}; | |
24648 | ||
24649 | int get_tcb_value (void) | |
24650 | @{ | |
24651 | // Generate @samp{mov.l @@(8,gbr),r0} instruction | |
24652 | return ((my_tcb*)__builtin_thread_pointer ())->c; | |
24653 | @} | |
24654 | ||
24655 | @end smallexample | |
f25efe50 | 24656 | @enddefbuiltin |
d77de738 | 24657 | |
f25efe50 | 24658 | @defbuiltin{{unsigned int} __builtin_sh_get_fpscr (void)} |
d77de738 | 24659 | Returns the value that is currently set in the @samp{FPSCR} register. |
f25efe50 | 24660 | @enddefbuiltin |
d77de738 | 24661 | |
f25efe50 | 24662 | @defbuiltin{{void} __builtin_sh_set_fpscr (unsigned int @var{val})} |
d77de738 ML |
24663 | Sets the @samp{FPSCR} register to the specified value @var{val}, while |
24664 | preserving the current values of the FR, SZ and PR bits. | |
f25efe50 | 24665 | @enddefbuiltin |
d77de738 ML |
24666 | |
24667 | @node SPARC VIS Built-in Functions | |
24668 | @subsection SPARC VIS Built-in Functions | |
24669 | ||
24670 | GCC supports SIMD operations on the SPARC using both the generic vector | |
24671 | extensions (@pxref{Vector Extensions}) as well as built-in functions for | |
24672 | the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} | |
24673 | switch, the VIS extension is exposed as the following built-in functions: | |
24674 | ||
24675 | @smallexample | |
24676 | typedef int v1si __attribute__ ((vector_size (4))); | |
24677 | typedef int v2si __attribute__ ((vector_size (8))); | |
24678 | typedef short v4hi __attribute__ ((vector_size (8))); | |
24679 | typedef short v2hi __attribute__ ((vector_size (4))); | |
24680 | typedef unsigned char v8qi __attribute__ ((vector_size (8))); | |
24681 | typedef unsigned char v4qi __attribute__ ((vector_size (4))); | |
24682 | ||
24683 | void __builtin_vis_write_gsr (int64_t); | |
24684 | int64_t __builtin_vis_read_gsr (void); | |
24685 | ||
24686 | void * __builtin_vis_alignaddr (void *, long); | |
24687 | void * __builtin_vis_alignaddrl (void *, long); | |
24688 | int64_t __builtin_vis_faligndatadi (int64_t, int64_t); | |
24689 | v2si __builtin_vis_faligndatav2si (v2si, v2si); | |
24690 | v4hi __builtin_vis_faligndatav4hi (v4si, v4si); | |
24691 | v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); | |
24692 | ||
24693 | v4hi __builtin_vis_fexpand (v4qi); | |
24694 | ||
24695 | v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); | |
24696 | v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); | |
24697 | v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); | |
24698 | v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); | |
24699 | v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); | |
24700 | v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); | |
24701 | v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); | |
24702 | ||
24703 | v4qi __builtin_vis_fpack16 (v4hi); | |
24704 | v8qi __builtin_vis_fpack32 (v2si, v8qi); | |
24705 | v2hi __builtin_vis_fpackfix (v2si); | |
24706 | v8qi __builtin_vis_fpmerge (v4qi, v4qi); | |
24707 | ||
24708 | int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); | |
24709 | ||
24710 | long __builtin_vis_edge8 (void *, void *); | |
24711 | long __builtin_vis_edge8l (void *, void *); | |
24712 | long __builtin_vis_edge16 (void *, void *); | |
24713 | long __builtin_vis_edge16l (void *, void *); | |
24714 | long __builtin_vis_edge32 (void *, void *); | |
24715 | long __builtin_vis_edge32l (void *, void *); | |
24716 | ||
24717 | long __builtin_vis_fcmple16 (v4hi, v4hi); | |
24718 | long __builtin_vis_fcmple32 (v2si, v2si); | |
24719 | long __builtin_vis_fcmpne16 (v4hi, v4hi); | |
24720 | long __builtin_vis_fcmpne32 (v2si, v2si); | |
24721 | long __builtin_vis_fcmpgt16 (v4hi, v4hi); | |
24722 | long __builtin_vis_fcmpgt32 (v2si, v2si); | |
24723 | long __builtin_vis_fcmpeq16 (v4hi, v4hi); | |
24724 | long __builtin_vis_fcmpeq32 (v2si, v2si); | |
24725 | ||
24726 | v4hi __builtin_vis_fpadd16 (v4hi, v4hi); | |
24727 | v2hi __builtin_vis_fpadd16s (v2hi, v2hi); | |
24728 | v2si __builtin_vis_fpadd32 (v2si, v2si); | |
24729 | v1si __builtin_vis_fpadd32s (v1si, v1si); | |
24730 | v4hi __builtin_vis_fpsub16 (v4hi, v4hi); | |
24731 | v2hi __builtin_vis_fpsub16s (v2hi, v2hi); | |
24732 | v2si __builtin_vis_fpsub32 (v2si, v2si); | |
24733 | v1si __builtin_vis_fpsub32s (v1si, v1si); | |
24734 | ||
24735 | long __builtin_vis_array8 (long, long); | |
24736 | long __builtin_vis_array16 (long, long); | |
24737 | long __builtin_vis_array32 (long, long); | |
24738 | @end smallexample | |
24739 | ||
24740 | When you use the @option{-mvis2} switch, the VIS version 2.0 built-in | |
24741 | functions also become available: | |
24742 | ||
24743 | @smallexample | |
24744 | long __builtin_vis_bmask (long, long); | |
24745 | int64_t __builtin_vis_bshuffledi (int64_t, int64_t); | |
24746 | v2si __builtin_vis_bshufflev2si (v2si, v2si); | |
24747 | v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); | |
24748 | v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); | |
24749 | ||
24750 | long __builtin_vis_edge8n (void *, void *); | |
24751 | long __builtin_vis_edge8ln (void *, void *); | |
24752 | long __builtin_vis_edge16n (void *, void *); | |
24753 | long __builtin_vis_edge16ln (void *, void *); | |
24754 | long __builtin_vis_edge32n (void *, void *); | |
24755 | long __builtin_vis_edge32ln (void *, void *); | |
24756 | @end smallexample | |
24757 | ||
24758 | When you use the @option{-mvis3} switch, the VIS version 3.0 built-in | |
24759 | functions also become available: | |
24760 | ||
24761 | @smallexample | |
24762 | void __builtin_vis_cmask8 (long); | |
24763 | void __builtin_vis_cmask16 (long); | |
24764 | void __builtin_vis_cmask32 (long); | |
24765 | ||
24766 | v4hi __builtin_vis_fchksm16 (v4hi, v4hi); | |
24767 | ||
24768 | v4hi __builtin_vis_fsll16 (v4hi, v4hi); | |
24769 | v4hi __builtin_vis_fslas16 (v4hi, v4hi); | |
24770 | v4hi __builtin_vis_fsrl16 (v4hi, v4hi); | |
24771 | v4hi __builtin_vis_fsra16 (v4hi, v4hi); | |
24772 | v2si __builtin_vis_fsll16 (v2si, v2si); | |
24773 | v2si __builtin_vis_fslas16 (v2si, v2si); | |
24774 | v2si __builtin_vis_fsrl16 (v2si, v2si); | |
24775 | v2si __builtin_vis_fsra16 (v2si, v2si); | |
24776 | ||
24777 | long __builtin_vis_pdistn (v8qi, v8qi); | |
24778 | ||
24779 | v4hi __builtin_vis_fmean16 (v4hi, v4hi); | |
24780 | ||
24781 | int64_t __builtin_vis_fpadd64 (int64_t, int64_t); | |
24782 | int64_t __builtin_vis_fpsub64 (int64_t, int64_t); | |
24783 | ||
24784 | v4hi __builtin_vis_fpadds16 (v4hi, v4hi); | |
24785 | v2hi __builtin_vis_fpadds16s (v2hi, v2hi); | |
24786 | v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); | |
24787 | v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); | |
24788 | v2si __builtin_vis_fpadds32 (v2si, v2si); | |
24789 | v1si __builtin_vis_fpadds32s (v1si, v1si); | |
24790 | v2si __builtin_vis_fpsubs32 (v2si, v2si); | |
24791 | v1si __builtin_vis_fpsubs32s (v1si, v1si); | |
24792 | ||
24793 | long __builtin_vis_fucmple8 (v8qi, v8qi); | |
24794 | long __builtin_vis_fucmpne8 (v8qi, v8qi); | |
24795 | long __builtin_vis_fucmpgt8 (v8qi, v8qi); | |
24796 | long __builtin_vis_fucmpeq8 (v8qi, v8qi); | |
24797 | ||
24798 | float __builtin_vis_fhadds (float, float); | |
24799 | double __builtin_vis_fhaddd (double, double); | |
24800 | float __builtin_vis_fhsubs (float, float); | |
24801 | double __builtin_vis_fhsubd (double, double); | |
24802 | float __builtin_vis_fnhadds (float, float); | |
24803 | double __builtin_vis_fnhaddd (double, double); | |
24804 | ||
24805 | int64_t __builtin_vis_umulxhi (int64_t, int64_t); | |
24806 | int64_t __builtin_vis_xmulx (int64_t, int64_t); | |
24807 | int64_t __builtin_vis_xmulxhi (int64_t, int64_t); | |
24808 | @end smallexample | |
24809 | ||
24810 | When you use the @option{-mvis4} switch, the VIS version 4.0 built-in | |
24811 | functions also become available: | |
24812 | ||
24813 | @smallexample | |
24814 | v8qi __builtin_vis_fpadd8 (v8qi, v8qi); | |
24815 | v8qi __builtin_vis_fpadds8 (v8qi, v8qi); | |
24816 | v8qi __builtin_vis_fpaddus8 (v8qi, v8qi); | |
24817 | v4hi __builtin_vis_fpaddus16 (v4hi, v4hi); | |
24818 | ||
24819 | v8qi __builtin_vis_fpsub8 (v8qi, v8qi); | |
24820 | v8qi __builtin_vis_fpsubs8 (v8qi, v8qi); | |
24821 | v8qi __builtin_vis_fpsubus8 (v8qi, v8qi); | |
24822 | v4hi __builtin_vis_fpsubus16 (v4hi, v4hi); | |
24823 | ||
24824 | long __builtin_vis_fpcmple8 (v8qi, v8qi); | |
24825 | long __builtin_vis_fpcmpgt8 (v8qi, v8qi); | |
24826 | long __builtin_vis_fpcmpule16 (v4hi, v4hi); | |
24827 | long __builtin_vis_fpcmpugt16 (v4hi, v4hi); | |
24828 | long __builtin_vis_fpcmpule32 (v2si, v2si); | |
24829 | long __builtin_vis_fpcmpugt32 (v2si, v2si); | |
24830 | ||
24831 | v8qi __builtin_vis_fpmax8 (v8qi, v8qi); | |
24832 | v4hi __builtin_vis_fpmax16 (v4hi, v4hi); | |
24833 | v2si __builtin_vis_fpmax32 (v2si, v2si); | |
24834 | ||
24835 | v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi); | |
24836 | v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi); | |
24837 | v2si __builtin_vis_fpmaxu32 (v2si, v2si); | |
24838 | ||
24839 | v8qi __builtin_vis_fpmin8 (v8qi, v8qi); | |
24840 | v4hi __builtin_vis_fpmin16 (v4hi, v4hi); | |
24841 | v2si __builtin_vis_fpmin32 (v2si, v2si); | |
24842 | ||
24843 | v8qi __builtin_vis_fpminu8 (v8qi, v8qi); | |
24844 | v4hi __builtin_vis_fpminu16 (v4hi, v4hi); | |
24845 | v2si __builtin_vis_fpminu32 (v2si, v2si); | |
24846 | @end smallexample | |
24847 | ||
24848 | When you use the @option{-mvis4b} switch, the VIS version 4.0B | |
24849 | built-in functions also become available: | |
24850 | ||
24851 | @smallexample | |
24852 | v8qi __builtin_vis_dictunpack8 (double, int); | |
24853 | v4hi __builtin_vis_dictunpack16 (double, int); | |
24854 | v2si __builtin_vis_dictunpack32 (double, int); | |
24855 | ||
24856 | long __builtin_vis_fpcmple8shl (v8qi, v8qi, int); | |
24857 | long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int); | |
24858 | long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int); | |
24859 | long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int); | |
24860 | ||
24861 | long __builtin_vis_fpcmple16shl (v4hi, v4hi, int); | |
24862 | long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int); | |
24863 | long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int); | |
24864 | long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int); | |
24865 | ||
24866 | long __builtin_vis_fpcmple32shl (v2si, v2si, int); | |
24867 | long __builtin_vis_fpcmpgt32shl (v2si, v2si, int); | |
24868 | long __builtin_vis_fpcmpeq32shl (v2si, v2si, int); | |
24869 | long __builtin_vis_fpcmpne32shl (v2si, v2si, int); | |
24870 | ||
24871 | long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int); | |
24872 | long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int); | |
24873 | long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int); | |
24874 | long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int); | |
24875 | long __builtin_vis_fpcmpule32shl (v2si, v2si, int); | |
24876 | long __builtin_vis_fpcmpugt32shl (v2si, v2si, int); | |
24877 | ||
24878 | long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int); | |
24879 | long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int); | |
24880 | long __builtin_vis_fpcmpde32shl (v2si, v2si, int); | |
24881 | ||
24882 | long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int); | |
24883 | long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int); | |
24884 | long __builtin_vis_fpcmpur32shl (v2si, v2si, int); | |
24885 | @end smallexample | |
24886 | ||
24887 | @node TI C6X Built-in Functions | |
24888 | @subsection TI C6X Built-in Functions | |
24889 | ||
24890 | GCC provides intrinsics to access certain instructions of the TI C6X | |
24891 | processors. These intrinsics, listed below, are available after | |
24892 | inclusion of the @code{c6x_intrinsics.h} header file. They map directly | |
24893 | to C6X instructions. | |
24894 | ||
24895 | @smallexample | |
24896 | int _sadd (int, int); | |
24897 | int _ssub (int, int); | |
24898 | int _sadd2 (int, int); | |
24899 | int _ssub2 (int, int); | |
24900 | long long _mpy2 (int, int); | |
24901 | long long _smpy2 (int, int); | |
24902 | int _add4 (int, int); | |
24903 | int _sub4 (int, int); | |
24904 | int _saddu4 (int, int); | |
24905 | ||
24906 | int _smpy (int, int); | |
24907 | int _smpyh (int, int); | |
24908 | int _smpyhl (int, int); | |
24909 | int _smpylh (int, int); | |
24910 | ||
24911 | int _sshl (int, int); | |
24912 | int _subc (int, int); | |
24913 | ||
24914 | int _avg2 (int, int); | |
24915 | int _avgu4 (int, int); | |
24916 | ||
24917 | int _clrr (int, int); | |
24918 | int _extr (int, int); | |
24919 | int _extru (int, int); | |
24920 | int _abs (int); | |
24921 | int _abs2 (int); | |
24922 | @end smallexample | |
24923 | ||
24924 | @node x86 Built-in Functions | |
24925 | @subsection x86 Built-in Functions | |
24926 | ||
24927 | These built-in functions are available for the x86-32 and x86-64 family | |
24928 | of computers, depending on the command-line switches used. | |
24929 | ||
24930 | If you specify command-line switches such as @option{-msse}, | |
24931 | the compiler could use the extended instruction sets even if the built-ins | |
24932 | are not used explicitly in the program. For this reason, applications | |
24933 | that perform run-time CPU detection must compile separate files for each | |
24934 | supported architecture, using the appropriate flags. In particular, | |
24935 | the file containing the CPU detection code should be compiled without | |
24936 | these options. | |
24937 | ||
24938 | The following machine modes are available for use with MMX built-in functions | |
24939 | (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, | |
24940 | @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a | |
24941 | vector of eight 8-bit integers. Some of the built-in functions operate on | |
24942 | MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. | |
24943 | ||
24944 | If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector | |
24945 | of two 32-bit floating-point values. | |
24946 | ||
24947 | If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit | |
24948 | floating-point values. Some instructions use a vector of four 32-bit | |
24949 | integers, these use @code{V4SI}. Finally, some instructions operate on an | |
24950 | entire vector register, interpreting it as a 128-bit integer, these use mode | |
24951 | @code{TI}. | |
24952 | ||
24953 | The x86-32 and x86-64 family of processors use additional built-in | |
24954 | functions for efficient use of @code{TF} (@code{__float128}) 128-bit | |
24955 | floating point and @code{TC} 128-bit complex floating-point values. | |
24956 | ||
f25efe50 | 24957 | The following floating-point built-in functions are always available: |
d77de738 | 24958 | |
f25efe50 AA |
24959 | @defbuiltin{__float128 __builtin_fabsq (__float128 @var{x}))} |
24960 | Computes the absolute value of @var{x}. | |
24961 | @enddefbuiltin | |
d77de738 | 24962 | |
f25efe50 AA |
24963 | @defbuiltin{__float128 __builtin_copysignq (__float128 @var{x}, @ |
24964 | __float128 @var{y})} | |
24965 | Copies the sign of @var{y} into @var{x} and returns the new value of | |
24966 | @var{x}. | |
24967 | @enddefbuiltin | |
d77de738 | 24968 | |
f25efe50 | 24969 | @defbuiltin{__float128 __builtin_infq (void)} |
d77de738 | 24970 | Similar to @code{__builtin_inf}, except the return type is @code{__float128}. |
f25efe50 | 24971 | @enddefbuiltin |
d77de738 | 24972 | |
f25efe50 | 24973 | @defbuiltin{__float128 __builtin_huge_valq (void)} |
d77de738 | 24974 | Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. |
f25efe50 | 24975 | @enddefbuiltin |
d77de738 | 24976 | |
f25efe50 | 24977 | @defbuiltin{__float128 __builtin_nanq (void)} |
d77de738 | 24978 | Similar to @code{__builtin_nan}, except the return type is @code{__float128}. |
f25efe50 | 24979 | @enddefbuiltin |
d77de738 | 24980 | |
f25efe50 | 24981 | @defbuiltin{__float128 __builtin_nansq (void)} |
d77de738 | 24982 | Similar to @code{__builtin_nans}, except the return type is @code{__float128}. |
f25efe50 | 24983 | @enddefbuiltin |
d77de738 ML |
24984 | |
24985 | The following built-in function is always available. | |
24986 | ||
f25efe50 | 24987 | @defbuiltin{void __builtin_ia32_pause (void)} |
d77de738 ML |
24988 | Generates the @code{pause} machine instruction with a compiler memory |
24989 | barrier. | |
f25efe50 | 24990 | @enddefbuiltin |
d77de738 ML |
24991 | |
24992 | The following built-in functions are always available and can be used to | |
24993 | check the target platform type. | |
24994 | ||
f25efe50 | 24995 | @defbuiltin{void __builtin_cpu_init (void)} |
d77de738 ML |
24996 | This function runs the CPU detection code to check the type of CPU and the |
24997 | features supported. This built-in function needs to be invoked along with the built-in functions | |
24998 | to check CPU type and features, @code{__builtin_cpu_is} and | |
24999 | @code{__builtin_cpu_supports}, only when used in a function that is | |
25000 | executed before any constructors are called. The CPU detection code is | |
25001 | automatically executed in a very high priority constructor. | |
25002 | ||
25003 | For example, this function has to be used in @code{ifunc} resolvers that | |
25004 | check for CPU type using the built-in functions @code{__builtin_cpu_is} | |
25005 | and @code{__builtin_cpu_supports}, or in constructors on targets that | |
25006 | don't support constructor priority. | |
25007 | @smallexample | |
25008 | ||
25009 | static void (*resolve_memcpy (void)) (void) | |
25010 | @{ | |
25011 | // ifunc resolvers fire before constructors, explicitly call the init | |
25012 | // function. | |
25013 | __builtin_cpu_init (); | |
25014 | if (__builtin_cpu_supports ("ssse3")) | |
25015 | return ssse3_memcpy; // super fast memcpy with ssse3 instructions. | |
25016 | else | |
25017 | return default_memcpy; | |
25018 | @} | |
25019 | ||
25020 | void *memcpy (void *, const void *, size_t) | |
25021 | __attribute__ ((ifunc ("resolve_memcpy"))); | |
25022 | @end smallexample | |
25023 | ||
f25efe50 | 25024 | @enddefbuiltin |
d77de738 | 25025 | |
f25efe50 | 25026 | @defbuiltin{int __builtin_cpu_is (const char *@var{cpuname})} |
d77de738 ML |
25027 | This function returns a positive integer if the run-time CPU |
25028 | is of type @var{cpuname} | |
25029 | and returns @code{0} otherwise. The following CPU names can be detected: | |
25030 | ||
25031 | @table @samp | |
25032 | @item amd | |
25033 | AMD CPU. | |
25034 | ||
25035 | @item intel | |
25036 | Intel CPU. | |
25037 | ||
25038 | @item atom | |
25039 | Intel Atom CPU. | |
25040 | ||
25041 | @item slm | |
25042 | Intel Silvermont CPU. | |
25043 | ||
25044 | @item core2 | |
25045 | Intel Core 2 CPU. | |
25046 | ||
25047 | @item corei7 | |
25048 | Intel Core i7 CPU. | |
25049 | ||
25050 | @item nehalem | |
25051 | Intel Core i7 Nehalem CPU. | |
25052 | ||
25053 | @item westmere | |
25054 | Intel Core i7 Westmere CPU. | |
25055 | ||
25056 | @item sandybridge | |
25057 | Intel Core i7 Sandy Bridge CPU. | |
25058 | ||
25059 | @item ivybridge | |
25060 | Intel Core i7 Ivy Bridge CPU. | |
25061 | ||
25062 | @item haswell | |
25063 | Intel Core i7 Haswell CPU. | |
25064 | ||
25065 | @item broadwell | |
25066 | Intel Core i7 Broadwell CPU. | |
25067 | ||
25068 | @item skylake | |
25069 | Intel Core i7 Skylake CPU. | |
25070 | ||
25071 | @item skylake-avx512 | |
25072 | Intel Core i7 Skylake AVX512 CPU. | |
25073 | ||
25074 | @item cannonlake | |
25075 | Intel Core i7 Cannon Lake CPU. | |
25076 | ||
25077 | @item icelake-client | |
25078 | Intel Core i7 Ice Lake Client CPU. | |
25079 | ||
25080 | @item icelake-server | |
25081 | Intel Core i7 Ice Lake Server CPU. | |
25082 | ||
25083 | @item cascadelake | |
25084 | Intel Core i7 Cascadelake CPU. | |
25085 | ||
25086 | @item tigerlake | |
25087 | Intel Core i7 Tigerlake CPU. | |
25088 | ||
25089 | @item cooperlake | |
25090 | Intel Core i7 Cooperlake CPU. | |
25091 | ||
25092 | @item sapphirerapids | |
25093 | Intel Core i7 sapphirerapids CPU. | |
25094 | ||
25095 | @item alderlake | |
25096 | Intel Core i7 Alderlake CPU. | |
25097 | ||
25098 | @item rocketlake | |
25099 | Intel Core i7 Rocketlake CPU. | |
25100 | ||
25101 | @item graniterapids | |
25102 | Intel Core i7 graniterapids CPU. | |
25103 | ||
a0cb65d3 MZ |
25104 | @item graniterapids-d |
25105 | Intel Core i7 graniterapids D CPU. | |
25106 | ||
faa0e82b HJ |
25107 | @item arrowlake |
25108 | Intel Core i7 Arrow Lake CPU. | |
25109 | ||
25110 | @item arrowlake-s | |
25111 | Intel Core i7 Arrow Lake S CPU. | |
25112 | ||
25113 | @item pantherlake | |
25114 | Intel Core i7 Panther Lake CPU. | |
25115 | ||
d77de738 ML |
25116 | @item bonnell |
25117 | Intel Atom Bonnell CPU. | |
25118 | ||
25119 | @item silvermont | |
25120 | Intel Atom Silvermont CPU. | |
25121 | ||
25122 | @item goldmont | |
25123 | Intel Atom Goldmont CPU. | |
25124 | ||
25125 | @item goldmont-plus | |
25126 | Intel Atom Goldmont Plus CPU. | |
25127 | ||
25128 | @item tremont | |
25129 | Intel Atom Tremont CPU. | |
25130 | ||
25131 | @item sierraforest | |
25132 | Intel Atom Sierra Forest CPU. | |
25133 | ||
25134 | @item grandridge | |
25135 | Intel Atom Grand Ridge CPU. | |
25136 | ||
7370c479 HJ |
25137 | @item clearwaterforest |
25138 | Intel Atom Clearwater Forest CPU. | |
25139 | ||
d77de738 ML |
25140 | @item knl |
25141 | Intel Knights Landing CPU. | |
25142 | ||
25143 | @item knm | |
25144 | Intel Knights Mill CPU. | |
25145 | ||
25146 | @item lujiazui | |
25147 | ZHAOXIN lujiazui CPU. | |
25148 | ||
94c0b26f M |
25149 | @item yongfeng |
25150 | ZHAOXIN yongfeng CPU. | |
25151 | ||
d77de738 ML |
25152 | @item amdfam10h |
25153 | AMD Family 10h CPU. | |
25154 | ||
25155 | @item barcelona | |
25156 | AMD Family 10h Barcelona CPU. | |
25157 | ||
25158 | @item shanghai | |
25159 | AMD Family 10h Shanghai CPU. | |
25160 | ||
25161 | @item istanbul | |
25162 | AMD Family 10h Istanbul CPU. | |
25163 | ||
25164 | @item btver1 | |
25165 | AMD Family 14h CPU. | |
25166 | ||
25167 | @item amdfam15h | |
25168 | AMD Family 15h CPU. | |
25169 | ||
25170 | @item bdver1 | |
25171 | AMD Family 15h Bulldozer version 1. | |
25172 | ||
25173 | @item bdver2 | |
25174 | AMD Family 15h Bulldozer version 2. | |
25175 | ||
25176 | @item bdver3 | |
25177 | AMD Family 15h Bulldozer version 3. | |
25178 | ||
25179 | @item bdver4 | |
25180 | AMD Family 15h Bulldozer version 4. | |
25181 | ||
25182 | @item btver2 | |
25183 | AMD Family 16h CPU. | |
25184 | ||
25185 | @item amdfam17h | |
25186 | AMD Family 17h CPU. | |
25187 | ||
25188 | @item znver1 | |
25189 | AMD Family 17h Zen version 1. | |
25190 | ||
25191 | @item znver2 | |
25192 | AMD Family 17h Zen version 2. | |
25193 | ||
25194 | @item amdfam19h | |
25195 | AMD Family 19h CPU. | |
25196 | ||
25197 | @item znver3 | |
25198 | AMD Family 19h Zen version 3. | |
25199 | ||
25200 | @item znver4 | |
25201 | AMD Family 19h Zen version 4. | |
d77de738 ML |
25202 | @end table |
25203 | ||
25204 | Here is an example: | |
25205 | @smallexample | |
25206 | if (__builtin_cpu_is ("corei7")) | |
25207 | @{ | |
25208 | do_corei7 (); // Core i7 specific implementation. | |
25209 | @} | |
25210 | else | |
25211 | @{ | |
25212 | do_generic (); // Generic implementation. | |
25213 | @} | |
25214 | @end smallexample | |
f25efe50 | 25215 | @enddefbuiltin |
d77de738 | 25216 | |
f25efe50 | 25217 | @defbuiltin{int __builtin_cpu_supports (const char *@var{feature})} |
d77de738 ML |
25218 | This function returns a positive integer if the run-time CPU |
25219 | supports @var{feature} | |
25220 | and returns @code{0} otherwise. The following features can be detected: | |
25221 | ||
25222 | @table @samp | |
25223 | @item cmov | |
25224 | CMOV instruction. | |
25225 | @item mmx | |
25226 | MMX instructions. | |
25227 | @item popcnt | |
25228 | POPCNT instruction. | |
25229 | @item sse | |
25230 | SSE instructions. | |
25231 | @item sse2 | |
25232 | SSE2 instructions. | |
25233 | @item sse3 | |
25234 | SSE3 instructions. | |
25235 | @item ssse3 | |
25236 | SSSE3 instructions. | |
25237 | @item sse4.1 | |
25238 | SSE4.1 instructions. | |
25239 | @item sse4.2 | |
25240 | SSE4.2 instructions. | |
25241 | @item avx | |
25242 | AVX instructions. | |
25243 | @item avx2 | |
25244 | AVX2 instructions. | |
25245 | @item sse4a | |
25246 | SSE4A instructions. | |
25247 | @item fma4 | |
25248 | FMA4 instructions. | |
25249 | @item xop | |
25250 | XOP instructions. | |
25251 | @item fma | |
25252 | FMA instructions. | |
25253 | @item avx512f | |
25254 | AVX512F instructions. | |
25255 | @item bmi | |
25256 | BMI instructions. | |
25257 | @item bmi2 | |
25258 | BMI2 instructions. | |
25259 | @item aes | |
25260 | AES instructions. | |
25261 | @item pclmul | |
25262 | PCLMUL instructions. | |
25263 | @item avx512vl | |
25264 | AVX512VL instructions. | |
25265 | @item avx512bw | |
25266 | AVX512BW instructions. | |
25267 | @item avx512dq | |
25268 | AVX512DQ instructions. | |
25269 | @item avx512cd | |
25270 | AVX512CD instructions. | |
25271 | @item avx512er | |
25272 | AVX512ER instructions. | |
25273 | @item avx512pf | |
25274 | AVX512PF instructions. | |
25275 | @item avx512vbmi | |
25276 | AVX512VBMI instructions. | |
25277 | @item avx512ifma | |
25278 | AVX512IFMA instructions. | |
25279 | @item avx5124vnniw | |
25280 | AVX5124VNNIW instructions. | |
25281 | @item avx5124fmaps | |
25282 | AVX5124FMAPS instructions. | |
25283 | @item avx512vpopcntdq | |
25284 | AVX512VPOPCNTDQ instructions. | |
25285 | @item avx512vbmi2 | |
25286 | AVX512VBMI2 instructions. | |
25287 | @item gfni | |
25288 | GFNI instructions. | |
25289 | @item vpclmulqdq | |
25290 | VPCLMULQDQ instructions. | |
25291 | @item avx512vnni | |
25292 | AVX512VNNI instructions. | |
25293 | @item avx512bitalg | |
25294 | AVX512BITALG instructions. | |
d71b20fc ML |
25295 | @item x86-64 |
25296 | Baseline x86-64 microarchitecture level (as defined in x86-64 psABI). | |
25297 | @item x86-64-v2 | |
25298 | x86-64-v2 microarchitecture level. | |
25299 | @item x86-64-v3 | |
25300 | x86-64-v3 microarchitecture level. | |
25301 | @item x86-64-v4 | |
25302 | x86-64-v4 microarchitecture level. | |
25303 | ||
25304 | ||
d77de738 ML |
25305 | @end table |
25306 | ||
25307 | Here is an example: | |
25308 | @smallexample | |
25309 | if (__builtin_cpu_supports ("popcnt")) | |
25310 | @{ | |
25311 | asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc"); | |
25312 | @} | |
25313 | else | |
25314 | @{ | |
25315 | count = generic_countbits (n); //generic implementation. | |
25316 | @} | |
25317 | @end smallexample | |
f25efe50 | 25318 | @enddefbuiltin |
d77de738 ML |
25319 | |
25320 | The following built-in functions are made available by @option{-mmmx}. | |
25321 | All of them generate the machine instruction that is part of the name. | |
25322 | ||
25323 | @smallexample | |
25324 | v8qi __builtin_ia32_paddb (v8qi, v8qi); | |
25325 | v4hi __builtin_ia32_paddw (v4hi, v4hi); | |
25326 | v2si __builtin_ia32_paddd (v2si, v2si); | |
25327 | v8qi __builtin_ia32_psubb (v8qi, v8qi); | |
25328 | v4hi __builtin_ia32_psubw (v4hi, v4hi); | |
25329 | v2si __builtin_ia32_psubd (v2si, v2si); | |
25330 | v8qi __builtin_ia32_paddsb (v8qi, v8qi); | |
25331 | v4hi __builtin_ia32_paddsw (v4hi, v4hi); | |
25332 | v8qi __builtin_ia32_psubsb (v8qi, v8qi); | |
25333 | v4hi __builtin_ia32_psubsw (v4hi, v4hi); | |
25334 | v8qi __builtin_ia32_paddusb (v8qi, v8qi); | |
25335 | v4hi __builtin_ia32_paddusw (v4hi, v4hi); | |
25336 | v8qi __builtin_ia32_psubusb (v8qi, v8qi); | |
25337 | v4hi __builtin_ia32_psubusw (v4hi, v4hi); | |
25338 | v4hi __builtin_ia32_pmullw (v4hi, v4hi); | |
25339 | v4hi __builtin_ia32_pmulhw (v4hi, v4hi); | |
25340 | di __builtin_ia32_pand (di, di); | |
25341 | di __builtin_ia32_pandn (di,di); | |
25342 | di __builtin_ia32_por (di, di); | |
25343 | di __builtin_ia32_pxor (di, di); | |
25344 | v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi); | |
25345 | v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi); | |
25346 | v2si __builtin_ia32_pcmpeqd (v2si, v2si); | |
25347 | v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi); | |
25348 | v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi); | |
25349 | v2si __builtin_ia32_pcmpgtd (v2si, v2si); | |
25350 | v8qi __builtin_ia32_punpckhbw (v8qi, v8qi); | |
25351 | v4hi __builtin_ia32_punpckhwd (v4hi, v4hi); | |
25352 | v2si __builtin_ia32_punpckhdq (v2si, v2si); | |
25353 | v8qi __builtin_ia32_punpcklbw (v8qi, v8qi); | |
25354 | v4hi __builtin_ia32_punpcklwd (v4hi, v4hi); | |
25355 | v2si __builtin_ia32_punpckldq (v2si, v2si); | |
25356 | v8qi __builtin_ia32_packsswb (v4hi, v4hi); | |
25357 | v4hi __builtin_ia32_packssdw (v2si, v2si); | |
25358 | v8qi __builtin_ia32_packuswb (v4hi, v4hi); | |
25359 | ||
25360 | v4hi __builtin_ia32_psllw (v4hi, v4hi); | |
25361 | v2si __builtin_ia32_pslld (v2si, v2si); | |
25362 | v1di __builtin_ia32_psllq (v1di, v1di); | |
25363 | v4hi __builtin_ia32_psrlw (v4hi, v4hi); | |
25364 | v2si __builtin_ia32_psrld (v2si, v2si); | |
25365 | v1di __builtin_ia32_psrlq (v1di, v1di); | |
25366 | v4hi __builtin_ia32_psraw (v4hi, v4hi); | |
25367 | v2si __builtin_ia32_psrad (v2si, v2si); | |
25368 | v4hi __builtin_ia32_psllwi (v4hi, int); | |
25369 | v2si __builtin_ia32_pslldi (v2si, int); | |
25370 | v1di __builtin_ia32_psllqi (v1di, int); | |
25371 | v4hi __builtin_ia32_psrlwi (v4hi, int); | |
25372 | v2si __builtin_ia32_psrldi (v2si, int); | |
25373 | v1di __builtin_ia32_psrlqi (v1di, int); | |
25374 | v4hi __builtin_ia32_psrawi (v4hi, int); | |
25375 | v2si __builtin_ia32_psradi (v2si, int); | |
25376 | @end smallexample | |
25377 | ||
25378 | The following built-in functions are made available either with | |
25379 | @option{-msse}, or with @option{-m3dnowa}. All of them generate | |
25380 | the machine instruction that is part of the name. | |
25381 | ||
25382 | @smallexample | |
25383 | v4hi __builtin_ia32_pmulhuw (v4hi, v4hi); | |
25384 | v8qi __builtin_ia32_pavgb (v8qi, v8qi); | |
25385 | v4hi __builtin_ia32_pavgw (v4hi, v4hi); | |
25386 | v1di __builtin_ia32_psadbw (v8qi, v8qi); | |
25387 | v8qi __builtin_ia32_pmaxub (v8qi, v8qi); | |
25388 | v4hi __builtin_ia32_pmaxsw (v4hi, v4hi); | |
25389 | v8qi __builtin_ia32_pminub (v8qi, v8qi); | |
25390 | v4hi __builtin_ia32_pminsw (v4hi, v4hi); | |
25391 | int __builtin_ia32_pmovmskb (v8qi); | |
25392 | void __builtin_ia32_maskmovq (v8qi, v8qi, char *); | |
25393 | void __builtin_ia32_movntq (di *, di); | |
25394 | void __builtin_ia32_sfence (void); | |
25395 | @end smallexample | |
25396 | ||
25397 | The following built-in functions are available when @option{-msse} is used. | |
25398 | All of them generate the machine instruction that is part of the name. | |
25399 | ||
25400 | @smallexample | |
25401 | int __builtin_ia32_comieq (v4sf, v4sf); | |
25402 | int __builtin_ia32_comineq (v4sf, v4sf); | |
25403 | int __builtin_ia32_comilt (v4sf, v4sf); | |
25404 | int __builtin_ia32_comile (v4sf, v4sf); | |
25405 | int __builtin_ia32_comigt (v4sf, v4sf); | |
25406 | int __builtin_ia32_comige (v4sf, v4sf); | |
25407 | int __builtin_ia32_ucomieq (v4sf, v4sf); | |
25408 | int __builtin_ia32_ucomineq (v4sf, v4sf); | |
25409 | int __builtin_ia32_ucomilt (v4sf, v4sf); | |
25410 | int __builtin_ia32_ucomile (v4sf, v4sf); | |
25411 | int __builtin_ia32_ucomigt (v4sf, v4sf); | |
25412 | int __builtin_ia32_ucomige (v4sf, v4sf); | |
25413 | v4sf __builtin_ia32_addps (v4sf, v4sf); | |
25414 | v4sf __builtin_ia32_subps (v4sf, v4sf); | |
25415 | v4sf __builtin_ia32_mulps (v4sf, v4sf); | |
25416 | v4sf __builtin_ia32_divps (v4sf, v4sf); | |
25417 | v4sf __builtin_ia32_addss (v4sf, v4sf); | |
25418 | v4sf __builtin_ia32_subss (v4sf, v4sf); | |
25419 | v4sf __builtin_ia32_mulss (v4sf, v4sf); | |
25420 | v4sf __builtin_ia32_divss (v4sf, v4sf); | |
25421 | v4sf __builtin_ia32_cmpeqps (v4sf, v4sf); | |
25422 | v4sf __builtin_ia32_cmpltps (v4sf, v4sf); | |
25423 | v4sf __builtin_ia32_cmpleps (v4sf, v4sf); | |
25424 | v4sf __builtin_ia32_cmpgtps (v4sf, v4sf); | |
25425 | v4sf __builtin_ia32_cmpgeps (v4sf, v4sf); | |
25426 | v4sf __builtin_ia32_cmpunordps (v4sf, v4sf); | |
25427 | v4sf __builtin_ia32_cmpneqps (v4sf, v4sf); | |
25428 | v4sf __builtin_ia32_cmpnltps (v4sf, v4sf); | |
25429 | v4sf __builtin_ia32_cmpnleps (v4sf, v4sf); | |
25430 | v4sf __builtin_ia32_cmpngtps (v4sf, v4sf); | |
25431 | v4sf __builtin_ia32_cmpngeps (v4sf, v4sf); | |
25432 | v4sf __builtin_ia32_cmpordps (v4sf, v4sf); | |
25433 | v4sf __builtin_ia32_cmpeqss (v4sf, v4sf); | |
25434 | v4sf __builtin_ia32_cmpltss (v4sf, v4sf); | |
25435 | v4sf __builtin_ia32_cmpless (v4sf, v4sf); | |
25436 | v4sf __builtin_ia32_cmpunordss (v4sf, v4sf); | |
25437 | v4sf __builtin_ia32_cmpneqss (v4sf, v4sf); | |
25438 | v4sf __builtin_ia32_cmpnltss (v4sf, v4sf); | |
25439 | v4sf __builtin_ia32_cmpnless (v4sf, v4sf); | |
25440 | v4sf __builtin_ia32_cmpordss (v4sf, v4sf); | |
25441 | v4sf __builtin_ia32_maxps (v4sf, v4sf); | |
25442 | v4sf __builtin_ia32_maxss (v4sf, v4sf); | |
25443 | v4sf __builtin_ia32_minps (v4sf, v4sf); | |
25444 | v4sf __builtin_ia32_minss (v4sf, v4sf); | |
25445 | v4sf __builtin_ia32_andps (v4sf, v4sf); | |
25446 | v4sf __builtin_ia32_andnps (v4sf, v4sf); | |
25447 | v4sf __builtin_ia32_orps (v4sf, v4sf); | |
25448 | v4sf __builtin_ia32_xorps (v4sf, v4sf); | |
25449 | v4sf __builtin_ia32_movss (v4sf, v4sf); | |
25450 | v4sf __builtin_ia32_movhlps (v4sf, v4sf); | |
25451 | v4sf __builtin_ia32_movlhps (v4sf, v4sf); | |
25452 | v4sf __builtin_ia32_unpckhps (v4sf, v4sf); | |
25453 | v4sf __builtin_ia32_unpcklps (v4sf, v4sf); | |
25454 | v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si); | |
25455 | v4sf __builtin_ia32_cvtsi2ss (v4sf, int); | |
25456 | v2si __builtin_ia32_cvtps2pi (v4sf); | |
25457 | int __builtin_ia32_cvtss2si (v4sf); | |
25458 | v2si __builtin_ia32_cvttps2pi (v4sf); | |
25459 | int __builtin_ia32_cvttss2si (v4sf); | |
25460 | v4sf __builtin_ia32_rcpps (v4sf); | |
25461 | v4sf __builtin_ia32_rsqrtps (v4sf); | |
25462 | v4sf __builtin_ia32_sqrtps (v4sf); | |
25463 | v4sf __builtin_ia32_rcpss (v4sf); | |
25464 | v4sf __builtin_ia32_rsqrtss (v4sf); | |
25465 | v4sf __builtin_ia32_sqrtss (v4sf); | |
25466 | v4sf __builtin_ia32_shufps (v4sf, v4sf, int); | |
25467 | void __builtin_ia32_movntps (float *, v4sf); | |
25468 | int __builtin_ia32_movmskps (v4sf); | |
25469 | @end smallexample | |
25470 | ||
25471 | The following built-in functions are available when @option{-msse} is used. | |
25472 | ||
f25efe50 | 25473 | @defbuiltin{v4sf __builtin_ia32_loadups (float *)} |
d77de738 | 25474 | Generates the @code{movups} machine instruction as a load from memory. |
f25efe50 AA |
25475 | @enddefbuiltin |
25476 | ||
25477 | @defbuiltin{void __builtin_ia32_storeups (float *, v4sf)} | |
d77de738 | 25478 | Generates the @code{movups} machine instruction as a store to memory. |
f25efe50 AA |
25479 | @enddefbuiltin |
25480 | ||
25481 | @defbuiltin{v4sf __builtin_ia32_loadss (float *)} | |
d77de738 | 25482 | Generates the @code{movss} machine instruction as a load from memory. |
f25efe50 AA |
25483 | @enddefbuiltin |
25484 | ||
25485 | @defbuiltin{v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)} | |
d77de738 | 25486 | Generates the @code{movhps} machine instruction as a load from memory. |
f25efe50 AA |
25487 | @enddefbuiltin |
25488 | ||
25489 | @defbuiltin{v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)} | |
d77de738 | 25490 | Generates the @code{movlps} machine instruction as a load from memory |
f25efe50 AA |
25491 | @enddefbuiltin |
25492 | ||
25493 | @defbuiltin{void __builtin_ia32_storehps (v2sf *, v4sf)} | |
d77de738 | 25494 | Generates the @code{movhps} machine instruction as a store to memory. |
f25efe50 AA |
25495 | @enddefbuiltin |
25496 | ||
25497 | @defbuiltin{void __builtin_ia32_storelps (v2sf *, v4sf)} | |
d77de738 | 25498 | Generates the @code{movlps} machine instruction as a store to memory. |
f25efe50 | 25499 | @enddefbuiltin |
d77de738 ML |
25500 | |
25501 | The following built-in functions are available when @option{-msse2} is used. | |
25502 | All of them generate the machine instruction that is part of the name. | |
25503 | ||
25504 | @smallexample | |
25505 | int __builtin_ia32_comisdeq (v2df, v2df); | |
25506 | int __builtin_ia32_comisdlt (v2df, v2df); | |
25507 | int __builtin_ia32_comisdle (v2df, v2df); | |
25508 | int __builtin_ia32_comisdgt (v2df, v2df); | |
25509 | int __builtin_ia32_comisdge (v2df, v2df); | |
25510 | int __builtin_ia32_comisdneq (v2df, v2df); | |
25511 | int __builtin_ia32_ucomisdeq (v2df, v2df); | |
25512 | int __builtin_ia32_ucomisdlt (v2df, v2df); | |
25513 | int __builtin_ia32_ucomisdle (v2df, v2df); | |
25514 | int __builtin_ia32_ucomisdgt (v2df, v2df); | |
25515 | int __builtin_ia32_ucomisdge (v2df, v2df); | |
25516 | int __builtin_ia32_ucomisdneq (v2df, v2df); | |
25517 | v2df __builtin_ia32_cmpeqpd (v2df, v2df); | |
25518 | v2df __builtin_ia32_cmpltpd (v2df, v2df); | |
25519 | v2df __builtin_ia32_cmplepd (v2df, v2df); | |
25520 | v2df __builtin_ia32_cmpgtpd (v2df, v2df); | |
25521 | v2df __builtin_ia32_cmpgepd (v2df, v2df); | |
25522 | v2df __builtin_ia32_cmpunordpd (v2df, v2df); | |
25523 | v2df __builtin_ia32_cmpneqpd (v2df, v2df); | |
25524 | v2df __builtin_ia32_cmpnltpd (v2df, v2df); | |
25525 | v2df __builtin_ia32_cmpnlepd (v2df, v2df); | |
25526 | v2df __builtin_ia32_cmpngtpd (v2df, v2df); | |
25527 | v2df __builtin_ia32_cmpngepd (v2df, v2df); | |
25528 | v2df __builtin_ia32_cmpordpd (v2df, v2df); | |
25529 | v2df __builtin_ia32_cmpeqsd (v2df, v2df); | |
25530 | v2df __builtin_ia32_cmpltsd (v2df, v2df); | |
25531 | v2df __builtin_ia32_cmplesd (v2df, v2df); | |
25532 | v2df __builtin_ia32_cmpunordsd (v2df, v2df); | |
25533 | v2df __builtin_ia32_cmpneqsd (v2df, v2df); | |
25534 | v2df __builtin_ia32_cmpnltsd (v2df, v2df); | |
25535 | v2df __builtin_ia32_cmpnlesd (v2df, v2df); | |
25536 | v2df __builtin_ia32_cmpordsd (v2df, v2df); | |
25537 | v2di __builtin_ia32_paddq (v2di, v2di); | |
25538 | v2di __builtin_ia32_psubq (v2di, v2di); | |
25539 | v2df __builtin_ia32_addpd (v2df, v2df); | |
25540 | v2df __builtin_ia32_subpd (v2df, v2df); | |
25541 | v2df __builtin_ia32_mulpd (v2df, v2df); | |
25542 | v2df __builtin_ia32_divpd (v2df, v2df); | |
25543 | v2df __builtin_ia32_addsd (v2df, v2df); | |
25544 | v2df __builtin_ia32_subsd (v2df, v2df); | |
25545 | v2df __builtin_ia32_mulsd (v2df, v2df); | |
25546 | v2df __builtin_ia32_divsd (v2df, v2df); | |
25547 | v2df __builtin_ia32_minpd (v2df, v2df); | |
25548 | v2df __builtin_ia32_maxpd (v2df, v2df); | |
25549 | v2df __builtin_ia32_minsd (v2df, v2df); | |
25550 | v2df __builtin_ia32_maxsd (v2df, v2df); | |
25551 | v2df __builtin_ia32_andpd (v2df, v2df); | |
25552 | v2df __builtin_ia32_andnpd (v2df, v2df); | |
25553 | v2df __builtin_ia32_orpd (v2df, v2df); | |
25554 | v2df __builtin_ia32_xorpd (v2df, v2df); | |
25555 | v2df __builtin_ia32_movsd (v2df, v2df); | |
25556 | v2df __builtin_ia32_unpckhpd (v2df, v2df); | |
25557 | v2df __builtin_ia32_unpcklpd (v2df, v2df); | |
25558 | v16qi __builtin_ia32_paddb128 (v16qi, v16qi); | |
25559 | v8hi __builtin_ia32_paddw128 (v8hi, v8hi); | |
25560 | v4si __builtin_ia32_paddd128 (v4si, v4si); | |
25561 | v2di __builtin_ia32_paddq128 (v2di, v2di); | |
25562 | v16qi __builtin_ia32_psubb128 (v16qi, v16qi); | |
25563 | v8hi __builtin_ia32_psubw128 (v8hi, v8hi); | |
25564 | v4si __builtin_ia32_psubd128 (v4si, v4si); | |
25565 | v2di __builtin_ia32_psubq128 (v2di, v2di); | |
25566 | v8hi __builtin_ia32_pmullw128 (v8hi, v8hi); | |
25567 | v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi); | |
25568 | v2di __builtin_ia32_pand128 (v2di, v2di); | |
25569 | v2di __builtin_ia32_pandn128 (v2di, v2di); | |
25570 | v2di __builtin_ia32_por128 (v2di, v2di); | |
25571 | v2di __builtin_ia32_pxor128 (v2di, v2di); | |
25572 | v16qi __builtin_ia32_pavgb128 (v16qi, v16qi); | |
25573 | v8hi __builtin_ia32_pavgw128 (v8hi, v8hi); | |
25574 | v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi); | |
25575 | v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi); | |
25576 | v4si __builtin_ia32_pcmpeqd128 (v4si, v4si); | |
25577 | v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi); | |
25578 | v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi); | |
25579 | v4si __builtin_ia32_pcmpgtd128 (v4si, v4si); | |
25580 | v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi); | |
25581 | v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi); | |
25582 | v16qi __builtin_ia32_pminub128 (v16qi, v16qi); | |
25583 | v8hi __builtin_ia32_pminsw128 (v8hi, v8hi); | |
25584 | v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi); | |
25585 | v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi); | |
25586 | v4si __builtin_ia32_punpckhdq128 (v4si, v4si); | |
25587 | v2di __builtin_ia32_punpckhqdq128 (v2di, v2di); | |
25588 | v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi); | |
25589 | v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi); | |
25590 | v4si __builtin_ia32_punpckldq128 (v4si, v4si); | |
25591 | v2di __builtin_ia32_punpcklqdq128 (v2di, v2di); | |
25592 | v16qi __builtin_ia32_packsswb128 (v8hi, v8hi); | |
25593 | v8hi __builtin_ia32_packssdw128 (v4si, v4si); | |
25594 | v16qi __builtin_ia32_packuswb128 (v8hi, v8hi); | |
25595 | v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi); | |
25596 | void __builtin_ia32_maskmovdqu (v16qi, v16qi); | |
25597 | v2df __builtin_ia32_loadupd (double *); | |
25598 | void __builtin_ia32_storeupd (double *, v2df); | |
25599 | v2df __builtin_ia32_loadhpd (v2df, double const *); | |
25600 | v2df __builtin_ia32_loadlpd (v2df, double const *); | |
25601 | int __builtin_ia32_movmskpd (v2df); | |
25602 | int __builtin_ia32_pmovmskb128 (v16qi); | |
25603 | void __builtin_ia32_movnti (int *, int); | |
25604 | void __builtin_ia32_movnti64 (long long int *, long long int); | |
25605 | void __builtin_ia32_movntpd (double *, v2df); | |
25606 | void __builtin_ia32_movntdq (v2df *, v2df); | |
25607 | v4si __builtin_ia32_pshufd (v4si, int); | |
25608 | v8hi __builtin_ia32_pshuflw (v8hi, int); | |
25609 | v8hi __builtin_ia32_pshufhw (v8hi, int); | |
25610 | v2di __builtin_ia32_psadbw128 (v16qi, v16qi); | |
25611 | v2df __builtin_ia32_sqrtpd (v2df); | |
25612 | v2df __builtin_ia32_sqrtsd (v2df); | |
25613 | v2df __builtin_ia32_shufpd (v2df, v2df, int); | |
25614 | v2df __builtin_ia32_cvtdq2pd (v4si); | |
25615 | v4sf __builtin_ia32_cvtdq2ps (v4si); | |
25616 | v4si __builtin_ia32_cvtpd2dq (v2df); | |
25617 | v2si __builtin_ia32_cvtpd2pi (v2df); | |
25618 | v4sf __builtin_ia32_cvtpd2ps (v2df); | |
25619 | v4si __builtin_ia32_cvttpd2dq (v2df); | |
25620 | v2si __builtin_ia32_cvttpd2pi (v2df); | |
25621 | v2df __builtin_ia32_cvtpi2pd (v2si); | |
25622 | int __builtin_ia32_cvtsd2si (v2df); | |
25623 | int __builtin_ia32_cvttsd2si (v2df); | |
25624 | long long __builtin_ia32_cvtsd2si64 (v2df); | |
25625 | long long __builtin_ia32_cvttsd2si64 (v2df); | |
25626 | v4si __builtin_ia32_cvtps2dq (v4sf); | |
25627 | v2df __builtin_ia32_cvtps2pd (v4sf); | |
25628 | v4si __builtin_ia32_cvttps2dq (v4sf); | |
25629 | v2df __builtin_ia32_cvtsi2sd (v2df, int); | |
25630 | v2df __builtin_ia32_cvtsi642sd (v2df, long long); | |
25631 | v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df); | |
25632 | v2df __builtin_ia32_cvtss2sd (v2df, v4sf); | |
25633 | void __builtin_ia32_clflush (const void *); | |
25634 | void __builtin_ia32_lfence (void); | |
25635 | void __builtin_ia32_mfence (void); | |
25636 | v16qi __builtin_ia32_loaddqu (const char *); | |
25637 | void __builtin_ia32_storedqu (char *, v16qi); | |
25638 | v1di __builtin_ia32_pmuludq (v2si, v2si); | |
25639 | v2di __builtin_ia32_pmuludq128 (v4si, v4si); | |
25640 | v8hi __builtin_ia32_psllw128 (v8hi, v8hi); | |
25641 | v4si __builtin_ia32_pslld128 (v4si, v4si); | |
25642 | v2di __builtin_ia32_psllq128 (v2di, v2di); | |
25643 | v8hi __builtin_ia32_psrlw128 (v8hi, v8hi); | |
25644 | v4si __builtin_ia32_psrld128 (v4si, v4si); | |
25645 | v2di __builtin_ia32_psrlq128 (v2di, v2di); | |
25646 | v8hi __builtin_ia32_psraw128 (v8hi, v8hi); | |
25647 | v4si __builtin_ia32_psrad128 (v4si, v4si); | |
25648 | v2di __builtin_ia32_pslldqi128 (v2di, int); | |
25649 | v8hi __builtin_ia32_psllwi128 (v8hi, int); | |
25650 | v4si __builtin_ia32_pslldi128 (v4si, int); | |
25651 | v2di __builtin_ia32_psllqi128 (v2di, int); | |
25652 | v2di __builtin_ia32_psrldqi128 (v2di, int); | |
25653 | v8hi __builtin_ia32_psrlwi128 (v8hi, int); | |
25654 | v4si __builtin_ia32_psrldi128 (v4si, int); | |
25655 | v2di __builtin_ia32_psrlqi128 (v2di, int); | |
25656 | v8hi __builtin_ia32_psrawi128 (v8hi, int); | |
25657 | v4si __builtin_ia32_psradi128 (v4si, int); | |
25658 | v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi); | |
25659 | v2di __builtin_ia32_movq128 (v2di); | |
25660 | @end smallexample | |
25661 | ||
25662 | The following built-in functions are available when @option{-msse3} is used. | |
25663 | All of them generate the machine instruction that is part of the name. | |
25664 | ||
25665 | @smallexample | |
25666 | v2df __builtin_ia32_addsubpd (v2df, v2df); | |
25667 | v4sf __builtin_ia32_addsubps (v4sf, v4sf); | |
25668 | v2df __builtin_ia32_haddpd (v2df, v2df); | |
25669 | v4sf __builtin_ia32_haddps (v4sf, v4sf); | |
25670 | v2df __builtin_ia32_hsubpd (v2df, v2df); | |
25671 | v4sf __builtin_ia32_hsubps (v4sf, v4sf); | |
25672 | v16qi __builtin_ia32_lddqu (char const *); | |
25673 | void __builtin_ia32_monitor (void *, unsigned int, unsigned int); | |
25674 | v4sf __builtin_ia32_movshdup (v4sf); | |
25675 | v4sf __builtin_ia32_movsldup (v4sf); | |
25676 | void __builtin_ia32_mwait (unsigned int, unsigned int); | |
25677 | @end smallexample | |
25678 | ||
25679 | The following built-in functions are available when @option{-mssse3} is used. | |
25680 | All of them generate the machine instruction that is part of the name. | |
25681 | ||
25682 | @smallexample | |
25683 | v2si __builtin_ia32_phaddd (v2si, v2si); | |
25684 | v4hi __builtin_ia32_phaddw (v4hi, v4hi); | |
25685 | v4hi __builtin_ia32_phaddsw (v4hi, v4hi); | |
25686 | v2si __builtin_ia32_phsubd (v2si, v2si); | |
25687 | v4hi __builtin_ia32_phsubw (v4hi, v4hi); | |
25688 | v4hi __builtin_ia32_phsubsw (v4hi, v4hi); | |
25689 | v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi); | |
25690 | v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi); | |
25691 | v8qi __builtin_ia32_pshufb (v8qi, v8qi); | |
25692 | v8qi __builtin_ia32_psignb (v8qi, v8qi); | |
25693 | v2si __builtin_ia32_psignd (v2si, v2si); | |
25694 | v4hi __builtin_ia32_psignw (v4hi, v4hi); | |
25695 | v1di __builtin_ia32_palignr (v1di, v1di, int); | |
25696 | v8qi __builtin_ia32_pabsb (v8qi); | |
25697 | v2si __builtin_ia32_pabsd (v2si); | |
25698 | v4hi __builtin_ia32_pabsw (v4hi); | |
25699 | @end smallexample | |
25700 | ||
25701 | The following built-in functions are available when @option{-mssse3} is used. | |
25702 | All of them generate the machine instruction that is part of the name. | |
25703 | ||
25704 | @smallexample | |
25705 | v4si __builtin_ia32_phaddd128 (v4si, v4si); | |
25706 | v8hi __builtin_ia32_phaddw128 (v8hi, v8hi); | |
25707 | v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi); | |
25708 | v4si __builtin_ia32_phsubd128 (v4si, v4si); | |
25709 | v8hi __builtin_ia32_phsubw128 (v8hi, v8hi); | |
25710 | v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi); | |
25711 | v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi); | |
25712 | v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi); | |
25713 | v16qi __builtin_ia32_pshufb128 (v16qi, v16qi); | |
25714 | v16qi __builtin_ia32_psignb128 (v16qi, v16qi); | |
25715 | v4si __builtin_ia32_psignd128 (v4si, v4si); | |
25716 | v8hi __builtin_ia32_psignw128 (v8hi, v8hi); | |
25717 | v2di __builtin_ia32_palignr128 (v2di, v2di, int); | |
25718 | v16qi __builtin_ia32_pabsb128 (v16qi); | |
25719 | v4si __builtin_ia32_pabsd128 (v4si); | |
25720 | v8hi __builtin_ia32_pabsw128 (v8hi); | |
25721 | @end smallexample | |
25722 | ||
25723 | The following built-in functions are available when @option{-msse4.1} is | |
25724 | used. All of them generate the machine instruction that is part of the | |
25725 | name. | |
25726 | ||
25727 | @smallexample | |
25728 | v2df __builtin_ia32_blendpd (v2df, v2df, const int); | |
25729 | v4sf __builtin_ia32_blendps (v4sf, v4sf, const int); | |
25730 | v2df __builtin_ia32_blendvpd (v2df, v2df, v2df); | |
25731 | v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf); | |
25732 | v2df __builtin_ia32_dppd (v2df, v2df, const int); | |
25733 | v4sf __builtin_ia32_dpps (v4sf, v4sf, const int); | |
25734 | v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int); | |
25735 | v2di __builtin_ia32_movntdqa (v2di *); | |
25736 | v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int); | |
25737 | v8hi __builtin_ia32_packusdw128 (v4si, v4si); | |
25738 | v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi); | |
25739 | v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int); | |
25740 | v2di __builtin_ia32_pcmpeqq (v2di, v2di); | |
25741 | v8hi __builtin_ia32_phminposuw128 (v8hi); | |
25742 | v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi); | |
25743 | v4si __builtin_ia32_pmaxsd128 (v4si, v4si); | |
25744 | v4si __builtin_ia32_pmaxud128 (v4si, v4si); | |
25745 | v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi); | |
25746 | v16qi __builtin_ia32_pminsb128 (v16qi, v16qi); | |
25747 | v4si __builtin_ia32_pminsd128 (v4si, v4si); | |
25748 | v4si __builtin_ia32_pminud128 (v4si, v4si); | |
25749 | v8hi __builtin_ia32_pminuw128 (v8hi, v8hi); | |
25750 | v4si __builtin_ia32_pmovsxbd128 (v16qi); | |
25751 | v2di __builtin_ia32_pmovsxbq128 (v16qi); | |
25752 | v8hi __builtin_ia32_pmovsxbw128 (v16qi); | |
25753 | v2di __builtin_ia32_pmovsxdq128 (v4si); | |
25754 | v4si __builtin_ia32_pmovsxwd128 (v8hi); | |
25755 | v2di __builtin_ia32_pmovsxwq128 (v8hi); | |
25756 | v4si __builtin_ia32_pmovzxbd128 (v16qi); | |
25757 | v2di __builtin_ia32_pmovzxbq128 (v16qi); | |
25758 | v8hi __builtin_ia32_pmovzxbw128 (v16qi); | |
25759 | v2di __builtin_ia32_pmovzxdq128 (v4si); | |
25760 | v4si __builtin_ia32_pmovzxwd128 (v8hi); | |
25761 | v2di __builtin_ia32_pmovzxwq128 (v8hi); | |
25762 | v2di __builtin_ia32_pmuldq128 (v4si, v4si); | |
25763 | v4si __builtin_ia32_pmulld128 (v4si, v4si); | |
25764 | int __builtin_ia32_ptestc128 (v2di, v2di); | |
25765 | int __builtin_ia32_ptestnzc128 (v2di, v2di); | |
25766 | int __builtin_ia32_ptestz128 (v2di, v2di); | |
25767 | v2df __builtin_ia32_roundpd (v2df, const int); | |
25768 | v4sf __builtin_ia32_roundps (v4sf, const int); | |
25769 | v2df __builtin_ia32_roundsd (v2df, v2df, const int); | |
25770 | v4sf __builtin_ia32_roundss (v4sf, v4sf, const int); | |
25771 | @end smallexample | |
25772 | ||
25773 | The following built-in functions are available when @option{-msse4.1} is | |
25774 | used. | |
25775 | ||
f25efe50 | 25776 | @defbuiltin{v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)} |
d77de738 | 25777 | Generates the @code{insertps} machine instruction. |
f25efe50 AA |
25778 | @enddefbuiltin |
25779 | ||
25780 | @defbuiltin{int __builtin_ia32_vec_ext_v16qi (v16qi, const int)} | |
d77de738 | 25781 | Generates the @code{pextrb} machine instruction. |
f25efe50 AA |
25782 | @enddefbuiltin |
25783 | ||
25784 | @defbuiltin{v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)} | |
d77de738 | 25785 | Generates the @code{pinsrb} machine instruction. |
f25efe50 AA |
25786 | @enddefbuiltin |
25787 | ||
25788 | @defbuiltin{v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)} | |
d77de738 | 25789 | Generates the @code{pinsrd} machine instruction. |
f25efe50 AA |
25790 | @enddefbuiltin |
25791 | ||
25792 | @defbuiltin{v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)} | |
d77de738 | 25793 | Generates the @code{pinsrq} machine instruction in 64bit mode. |
f25efe50 | 25794 | @enddefbuiltin |
d77de738 ML |
25795 | |
25796 | The following built-in functions are changed to generate new SSE4.1 | |
25797 | instructions when @option{-msse4.1} is used. | |
25798 | ||
f25efe50 | 25799 | @defbuiltin{float __builtin_ia32_vec_ext_v4sf (v4sf, const int)} |
d77de738 | 25800 | Generates the @code{extractps} machine instruction. |
f25efe50 AA |
25801 | @enddefbuiltin |
25802 | ||
25803 | @defbuiltin{int __builtin_ia32_vec_ext_v4si (v4si, const int)} | |
d77de738 | 25804 | Generates the @code{pextrd} machine instruction. |
f25efe50 AA |
25805 | @enddefbuiltin |
25806 | ||
ff99671a | 25807 | @defbuiltin{{long long} __builtin_ia32_vec_ext_v2di (v2di, const int)} |
d77de738 | 25808 | Generates the @code{pextrq} machine instruction in 64bit mode. |
f25efe50 | 25809 | @enddefbuiltin |
d77de738 ML |
25810 | |
25811 | The following built-in functions are available when @option{-msse4.2} is | |
25812 | used. All of them generate the machine instruction that is part of the | |
25813 | name. | |
25814 | ||
25815 | @smallexample | |
25816 | v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int); | |
25817 | int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int); | |
25818 | int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int); | |
25819 | int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int); | |
25820 | int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int); | |
25821 | int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int); | |
25822 | int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int); | |
25823 | v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int); | |
25824 | int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int); | |
25825 | int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int); | |
25826 | int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int); | |
25827 | int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int); | |
25828 | int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int); | |
25829 | int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int); | |
25830 | v2di __builtin_ia32_pcmpgtq (v2di, v2di); | |
25831 | @end smallexample | |
25832 | ||
25833 | The following built-in functions are available when @option{-msse4.2} is | |
25834 | used. | |
25835 | ||
ff99671a | 25836 | @defbuiltin{{unsigned int} __builtin_ia32_crc32qi (unsigned int, unsigned char)} |
d77de738 | 25837 | Generates the @code{crc32b} machine instruction. |
f25efe50 AA |
25838 | @enddefbuiltin |
25839 | ||
ff99671a | 25840 | @defbuiltin{{unsigned int} __builtin_ia32_crc32hi (unsigned int, unsigned short)} |
d77de738 | 25841 | Generates the @code{crc32w} machine instruction. |
f25efe50 AA |
25842 | @enddefbuiltin |
25843 | ||
ff99671a | 25844 | @defbuiltin{{unsigned int} __builtin_ia32_crc32si (unsigned int, unsigned int)} |
d77de738 | 25845 | Generates the @code{crc32l} machine instruction. |
f25efe50 AA |
25846 | @enddefbuiltin |
25847 | ||
ff99671a | 25848 | @defbuiltin{{unsigned long long} __builtin_ia32_crc32di (unsigned long long, unsigned long long)} |
d77de738 | 25849 | Generates the @code{crc32q} machine instruction. |
f25efe50 | 25850 | @enddefbuiltin |
d77de738 ML |
25851 | |
25852 | The following built-in functions are changed to generate new SSE4.2 | |
25853 | instructions when @option{-msse4.2} is used. | |
25854 | ||
f25efe50 | 25855 | @defbuiltin{int __builtin_popcount (unsigned int)} |
d77de738 | 25856 | Generates the @code{popcntl} machine instruction. |
f25efe50 AA |
25857 | @enddefbuiltin |
25858 | ||
25859 | @defbuiltin{int __builtin_popcountl (unsigned long)} | |
d77de738 ML |
25860 | Generates the @code{popcntl} or @code{popcntq} machine instruction, |
25861 | depending on the size of @code{unsigned long}. | |
f25efe50 AA |
25862 | @enddefbuiltin |
25863 | ||
25864 | @defbuiltin{int __builtin_popcountll (unsigned long long)} | |
d77de738 | 25865 | Generates the @code{popcntq} machine instruction. |
f25efe50 | 25866 | @enddefbuiltin |
d77de738 ML |
25867 | |
25868 | The following built-in functions are available when @option{-mavx} is | |
25869 | used. All of them generate the machine instruction that is part of the | |
25870 | name. | |
25871 | ||
25872 | @smallexample | |
25873 | v4df __builtin_ia32_addpd256 (v4df,v4df); | |
25874 | v8sf __builtin_ia32_addps256 (v8sf,v8sf); | |
25875 | v4df __builtin_ia32_addsubpd256 (v4df,v4df); | |
25876 | v8sf __builtin_ia32_addsubps256 (v8sf,v8sf); | |
25877 | v4df __builtin_ia32_andnpd256 (v4df,v4df); | |
25878 | v8sf __builtin_ia32_andnps256 (v8sf,v8sf); | |
25879 | v4df __builtin_ia32_andpd256 (v4df,v4df); | |
25880 | v8sf __builtin_ia32_andps256 (v8sf,v8sf); | |
25881 | v4df __builtin_ia32_blendpd256 (v4df,v4df,int); | |
25882 | v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int); | |
25883 | v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df); | |
25884 | v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf); | |
25885 | v2df __builtin_ia32_cmppd (v2df,v2df,int); | |
25886 | v4df __builtin_ia32_cmppd256 (v4df,v4df,int); | |
25887 | v4sf __builtin_ia32_cmpps (v4sf,v4sf,int); | |
25888 | v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int); | |
25889 | v2df __builtin_ia32_cmpsd (v2df,v2df,int); | |
25890 | v4sf __builtin_ia32_cmpss (v4sf,v4sf,int); | |
25891 | v4df __builtin_ia32_cvtdq2pd256 (v4si); | |
25892 | v8sf __builtin_ia32_cvtdq2ps256 (v8si); | |
25893 | v4si __builtin_ia32_cvtpd2dq256 (v4df); | |
25894 | v4sf __builtin_ia32_cvtpd2ps256 (v4df); | |
25895 | v8si __builtin_ia32_cvtps2dq256 (v8sf); | |
25896 | v4df __builtin_ia32_cvtps2pd256 (v4sf); | |
25897 | v4si __builtin_ia32_cvttpd2dq256 (v4df); | |
25898 | v8si __builtin_ia32_cvttps2dq256 (v8sf); | |
25899 | v4df __builtin_ia32_divpd256 (v4df,v4df); | |
25900 | v8sf __builtin_ia32_divps256 (v8sf,v8sf); | |
25901 | v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int); | |
25902 | v4df __builtin_ia32_haddpd256 (v4df,v4df); | |
25903 | v8sf __builtin_ia32_haddps256 (v8sf,v8sf); | |
25904 | v4df __builtin_ia32_hsubpd256 (v4df,v4df); | |
25905 | v8sf __builtin_ia32_hsubps256 (v8sf,v8sf); | |
25906 | v32qi __builtin_ia32_lddqu256 (pcchar); | |
25907 | v32qi __builtin_ia32_loaddqu256 (pcchar); | |
25908 | v4df __builtin_ia32_loadupd256 (pcdouble); | |
25909 | v8sf __builtin_ia32_loadups256 (pcfloat); | |
25910 | v2df __builtin_ia32_maskloadpd (pcv2df,v2df); | |
25911 | v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df); | |
25912 | v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf); | |
25913 | v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf); | |
25914 | void __builtin_ia32_maskstorepd (pv2df,v2df,v2df); | |
25915 | void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df); | |
25916 | void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf); | |
25917 | void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf); | |
25918 | v4df __builtin_ia32_maxpd256 (v4df,v4df); | |
25919 | v8sf __builtin_ia32_maxps256 (v8sf,v8sf); | |
25920 | v4df __builtin_ia32_minpd256 (v4df,v4df); | |
25921 | v8sf __builtin_ia32_minps256 (v8sf,v8sf); | |
25922 | v4df __builtin_ia32_movddup256 (v4df); | |
25923 | int __builtin_ia32_movmskpd256 (v4df); | |
25924 | int __builtin_ia32_movmskps256 (v8sf); | |
25925 | v8sf __builtin_ia32_movshdup256 (v8sf); | |
25926 | v8sf __builtin_ia32_movsldup256 (v8sf); | |
25927 | v4df __builtin_ia32_mulpd256 (v4df,v4df); | |
25928 | v8sf __builtin_ia32_mulps256 (v8sf,v8sf); | |
25929 | v4df __builtin_ia32_orpd256 (v4df,v4df); | |
25930 | v8sf __builtin_ia32_orps256 (v8sf,v8sf); | |
25931 | v2df __builtin_ia32_pd_pd256 (v4df); | |
25932 | v4df __builtin_ia32_pd256_pd (v2df); | |
25933 | v4sf __builtin_ia32_ps_ps256 (v8sf); | |
25934 | v8sf __builtin_ia32_ps256_ps (v4sf); | |
25935 | int __builtin_ia32_ptestc256 (v4di,v4di,ptest); | |
25936 | int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest); | |
25937 | int __builtin_ia32_ptestz256 (v4di,v4di,ptest); | |
25938 | v8sf __builtin_ia32_rcpps256 (v8sf); | |
25939 | v4df __builtin_ia32_roundpd256 (v4df,int); | |
25940 | v8sf __builtin_ia32_roundps256 (v8sf,int); | |
25941 | v8sf __builtin_ia32_rsqrtps_nr256 (v8sf); | |
25942 | v8sf __builtin_ia32_rsqrtps256 (v8sf); | |
25943 | v4df __builtin_ia32_shufpd256 (v4df,v4df,int); | |
25944 | v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int); | |
25945 | v4si __builtin_ia32_si_si256 (v8si); | |
25946 | v8si __builtin_ia32_si256_si (v4si); | |
25947 | v4df __builtin_ia32_sqrtpd256 (v4df); | |
25948 | v8sf __builtin_ia32_sqrtps_nr256 (v8sf); | |
25949 | v8sf __builtin_ia32_sqrtps256 (v8sf); | |
25950 | void __builtin_ia32_storedqu256 (pchar,v32qi); | |
25951 | void __builtin_ia32_storeupd256 (pdouble,v4df); | |
25952 | void __builtin_ia32_storeups256 (pfloat,v8sf); | |
25953 | v4df __builtin_ia32_subpd256 (v4df,v4df); | |
25954 | v8sf __builtin_ia32_subps256 (v8sf,v8sf); | |
25955 | v4df __builtin_ia32_unpckhpd256 (v4df,v4df); | |
25956 | v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf); | |
25957 | v4df __builtin_ia32_unpcklpd256 (v4df,v4df); | |
25958 | v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf); | |
25959 | v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df); | |
25960 | v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf); | |
25961 | v4df __builtin_ia32_vbroadcastsd256 (pcdouble); | |
25962 | v4sf __builtin_ia32_vbroadcastss (pcfloat); | |
25963 | v8sf __builtin_ia32_vbroadcastss256 (pcfloat); | |
25964 | v2df __builtin_ia32_vextractf128_pd256 (v4df,int); | |
25965 | v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int); | |
25966 | v4si __builtin_ia32_vextractf128_si256 (v8si,int); | |
25967 | v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int); | |
25968 | v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int); | |
25969 | v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int); | |
25970 | v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int); | |
25971 | v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int); | |
25972 | v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int); | |
25973 | v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int); | |
25974 | v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int); | |
25975 | v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int); | |
25976 | v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int); | |
25977 | v2df __builtin_ia32_vpermilpd (v2df,int); | |
25978 | v4df __builtin_ia32_vpermilpd256 (v4df,int); | |
25979 | v4sf __builtin_ia32_vpermilps (v4sf,int); | |
25980 | v8sf __builtin_ia32_vpermilps256 (v8sf,int); | |
25981 | v2df __builtin_ia32_vpermilvarpd (v2df,v2di); | |
25982 | v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di); | |
25983 | v4sf __builtin_ia32_vpermilvarps (v4sf,v4si); | |
25984 | v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si); | |
25985 | int __builtin_ia32_vtestcpd (v2df,v2df,ptest); | |
25986 | int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest); | |
25987 | int __builtin_ia32_vtestcps (v4sf,v4sf,ptest); | |
25988 | int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest); | |
25989 | int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest); | |
25990 | int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest); | |
25991 | int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest); | |
25992 | int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest); | |
25993 | int __builtin_ia32_vtestzpd (v2df,v2df,ptest); | |
25994 | int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest); | |
25995 | int __builtin_ia32_vtestzps (v4sf,v4sf,ptest); | |
25996 | int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest); | |
25997 | void __builtin_ia32_vzeroall (void); | |
25998 | void __builtin_ia32_vzeroupper (void); | |
25999 | v4df __builtin_ia32_xorpd256 (v4df,v4df); | |
26000 | v8sf __builtin_ia32_xorps256 (v8sf,v8sf); | |
26001 | @end smallexample | |
26002 | ||
26003 | The following built-in functions are available when @option{-mavx2} is | |
26004 | used. All of them generate the machine instruction that is part of the | |
26005 | name. | |
26006 | ||
26007 | @smallexample | |
26008 | v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int); | |
26009 | v32qi __builtin_ia32_pabsb256 (v32qi); | |
26010 | v16hi __builtin_ia32_pabsw256 (v16hi); | |
26011 | v8si __builtin_ia32_pabsd256 (v8si); | |
26012 | v16hi __builtin_ia32_packssdw256 (v8si,v8si); | |
26013 | v32qi __builtin_ia32_packsswb256 (v16hi,v16hi); | |
26014 | v16hi __builtin_ia32_packusdw256 (v8si,v8si); | |
26015 | v32qi __builtin_ia32_packuswb256 (v16hi,v16hi); | |
26016 | v32qi __builtin_ia32_paddb256 (v32qi,v32qi); | |
26017 | v16hi __builtin_ia32_paddw256 (v16hi,v16hi); | |
26018 | v8si __builtin_ia32_paddd256 (v8si,v8si); | |
26019 | v4di __builtin_ia32_paddq256 (v4di,v4di); | |
26020 | v32qi __builtin_ia32_paddsb256 (v32qi,v32qi); | |
26021 | v16hi __builtin_ia32_paddsw256 (v16hi,v16hi); | |
26022 | v32qi __builtin_ia32_paddusb256 (v32qi,v32qi); | |
26023 | v16hi __builtin_ia32_paddusw256 (v16hi,v16hi); | |
26024 | v4di __builtin_ia32_palignr256 (v4di,v4di,int); | |
26025 | v4di __builtin_ia32_andsi256 (v4di,v4di); | |
26026 | v4di __builtin_ia32_andnotsi256 (v4di,v4di); | |
26027 | v32qi __builtin_ia32_pavgb256 (v32qi,v32qi); | |
26028 | v16hi __builtin_ia32_pavgw256 (v16hi,v16hi); | |
26029 | v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi); | |
26030 | v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int); | |
26031 | v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi); | |
26032 | v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi); | |
26033 | v8si __builtin_ia32_pcmpeqd256 (c8si,v8si); | |
26034 | v4di __builtin_ia32_pcmpeqq256 (v4di,v4di); | |
26035 | v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi); | |
26036 | v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi); | |
26037 | v8si __builtin_ia32_pcmpgtd256 (v8si,v8si); | |
26038 | v4di __builtin_ia32_pcmpgtq256 (v4di,v4di); | |
26039 | v16hi __builtin_ia32_phaddw256 (v16hi,v16hi); | |
26040 | v8si __builtin_ia32_phaddd256 (v8si,v8si); | |
26041 | v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi); | |
26042 | v16hi __builtin_ia32_phsubw256 (v16hi,v16hi); | |
26043 | v8si __builtin_ia32_phsubd256 (v8si,v8si); | |
26044 | v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi); | |
26045 | v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi); | |
26046 | v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi); | |
26047 | v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi); | |
26048 | v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi); | |
26049 | v8si __builtin_ia32_pmaxsd256 (v8si,v8si); | |
26050 | v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi); | |
26051 | v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi); | |
26052 | v8si __builtin_ia32_pmaxud256 (v8si,v8si); | |
26053 | v32qi __builtin_ia32_pminsb256 (v32qi,v32qi); | |
26054 | v16hi __builtin_ia32_pminsw256 (v16hi,v16hi); | |
26055 | v8si __builtin_ia32_pminsd256 (v8si,v8si); | |
26056 | v32qi __builtin_ia32_pminub256 (v32qi,v32qi); | |
26057 | v16hi __builtin_ia32_pminuw256 (v16hi,v16hi); | |
26058 | v8si __builtin_ia32_pminud256 (v8si,v8si); | |
26059 | int __builtin_ia32_pmovmskb256 (v32qi); | |
26060 | v16hi __builtin_ia32_pmovsxbw256 (v16qi); | |
26061 | v8si __builtin_ia32_pmovsxbd256 (v16qi); | |
26062 | v4di __builtin_ia32_pmovsxbq256 (v16qi); | |
26063 | v8si __builtin_ia32_pmovsxwd256 (v8hi); | |
26064 | v4di __builtin_ia32_pmovsxwq256 (v8hi); | |
26065 | v4di __builtin_ia32_pmovsxdq256 (v4si); | |
26066 | v16hi __builtin_ia32_pmovzxbw256 (v16qi); | |
26067 | v8si __builtin_ia32_pmovzxbd256 (v16qi); | |
26068 | v4di __builtin_ia32_pmovzxbq256 (v16qi); | |
26069 | v8si __builtin_ia32_pmovzxwd256 (v8hi); | |
26070 | v4di __builtin_ia32_pmovzxwq256 (v8hi); | |
26071 | v4di __builtin_ia32_pmovzxdq256 (v4si); | |
26072 | v4di __builtin_ia32_pmuldq256 (v8si,v8si); | |
26073 | v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi); | |
26074 | v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi); | |
26075 | v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi); | |
26076 | v16hi __builtin_ia32_pmullw256 (v16hi,v16hi); | |
26077 | v8si __builtin_ia32_pmulld256 (v8si,v8si); | |
26078 | v4di __builtin_ia32_pmuludq256 (v8si,v8si); | |
26079 | v4di __builtin_ia32_por256 (v4di,v4di); | |
26080 | v16hi __builtin_ia32_psadbw256 (v32qi,v32qi); | |
26081 | v32qi __builtin_ia32_pshufb256 (v32qi,v32qi); | |
26082 | v8si __builtin_ia32_pshufd256 (v8si,int); | |
26083 | v16hi __builtin_ia32_pshufhw256 (v16hi,int); | |
26084 | v16hi __builtin_ia32_pshuflw256 (v16hi,int); | |
26085 | v32qi __builtin_ia32_psignb256 (v32qi,v32qi); | |
26086 | v16hi __builtin_ia32_psignw256 (v16hi,v16hi); | |
26087 | v8si __builtin_ia32_psignd256 (v8si,v8si); | |
26088 | v4di __builtin_ia32_pslldqi256 (v4di,int); | |
26089 | v16hi __builtin_ia32_psllwi256 (16hi,int); | |
26090 | v16hi __builtin_ia32_psllw256(v16hi,v8hi); | |
26091 | v8si __builtin_ia32_pslldi256 (v8si,int); | |
26092 | v8si __builtin_ia32_pslld256(v8si,v4si); | |
26093 | v4di __builtin_ia32_psllqi256 (v4di,int); | |
26094 | v4di __builtin_ia32_psllq256(v4di,v2di); | |
26095 | v16hi __builtin_ia32_psrawi256 (v16hi,int); | |
26096 | v16hi __builtin_ia32_psraw256 (v16hi,v8hi); | |
26097 | v8si __builtin_ia32_psradi256 (v8si,int); | |
26098 | v8si __builtin_ia32_psrad256 (v8si,v4si); | |
26099 | v4di __builtin_ia32_psrldqi256 (v4di, int); | |
26100 | v16hi __builtin_ia32_psrlwi256 (v16hi,int); | |
26101 | v16hi __builtin_ia32_psrlw256 (v16hi,v8hi); | |
26102 | v8si __builtin_ia32_psrldi256 (v8si,int); | |
26103 | v8si __builtin_ia32_psrld256 (v8si,v4si); | |
26104 | v4di __builtin_ia32_psrlqi256 (v4di,int); | |
26105 | v4di __builtin_ia32_psrlq256(v4di,v2di); | |
26106 | v32qi __builtin_ia32_psubb256 (v32qi,v32qi); | |
26107 | v32hi __builtin_ia32_psubw256 (v16hi,v16hi); | |
26108 | v8si __builtin_ia32_psubd256 (v8si,v8si); | |
26109 | v4di __builtin_ia32_psubq256 (v4di,v4di); | |
26110 | v32qi __builtin_ia32_psubsb256 (v32qi,v32qi); | |
26111 | v16hi __builtin_ia32_psubsw256 (v16hi,v16hi); | |
26112 | v32qi __builtin_ia32_psubusb256 (v32qi,v32qi); | |
26113 | v16hi __builtin_ia32_psubusw256 (v16hi,v16hi); | |
26114 | v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi); | |
26115 | v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi); | |
26116 | v8si __builtin_ia32_punpckhdq256 (v8si,v8si); | |
26117 | v4di __builtin_ia32_punpckhqdq256 (v4di,v4di); | |
26118 | v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi); | |
26119 | v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi); | |
26120 | v8si __builtin_ia32_punpckldq256 (v8si,v8si); | |
26121 | v4di __builtin_ia32_punpcklqdq256 (v4di,v4di); | |
26122 | v4di __builtin_ia32_pxor256 (v4di,v4di); | |
26123 | v4di __builtin_ia32_movntdqa256 (pv4di); | |
26124 | v4sf __builtin_ia32_vbroadcastss_ps (v4sf); | |
26125 | v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf); | |
26126 | v4df __builtin_ia32_vbroadcastsd_pd256 (v2df); | |
26127 | v4di __builtin_ia32_vbroadcastsi256 (v2di); | |
26128 | v4si __builtin_ia32_pblendd128 (v4si,v4si); | |
26129 | v8si __builtin_ia32_pblendd256 (v8si,v8si); | |
26130 | v32qi __builtin_ia32_pbroadcastb256 (v16qi); | |
26131 | v16hi __builtin_ia32_pbroadcastw256 (v8hi); | |
26132 | v8si __builtin_ia32_pbroadcastd256 (v4si); | |
26133 | v4di __builtin_ia32_pbroadcastq256 (v2di); | |
26134 | v16qi __builtin_ia32_pbroadcastb128 (v16qi); | |
26135 | v8hi __builtin_ia32_pbroadcastw128 (v8hi); | |
26136 | v4si __builtin_ia32_pbroadcastd128 (v4si); | |
26137 | v2di __builtin_ia32_pbroadcastq128 (v2di); | |
26138 | v8si __builtin_ia32_permvarsi256 (v8si,v8si); | |
26139 | v4df __builtin_ia32_permdf256 (v4df,int); | |
26140 | v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf); | |
26141 | v4di __builtin_ia32_permdi256 (v4di,int); | |
26142 | v4di __builtin_ia32_permti256 (v4di,v4di,int); | |
26143 | v4di __builtin_ia32_extract128i256 (v4di,int); | |
26144 | v4di __builtin_ia32_insert128i256 (v4di,v2di,int); | |
26145 | v8si __builtin_ia32_maskloadd256 (pcv8si,v8si); | |
26146 | v4di __builtin_ia32_maskloadq256 (pcv4di,v4di); | |
26147 | v4si __builtin_ia32_maskloadd (pcv4si,v4si); | |
26148 | v2di __builtin_ia32_maskloadq (pcv2di,v2di); | |
26149 | void __builtin_ia32_maskstored256 (pv8si,v8si,v8si); | |
26150 | void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di); | |
26151 | void __builtin_ia32_maskstored (pv4si,v4si,v4si); | |
26152 | void __builtin_ia32_maskstoreq (pv2di,v2di,v2di); | |
26153 | v8si __builtin_ia32_psllv8si (v8si,v8si); | |
26154 | v4si __builtin_ia32_psllv4si (v4si,v4si); | |
26155 | v4di __builtin_ia32_psllv4di (v4di,v4di); | |
26156 | v2di __builtin_ia32_psllv2di (v2di,v2di); | |
26157 | v8si __builtin_ia32_psrav8si (v8si,v8si); | |
26158 | v4si __builtin_ia32_psrav4si (v4si,v4si); | |
26159 | v8si __builtin_ia32_psrlv8si (v8si,v8si); | |
26160 | v4si __builtin_ia32_psrlv4si (v4si,v4si); | |
26161 | v4di __builtin_ia32_psrlv4di (v4di,v4di); | |
26162 | v2di __builtin_ia32_psrlv2di (v2di,v2di); | |
26163 | v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int); | |
26164 | v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int); | |
26165 | v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int); | |
26166 | v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int); | |
26167 | v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int); | |
26168 | v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int); | |
26169 | v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int); | |
26170 | v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int); | |
26171 | v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int); | |
26172 | v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int); | |
26173 | v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int); | |
26174 | v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int); | |
26175 | v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int); | |
26176 | v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int); | |
26177 | v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int); | |
26178 | v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int); | |
26179 | @end smallexample | |
26180 | ||
26181 | The following built-in functions are available when @option{-maes} is | |
26182 | used. All of them generate the machine instruction that is part of the | |
26183 | name. | |
26184 | ||
26185 | @smallexample | |
26186 | v2di __builtin_ia32_aesenc128 (v2di, v2di); | |
26187 | v2di __builtin_ia32_aesenclast128 (v2di, v2di); | |
26188 | v2di __builtin_ia32_aesdec128 (v2di, v2di); | |
26189 | v2di __builtin_ia32_aesdeclast128 (v2di, v2di); | |
26190 | v2di __builtin_ia32_aeskeygenassist128 (v2di, const int); | |
26191 | v2di __builtin_ia32_aesimc128 (v2di); | |
26192 | @end smallexample | |
26193 | ||
26194 | The following built-in function is available when @option{-mpclmul} is | |
26195 | used. | |
26196 | ||
f25efe50 | 26197 | @defbuiltin{v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)} |
d77de738 | 26198 | Generates the @code{pclmulqdq} machine instruction. |
f25efe50 | 26199 | @enddefbuiltin |
d77de738 ML |
26200 | |
26201 | The following built-in function is available when @option{-mfsgsbase} is | |
26202 | used. All of them generate the machine instruction that is part of the | |
26203 | name. | |
26204 | ||
26205 | @smallexample | |
26206 | unsigned int __builtin_ia32_rdfsbase32 (void); | |
26207 | unsigned long long __builtin_ia32_rdfsbase64 (void); | |
26208 | unsigned int __builtin_ia32_rdgsbase32 (void); | |
26209 | unsigned long long __builtin_ia32_rdgsbase64 (void); | |
26210 | void _writefsbase_u32 (unsigned int); | |
26211 | void _writefsbase_u64 (unsigned long long); | |
26212 | void _writegsbase_u32 (unsigned int); | |
26213 | void _writegsbase_u64 (unsigned long long); | |
26214 | @end smallexample | |
26215 | ||
26216 | The following built-in function is available when @option{-mrdrnd} is | |
26217 | used. All of them generate the machine instruction that is part of the | |
26218 | name. | |
26219 | ||
26220 | @smallexample | |
26221 | unsigned int __builtin_ia32_rdrand16_step (unsigned short *); | |
26222 | unsigned int __builtin_ia32_rdrand32_step (unsigned int *); | |
26223 | unsigned int __builtin_ia32_rdrand64_step (unsigned long long *); | |
26224 | @end smallexample | |
26225 | ||
26226 | The following built-in function is available when @option{-mptwrite} is | |
26227 | used. All of them generate the machine instruction that is part of the | |
26228 | name. | |
26229 | ||
26230 | @smallexample | |
26231 | void __builtin_ia32_ptwrite32 (unsigned); | |
26232 | void __builtin_ia32_ptwrite64 (unsigned long long); | |
26233 | @end smallexample | |
26234 | ||
26235 | The following built-in functions are available when @option{-msse4a} is used. | |
26236 | All of them generate the machine instruction that is part of the name. | |
26237 | ||
26238 | @smallexample | |
26239 | void __builtin_ia32_movntsd (double *, v2df); | |
26240 | void __builtin_ia32_movntss (float *, v4sf); | |
26241 | v2di __builtin_ia32_extrq (v2di, v16qi); | |
26242 | v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int); | |
26243 | v2di __builtin_ia32_insertq (v2di, v2di); | |
26244 | v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int); | |
26245 | @end smallexample | |
26246 | ||
26247 | The following built-in functions are available when @option{-mxop} is used. | |
26248 | @smallexample | |
26249 | v2df __builtin_ia32_vfrczpd (v2df); | |
26250 | v4sf __builtin_ia32_vfrczps (v4sf); | |
26251 | v2df __builtin_ia32_vfrczsd (v2df); | |
26252 | v4sf __builtin_ia32_vfrczss (v4sf); | |
26253 | v4df __builtin_ia32_vfrczpd256 (v4df); | |
26254 | v8sf __builtin_ia32_vfrczps256 (v8sf); | |
26255 | v2di __builtin_ia32_vpcmov (v2di, v2di, v2di); | |
26256 | v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di); | |
26257 | v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si); | |
26258 | v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi); | |
26259 | v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi); | |
26260 | v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df); | |
26261 | v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf); | |
26262 | v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di); | |
26263 | v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si); | |
26264 | v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi); | |
26265 | v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi); | |
26266 | v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df); | |
26267 | v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf); | |
26268 | v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi); | |
26269 | v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi); | |
26270 | v4si __builtin_ia32_vpcomeqd (v4si, v4si); | |
26271 | v2di __builtin_ia32_vpcomeqq (v2di, v2di); | |
26272 | v16qi __builtin_ia32_vpcomequb (v16qi, v16qi); | |
26273 | v4si __builtin_ia32_vpcomequd (v4si, v4si); | |
26274 | v2di __builtin_ia32_vpcomequq (v2di, v2di); | |
26275 | v8hi __builtin_ia32_vpcomequw (v8hi, v8hi); | |
26276 | v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi); | |
26277 | v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi); | |
26278 | v4si __builtin_ia32_vpcomfalsed (v4si, v4si); | |
26279 | v2di __builtin_ia32_vpcomfalseq (v2di, v2di); | |
26280 | v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi); | |
26281 | v4si __builtin_ia32_vpcomfalseud (v4si, v4si); | |
26282 | v2di __builtin_ia32_vpcomfalseuq (v2di, v2di); | |
26283 | v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi); | |
26284 | v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi); | |
26285 | v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi); | |
26286 | v4si __builtin_ia32_vpcomged (v4si, v4si); | |
26287 | v2di __builtin_ia32_vpcomgeq (v2di, v2di); | |
26288 | v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi); | |
26289 | v4si __builtin_ia32_vpcomgeud (v4si, v4si); | |
26290 | v2di __builtin_ia32_vpcomgeuq (v2di, v2di); | |
26291 | v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi); | |
26292 | v8hi __builtin_ia32_vpcomgew (v8hi, v8hi); | |
26293 | v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi); | |
26294 | v4si __builtin_ia32_vpcomgtd (v4si, v4si); | |
26295 | v2di __builtin_ia32_vpcomgtq (v2di, v2di); | |
26296 | v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi); | |
26297 | v4si __builtin_ia32_vpcomgtud (v4si, v4si); | |
26298 | v2di __builtin_ia32_vpcomgtuq (v2di, v2di); | |
26299 | v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi); | |
26300 | v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi); | |
26301 | v16qi __builtin_ia32_vpcomleb (v16qi, v16qi); | |
26302 | v4si __builtin_ia32_vpcomled (v4si, v4si); | |
26303 | v2di __builtin_ia32_vpcomleq (v2di, v2di); | |
26304 | v16qi __builtin_ia32_vpcomleub (v16qi, v16qi); | |
26305 | v4si __builtin_ia32_vpcomleud (v4si, v4si); | |
26306 | v2di __builtin_ia32_vpcomleuq (v2di, v2di); | |
26307 | v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi); | |
26308 | v8hi __builtin_ia32_vpcomlew (v8hi, v8hi); | |
26309 | v16qi __builtin_ia32_vpcomltb (v16qi, v16qi); | |
26310 | v4si __builtin_ia32_vpcomltd (v4si, v4si); | |
26311 | v2di __builtin_ia32_vpcomltq (v2di, v2di); | |
26312 | v16qi __builtin_ia32_vpcomltub (v16qi, v16qi); | |
26313 | v4si __builtin_ia32_vpcomltud (v4si, v4si); | |
26314 | v2di __builtin_ia32_vpcomltuq (v2di, v2di); | |
26315 | v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi); | |
26316 | v8hi __builtin_ia32_vpcomltw (v8hi, v8hi); | |
26317 | v16qi __builtin_ia32_vpcomneb (v16qi, v16qi); | |
26318 | v4si __builtin_ia32_vpcomned (v4si, v4si); | |
26319 | v2di __builtin_ia32_vpcomneq (v2di, v2di); | |
26320 | v16qi __builtin_ia32_vpcomneub (v16qi, v16qi); | |
26321 | v4si __builtin_ia32_vpcomneud (v4si, v4si); | |
26322 | v2di __builtin_ia32_vpcomneuq (v2di, v2di); | |
26323 | v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi); | |
26324 | v8hi __builtin_ia32_vpcomnew (v8hi, v8hi); | |
26325 | v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi); | |
26326 | v4si __builtin_ia32_vpcomtrued (v4si, v4si); | |
26327 | v2di __builtin_ia32_vpcomtrueq (v2di, v2di); | |
26328 | v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi); | |
26329 | v4si __builtin_ia32_vpcomtrueud (v4si, v4si); | |
26330 | v2di __builtin_ia32_vpcomtrueuq (v2di, v2di); | |
26331 | v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi); | |
26332 | v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi); | |
26333 | v4si __builtin_ia32_vphaddbd (v16qi); | |
26334 | v2di __builtin_ia32_vphaddbq (v16qi); | |
26335 | v8hi __builtin_ia32_vphaddbw (v16qi); | |
26336 | v2di __builtin_ia32_vphadddq (v4si); | |
26337 | v4si __builtin_ia32_vphaddubd (v16qi); | |
26338 | v2di __builtin_ia32_vphaddubq (v16qi); | |
26339 | v8hi __builtin_ia32_vphaddubw (v16qi); | |
26340 | v2di __builtin_ia32_vphaddudq (v4si); | |
26341 | v4si __builtin_ia32_vphadduwd (v8hi); | |
26342 | v2di __builtin_ia32_vphadduwq (v8hi); | |
26343 | v4si __builtin_ia32_vphaddwd (v8hi); | |
26344 | v2di __builtin_ia32_vphaddwq (v8hi); | |
26345 | v8hi __builtin_ia32_vphsubbw (v16qi); | |
26346 | v2di __builtin_ia32_vphsubdq (v4si); | |
26347 | v4si __builtin_ia32_vphsubwd (v8hi); | |
26348 | v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si); | |
26349 | v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di); | |
26350 | v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di); | |
26351 | v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si); | |
26352 | v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di); | |
26353 | v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di); | |
26354 | v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si); | |
26355 | v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi); | |
26356 | v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si); | |
26357 | v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi); | |
26358 | v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si); | |
26359 | v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si); | |
26360 | v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi); | |
26361 | v16qi __builtin_ia32_vprotb (v16qi, v16qi); | |
26362 | v4si __builtin_ia32_vprotd (v4si, v4si); | |
26363 | v2di __builtin_ia32_vprotq (v2di, v2di); | |
26364 | v8hi __builtin_ia32_vprotw (v8hi, v8hi); | |
26365 | v16qi __builtin_ia32_vpshab (v16qi, v16qi); | |
26366 | v4si __builtin_ia32_vpshad (v4si, v4si); | |
26367 | v2di __builtin_ia32_vpshaq (v2di, v2di); | |
26368 | v8hi __builtin_ia32_vpshaw (v8hi, v8hi); | |
26369 | v16qi __builtin_ia32_vpshlb (v16qi, v16qi); | |
26370 | v4si __builtin_ia32_vpshld (v4si, v4si); | |
26371 | v2di __builtin_ia32_vpshlq (v2di, v2di); | |
26372 | v8hi __builtin_ia32_vpshlw (v8hi, v8hi); | |
26373 | @end smallexample | |
26374 | ||
26375 | The following built-in functions are available when @option{-mfma4} is used. | |
26376 | All of them generate the machine instruction that is part of the name. | |
26377 | ||
26378 | @smallexample | |
26379 | v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df); | |
26380 | v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf); | |
26381 | v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df); | |
26382 | v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf); | |
26383 | v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df); | |
26384 | v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf); | |
26385 | v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df); | |
26386 | v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf); | |
26387 | v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df); | |
26388 | v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf); | |
26389 | v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df); | |
26390 | v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf); | |
26391 | v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df); | |
26392 | v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf); | |
26393 | v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df); | |
26394 | v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf); | |
26395 | v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df); | |
26396 | v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf); | |
26397 | v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df); | |
26398 | v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf); | |
26399 | v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df); | |
26400 | v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf); | |
26401 | v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df); | |
26402 | v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf); | |
26403 | v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df); | |
26404 | v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf); | |
26405 | v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df); | |
26406 | v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf); | |
26407 | v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df); | |
26408 | v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf); | |
26409 | v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df); | |
26410 | v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf); | |
26411 | ||
26412 | @end smallexample | |
26413 | ||
26414 | The following built-in functions are available when @option{-mlwp} is used. | |
26415 | ||
26416 | @smallexample | |
26417 | void __builtin_ia32_llwpcb16 (void *); | |
26418 | void __builtin_ia32_llwpcb32 (void *); | |
26419 | void __builtin_ia32_llwpcb64 (void *); | |
26420 | void * __builtin_ia32_llwpcb16 (void); | |
26421 | void * __builtin_ia32_llwpcb32 (void); | |
26422 | void * __builtin_ia32_llwpcb64 (void); | |
26423 | void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short); | |
26424 | void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int); | |
26425 | void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int); | |
26426 | unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short); | |
26427 | unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int); | |
26428 | unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int); | |
26429 | @end smallexample | |
26430 | ||
26431 | The following built-in functions are available when @option{-mbmi} is used. | |
26432 | All of them generate the machine instruction that is part of the name. | |
26433 | @smallexample | |
26434 | unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); | |
26435 | unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); | |
26436 | @end smallexample | |
26437 | ||
26438 | The following built-in functions are available when @option{-mbmi2} is used. | |
26439 | All of them generate the machine instruction that is part of the name. | |
26440 | @smallexample | |
26441 | unsigned int _bzhi_u32 (unsigned int, unsigned int); | |
26442 | unsigned int _pdep_u32 (unsigned int, unsigned int); | |
26443 | unsigned int _pext_u32 (unsigned int, unsigned int); | |
26444 | unsigned long long _bzhi_u64 (unsigned long long, unsigned long long); | |
26445 | unsigned long long _pdep_u64 (unsigned long long, unsigned long long); | |
26446 | unsigned long long _pext_u64 (unsigned long long, unsigned long long); | |
26447 | @end smallexample | |
26448 | ||
26449 | The following built-in functions are available when @option{-mlzcnt} is used. | |
26450 | All of them generate the machine instruction that is part of the name. | |
26451 | @smallexample | |
26452 | unsigned short __builtin_ia32_lzcnt_u16(unsigned short); | |
26453 | unsigned int __builtin_ia32_lzcnt_u32(unsigned int); | |
26454 | unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); | |
26455 | @end smallexample | |
26456 | ||
26457 | The following built-in functions are available when @option{-mfxsr} is used. | |
26458 | All of them generate the machine instruction that is part of the name. | |
26459 | @smallexample | |
26460 | void __builtin_ia32_fxsave (void *); | |
26461 | void __builtin_ia32_fxrstor (void *); | |
26462 | void __builtin_ia32_fxsave64 (void *); | |
26463 | void __builtin_ia32_fxrstor64 (void *); | |
26464 | @end smallexample | |
26465 | ||
26466 | The following built-in functions are available when @option{-mxsave} is used. | |
26467 | All of them generate the machine instruction that is part of the name. | |
26468 | @smallexample | |
26469 | void __builtin_ia32_xsave (void *, long long); | |
26470 | void __builtin_ia32_xrstor (void *, long long); | |
26471 | void __builtin_ia32_xsave64 (void *, long long); | |
26472 | void __builtin_ia32_xrstor64 (void *, long long); | |
26473 | @end smallexample | |
26474 | ||
26475 | The following built-in functions are available when @option{-mxsaveopt} is used. | |
26476 | All of them generate the machine instruction that is part of the name. | |
26477 | @smallexample | |
26478 | void __builtin_ia32_xsaveopt (void *, long long); | |
26479 | void __builtin_ia32_xsaveopt64 (void *, long long); | |
26480 | @end smallexample | |
26481 | ||
26482 | The following built-in functions are available when @option{-mtbm} is used. | |
26483 | Both of them generate the immediate form of the bextr machine instruction. | |
26484 | @smallexample | |
26485 | unsigned int __builtin_ia32_bextri_u32 (unsigned int, | |
26486 | const unsigned int); | |
26487 | unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, | |
26488 | const unsigned long long); | |
26489 | @end smallexample | |
26490 | ||
26491 | ||
26492 | The following built-in functions are available when @option{-m3dnow} is used. | |
26493 | All of them generate the machine instruction that is part of the name. | |
26494 | ||
26495 | @smallexample | |
26496 | void __builtin_ia32_femms (void); | |
26497 | v8qi __builtin_ia32_pavgusb (v8qi, v8qi); | |
26498 | v2si __builtin_ia32_pf2id (v2sf); | |
26499 | v2sf __builtin_ia32_pfacc (v2sf, v2sf); | |
26500 | v2sf __builtin_ia32_pfadd (v2sf, v2sf); | |
26501 | v2si __builtin_ia32_pfcmpeq (v2sf, v2sf); | |
26502 | v2si __builtin_ia32_pfcmpge (v2sf, v2sf); | |
26503 | v2si __builtin_ia32_pfcmpgt (v2sf, v2sf); | |
26504 | v2sf __builtin_ia32_pfmax (v2sf, v2sf); | |
26505 | v2sf __builtin_ia32_pfmin (v2sf, v2sf); | |
26506 | v2sf __builtin_ia32_pfmul (v2sf, v2sf); | |
26507 | v2sf __builtin_ia32_pfrcp (v2sf); | |
26508 | v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf); | |
26509 | v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf); | |
26510 | v2sf __builtin_ia32_pfrsqrt (v2sf); | |
26511 | v2sf __builtin_ia32_pfsub (v2sf, v2sf); | |
26512 | v2sf __builtin_ia32_pfsubr (v2sf, v2sf); | |
26513 | v2sf __builtin_ia32_pi2fd (v2si); | |
26514 | v4hi __builtin_ia32_pmulhrw (v4hi, v4hi); | |
26515 | @end smallexample | |
26516 | ||
26517 | The following built-in functions are available when @option{-m3dnowa} is used. | |
26518 | All of them generate the machine instruction that is part of the name. | |
26519 | ||
26520 | @smallexample | |
26521 | v2si __builtin_ia32_pf2iw (v2sf); | |
26522 | v2sf __builtin_ia32_pfnacc (v2sf, v2sf); | |
26523 | v2sf __builtin_ia32_pfpnacc (v2sf, v2sf); | |
26524 | v2sf __builtin_ia32_pi2fw (v2si); | |
26525 | v2sf __builtin_ia32_pswapdsf (v2sf); | |
26526 | v2si __builtin_ia32_pswapdsi (v2si); | |
26527 | @end smallexample | |
26528 | ||
26529 | The following built-in functions are available when @option{-mrtm} is used | |
26530 | They are used for restricted transactional memory. These are the internal | |
26531 | low level functions. Normally the functions in | |
26532 | @ref{x86 transactional memory intrinsics} should be used instead. | |
26533 | ||
26534 | @smallexample | |
26535 | int __builtin_ia32_xbegin (); | |
26536 | void __builtin_ia32_xend (); | |
26537 | void __builtin_ia32_xabort (status); | |
26538 | int __builtin_ia32_xtest (); | |
26539 | @end smallexample | |
26540 | ||
26541 | The following built-in functions are available when @option{-mmwaitx} is used. | |
26542 | All of them generate the machine instruction that is part of the name. | |
26543 | @smallexample | |
26544 | void __builtin_ia32_monitorx (void *, unsigned int, unsigned int); | |
26545 | void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int); | |
26546 | @end smallexample | |
26547 | ||
26548 | The following built-in functions are available when @option{-mclzero} is used. | |
26549 | All of them generate the machine instruction that is part of the name. | |
26550 | @smallexample | |
26551 | void __builtin_i32_clzero (void *); | |
26552 | @end smallexample | |
26553 | ||
26554 | The following built-in functions are available when @option{-mpku} is used. | |
26555 | They generate reads and writes to PKRU. | |
26556 | @smallexample | |
26557 | void __builtin_ia32_wrpkru (unsigned int); | |
26558 | unsigned int __builtin_ia32_rdpkru (); | |
26559 | @end smallexample | |
26560 | ||
26561 | The following built-in functions are available when | |
26562 | @option{-mshstk} option is used. They support shadow stack | |
26563 | machine instructions from Intel Control-flow Enforcement Technology (CET). | |
26564 | Each built-in function generates the machine instruction that is part | |
26565 | of the function's name. These are the internal low-level functions. | |
26566 | Normally the functions in @ref{x86 control-flow protection intrinsics} | |
26567 | should be used instead. | |
26568 | ||
26569 | @smallexample | |
26570 | unsigned int __builtin_ia32_rdsspd (void); | |
26571 | unsigned long long __builtin_ia32_rdsspq (void); | |
26572 | void __builtin_ia32_incsspd (unsigned int); | |
26573 | void __builtin_ia32_incsspq (unsigned long long); | |
26574 | void __builtin_ia32_saveprevssp(void); | |
26575 | void __builtin_ia32_rstorssp(void *); | |
26576 | void __builtin_ia32_wrssd(unsigned int, void *); | |
26577 | void __builtin_ia32_wrssq(unsigned long long, void *); | |
26578 | void __builtin_ia32_wrussd(unsigned int, void *); | |
26579 | void __builtin_ia32_wrussq(unsigned long long, void *); | |
26580 | void __builtin_ia32_setssbsy(void); | |
26581 | void __builtin_ia32_clrssbsy(void *); | |
26582 | @end smallexample | |
26583 | ||
26584 | @node x86 transactional memory intrinsics | |
26585 | @subsection x86 Transactional Memory Intrinsics | |
26586 | ||
26587 | These hardware transactional memory intrinsics for x86 allow you to use | |
26588 | memory transactions with RTM (Restricted Transactional Memory). | |
26589 | This support is enabled with the @option{-mrtm} option. | |
26590 | For using HLE (Hardware Lock Elision) see | |
26591 | @ref{x86 specific memory model extensions for transactional memory} instead. | |
26592 | ||
26593 | A memory transaction commits all changes to memory in an atomic way, | |
26594 | as visible to other threads. If the transaction fails it is rolled back | |
26595 | and all side effects discarded. | |
26596 | ||
26597 | Generally there is no guarantee that a memory transaction ever succeeds | |
26598 | and suitable fallback code always needs to be supplied. | |
26599 | ||
26600 | @deftypefn {RTM Function} {unsigned} _xbegin () | |
26601 | Start a RTM (Restricted Transactional Memory) transaction. | |
26602 | Returns @code{_XBEGIN_STARTED} when the transaction | |
26603 | started successfully (note this is not 0, so the constant has to be | |
26604 | explicitly tested). | |
26605 | ||
26606 | If the transaction aborts, all side effects | |
26607 | are undone and an abort code encoded as a bit mask is returned. | |
26608 | The following macros are defined: | |
26609 | ||
f25efe50 | 26610 | @defmac{_XABORT_EXPLICIT} |
d77de738 ML |
26611 | Transaction was explicitly aborted with @code{_xabort}. The parameter passed |
26612 | to @code{_xabort} is available with @code{_XABORT_CODE(status)}. | |
f25efe50 AA |
26613 | @end defmac |
26614 | ||
26615 | @defmac{_XABORT_RETRY} | |
d77de738 | 26616 | Transaction retry is possible. |
f25efe50 AA |
26617 | @end defmac |
26618 | ||
26619 | @defmac{_XABORT_CONFLICT} | |
d77de738 | 26620 | Transaction abort due to a memory conflict with another thread. |
f25efe50 AA |
26621 | @end defmac |
26622 | ||
26623 | @defmac{_XABORT_CAPACITY} | |
d77de738 | 26624 | Transaction abort due to the transaction using too much memory. |
f25efe50 AA |
26625 | @end defmac |
26626 | ||
26627 | @defmac{_XABORT_DEBUG} | |
d77de738 | 26628 | Transaction abort due to a debug trap. |
f25efe50 AA |
26629 | @end defmac |
26630 | ||
26631 | @defmac{_XABORT_NESTED} | |
d77de738 | 26632 | Transaction abort in an inner nested transaction. |
f25efe50 | 26633 | @end defmac |
d77de738 ML |
26634 | |
26635 | There is no guarantee | |
26636 | any transaction ever succeeds, so there always needs to be a valid | |
26637 | fallback path. | |
26638 | @end deftypefn | |
26639 | ||
26640 | @deftypefn {RTM Function} {void} _xend () | |
26641 | Commit the current transaction. When no transaction is active this faults. | |
26642 | All memory side effects of the transaction become visible | |
26643 | to other threads in an atomic manner. | |
26644 | @end deftypefn | |
26645 | ||
26646 | @deftypefn {RTM Function} {int} _xtest () | |
26647 | Return a nonzero value if a transaction is currently active, otherwise 0. | |
26648 | @end deftypefn | |
26649 | ||
26650 | @deftypefn {RTM Function} {void} _xabort (status) | |
26651 | Abort the current transaction. When no transaction is active this is a no-op. | |
26652 | The @var{status} is an 8-bit constant; its value is encoded in the return | |
26653 | value from @code{_xbegin}. | |
26654 | @end deftypefn | |
26655 | ||
26656 | Here is an example showing handling for @code{_XABORT_RETRY} | |
26657 | and a fallback path for other failures: | |
26658 | ||
26659 | @smallexample | |
26660 | #include <immintrin.h> | |
26661 | ||
26662 | int n_tries, max_tries; | |
26663 | unsigned status = _XABORT_EXPLICIT; | |
26664 | ... | |
26665 | ||
26666 | for (n_tries = 0; n_tries < max_tries; n_tries++) | |
26667 | @{ | |
26668 | status = _xbegin (); | |
26669 | if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY)) | |
26670 | break; | |
26671 | @} | |
26672 | if (status == _XBEGIN_STARTED) | |
26673 | @{ | |
26674 | ... transaction code... | |
26675 | _xend (); | |
26676 | @} | |
26677 | else | |
26678 | @{ | |
26679 | ... non-transactional fallback path... | |
26680 | @} | |
26681 | @end smallexample | |
26682 | ||
26683 | @noindent | |
26684 | Note that, in most cases, the transactional and non-transactional code | |
26685 | must synchronize together to ensure consistency. | |
26686 | ||
26687 | @node x86 control-flow protection intrinsics | |
26688 | @subsection x86 Control-Flow Protection Intrinsics | |
26689 | ||
26690 | @deftypefn {CET Function} {ret_type} _get_ssp (void) | |
26691 | Get the current value of shadow stack pointer if shadow stack support | |
26692 | from Intel CET is enabled in the hardware or @code{0} otherwise. | |
26693 | The @code{ret_type} is @code{unsigned long long} for 64-bit targets | |
26694 | and @code{unsigned int} for 32-bit targets. | |
26695 | @end deftypefn | |
26696 | ||
26697 | @deftypefn {CET Function} void _inc_ssp (unsigned int) | |
26698 | Increment the current shadow stack pointer by the size specified by the | |
26699 | function argument. The argument is masked to a byte value for security | |
26700 | reasons, so to increment by more than 255 bytes you must call the function | |
26701 | multiple times. | |
26702 | @end deftypefn | |
26703 | ||
26704 | The shadow stack unwind code looks like: | |
26705 | ||
26706 | @smallexample | |
26707 | #include <immintrin.h> | |
26708 | ||
26709 | /* Unwind the shadow stack for EH. */ | |
26710 | #define _Unwind_Frames_Extra(x) \ | |
26711 | do \ | |
26712 | @{ \ | |
26713 | _Unwind_Word ssp = _get_ssp (); \ | |
26714 | if (ssp != 0) \ | |
26715 | @{ \ | |
26716 | _Unwind_Word tmp = (x); \ | |
26717 | while (tmp > 255) \ | |
26718 | @{ \ | |
26719 | _inc_ssp (tmp); \ | |
26720 | tmp -= 255; \ | |
26721 | @} \ | |
26722 | _inc_ssp (tmp); \ | |
26723 | @} \ | |
26724 | @} \ | |
26725 | while (0) | |
26726 | @end smallexample | |
26727 | ||
26728 | @noindent | |
26729 | This code runs unconditionally on all 64-bit processors. For 32-bit | |
26730 | processors the code runs on those that support multi-byte NOP instructions. | |
26731 | ||
26732 | @node Target Format Checks | |
26733 | @section Format Checks Specific to Particular Target Machines | |
26734 | ||
26735 | For some target machines, GCC supports additional options to the | |
26736 | format attribute | |
26737 | (@pxref{Function Attributes,,Declaring Attributes of Functions}). | |
26738 | ||
26739 | @menu | |
26740 | * Solaris Format Checks:: | |
26741 | * Darwin Format Checks:: | |
26742 | @end menu | |
26743 | ||
26744 | @node Solaris Format Checks | |
26745 | @subsection Solaris Format Checks | |
26746 | ||
26747 | Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format | |
26748 | check. @code{cmn_err} accepts a subset of the standard @code{printf} | |
26749 | conversions, and the two-argument @code{%b} conversion for displaying | |
26750 | bit-fields. See the Solaris man page for @code{cmn_err} for more information. | |
26751 | ||
26752 | @node Darwin Format Checks | |
26753 | @subsection Darwin Format Checks | |
26754 | ||
26755 | In addition to the full set of format archetypes (attribute format style | |
26756 | arguments such as @code{printf}, @code{scanf}, @code{strftime}, and | |
26757 | @code{strfmon}), Darwin targets also support the @code{CFString} (or | |
26758 | @code{__CFString__}) archetype in the @code{format} attribute. | |
26759 | Declarations with this archetype are parsed for correct syntax | |
26760 | and argument types. However, parsing of the format string itself and | |
26761 | validating arguments against it in calls to such functions is currently | |
26762 | not performed. | |
26763 | ||
26764 | Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may | |
26765 | also be used as format arguments. Note that the relevant headers are only likely to be | |
26766 | available on Darwin (OSX) installations. On such installations, the XCode and system | |
26767 | documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and | |
26768 | associated functions. | |
26769 | ||
26770 | @node Pragmas | |
26771 | @section Pragmas Accepted by GCC | |
26772 | @cindex pragmas | |
26773 | @cindex @code{#pragma} | |
26774 | ||
26775 | GCC supports several types of pragmas, primarily in order to compile | |
26776 | code originally written for other compilers. Note that in general | |
26777 | we do not recommend the use of pragmas; @xref{Function Attributes}, | |
26778 | for further explanation. | |
26779 | ||
26780 | The GNU C preprocessor recognizes several pragmas in addition to the | |
26781 | compiler pragmas documented here. Refer to the CPP manual for more | |
26782 | information. | |
26783 | ||
26784 | @menu | |
26785 | * AArch64 Pragmas:: | |
26786 | * ARM Pragmas:: | |
26787 | * M32C Pragmas:: | |
d77de738 ML |
26788 | * PRU Pragmas:: |
26789 | * RS/6000 and PowerPC Pragmas:: | |
26790 | * S/390 Pragmas:: | |
26791 | * Darwin Pragmas:: | |
26792 | * Solaris Pragmas:: | |
26793 | * Symbol-Renaming Pragmas:: | |
26794 | * Structure-Layout Pragmas:: | |
26795 | * Weak Pragmas:: | |
26796 | * Diagnostic Pragmas:: | |
26797 | * Visibility Pragmas:: | |
26798 | * Push/Pop Macro Pragmas:: | |
26799 | * Function Specific Option Pragmas:: | |
26800 | * Loop-Specific Pragmas:: | |
26801 | @end menu | |
26802 | ||
26803 | @node AArch64 Pragmas | |
26804 | @subsection AArch64 Pragmas | |
26805 | ||
26806 | The pragmas defined by the AArch64 target correspond to the AArch64 | |
26807 | target function attributes. They can be specified as below: | |
26808 | @smallexample | |
26809 | #pragma GCC target("string") | |
26810 | @end smallexample | |
26811 | ||
26812 | where @code{@var{string}} can be any string accepted as an AArch64 target | |
26813 | attribute. @xref{AArch64 Function Attributes}, for more details | |
26814 | on the permissible values of @code{string}. | |
26815 | ||
26816 | @node ARM Pragmas | |
26817 | @subsection ARM Pragmas | |
26818 | ||
26819 | The ARM target defines pragmas for controlling the default addition of | |
26820 | @code{long_call} and @code{short_call} attributes to functions. | |
26821 | @xref{Function Attributes}, for information about the effects of these | |
26822 | attributes. | |
26823 | ||
26824 | @table @code | |
d77de738 | 26825 | @cindex pragma, long_calls |
f25efe50 | 26826 | @item long_calls |
d77de738 ML |
26827 | Set all subsequent functions to have the @code{long_call} attribute. |
26828 | ||
d77de738 | 26829 | @cindex pragma, no_long_calls |
f25efe50 | 26830 | @item no_long_calls |
d77de738 ML |
26831 | Set all subsequent functions to have the @code{short_call} attribute. |
26832 | ||
d77de738 | 26833 | @cindex pragma, long_calls_off |
f25efe50 | 26834 | @item long_calls_off |
d77de738 ML |
26835 | Do not affect the @code{long_call} or @code{short_call} attributes of |
26836 | subsequent functions. | |
26837 | @end table | |
26838 | ||
26839 | @node M32C Pragmas | |
26840 | @subsection M32C Pragmas | |
26841 | ||
26842 | @table @code | |
d77de738 | 26843 | @cindex pragma, memregs |
f25efe50 | 26844 | @item GCC memregs @var{number} |
d77de738 ML |
26845 | Overrides the command-line option @code{-memregs=} for the current |
26846 | file. Use with care! This pragma must be before any function in the | |
26847 | file, and mixing different memregs values in different objects may | |
26848 | make them incompatible. This pragma is useful when a | |
26849 | performance-critical function uses a memreg for temporary values, | |
26850 | as it may allow you to reduce the number of memregs used. | |
26851 | ||
d77de738 | 26852 | @cindex pragma, address |
f25efe50 | 26853 | @item ADDRESS @var{name} @var{address} |
d77de738 ML |
26854 | For any declared symbols matching @var{name}, this does three things |
26855 | to that symbol: it forces the symbol to be located at the given | |
26856 | address (a number), it forces the symbol to be volatile, and it | |
26857 | changes the symbol's scope to be static. This pragma exists for | |
26858 | compatibility with other compilers, but note that the common | |
26859 | @code{1234H} numeric syntax is not supported (use @code{0x1234} | |
26860 | instead). Example: | |
26861 | ||
26862 | @smallexample | |
26863 | #pragma ADDRESS port3 0x103 | |
26864 | char port3; | |
26865 | @end smallexample | |
26866 | ||
26867 | @end table | |
26868 | ||
d77de738 ML |
26869 | @node PRU Pragmas |
26870 | @subsection PRU Pragmas | |
26871 | ||
26872 | @table @code | |
26873 | ||
d77de738 | 26874 | @cindex pragma, ctable_entry |
f25efe50 | 26875 | @item ctable_entry @var{index} @var{constant_address} |
d77de738 ML |
26876 | Specifies that the PRU CTABLE entry given by @var{index} has the value |
26877 | @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions | |
26878 | when the load/store address is known and can be addressed with some CTABLE | |
26879 | entry. For example: | |
26880 | ||
26881 | @smallexample | |
26882 | /* will compile to "sbco Rx, 2, 0x10, 4" */ | |
26883 | #pragma ctable_entry 2 0x4802a000 | |
26884 | *(unsigned int *)0x4802a010 = val; | |
26885 | @end smallexample | |
26886 | ||
26887 | @end table | |
26888 | ||
26889 | @node RS/6000 and PowerPC Pragmas | |
26890 | @subsection RS/6000 and PowerPC Pragmas | |
26891 | ||
26892 | The RS/6000 and PowerPC targets define one pragma for controlling | |
26893 | whether or not the @code{longcall} attribute is added to function | |
26894 | declarations by default. This pragma overrides the @option{-mlongcall} | |
26895 | option, but not the @code{longcall} and @code{shortcall} attributes. | |
26896 | @xref{RS/6000 and PowerPC Options}, for more information about when long | |
26897 | calls are and are not necessary. | |
26898 | ||
26899 | @table @code | |
d77de738 | 26900 | @cindex pragma, longcall |
f25efe50 | 26901 | @item longcall (1) |
d77de738 ML |
26902 | Apply the @code{longcall} attribute to all subsequent function |
26903 | declarations. | |
26904 | ||
26905 | @item longcall (0) | |
26906 | Do not apply the @code{longcall} attribute to subsequent function | |
26907 | declarations. | |
26908 | @end table | |
26909 | ||
26910 | @c Describe h8300 pragmas here. | |
26911 | @c Describe sh pragmas here. | |
26912 | @c Describe v850 pragmas here. | |
26913 | ||
26914 | @node S/390 Pragmas | |
26915 | @subsection S/390 Pragmas | |
26916 | ||
26917 | The pragmas defined by the S/390 target correspond to the S/390 | |
26918 | target function attributes and some the additional options: | |
26919 | ||
26920 | @table @samp | |
26921 | @item zvector | |
26922 | @itemx no-zvector | |
26923 | @end table | |
26924 | ||
26925 | Note that options of the pragma, unlike options of the target | |
26926 | attribute, do change the value of preprocessor macros like | |
26927 | @code{__VEC__}. They can be specified as below: | |
26928 | ||
26929 | @smallexample | |
26930 | #pragma GCC target("string[,string]...") | |
26931 | #pragma GCC target("string"[,"string"]...) | |
26932 | @end smallexample | |
26933 | ||
26934 | @node Darwin Pragmas | |
26935 | @subsection Darwin Pragmas | |
26936 | ||
26937 | The following pragmas are available for all architectures running the | |
26938 | Darwin operating system. These are useful for compatibility with other | |
a335cf24 | 26939 | macOS compilers. |
d77de738 ML |
26940 | |
26941 | @table @code | |
d77de738 | 26942 | @cindex pragma, mark |
f25efe50 | 26943 | @item mark @var{tokens}@dots{} |
d77de738 ML |
26944 | This pragma is accepted, but has no effect. |
26945 | ||
d77de738 | 26946 | @cindex pragma, options align |
f25efe50 | 26947 | @item options align=@var{alignment} |
d77de738 ML |
26948 | This pragma sets the alignment of fields in structures. The values of |
26949 | @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or | |
26950 | @code{power}, to emulate PowerPC alignment. Uses of this pragma nest | |
26951 | properly; to restore the previous setting, use @code{reset} for the | |
26952 | @var{alignment}. | |
26953 | ||
d77de738 | 26954 | @cindex pragma, segment |
f25efe50 | 26955 | @item segment @var{tokens}@dots{} |
d77de738 ML |
26956 | This pragma is accepted, but has no effect. |
26957 | ||
d77de738 | 26958 | @cindex pragma, unused |
f25efe50 | 26959 | @item unused (@var{var} [, @var{var}]@dots{}) |
d77de738 ML |
26960 | This pragma declares variables to be possibly unused. GCC does not |
26961 | produce warnings for the listed variables. The effect is similar to | |
26962 | that of the @code{unused} attribute, except that this pragma may appear | |
26963 | anywhere within the variables' scopes. | |
26964 | @end table | |
26965 | ||
26966 | @node Solaris Pragmas | |
26967 | @subsection Solaris Pragmas | |
26968 | ||
26969 | The Solaris target supports @code{#pragma redefine_extname} | |
26970 | (@pxref{Symbol-Renaming Pragmas}). It also supports additional | |
26971 | @code{#pragma} directives for compatibility with the system compiler. | |
26972 | ||
26973 | @table @code | |
d77de738 | 26974 | @cindex pragma, align |
f25efe50 | 26975 | @item align @var{alignment} (@var{variable} [, @var{variable}]...) |
d77de738 ML |
26976 | |
26977 | Increase the minimum alignment of each @var{variable} to @var{alignment}. | |
26978 | This is the same as GCC's @code{aligned} attribute @pxref{Variable | |
26979 | Attributes}). Macro expansion occurs on the arguments to this pragma | |
26980 | when compiling C and Objective-C@. It does not currently occur when | |
26981 | compiling C++, but this is a bug which may be fixed in a future | |
26982 | release. | |
26983 | ||
d77de738 | 26984 | @cindex pragma, fini |
f25efe50 | 26985 | @item fini (@var{function} [, @var{function}]...) |
d77de738 ML |
26986 | |
26987 | This pragma causes each listed @var{function} to be called after | |
26988 | main, or during shared module unloading, by adding a call to the | |
26989 | @code{.fini} section. | |
26990 | ||
d77de738 | 26991 | @cindex pragma, init |
f25efe50 | 26992 | @item init (@var{function} [, @var{function}]...) |
d77de738 ML |
26993 | |
26994 | This pragma causes each listed @var{function} to be called during | |
26995 | initialization (before @code{main}) or during shared module loading, by | |
26996 | adding a call to the @code{.init} section. | |
26997 | ||
26998 | @end table | |
26999 | ||
27000 | @node Symbol-Renaming Pragmas | |
27001 | @subsection Symbol-Renaming Pragmas | |
27002 | ||
27003 | GCC supports a @code{#pragma} directive that changes the name used in | |
27004 | assembly for a given declaration. While this pragma is supported on all | |
27005 | platforms, it is intended primarily to provide compatibility with the | |
27006 | Solaris system headers. This effect can also be achieved using the asm | |
27007 | labels extension (@pxref{Asm Labels}). | |
27008 | ||
27009 | @table @code | |
d77de738 | 27010 | @cindex pragma, redefine_extname |
f25efe50 | 27011 | @item redefine_extname @var{oldname} @var{newname} |
d77de738 ML |
27012 | |
27013 | This pragma gives the C function @var{oldname} the assembly symbol | |
27014 | @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} | |
27015 | is defined if this pragma is available (currently on all platforms). | |
27016 | @end table | |
27017 | ||
27018 | This pragma and the @code{asm} labels extension interact in a complicated | |
27019 | manner. Here are some corner cases you may want to be aware of: | |
27020 | ||
27021 | @enumerate | |
27022 | @item This pragma silently applies only to declarations with external | |
27023 | linkage. The @code{asm} label feature does not have this restriction. | |
27024 | ||
27025 | @item In C++, this pragma silently applies only to declarations with | |
27026 | ``C'' linkage. Again, @code{asm} labels do not have this restriction. | |
27027 | ||
27028 | @item If either of the ways of changing the assembly name of a | |
27029 | declaration are applied to a declaration whose assembly name has | |
27030 | already been determined (either by a previous use of one of these | |
27031 | features, or because the compiler needed the assembly name in order to | |
27032 | generate code), and the new name is different, a warning issues and | |
27033 | the name does not change. | |
27034 | ||
27035 | @item The @var{oldname} used by @code{#pragma redefine_extname} is | |
27036 | always the C-language name. | |
27037 | @end enumerate | |
27038 | ||
27039 | @node Structure-Layout Pragmas | |
27040 | @subsection Structure-Layout Pragmas | |
27041 | ||
27042 | For compatibility with Microsoft Windows compilers, GCC supports a | |
27043 | set of @code{#pragma} directives that change the maximum alignment of | |
27044 | members of structures (other than zero-width bit-fields), unions, and | |
27045 | classes subsequently defined. The @var{n} value below always is required | |
27046 | to be a small power of two and specifies the new alignment in bytes. | |
27047 | ||
27048 | @enumerate | |
27049 | @item @code{#pragma pack(@var{n})} simply sets the new alignment. | |
27050 | @item @code{#pragma pack()} sets the alignment to the one that was in | |
27051 | effect when compilation started (see also command-line option | |
27052 | @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). | |
27053 | @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment | |
27054 | setting on an internal stack and then optionally sets the new alignment. | |
27055 | @item @code{#pragma pack(pop)} restores the alignment setting to the one | |
27056 | saved at the top of the internal stack (and removes that stack entry). | |
27057 | Note that @code{#pragma pack([@var{n}])} does not influence this internal | |
27058 | stack; thus it is possible to have @code{#pragma pack(push)} followed by | |
27059 | multiple @code{#pragma pack(@var{n})} instances and finalized by a single | |
27060 | @code{#pragma pack(pop)}. | |
27061 | @end enumerate | |
27062 | ||
27063 | Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} | |
27064 | directive which lays out structures and unions subsequently defined as the | |
27065 | documented @code{__attribute__ ((ms_struct))}. | |
27066 | ||
27067 | @enumerate | |
27068 | @item @code{#pragma ms_struct on} turns on the Microsoft layout. | |
27069 | @item @code{#pragma ms_struct off} turns off the Microsoft layout. | |
27070 | @item @code{#pragma ms_struct reset} goes back to the default layout. | |
27071 | @end enumerate | |
27072 | ||
27073 | Most targets also support the @code{#pragma scalar_storage_order} directive | |
27074 | which lays out structures and unions subsequently defined as the documented | |
27075 | @code{__attribute__ ((scalar_storage_order))}. | |
27076 | ||
27077 | @enumerate | |
27078 | @item @code{#pragma scalar_storage_order big-endian} sets the storage order | |
27079 | of the scalar fields to big-endian. | |
27080 | @item @code{#pragma scalar_storage_order little-endian} sets the storage order | |
27081 | of the scalar fields to little-endian. | |
27082 | @item @code{#pragma scalar_storage_order default} goes back to the endianness | |
27083 | that was in effect when compilation started (see also command-line option | |
27084 | @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). | |
27085 | @end enumerate | |
27086 | ||
27087 | @node Weak Pragmas | |
27088 | @subsection Weak Pragmas | |
27089 | ||
27090 | For compatibility with SVR4, GCC supports a set of @code{#pragma} | |
27091 | directives for declaring symbols to be weak, and defining weak | |
27092 | aliases. | |
27093 | ||
27094 | @table @code | |
d77de738 | 27095 | @cindex pragma, weak |
f33d7a88 | 27096 | @item #pragma weak @var{symbol} |
d77de738 ML |
27097 | This pragma declares @var{symbol} to be weak, as if the declaration |
27098 | had the attribute of the same name. The pragma may appear before | |
27099 | or after the declaration of @var{symbol}. It is not an error for | |
27100 | @var{symbol} to never be defined at all. | |
27101 | ||
27102 | @item #pragma weak @var{symbol1} = @var{symbol2} | |
27103 | This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. | |
27104 | It is an error if @var{symbol2} is not defined in the current | |
27105 | translation unit. | |
27106 | @end table | |
27107 | ||
27108 | @node Diagnostic Pragmas | |
27109 | @subsection Diagnostic Pragmas | |
27110 | ||
27111 | GCC allows the user to selectively enable or disable certain types of | |
27112 | diagnostics, and change the kind of the diagnostic. For example, a | |
27113 | project's policy might require that all sources compile with | |
27114 | @option{-Werror} but certain files might have exceptions allowing | |
27115 | specific types of warnings. Or, a project might selectively enable | |
27116 | diagnostics and treat them as errors depending on which preprocessor | |
27117 | macros are defined. | |
27118 | ||
27119 | @table @code | |
d77de738 | 27120 | @cindex pragma, diagnostic |
f25efe50 | 27121 | @item #pragma GCC diagnostic @var{kind} @var{option} |
d77de738 ML |
27122 | |
27123 | Modifies the disposition of a diagnostic. Note that not all | |
27124 | diagnostics are modifiable; at the moment only warnings (normally | |
27125 | controlled by @samp{-W@dots{}}) can be controlled, and not all of them. | |
27126 | Use @option{-fdiagnostics-show-option} to determine which diagnostics | |
27127 | are controllable and which option controls them. | |
27128 | ||
27129 | @var{kind} is @samp{error} to treat this diagnostic as an error, | |
27130 | @samp{warning} to treat it like a warning (even if @option{-Werror} is | |
27131 | in effect), or @samp{ignored} if the diagnostic is to be ignored. | |
27132 | @var{option} is a double quoted string that matches the command-line | |
27133 | option. | |
27134 | ||
27135 | @smallexample | |
27136 | #pragma GCC diagnostic warning "-Wformat" | |
27137 | #pragma GCC diagnostic error "-Wformat" | |
27138 | #pragma GCC diagnostic ignored "-Wformat" | |
27139 | @end smallexample | |
27140 | ||
27141 | Note that these pragmas override any command-line options. GCC keeps | |
27142 | track of the location of each pragma, and issues diagnostics according | |
27143 | to the state as of that point in the source file. Thus, pragmas occurring | |
27144 | after a line do not affect diagnostics caused by that line. | |
27145 | ||
27146 | @item #pragma GCC diagnostic push | |
27147 | @itemx #pragma GCC diagnostic pop | |
27148 | ||
27149 | Causes GCC to remember the state of the diagnostics as of each | |
27150 | @code{push}, and restore to that point at each @code{pop}. If a | |
27151 | @code{pop} has no matching @code{push}, the command-line options are | |
27152 | restored. | |
27153 | ||
27154 | @smallexample | |
27155 | #pragma GCC diagnostic error "-Wuninitialized" | |
27156 | foo(a); /* error is given for this one */ | |
27157 | #pragma GCC diagnostic push | |
27158 | #pragma GCC diagnostic ignored "-Wuninitialized" | |
27159 | foo(b); /* no diagnostic for this one */ | |
27160 | #pragma GCC diagnostic pop | |
27161 | foo(c); /* error is given for this one */ | |
27162 | #pragma GCC diagnostic pop | |
27163 | foo(d); /* depends on command-line options */ | |
27164 | @end smallexample | |
27165 | ||
27166 | @item #pragma GCC diagnostic ignored_attributes | |
27167 | ||
27168 | Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress | |
094a609c | 27169 | warnings about unknown scoped attributes (in C++11 and C23). For example, |
d77de738 ML |
27170 | @code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables |
27171 | warning about the following declaration: | |
27172 | ||
27173 | @smallexample | |
27174 | [[vendor::attr]] void f(); | |
27175 | @end smallexample | |
27176 | ||
27177 | whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents | |
27178 | warning about both of these declarations: | |
27179 | ||
27180 | @smallexample | |
27181 | [[vendor::safe]] void f(); | |
27182 | [[vendor::unsafe]] void f2(); | |
27183 | @end smallexample | |
27184 | ||
27185 | @end table | |
27186 | ||
27187 | GCC also offers a simple mechanism for printing messages during | |
27188 | compilation. | |
27189 | ||
27190 | @table @code | |
d77de738 | 27191 | @cindex pragma, diagnostic |
f25efe50 | 27192 | @item #pragma message @var{string} |
d77de738 ML |
27193 | |
27194 | Prints @var{string} as a compiler message on compilation. The message | |
27195 | is informational only, and is neither a compilation warning nor an | |
27196 | error. Newlines can be included in the string by using the @samp{\n} | |
27197 | escape sequence. | |
27198 | ||
27199 | @smallexample | |
27200 | #pragma message "Compiling " __FILE__ "..." | |
27201 | @end smallexample | |
27202 | ||
27203 | @var{string} may be parenthesized, and is printed with location | |
27204 | information. For example, | |
27205 | ||
27206 | @smallexample | |
27207 | #define DO_PRAGMA(x) _Pragma (#x) | |
27208 | #define TODO(x) DO_PRAGMA(message ("TODO - " #x)) | |
27209 | ||
27210 | TODO(Remember to fix this) | |
27211 | @end smallexample | |
27212 | ||
27213 | @noindent | |
27214 | prints @samp{/tmp/file.c:4: note: #pragma message: | |
27215 | TODO - Remember to fix this}. | |
27216 | ||
d77de738 | 27217 | @cindex pragma, diagnostic |
f25efe50 | 27218 | @item #pragma GCC error @var{message} |
d77de738 ML |
27219 | Generates an error message. This pragma @emph{is} considered to |
27220 | indicate an error in the compilation, and it will be treated as such. | |
27221 | ||
27222 | Newlines can be included in the string by using the @samp{\n} | |
27223 | escape sequence. They will be displayed as newlines even if the | |
27224 | @option{-fmessage-length} option is set to zero. | |
27225 | ||
27226 | The error is only generated if the pragma is present in the code after | |
27227 | pre-processing has been completed. It does not matter however if the | |
27228 | code containing the pragma is unreachable: | |
27229 | ||
27230 | @smallexample | |
27231 | #if 0 | |
27232 | #pragma GCC error "this error is not seen" | |
27233 | #endif | |
27234 | void foo (void) | |
27235 | @{ | |
27236 | return; | |
27237 | #pragma GCC error "this error is seen" | |
27238 | @} | |
27239 | @end smallexample | |
27240 | ||
d77de738 | 27241 | @cindex pragma, diagnostic |
f25efe50 | 27242 | @item #pragma GCC warning @var{message} |
d77de738 ML |
27243 | This is just like @samp{pragma GCC error} except that a warning |
27244 | message is issued instead of an error message. Unless | |
27245 | @option{-Werror} is in effect, in which case this pragma will generate | |
27246 | an error as well. | |
27247 | ||
27248 | @end table | |
27249 | ||
27250 | @node Visibility Pragmas | |
27251 | @subsection Visibility Pragmas | |
27252 | ||
27253 | @table @code | |
f25efe50 | 27254 | @cindex pragma, visibility |
d77de738 ML |
27255 | @item #pragma GCC visibility push(@var{visibility}) |
27256 | @itemx #pragma GCC visibility pop | |
d77de738 ML |
27257 | |
27258 | This pragma allows the user to set the visibility for multiple | |
27259 | declarations without having to give each a visibility attribute | |
27260 | (@pxref{Function Attributes}). | |
27261 | ||
27262 | In C++, @samp{#pragma GCC visibility} affects only namespace-scope | |
27263 | declarations. Class members and template specializations are not | |
27264 | affected; if you want to override the visibility for a particular | |
27265 | member or instantiation, you must use an attribute. | |
27266 | ||
27267 | @end table | |
27268 | ||
27269 | ||
27270 | @node Push/Pop Macro Pragmas | |
27271 | @subsection Push/Pop Macro Pragmas | |
27272 | ||
27273 | For compatibility with Microsoft Windows compilers, GCC supports | |
27274 | @samp{#pragma push_macro(@var{"macro_name"})} | |
27275 | and @samp{#pragma pop_macro(@var{"macro_name"})}. | |
27276 | ||
27277 | @table @code | |
d77de738 | 27278 | @cindex pragma, push_macro |
f25efe50 | 27279 | @item #pragma push_macro(@var{"macro_name"}) |
d77de738 ML |
27280 | This pragma saves the value of the macro named as @var{macro_name} to |
27281 | the top of the stack for this macro. | |
27282 | ||
d77de738 | 27283 | @cindex pragma, pop_macro |
f25efe50 | 27284 | @item #pragma pop_macro(@var{"macro_name"}) |
d77de738 ML |
27285 | This pragma sets the value of the macro named as @var{macro_name} to |
27286 | the value on top of the stack for this macro. If the stack for | |
27287 | @var{macro_name} is empty, the value of the macro remains unchanged. | |
27288 | @end table | |
27289 | ||
27290 | For example: | |
27291 | ||
27292 | @smallexample | |
27293 | #define X 1 | |
27294 | #pragma push_macro("X") | |
27295 | #undef X | |
27296 | #define X -1 | |
27297 | #pragma pop_macro("X") | |
27298 | int x [X]; | |
27299 | @end smallexample | |
27300 | ||
27301 | @noindent | |
27302 | In this example, the definition of X as 1 is saved by @code{#pragma | |
27303 | push_macro} and restored by @code{#pragma pop_macro}. | |
27304 | ||
27305 | @node Function Specific Option Pragmas | |
27306 | @subsection Function Specific Option Pragmas | |
27307 | ||
27308 | @table @code | |
d77de738 | 27309 | @cindex pragma GCC target |
f25efe50 | 27310 | @item #pragma GCC target (@var{string}, @dots{}) |
d77de738 ML |
27311 | |
27312 | This pragma allows you to set target-specific options for functions | |
27313 | defined later in the source file. One or more strings can be | |
27314 | specified. Each function that is defined after this point is treated | |
27315 | as if it had been declared with one @code{target(}@var{string}@code{)} | |
27316 | attribute for each @var{string} argument. The parentheses around | |
27317 | the strings in the pragma are optional. @xref{Function Attributes}, | |
27318 | for more information about the @code{target} attribute and the attribute | |
27319 | syntax. | |
27320 | ||
27321 | The @code{#pragma GCC target} pragma is presently implemented for | |
27322 | x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. | |
27323 | ||
d77de738 | 27324 | @cindex pragma GCC optimize |
f25efe50 | 27325 | @item #pragma GCC optimize (@var{string}, @dots{}) |
d77de738 ML |
27326 | |
27327 | This pragma allows you to set global optimization options for functions | |
27328 | defined later in the source file. One or more strings can be | |
27329 | specified. Each function that is defined after this point is treated | |
27330 | as if it had been declared with one @code{optimize(}@var{string}@code{)} | |
27331 | attribute for each @var{string} argument. The parentheses around | |
27332 | the strings in the pragma are optional. @xref{Function Attributes}, | |
27333 | for more information about the @code{optimize} attribute and the attribute | |
27334 | syntax. | |
27335 | ||
d77de738 ML |
27336 | @cindex pragma GCC push_options |
27337 | @cindex pragma GCC pop_options | |
f25efe50 AA |
27338 | @item #pragma GCC push_options |
27339 | @itemx #pragma GCC pop_options | |
d77de738 ML |
27340 | |
27341 | These pragmas maintain a stack of the current target and optimization | |
27342 | options. It is intended for include files where you temporarily want | |
27343 | to switch to using a different @samp{#pragma GCC target} or | |
27344 | @samp{#pragma GCC optimize} and then to pop back to the previous | |
27345 | options. | |
27346 | ||
d77de738 | 27347 | @cindex pragma GCC reset_options |
f25efe50 | 27348 | @item #pragma GCC reset_options |
d77de738 ML |
27349 | |
27350 | This pragma clears the current @code{#pragma GCC target} and | |
27351 | @code{#pragma GCC optimize} to use the default switches as specified | |
27352 | on the command line. | |
27353 | ||
27354 | @end table | |
27355 | ||
27356 | @node Loop-Specific Pragmas | |
27357 | @subsection Loop-Specific Pragmas | |
27358 | ||
27359 | @table @code | |
d77de738 | 27360 | @cindex pragma GCC ivdep |
f25efe50 | 27361 | @item #pragma GCC ivdep |
d77de738 ML |
27362 | |
27363 | With this pragma, the programmer asserts that there are no loop-carried | |
27364 | dependencies which would prevent consecutive iterations of | |
27365 | the following loop from executing concurrently with SIMD | |
27366 | (single instruction multiple data) instructions. | |
27367 | ||
27368 | For example, the compiler can only unconditionally vectorize the following | |
27369 | loop with the pragma: | |
27370 | ||
27371 | @smallexample | |
27372 | void foo (int n, int *a, int *b, int *c) | |
27373 | @{ | |
27374 | int i, j; | |
27375 | #pragma GCC ivdep | |
27376 | for (i = 0; i < n; ++i) | |
27377 | a[i] = b[i] + c[i]; | |
27378 | @} | |
27379 | @end smallexample | |
27380 | ||
27381 | @noindent | |
27382 | In this example, using the @code{restrict} qualifier had the same | |
27383 | effect. In the following example, that would not be possible. Assume | |
27384 | @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows | |
27385 | that it can unconditionally vectorize the following loop: | |
27386 | ||
27387 | @smallexample | |
27388 | void ignore_vec_dep (int *a, int k, int c, int m) | |
27389 | @{ | |
27390 | #pragma GCC ivdep | |
27391 | for (int i = 0; i < m; i++) | |
27392 | a[i] = a[i + k] * c; | |
27393 | @} | |
27394 | @end smallexample | |
27395 | ||
73b98860 TC |
27396 | @cindex pragma GCC novector |
27397 | @item #pragma GCC novector | |
27398 | ||
27399 | With this pragma, the programmer asserts that the following loop should be | |
27400 | prevented from executing concurrently with SIMD (single instruction multiple | |
27401 | data) instructions. | |
27402 | ||
27403 | For example, the compiler cannot vectorize the following loop with the pragma: | |
27404 | ||
27405 | @smallexample | |
27406 | void foo (int n, int *a, int *b, int *c) | |
27407 | @{ | |
27408 | int i, j; | |
27409 | #pragma GCC novector | |
27410 | for (i = 0; i < n; ++i) | |
27411 | a[i] = b[i] + c[i]; | |
27412 | @} | |
27413 | @end smallexample | |
27414 | ||
d77de738 | 27415 | @cindex pragma GCC unroll @var{n} |
f25efe50 | 27416 | @item #pragma GCC unroll @var{n} |
d77de738 ML |
27417 | |
27418 | You can use this pragma to control how many times a loop should be unrolled. | |
27419 | It must be placed immediately before a @code{for}, @code{while} or @code{do} | |
27420 | loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. | |
27421 | @var{n} is an integer constant expression specifying the unrolling factor. | |
27422 | The values of @math{0} and @math{1} block any unrolling of the loop. | |
27423 | ||
27424 | @end table | |
27425 | ||
27426 | @node Unnamed Fields | |
27427 | @section Unnamed Structure and Union Fields | |
27428 | @cindex @code{struct} | |
27429 | @cindex @code{union} | |
27430 | ||
27431 | As permitted by ISO C11 and for compatibility with other compilers, | |
27432 | GCC allows you to define | |
27433 | a structure or union that contains, as fields, structures and unions | |
27434 | without names. For example: | |
27435 | ||
27436 | @smallexample | |
27437 | struct @{ | |
27438 | int a; | |
27439 | union @{ | |
27440 | int b; | |
27441 | float c; | |
27442 | @}; | |
27443 | int d; | |
27444 | @} foo; | |
27445 | @end smallexample | |
27446 | ||
27447 | @noindent | |
27448 | In this example, you are able to access members of the unnamed | |
27449 | union with code like @samp{foo.b}. Note that only unnamed structs and | |
27450 | unions are allowed, you may not have, for example, an unnamed | |
27451 | @code{int}. | |
27452 | ||
27453 | You must never create such structures that cause ambiguous field definitions. | |
27454 | For example, in this structure: | |
27455 | ||
27456 | @smallexample | |
27457 | struct @{ | |
27458 | int a; | |
27459 | struct @{ | |
27460 | int a; | |
27461 | @}; | |
27462 | @} foo; | |
27463 | @end smallexample | |
27464 | ||
27465 | @noindent | |
27466 | it is ambiguous which @code{a} is being referred to with @samp{foo.a}. | |
27467 | The compiler gives errors for such constructs. | |
27468 | ||
27469 | @opindex fms-extensions | |
27470 | Unless @option{-fms-extensions} is used, the unnamed field must be a | |
27471 | structure or union definition without a tag (for example, @samp{struct | |
27472 | @{ int a; @};}). If @option{-fms-extensions} is used, the field may | |
27473 | also be a definition with a tag such as @samp{struct foo @{ int a; | |
27474 | @};}, a reference to a previously defined structure or union such as | |
27475 | @samp{struct foo;}, or a reference to a @code{typedef} name for a | |
27476 | previously defined structure or union type. | |
27477 | ||
27478 | @opindex fplan9-extensions | |
27479 | The option @option{-fplan9-extensions} enables | |
27480 | @option{-fms-extensions} as well as two other extensions. First, a | |
27481 | pointer to a structure is automatically converted to a pointer to an | |
27482 | anonymous field for assignments and function calls. For example: | |
27483 | ||
27484 | @smallexample | |
27485 | struct s1 @{ int a; @}; | |
27486 | struct s2 @{ struct s1; @}; | |
27487 | extern void f1 (struct s1 *); | |
27488 | void f2 (struct s2 *p) @{ f1 (p); @} | |
27489 | @end smallexample | |
27490 | ||
27491 | @noindent | |
27492 | In the call to @code{f1} inside @code{f2}, the pointer @code{p} is | |
27493 | converted into a pointer to the anonymous field. | |
27494 | ||
27495 | Second, when the type of an anonymous field is a @code{typedef} for a | |
27496 | @code{struct} or @code{union}, code may refer to the field using the | |
27497 | name of the @code{typedef}. | |
27498 | ||
27499 | @smallexample | |
27500 | typedef struct @{ int a; @} s1; | |
27501 | struct s2 @{ s1; @}; | |
27502 | s1 f1 (struct s2 *p) @{ return p->s1; @} | |
27503 | @end smallexample | |
27504 | ||
27505 | These usages are only permitted when they are not ambiguous. | |
27506 | ||
27507 | @node Thread-Local | |
27508 | @section Thread-Local Storage | |
27509 | @cindex Thread-Local Storage | |
27510 | @cindex @acronym{TLS} | |
27511 | @cindex @code{__thread} | |
27512 | ||
27513 | Thread-local storage (@acronym{TLS}) is a mechanism by which variables | |
27514 | are allocated such that there is one instance of the variable per extant | |
27515 | thread. The runtime model GCC uses to implement this originates | |
27516 | in the IA-64 processor-specific ABI, but has since been migrated | |
27517 | to other processors as well. It requires significant support from | |
27518 | the linker (@command{ld}), dynamic linker (@command{ld.so}), and | |
27519 | system libraries (@file{libc.so} and @file{libpthread.so}), so it | |
27520 | is not available everywhere. | |
27521 | ||
27522 | At the user level, the extension is visible with a new storage | |
27523 | class keyword: @code{__thread}. For example: | |
27524 | ||
27525 | @smallexample | |
27526 | __thread int i; | |
27527 | extern __thread struct state s; | |
27528 | static __thread char *p; | |
27529 | @end smallexample | |
27530 | ||
27531 | The @code{__thread} specifier may be used alone, with the @code{extern} | |
27532 | or @code{static} specifiers, but with no other storage class specifier. | |
27533 | When used with @code{extern} or @code{static}, @code{__thread} must appear | |
27534 | immediately after the other storage class specifier. | |
27535 | ||
27536 | The @code{__thread} specifier may be applied to any global, file-scoped | |
27537 | static, function-scoped static, or static data member of a class. It may | |
27538 | not be applied to block-scoped automatic or non-static data member. | |
27539 | ||
27540 | When the address-of operator is applied to a thread-local variable, it is | |
27541 | evaluated at run time and returns the address of the current thread's | |
27542 | instance of that variable. An address so obtained may be used by any | |
27543 | thread. When a thread terminates, any pointers to thread-local variables | |
27544 | in that thread become invalid. | |
27545 | ||
27546 | No static initialization may refer to the address of a thread-local variable. | |
27547 | ||
27548 | In C++, if an initializer is present for a thread-local variable, it must | |
27549 | be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ | |
27550 | standard. | |
27551 | ||
27552 | See @uref{https://www.akkadia.org/drepper/tls.pdf, | |
27553 | ELF Handling For Thread-Local Storage} for a detailed explanation of | |
27554 | the four thread-local storage addressing models, and how the runtime | |
27555 | is expected to function. | |
27556 | ||
27557 | @menu | |
27558 | * C99 Thread-Local Edits:: | |
27559 | * C++98 Thread-Local Edits:: | |
27560 | @end menu | |
27561 | ||
27562 | @node C99 Thread-Local Edits | |
27563 | @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage | |
27564 | ||
27565 | The following are a set of changes to ISO/IEC 9899:1999 (aka C99) | |
27566 | that document the exact semantics of the language extension. | |
27567 | ||
27568 | @itemize @bullet | |
27569 | @item | |
27570 | @cite{5.1.2 Execution environments} | |
27571 | ||
27572 | Add new text after paragraph 1 | |
27573 | ||
27574 | @quotation | |
27575 | Within either execution environment, a @dfn{thread} is a flow of | |
27576 | control within a program. It is implementation defined whether | |
27577 | or not there may be more than one thread associated with a program. | |
27578 | It is implementation defined how threads beyond the first are | |
27579 | created, the name and type of the function called at thread | |
27580 | startup, and how threads may be terminated. However, objects | |
27581 | with thread storage duration shall be initialized before thread | |
27582 | startup. | |
27583 | @end quotation | |
27584 | ||
27585 | @item | |
27586 | @cite{6.2.4 Storage durations of objects} | |
27587 | ||
27588 | Add new text before paragraph 3 | |
27589 | ||
27590 | @quotation | |
27591 | An object whose identifier is declared with the storage-class | |
27592 | specifier @w{@code{__thread}} has @dfn{thread storage duration}. | |
27593 | Its lifetime is the entire execution of the thread, and its | |
27594 | stored value is initialized only once, prior to thread startup. | |
27595 | @end quotation | |
27596 | ||
27597 | @item | |
27598 | @cite{6.4.1 Keywords} | |
27599 | ||
27600 | Add @code{__thread}. | |
27601 | ||
27602 | @item | |
27603 | @cite{6.7.1 Storage-class specifiers} | |
27604 | ||
27605 | Add @code{__thread} to the list of storage class specifiers in | |
27606 | paragraph 1. | |
27607 | ||
27608 | Change paragraph 2 to | |
27609 | ||
27610 | @quotation | |
27611 | With the exception of @code{__thread}, at most one storage-class | |
27612 | specifier may be given [@dots{}]. The @code{__thread} specifier may | |
27613 | be used alone, or immediately following @code{extern} or | |
27614 | @code{static}. | |
27615 | @end quotation | |
27616 | ||
27617 | Add new text after paragraph 6 | |
27618 | ||
27619 | @quotation | |
27620 | The declaration of an identifier for a variable that has | |
27621 | block scope that specifies @code{__thread} shall also | |
27622 | specify either @code{extern} or @code{static}. | |
27623 | ||
27624 | The @code{__thread} specifier shall be used only with | |
27625 | variables. | |
27626 | @end quotation | |
27627 | @end itemize | |
27628 | ||
27629 | @node C++98 Thread-Local Edits | |
27630 | @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage | |
27631 | ||
27632 | The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) | |
27633 | that document the exact semantics of the language extension. | |
27634 | ||
27635 | @itemize @bullet | |
27636 | @item | |
27637 | @b{[intro.execution]} | |
27638 | ||
27639 | New text after paragraph 4 | |
27640 | ||
27641 | @quotation | |
27642 | A @dfn{thread} is a flow of control within the abstract machine. | |
27643 | It is implementation defined whether or not there may be more than | |
27644 | one thread. | |
27645 | @end quotation | |
27646 | ||
27647 | New text after paragraph 7 | |
27648 | ||
27649 | @quotation | |
27650 | It is unspecified whether additional action must be taken to | |
27651 | ensure when and whether side effects are visible to other threads. | |
27652 | @end quotation | |
27653 | ||
27654 | @item | |
27655 | @b{[lex.key]} | |
27656 | ||
27657 | Add @code{__thread}. | |
27658 | ||
27659 | @item | |
27660 | @b{[basic.start.main]} | |
27661 | ||
27662 | Add after paragraph 5 | |
27663 | ||
27664 | @quotation | |
27665 | The thread that begins execution at the @code{main} function is called | |
27666 | the @dfn{main thread}. It is implementation defined how functions | |
27667 | beginning threads other than the main thread are designated or typed. | |
27668 | A function so designated, as well as the @code{main} function, is called | |
27669 | a @dfn{thread startup function}. It is implementation defined what | |
27670 | happens if a thread startup function returns. It is implementation | |
27671 | defined what happens to other threads when any thread calls @code{exit}. | |
27672 | @end quotation | |
27673 | ||
27674 | @item | |
27675 | @b{[basic.start.init]} | |
27676 | ||
27677 | Add after paragraph 4 | |
27678 | ||
27679 | @quotation | |
27680 | The storage for an object of thread storage duration shall be | |
27681 | statically initialized before the first statement of the thread startup | |
27682 | function. An object of thread storage duration shall not require | |
27683 | dynamic initialization. | |
27684 | @end quotation | |
27685 | ||
27686 | @item | |
27687 | @b{[basic.start.term]} | |
27688 | ||
27689 | Add after paragraph 3 | |
27690 | ||
27691 | @quotation | |
27692 | The type of an object with thread storage duration shall not have a | |
27693 | non-trivial destructor, nor shall it be an array type whose elements | |
27694 | (directly or indirectly) have non-trivial destructors. | |
27695 | @end quotation | |
27696 | ||
27697 | @item | |
27698 | @b{[basic.stc]} | |
27699 | ||
27700 | Add ``thread storage duration'' to the list in paragraph 1. | |
27701 | ||
27702 | Change paragraph 2 | |
27703 | ||
27704 | @quotation | |
27705 | Thread, static, and automatic storage durations are associated with | |
27706 | objects introduced by declarations [@dots{}]. | |
27707 | @end quotation | |
27708 | ||
27709 | Add @code{__thread} to the list of specifiers in paragraph 3. | |
27710 | ||
27711 | @item | |
27712 | @b{[basic.stc.thread]} | |
27713 | ||
27714 | New section before @b{[basic.stc.static]} | |
27715 | ||
27716 | @quotation | |
27717 | The keyword @code{__thread} applied to a non-local object gives the | |
27718 | object thread storage duration. | |
27719 | ||
27720 | A local variable or class data member declared both @code{static} | |
27721 | and @code{__thread} gives the variable or member thread storage | |
27722 | duration. | |
27723 | @end quotation | |
27724 | ||
27725 | @item | |
27726 | @b{[basic.stc.static]} | |
27727 | ||
27728 | Change paragraph 1 | |
27729 | ||
27730 | @quotation | |
27731 | All objects that have neither thread storage duration, dynamic | |
27732 | storage duration nor are local [@dots{}]. | |
27733 | @end quotation | |
27734 | ||
27735 | @item | |
27736 | @b{[dcl.stc]} | |
27737 | ||
27738 | Add @code{__thread} to the list in paragraph 1. | |
27739 | ||
27740 | Change paragraph 1 | |
27741 | ||
27742 | @quotation | |
27743 | With the exception of @code{__thread}, at most one | |
27744 | @var{storage-class-specifier} shall appear in a given | |
27745 | @var{decl-specifier-seq}. The @code{__thread} specifier may | |
27746 | be used alone, or immediately following the @code{extern} or | |
27747 | @code{static} specifiers. [@dots{}] | |
27748 | @end quotation | |
27749 | ||
27750 | Add after paragraph 5 | |
27751 | ||
27752 | @quotation | |
27753 | The @code{__thread} specifier can be applied only to the names of objects | |
27754 | and to anonymous unions. | |
27755 | @end quotation | |
27756 | ||
27757 | @item | |
27758 | @b{[class.mem]} | |
27759 | ||
27760 | Add after paragraph 6 | |
27761 | ||
27762 | @quotation | |
27763 | Non-@code{static} members shall not be @code{__thread}. | |
27764 | @end quotation | |
27765 | @end itemize | |
27766 | ||
27767 | @node Binary constants | |
27768 | @section Binary Constants using the @samp{0b} Prefix | |
27769 | @cindex Binary constants using the @samp{0b} prefix | |
27770 | ||
27771 | Integer constants can be written as binary constants, consisting of a | |
27772 | sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or | |
27773 | @samp{0B}. This is particularly useful in environments that operate a | |
27774 | lot on the bit level (like microcontrollers). | |
27775 | ||
27776 | The following statements are identical: | |
27777 | ||
27778 | @smallexample | |
27779 | i = 42; | |
27780 | i = 0x2a; | |
27781 | i = 052; | |
27782 | i = 0b101010; | |
27783 | @end smallexample | |
27784 | ||
27785 | The type of these constants follows the same rules as for octal or | |
27786 | hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} | |
27787 | can be applied. | |
27788 | ||
27789 | @node C++ Extensions | |
27790 | @chapter Extensions to the C++ Language | |
27791 | @cindex extensions, C++ language | |
27792 | @cindex C++ language extensions | |
27793 | ||
27794 | The GNU compiler provides these extensions to the C++ language (and you | |
27795 | can also use most of the C language extensions in your C++ programs). If you | |
27796 | want to write code that checks whether these features are available, you can | |
27797 | test for the GNU compiler the same way as for C programs: check for a | |
27798 | predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to | |
27799 | test specifically for GNU C++ (@pxref{Common Predefined Macros,, | |
27800 | Predefined Macros,cpp,The GNU C Preprocessor}). | |
27801 | ||
27802 | @menu | |
27803 | * C++ Volatiles:: What constitutes an access to a volatile object. | |
27804 | * Restricted Pointers:: C99 restricted pointers and references. | |
27805 | * Vague Linkage:: Where G++ puts inlines, vtables and such. | |
27806 | * C++ Interface:: You can use a single C++ header file for both | |
27807 | declarations and definitions. | |
27808 | * Template Instantiation:: Methods for ensuring that exactly one copy of | |
27809 | each needed template instantiation is emitted. | |
27810 | * Bound member functions:: You can extract a function pointer to the | |
27811 | method denoted by a @samp{->*} or @samp{.*} expression. | |
27812 | * C++ Attributes:: Variable, function, and type attributes for C++ only. | |
27813 | * Function Multiversioning:: Declaring multiple function versions. | |
27814 | * Type Traits:: Compiler support for type traits. | |
27815 | * C++ Concepts:: Improved support for generic programming. | |
27816 | * Deprecated Features:: Things will disappear from G++. | |
27817 | * Backwards Compatibility:: Compatibilities with earlier definitions of C++. | |
27818 | @end menu | |
27819 | ||
27820 | @node C++ Volatiles | |
27821 | @section When is a Volatile C++ Object Accessed? | |
27822 | @cindex accessing volatiles | |
27823 | @cindex volatile read | |
27824 | @cindex volatile write | |
27825 | @cindex volatile access | |
27826 | ||
27827 | The C++ standard differs from the C standard in its treatment of | |
27828 | volatile objects. It fails to specify what constitutes a volatile | |
27829 | access, except to say that C++ should behave in a similar manner to C | |
27830 | with respect to volatiles, where possible. However, the different | |
27831 | lvalueness of expressions between C and C++ complicate the behavior. | |
27832 | G++ behaves the same as GCC for volatile access, @xref{C | |
27833 | Extensions,,Volatiles}, for a description of GCC's behavior. | |
27834 | ||
27835 | The C and C++ language specifications differ when an object is | |
27836 | accessed in a void context: | |
27837 | ||
27838 | @smallexample | |
27839 | volatile int *src = @var{somevalue}; | |
27840 | *src; | |
27841 | @end smallexample | |
27842 | ||
27843 | The C++ standard specifies that such expressions do not undergo lvalue | |
27844 | to rvalue conversion, and that the type of the dereferenced object may | |
27845 | be incomplete. The C++ standard does not specify explicitly that it | |
27846 | is lvalue to rvalue conversion that is responsible for causing an | |
27847 | access. There is reason to believe that it is, because otherwise | |
27848 | certain simple expressions become undefined. However, because it | |
27849 | would surprise most programmers, G++ treats dereferencing a pointer to | |
27850 | volatile object of complete type as GCC would do for an equivalent | |
27851 | type in C@. When the object has incomplete type, G++ issues a | |
27852 | warning; if you wish to force an error, you must force a conversion to | |
27853 | rvalue with, for instance, a static cast. | |
27854 | ||
27855 | When using a reference to volatile, G++ does not treat equivalent | |
27856 | expressions as accesses to volatiles, but instead issues a warning that | |
27857 | no volatile is accessed. The rationale for this is that otherwise it | |
27858 | becomes difficult to determine where volatile access occur, and not | |
27859 | possible to ignore the return value from functions returning volatile | |
27860 | references. Again, if you wish to force a read, cast the reference to | |
27861 | an rvalue. | |
27862 | ||
27863 | G++ implements the same behavior as GCC does when assigning to a | |
27864 | volatile object---there is no reread of the assigned-to object, the | |
27865 | assigned rvalue is reused. Note that in C++ assignment expressions | |
27866 | are lvalues, and if used as an lvalue, the volatile object is | |
27867 | referred to. For instance, @var{vref} refers to @var{vobj}, as | |
27868 | expected, in the following example: | |
27869 | ||
27870 | @smallexample | |
27871 | volatile int vobj; | |
27872 | volatile int &vref = vobj = @var{something}; | |
27873 | @end smallexample | |
27874 | ||
27875 | @node Restricted Pointers | |
27876 | @section Restricting Pointer Aliasing | |
27877 | @cindex restricted pointers | |
27878 | @cindex restricted references | |
27879 | @cindex restricted this pointer | |
27880 | ||
27881 | As with the C front end, G++ understands the C99 feature of restricted pointers, | |
27882 | specified with the @code{__restrict__}, or @code{__restrict} type | |
27883 | qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} | |
27884 | language flag, @code{restrict} is not a keyword in C++. | |
27885 | ||
27886 | In addition to allowing restricted pointers, you can specify restricted | |
27887 | references, which indicate that the reference is not aliased in the local | |
27888 | context. | |
27889 | ||
27890 | @smallexample | |
27891 | void fn (int *__restrict__ rptr, int &__restrict__ rref) | |
27892 | @{ | |
27893 | /* @r{@dots{}} */ | |
27894 | @} | |
27895 | @end smallexample | |
27896 | ||
27897 | @noindent | |
27898 | In the body of @code{fn}, @var{rptr} points to an unaliased integer and | |
27899 | @var{rref} refers to a (different) unaliased integer. | |
27900 | ||
27901 | You may also specify whether a member function's @var{this} pointer is | |
27902 | unaliased by using @code{__restrict__} as a member function qualifier. | |
27903 | ||
27904 | @smallexample | |
27905 | void T::fn () __restrict__ | |
27906 | @{ | |
27907 | /* @r{@dots{}} */ | |
27908 | @} | |
27909 | @end smallexample | |
27910 | ||
27911 | @noindent | |
27912 | Within the body of @code{T::fn}, @var{this} has the effective | |
27913 | definition @code{T *__restrict__ const this}. Notice that the | |
27914 | interpretation of a @code{__restrict__} member function qualifier is | |
27915 | different to that of @code{const} or @code{volatile} qualifier, in that it | |
27916 | is applied to the pointer rather than the object. This is consistent with | |
27917 | other compilers that implement restricted pointers. | |
27918 | ||
27919 | As with all outermost parameter qualifiers, @code{__restrict__} is | |
27920 | ignored in function definition matching. This means you only need to | |
27921 | specify @code{__restrict__} in a function definition, rather than | |
27922 | in a function prototype as well. | |
27923 | ||
27924 | @node Vague Linkage | |
27925 | @section Vague Linkage | |
27926 | @cindex vague linkage | |
27927 | ||
27928 | There are several constructs in C++ that require space in the object | |
27929 | file but are not clearly tied to a single translation unit. We say that | |
27930 | these constructs have ``vague linkage''. Typically such constructs are | |
27931 | emitted wherever they are needed, though sometimes we can be more | |
27932 | clever. | |
27933 | ||
27934 | @table @asis | |
27935 | @item Inline Functions | |
27936 | Inline functions are typically defined in a header file which can be | |
27937 | included in many different compilations. Hopefully they can usually be | |
27938 | inlined, but sometimes an out-of-line copy is necessary, if the address | |
27939 | of the function is taken or if inlining fails. In general, we emit an | |
27940 | out-of-line copy in all translation units where one is needed. As an | |
27941 | exception, we only emit inline virtual functions with the vtable, since | |
27942 | it always requires a copy. | |
27943 | ||
27944 | Local static variables and string constants used in an inline function | |
27945 | are also considered to have vague linkage, since they must be shared | |
27946 | between all inlined and out-of-line instances of the function. | |
27947 | ||
d77de738 | 27948 | @cindex vtable |
f25efe50 | 27949 | @item VTables |
d77de738 ML |
27950 | C++ virtual functions are implemented in most compilers using a lookup |
27951 | table, known as a vtable. The vtable contains pointers to the virtual | |
27952 | functions provided by a class, and each object of the class contains a | |
27953 | pointer to its vtable (or vtables, in some multiple-inheritance | |
27954 | situations). If the class declares any non-inline, non-pure virtual | |
27955 | functions, the first one is chosen as the ``key method'' for the class, | |
27956 | and the vtable is only emitted in the translation unit where the key | |
27957 | method is defined. | |
27958 | ||
27959 | @emph{Note:} If the chosen key method is later defined as inline, the | |
27960 | vtable is still emitted in every translation unit that defines it. | |
27961 | Make sure that any inline virtuals are declared inline in the class | |
27962 | body, even if they are not defined there. | |
27963 | ||
d77de738 ML |
27964 | @cindex @code{type_info} |
27965 | @cindex RTTI | |
f25efe50 | 27966 | @item @code{type_info} objects |
d77de738 ML |
27967 | C++ requires information about types to be written out in order to |
27968 | implement @samp{dynamic_cast}, @samp{typeid} and exception handling. | |
27969 | For polymorphic classes (classes with virtual functions), the @samp{type_info} | |
27970 | object is written out along with the vtable so that @samp{dynamic_cast} | |
27971 | can determine the dynamic type of a class object at run time. For all | |
27972 | other types, we write out the @samp{type_info} object when it is used: when | |
27973 | applying @samp{typeid} to an expression, throwing an object, or | |
27974 | referring to a type in a catch clause or exception specification. | |
27975 | ||
27976 | @item Template Instantiations | |
27977 | Most everything in this section also applies to template instantiations, | |
27978 | but there are other options as well. | |
27979 | @xref{Template Instantiation,,Where's the Template?}. | |
27980 | ||
27981 | @end table | |
27982 | ||
27983 | When used with GNU ld version 2.8 or later on an ELF system such as | |
27984 | GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of | |
27985 | these constructs will be discarded at link time. This is known as | |
27986 | COMDAT support. | |
27987 | ||
27988 | On targets that don't support COMDAT, but do support weak symbols, GCC | |
27989 | uses them. This way one copy overrides all the others, but | |
27990 | the unused copies still take up space in the executable. | |
27991 | ||
27992 | For targets that do not support either COMDAT or weak symbols, | |
27993 | most entities with vague linkage are emitted as local symbols to | |
27994 | avoid duplicate definition errors from the linker. This does not happen | |
27995 | for local statics in inlines, however, as having multiple copies | |
27996 | almost certainly breaks things. | |
27997 | ||
27998 | @xref{C++ Interface,,Declarations and Definitions in One Header}, for | |
27999 | another way to control placement of these constructs. | |
28000 | ||
28001 | @node C++ Interface | |
28002 | @section C++ Interface and Implementation Pragmas | |
28003 | ||
28004 | @cindex interface and implementation headers, C++ | |
28005 | @cindex C++ interface and implementation headers | |
28006 | @cindex pragmas, interface and implementation | |
28007 | ||
28008 | @code{#pragma interface} and @code{#pragma implementation} provide the | |
28009 | user with a way of explicitly directing the compiler to emit entities | |
28010 | with vague linkage (and debugging information) in a particular | |
28011 | translation unit. | |
28012 | ||
28013 | @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2 | |
28014 | by COMDAT support and the ``key method'' heuristic | |
28015 | mentioned in @ref{Vague Linkage}. Using them can actually cause your | |
28016 | program to grow due to unnecessary out-of-line copies of inline | |
28017 | functions. | |
28018 | ||
28019 | @table @code | |
f25efe50 | 28020 | @kindex #pragma interface |
d77de738 ML |
28021 | @item #pragma interface |
28022 | @itemx #pragma interface "@var{subdir}/@var{objects}.h" | |
d77de738 ML |
28023 | Use this directive in @emph{header files} that define object classes, to save |
28024 | space in most of the object files that use those classes. Normally, | |
28025 | local copies of certain information (backup copies of inline member | |
28026 | functions, debugging information, and the internal tables that implement | |
28027 | virtual functions) must be kept in each object file that includes class | |
28028 | definitions. You can use this pragma to avoid such duplication. When a | |
28029 | header file containing @samp{#pragma interface} is included in a | |
28030 | compilation, this auxiliary information is not generated (unless | |
28031 | the main input source file itself uses @samp{#pragma implementation}). | |
28032 | Instead, the object files contain references to be resolved at link | |
28033 | time. | |
28034 | ||
28035 | The second form of this directive is useful for the case where you have | |
28036 | multiple headers with the same name in different directories. If you | |
28037 | use this form, you must specify the same string to @samp{#pragma | |
28038 | implementation}. | |
28039 | ||
f25efe50 | 28040 | @kindex #pragma implementation |
d77de738 ML |
28041 | @item #pragma implementation |
28042 | @itemx #pragma implementation "@var{objects}.h" | |
d77de738 ML |
28043 | Use this pragma in a @emph{main input file}, when you want full output from |
28044 | included header files to be generated (and made globally visible). The | |
28045 | included header file, in turn, should use @samp{#pragma interface}. | |
28046 | Backup copies of inline member functions, debugging information, and the | |
28047 | internal tables used to implement virtual functions are all generated in | |
28048 | implementation files. | |
28049 | ||
28050 | @cindex implied @code{#pragma implementation} | |
28051 | @cindex @code{#pragma implementation}, implied | |
28052 | @cindex naming convention, implementation headers | |
28053 | If you use @samp{#pragma implementation} with no argument, it applies to | |
28054 | an include file with the same basename@footnote{A file's @dfn{basename} | |
28055 | is the name stripped of all leading path information and of trailing | |
28056 | suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source | |
28057 | file. For example, in @file{allclass.cc}, giving just | |
28058 | @samp{#pragma implementation} | |
28059 | by itself is equivalent to @samp{#pragma implementation "allclass.h"}. | |
28060 | ||
28061 | Use the string argument if you want a single implementation file to | |
28062 | include code from multiple header files. (You must also use | |
28063 | @samp{#include} to include the header file; @samp{#pragma | |
28064 | implementation} only specifies how to use the file---it doesn't actually | |
28065 | include it.) | |
28066 | ||
28067 | There is no way to split up the contents of a single header file into | |
28068 | multiple implementation files. | |
28069 | @end table | |
28070 | ||
28071 | @cindex inlining and C++ pragmas | |
28072 | @cindex C++ pragmas, effect on inlining | |
28073 | @cindex pragmas in C++, effect on inlining | |
28074 | @samp{#pragma implementation} and @samp{#pragma interface} also have an | |
28075 | effect on function inlining. | |
28076 | ||
28077 | If you define a class in a header file marked with @samp{#pragma | |
28078 | interface}, the effect on an inline function defined in that class is | |
28079 | similar to an explicit @code{extern} declaration---the compiler emits | |
28080 | no code at all to define an independent version of the function. Its | |
28081 | definition is used only for inlining with its callers. | |
28082 | ||
28083 | @opindex fno-implement-inlines | |
28084 | Conversely, when you include the same header file in a main source file | |
28085 | that declares it as @samp{#pragma implementation}, the compiler emits | |
28086 | code for the function itself; this defines a version of the function | |
28087 | that can be found via pointers (or by callers compiled without | |
28088 | inlining). If all calls to the function can be inlined, you can avoid | |
28089 | emitting the function by compiling with @option{-fno-implement-inlines}. | |
28090 | If any calls are not inlined, you will get linker errors. | |
28091 | ||
28092 | @node Template Instantiation | |
28093 | @section Where's the Template? | |
28094 | @cindex template instantiation | |
28095 | ||
28096 | C++ templates were the first language feature to require more | |
28097 | intelligence from the environment than was traditionally found on a UNIX | |
28098 | system. Somehow the compiler and linker have to make sure that each | |
28099 | template instance occurs exactly once in the executable if it is needed, | |
28100 | and not at all otherwise. There are two basic approaches to this | |
28101 | problem, which are referred to as the Borland model and the Cfront model. | |
28102 | ||
28103 | @table @asis | |
28104 | @item Borland model | |
28105 | Borland C++ solved the template instantiation problem by adding the code | |
28106 | equivalent of common blocks to their linker; the compiler emits template | |
28107 | instances in each translation unit that uses them, and the linker | |
28108 | collapses them together. The advantage of this model is that the linker | |
28109 | only has to consider the object files themselves; there is no external | |
28110 | complexity to worry about. The disadvantage is that compilation time | |
28111 | is increased because the template code is being compiled repeatedly. | |
28112 | Code written for this model tends to include definitions of all | |
28113 | templates in the header file, since they must be seen to be | |
28114 | instantiated. | |
28115 | ||
28116 | @item Cfront model | |
28117 | The AT&T C++ translator, Cfront, solved the template instantiation | |
28118 | problem by creating the notion of a template repository, an | |
28119 | automatically maintained place where template instances are stored. A | |
28120 | more modern version of the repository works as follows: As individual | |
28121 | object files are built, the compiler places any template definitions and | |
28122 | instantiations encountered in the repository. At link time, the link | |
28123 | wrapper adds in the objects in the repository and compiles any needed | |
28124 | instances that were not previously emitted. The advantages of this | |
28125 | model are more optimal compilation speed and the ability to use the | |
28126 | system linker; to implement the Borland model a compiler vendor also | |
28127 | needs to replace the linker. The disadvantages are vastly increased | |
28128 | complexity, and thus potential for error; for some code this can be | |
28129 | just as transparent, but in practice it can been very difficult to build | |
28130 | multiple programs in one directory and one program in multiple | |
28131 | directories. Code written for this model tends to separate definitions | |
28132 | of non-inline member templates into a separate file, which should be | |
28133 | compiled separately. | |
28134 | @end table | |
28135 | ||
28136 | G++ implements the Borland model on targets where the linker supports it, | |
a335cf24 | 28137 | including ELF targets (such as GNU/Linux), macOS and Microsoft Windows. |
d77de738 ML |
28138 | Otherwise G++ implements neither automatic model. |
28139 | ||
28140 | You have the following options for dealing with template instantiations: | |
28141 | ||
28142 | @enumerate | |
28143 | @item | |
28144 | Do nothing. Code written for the Borland model works fine, but | |
28145 | each translation unit contains instances of each of the templates it | |
28146 | uses. The duplicate instances will be discarded by the linker, but in | |
28147 | a large program, this can lead to an unacceptable amount of code | |
28148 | duplication in object files or shared libraries. | |
28149 | ||
28150 | Duplicate instances of a template can be avoided by defining an explicit | |
28151 | instantiation in one object file, and preventing the compiler from doing | |
28152 | implicit instantiations in any other object files by using an explicit | |
28153 | instantiation declaration, using the @code{extern template} syntax: | |
28154 | ||
28155 | @smallexample | |
28156 | extern template int max (int, int); | |
28157 | @end smallexample | |
28158 | ||
28159 | This syntax is defined in the C++ 2011 standard, but has been supported by | |
28160 | G++ and other compilers since well before 2011. | |
28161 | ||
28162 | Explicit instantiations can be used for the largest or most frequently | |
28163 | duplicated instances, without having to know exactly which other instances | |
28164 | are used in the rest of the program. You can scatter the explicit | |
28165 | instantiations throughout your program, perhaps putting them in the | |
28166 | translation units where the instances are used or the translation units | |
28167 | that define the templates themselves; you can put all of the explicit | |
28168 | instantiations you need into one big file; or you can create small files | |
28169 | like | |
28170 | ||
28171 | @smallexample | |
28172 | #include "Foo.h" | |
28173 | #include "Foo.cc" | |
28174 | ||
28175 | template class Foo<int>; | |
28176 | template ostream& operator << | |
28177 | (ostream&, const Foo<int>&); | |
28178 | @end smallexample | |
28179 | ||
28180 | @noindent | |
28181 | for each of the instances you need, and create a template instantiation | |
28182 | library from those. | |
28183 | ||
28184 | This is the simplest option, but also offers flexibility and | |
28185 | fine-grained control when necessary. It is also the most portable | |
28186 | alternative and programs using this approach will work with most modern | |
28187 | compilers. | |
28188 | ||
d77de738 | 28189 | @opindex fno-implicit-templates |
e54b01a1 | 28190 | @item |
d77de738 ML |
28191 | Compile your code with @option{-fno-implicit-templates} to disable the |
28192 | implicit generation of template instances, and explicitly instantiate | |
28193 | all the ones you use. This approach requires more knowledge of exactly | |
28194 | which instances you need than do the others, but it's less | |
28195 | mysterious and allows greater control if you want to ensure that only | |
28196 | the intended instances are used. | |
28197 | ||
28198 | If you are using Cfront-model code, you can probably get away with not | |
28199 | using @option{-fno-implicit-templates} when compiling files that don't | |
28200 | @samp{#include} the member template definitions. | |
28201 | ||
28202 | If you use one big file to do the instantiations, you may want to | |
28203 | compile it without @option{-fno-implicit-templates} so you get all of the | |
28204 | instances required by your explicit instantiations (but not by any | |
28205 | other files) without having to specify them as well. | |
28206 | ||
28207 | In addition to forward declaration of explicit instantiations | |
28208 | (with @code{extern}), G++ has extended the template instantiation | |
28209 | syntax to support instantiation of the compiler support data for a | |
28210 | template class (i.e.@: the vtable) without instantiating any of its | |
28211 | members (with @code{inline}), and instantiation of only the static data | |
28212 | members of a template class, without the support data or member | |
28213 | functions (with @code{static}): | |
28214 | ||
28215 | @smallexample | |
28216 | inline template class Foo<int>; | |
28217 | static template class Foo<int>; | |
28218 | @end smallexample | |
28219 | @end enumerate | |
28220 | ||
28221 | @node Bound member functions | |
28222 | @section Extracting the Function Pointer from a Bound Pointer to Member Function | |
28223 | @cindex pmf | |
28224 | @cindex pointer to member function | |
28225 | @cindex bound pointer to member function | |
28226 | ||
28227 | In C++, pointer to member functions (PMFs) are implemented using a wide | |
28228 | pointer of sorts to handle all the possible call mechanisms; the PMF | |
28229 | needs to store information about how to adjust the @samp{this} pointer, | |
28230 | and if the function pointed to is virtual, where to find the vtable, and | |
28231 | where in the vtable to look for the member function. If you are using | |
28232 | PMFs in an inner loop, you should really reconsider that decision. If | |
28233 | that is not an option, you can extract the pointer to the function that | |
28234 | would be called for a given object/PMF pair and call it directly inside | |
28235 | the inner loop, to save a bit of time. | |
28236 | ||
28237 | Note that you still pay the penalty for the call through a | |
28238 | function pointer; on most modern architectures, such a call defeats the | |
28239 | branch prediction features of the CPU@. This is also true of normal | |
28240 | virtual function calls. | |
28241 | ||
28242 | The syntax for this extension is | |
28243 | ||
28244 | @smallexample | |
28245 | extern A a; | |
28246 | extern int (A::*fp)(); | |
28247 | typedef int (*fptr)(A *); | |
28248 | ||
28249 | fptr p = (fptr)(a.*fp); | |
28250 | @end smallexample | |
28251 | ||
28252 | For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), | |
28253 | no object is needed to obtain the address of the function. They can be | |
28254 | converted to function pointers directly: | |
28255 | ||
28256 | @smallexample | |
28257 | fptr p1 = (fptr)(&A::foo); | |
28258 | @end smallexample | |
28259 | ||
28260 | @opindex Wno-pmf-conversions | |
28261 | You must specify @option{-Wno-pmf-conversions} to use this extension. | |
28262 | ||
28263 | @node C++ Attributes | |
28264 | @section C++-Specific Variable, Function, and Type Attributes | |
28265 | ||
28266 | Some attributes only make sense for C++ programs. | |
28267 | ||
28268 | @table @code | |
d77de738 ML |
28269 | @cindex @code{abi_tag} function attribute |
28270 | @cindex @code{abi_tag} variable attribute | |
28271 | @cindex @code{abi_tag} type attribute | |
f25efe50 | 28272 | @item abi_tag ("@var{tag}", ...) |
d77de738 ML |
28273 | The @code{abi_tag} attribute can be applied to a function, variable, or class |
28274 | declaration. It modifies the mangled name of the entity to | |
28275 | incorporate the tag name, in order to distinguish the function or | |
28276 | class from an earlier version with a different ABI; perhaps the class | |
28277 | has changed size, or the function has a different return type that is | |
28278 | not encoded in the mangled name. | |
28279 | ||
28280 | The attribute can also be applied to an inline namespace, but does not | |
28281 | affect the mangled name of the namespace; in this case it is only used | |
28282 | for @option{-Wabi-tag} warnings and automatic tagging of functions and | |
28283 | variables. Tagging inline namespaces is generally preferable to | |
28284 | tagging individual declarations, but the latter is sometimes | |
28285 | necessary, such as when only certain members of a class need to be | |
28286 | tagged. | |
28287 | ||
28288 | The argument can be a list of strings of arbitrary length. The | |
28289 | strings are sorted on output, so the order of the list is | |
28290 | unimportant. | |
28291 | ||
28292 | A redeclaration of an entity must not add new ABI tags, | |
28293 | since doing so would change the mangled name. | |
28294 | ||
28295 | The ABI tags apply to a name, so all instantiations and | |
28296 | specializations of a template have the same tags. The attribute will | |
28297 | be ignored if applied to an explicit specialization or instantiation. | |
28298 | ||
28299 | The @option{-Wabi-tag} flag enables a warning about a class which does | |
28300 | not have all the ABI tags used by its subobjects and virtual functions; for users with code | |
28301 | that needs to coexist with an earlier ABI, using this option can help | |
28302 | to find all affected types that need to be tagged. | |
28303 | ||
28304 | When a type involving an ABI tag is used as the type of a variable or | |
28305 | return type of a function where that tag is not already present in the | |
28306 | signature of the function, the tag is automatically applied to the | |
28307 | variable or function. @option{-Wabi-tag} also warns about this | |
28308 | situation; this warning can be avoided by explicitly tagging the | |
28309 | variable or function or moving it into a tagged inline namespace. | |
28310 | ||
d77de738 | 28311 | @cindex @code{init_priority} variable attribute |
f25efe50 | 28312 | @item init_priority (@var{priority}) |
d77de738 ML |
28313 | |
28314 | In Standard C++, objects defined at namespace scope are guaranteed to be | |
28315 | initialized in an order in strict accordance with that of their definitions | |
28316 | @emph{in a given translation unit}. No guarantee is made for initializations | |
28317 | across translation units. However, GNU C++ allows users to control the | |
28318 | order of initialization of objects defined at namespace scope with the | |
28319 | @code{init_priority} attribute by specifying a relative @var{priority}, | |
28320 | a constant integral expression currently bounded between 101 and 65535 | |
28321 | inclusive. Lower numbers indicate a higher priority. | |
28322 | ||
28323 | In the following example, @code{A} would normally be created before | |
28324 | @code{B}, but the @code{init_priority} attribute reverses that order: | |
28325 | ||
28326 | @smallexample | |
28327 | Some_Class A __attribute__ ((init_priority (2000))); | |
28328 | Some_Class B __attribute__ ((init_priority (543))); | |
28329 | @end smallexample | |
28330 | ||
28331 | @noindent | |
28332 | Note that the particular values of @var{priority} do not matter; only their | |
28333 | relative ordering. | |
28334 | ||
d77de738 | 28335 | @cindex @code{warn_unused} type attribute |
f25efe50 | 28336 | @item warn_unused |
d77de738 ML |
28337 | |
28338 | For C++ types with non-trivial constructors and/or destructors it is | |
28339 | impossible for the compiler to determine whether a variable of this | |
28340 | type is truly unused if it is not referenced. This type attribute | |
28341 | informs the compiler that variables of this type should be warned | |
28342 | about if they appear to be unused, just like variables of fundamental | |
28343 | types. | |
28344 | ||
28345 | This attribute is appropriate for types which just represent a value, | |
28346 | such as @code{std::string}; it is not appropriate for types which | |
28347 | control a resource, such as @code{std::lock_guard}. | |
28348 | ||
28349 | This attribute is also accepted in C, but it is unnecessary because C | |
28350 | does not have constructors or destructors. | |
28351 | ||
4f52e61e JM |
28352 | @cindex @code{cold} type attribute |
28353 | @item cold | |
28354 | ||
28355 | In addition to functions and labels, GNU C++ allows the @code{cold} | |
28356 | attribute to be used on C++ classes, structs, or unions. Applying | |
28357 | the @code{cold} attribute on a type has the effect of treating every | |
28358 | member function of the type, including implicit special member | |
28359 | functions, as cold. If a member function is marked with the | |
28360 | @code{hot} function attribute, the @code{hot} attribute takes | |
28361 | precedence and the @code{cold} attribute is not propagated. | |
28362 | ||
28363 | For the effects of the @code{cold} attribute on functions, see | |
28364 | @ref{Common Function Attributes}. | |
28365 | ||
28366 | @cindex @code{hot} type attribute | |
28367 | @item hot | |
28368 | ||
28369 | In addition to functions and labels, GNU C++ allows the @code{hot} | |
28370 | attribute to be used on C++ classes, structs, or unions. Applying | |
28371 | the @code{hot} attribute on a type has the effect of treating every | |
28372 | member function of the type, including implicit special member | |
28373 | functions, as hot. If a member function is marked with the | |
28374 | @code{cold} function attribute, the @code{cold} attribute takes | |
28375 | precedence and the @code{hot} attribute is not propagated. | |
28376 | ||
28377 | For the effects of the @code{hot} attribute on functions, see | |
28378 | @ref{Common Function Attributes}. | |
28379 | ||
d77de738 ML |
28380 | @end table |
28381 | ||
28382 | @node Function Multiversioning | |
28383 | @section Function Multiversioning | |
28384 | @cindex function versions | |
28385 | ||
28386 | With the GNU C++ front end, for x86 targets, you may specify multiple | |
28387 | versions of a function, where each function is specialized for a | |
28388 | specific target feature. At runtime, the appropriate version of the | |
28389 | function is automatically executed depending on the characteristics of | |
28390 | the execution platform. Here is an example. | |
28391 | ||
28392 | @smallexample | |
28393 | __attribute__ ((target ("default"))) | |
28394 | int foo () | |
28395 | @{ | |
28396 | // The default version of foo. | |
28397 | return 0; | |
28398 | @} | |
28399 | ||
28400 | __attribute__ ((target ("sse4.2"))) | |
28401 | int foo () | |
28402 | @{ | |
28403 | // foo version for SSE4.2 | |
28404 | return 1; | |
28405 | @} | |
28406 | ||
28407 | __attribute__ ((target ("arch=atom"))) | |
28408 | int foo () | |
28409 | @{ | |
28410 | // foo version for the Intel ATOM processor | |
28411 | return 2; | |
28412 | @} | |
28413 | ||
28414 | __attribute__ ((target ("arch=amdfam10"))) | |
28415 | int foo () | |
28416 | @{ | |
28417 | // foo version for the AMD Family 0x10 processors. | |
28418 | return 3; | |
28419 | @} | |
28420 | ||
28421 | int main () | |
28422 | @{ | |
28423 | int (*p)() = &foo; | |
28424 | assert ((*p) () == foo ()); | |
28425 | return 0; | |
28426 | @} | |
28427 | @end smallexample | |
28428 | ||
28429 | In the above example, four versions of function foo are created. The | |
28430 | first version of foo with the target attribute "default" is the default | |
28431 | version. This version gets executed when no other target specific | |
28432 | version qualifies for execution on a particular platform. A new version | |
28433 | of foo is created by using the same function signature but with a | |
28434 | different target string. Function foo is called or a pointer to it is | |
28435 | taken just like a regular function. GCC takes care of doing the | |
28436 | dispatching to call the right version at runtime. Refer to the | |
28437 | @uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on | |
28438 | Function Multiversioning} for more details. | |
28439 | ||
28440 | @node Type Traits | |
28441 | @section Type Traits | |
28442 | ||
28443 | The C++ front end implements syntactic extensions that allow | |
28444 | compile-time determination of | |
28445 | various characteristics of a type (or of a | |
28446 | pair of types). | |
28447 | ||
f25efe50 AA |
28448 | @defbuiltin{bool __has_nothrow_assign (@var{type})} |
28449 | If @var{type} is @code{const}-qualified or is a reference type then | |
d77de738 | 28450 | the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)} |
f25efe50 | 28451 | is @code{true} then the trait is @code{true}, else if @var{type} is |
d77de738 ML |
28452 | a cv-qualified class or union type with copy assignment operators that are |
28453 | known not to throw an exception then the trait is @code{true}, else it is | |
28454 | @code{false}. | |
f25efe50 | 28455 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 28456 | @code{void}, or an array of unknown bound. |
f25efe50 | 28457 | @enddefbuiltin |
d77de738 | 28458 | |
f25efe50 | 28459 | @defbuiltin{bool __has_nothrow_copy (@var{type})} |
d77de738 | 28460 | If @code{__has_trivial_copy (type)} is @code{true} then the trait is |
f25efe50 | 28461 | @code{true}, else if @var{type} is a cv-qualified class or union type |
d77de738 ML |
28462 | with copy constructors that are known not to throw an exception then |
28463 | the trait is @code{true}, else it is @code{false}. | |
f25efe50 | 28464 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 28465 | @code{void}, or an array of unknown bound. |
f25efe50 | 28466 | @enddefbuiltin |
d77de738 | 28467 | |
f25efe50 | 28468 | @defbuiltin{bool __has_nothrow_constructor (@var{type})} |
d77de738 | 28469 | If @code{__has_trivial_constructor (type)} is @code{true} then the trait |
f25efe50 | 28470 | is @code{true}, else if @var{type} is a cv class or union type (or array |
d77de738 ML |
28471 | thereof) with a default constructor that is known not to throw an |
28472 | exception then the trait is @code{true}, else it is @code{false}. | |
f25efe50 | 28473 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 28474 | @code{void}, or an array of unknown bound. |
f25efe50 | 28475 | @enddefbuiltin |
d77de738 | 28476 | |
f25efe50 AA |
28477 | @defbuiltin{bool __has_trivial_assign (@var{type})} |
28478 | If @var{type} is @code{const}- qualified or is a reference type then | |
d77de738 | 28479 | the trait is @code{false}. Otherwise if @code{__is_trivial (type)} is |
f25efe50 | 28480 | @code{true} then the trait is @code{true}, else if @var{type} is |
d77de738 ML |
28481 | a cv-qualified class or union type with a trivial copy assignment |
28482 | ([class.copy]) then the trait is @code{true}, else it is @code{false}. | |
f25efe50 | 28483 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 28484 | @code{void}, or an array of unknown bound. |
f25efe50 | 28485 | @enddefbuiltin |
d77de738 | 28486 | |
f25efe50 AA |
28487 | @defbuiltin{bool __has_trivial_copy (@var{type})} |
28488 | If @code{__is_trivial (type)} is @code{true} or @var{type} is a reference | |
28489 | type then the trait is @code{true}, else if @var{type} is a cv class | |
d77de738 | 28490 | or union type with a trivial copy constructor ([class.copy]) then the trait |
f25efe50 | 28491 | is @code{true}, else it is @code{false}. Requires: @var{type} shall be |
d77de738 ML |
28492 | a complete type, (possibly cv-qualified) @code{void}, or an array of unknown |
28493 | bound. | |
f25efe50 | 28494 | @enddefbuiltin |
d77de738 | 28495 | |
f25efe50 | 28496 | @defbuiltin{bool __has_trivial_constructor (@var{type})} |
d77de738 | 28497 | If @code{__is_trivial (type)} is @code{true} then the trait is @code{true}, |
f25efe50 | 28498 | else if @var{type} is a cv-qualified class or union type (or array thereof) |
d77de738 ML |
28499 | with a trivial default constructor ([class.ctor]) then the trait is @code{true}, |
28500 | else it is @code{false}. | |
f25efe50 | 28501 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 28502 | @code{void}, or an array of unknown bound. |
f25efe50 | 28503 | @enddefbuiltin |
d77de738 | 28504 | |
f25efe50 AA |
28505 | @defbuiltin{bool __has_trivial_destructor (@var{type})} |
28506 | If @code{__is_trivial (type)} is @code{true} or @var{type} is a reference type | |
28507 | then the trait is @code{true}, else if @var{type} is a cv class or union | |
d77de738 ML |
28508 | type (or array thereof) with a trivial destructor ([class.dtor]) then |
28509 | the trait is @code{true}, else it is @code{false}. | |
f25efe50 | 28510 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 28511 | @code{void}, or an array of unknown bound. |
f25efe50 | 28512 | @enddefbuiltin |
d77de738 | 28513 | |
f25efe50 AA |
28514 | @defbuiltin{bool __has_virtual_destructor (@var{type})} |
28515 | If @var{type} is a class type with a virtual destructor | |
d77de738 | 28516 | ([class.dtor]) then the trait is @code{true}, else it is @code{false}. |
f25efe50 AA |
28517 | Requires: If @var{type} is a non-union class type, it shall be a complete type. |
28518 | @enddefbuiltin | |
d77de738 | 28519 | |
f25efe50 AA |
28520 | @defbuiltin{bool __is_abstract (@var{type})} |
28521 | If @var{type} is an abstract class ([class.abstract]) then the trait | |
d77de738 | 28522 | is @code{true}, else it is @code{false}. |
f25efe50 AA |
28523 | Requires: If @var{type} is a non-union class type, it shall be a complete type. |
28524 | @enddefbuiltin | |
d77de738 | 28525 | |
f25efe50 AA |
28526 | @defbuiltin{bool __is_aggregate (@var{type})} |
28527 | If @var{type} is an aggregate type ([dcl.init.aggr]) the trait is | |
d77de738 | 28528 | @code{true}, else it is @code{false}. |
f25efe50 AA |
28529 | Requires: If @var{type} is a class type, it shall be a complete type. |
28530 | @enddefbuiltin | |
d77de738 | 28531 | |
f25efe50 AA |
28532 | @defbuiltin{bool __is_base_of (@var{base_type}, @var{derived_type})} |
28533 | If @var{base_type} is a base class of @var{derived_type} | |
d77de738 | 28534 | ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}. |
f25efe50 AA |
28535 | Top-level cv-qualifications of @var{base_type} and |
28536 | @var{derived_type} are ignored. For the purposes of this trait, a | |
d77de738 ML |
28537 | class type is considered is own base. |
28538 | Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)} | |
f25efe50 AA |
28539 | are @code{true} and @var{base_type} and @var{derived_type} are not the same |
28540 | type (disregarding cv-qualifiers), @var{derived_type} shall be a complete | |
d77de738 | 28541 | type. A diagnostic is produced if this requirement is not met. |
f25efe50 | 28542 | @enddefbuiltin |
d77de738 | 28543 | |
f25efe50 AA |
28544 | @defbuiltin{bool __is_class (@var{type})} |
28545 | If @var{type} is a cv-qualified class type, and not a union type | |
d77de738 | 28546 | ([basic.compound]) the trait is @code{true}, else it is @code{false}. |
f25efe50 | 28547 | @enddefbuiltin |
d77de738 | 28548 | |
30556bf8 | 28549 | @c FIXME Commented out for GCC 13, discuss user interface for GCC 14. |
f25efe50 | 28550 | @c @defbuiltin{bool __is_deducible (@var{template}, @var{type})} |
30556bf8 JM |
28551 | @c If template arguments for @code{template} can be deduced from |
28552 | @c @code{type} or obtained from default template arguments. | |
f25efe50 | 28553 | @c @enddefbuiltin |
148cbb15 | 28554 | |
f25efe50 | 28555 | @defbuiltin{bool __is_empty (@var{type})} |
d77de738 | 28556 | If @code{__is_class (type)} is @code{false} then the trait is @code{false}. |
f25efe50 | 28557 | Otherwise @var{type} is considered empty if and only if: @var{type} |
d77de738 | 28558 | has no non-static data members, or all non-static data members, if |
f25efe50 AA |
28559 | any, are bit-fields of length 0, and @var{type} has no virtual |
28560 | members, and @var{type} has no virtual base classes, and @var{type} | |
28561 | has no base classes @var{base_type} for which | |
d77de738 | 28562 | @code{__is_empty (base_type)} is @code{false}. |
f25efe50 AA |
28563 | Requires: If @var{type} is a non-union class type, it shall be a complete type. |
28564 | @enddefbuiltin | |
d77de738 | 28565 | |
f25efe50 AA |
28566 | @defbuiltin{bool __is_enum (@var{type})} |
28567 | If @var{type} is a cv enumeration type ([basic.compound]) the trait is | |
d77de738 | 28568 | @code{true}, else it is @code{false}. |
f25efe50 | 28569 | @enddefbuiltin |
d77de738 | 28570 | |
f25efe50 AA |
28571 | @defbuiltin{bool __is_final (@var{type})} |
28572 | If @var{type} is a class or union type marked @code{final}, then the trait | |
d77de738 | 28573 | is @code{true}, else it is @code{false}. |
f25efe50 AA |
28574 | Requires: If @var{type} is a class type, it shall be a complete type. |
28575 | @enddefbuiltin | |
d77de738 | 28576 | |
f25efe50 AA |
28577 | @defbuiltin{bool __is_literal_type (@var{type})} |
28578 | If @var{type} is a literal type ([basic.types]) the trait is | |
d77de738 | 28579 | @code{true}, else it is @code{false}. |
f25efe50 | 28580 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 28581 | @code{void}, or an array of unknown bound. |
f25efe50 | 28582 | @enddefbuiltin |
d77de738 | 28583 | |
f25efe50 AA |
28584 | @defbuiltin{bool __is_pod (@var{type})} |
28585 | If @var{type} is a cv POD type ([basic.types]) then the trait is @code{true}, | |
d77de738 | 28586 | else it is @code{false}. |
f25efe50 | 28587 | Requires: @var{type} shall be a complete type, (possibly cv-qualified) |
d77de738 | 28588 | @code{void}, or an array of unknown bound. |
f25efe50 | 28589 | @enddefbuiltin |
d77de738 | 28590 | |
f25efe50 AA |
28591 | @defbuiltin{bool __is_polymorphic (@var{type})} |
28592 | If @var{type} is a polymorphic class ([class.virtual]) then the trait | |
d77de738 | 28593 | is @code{true}, else it is @code{false}. |
f25efe50 AA |
28594 | Requires: If @var{type} is a non-union class type, it shall be a complete type. |
28595 | @enddefbuiltin | |
d77de738 | 28596 | |
f25efe50 AA |
28597 | @defbuiltin{bool __is_standard_layout (@var{type})} |
28598 | If @var{type} is a standard-layout type ([basic.types]) the trait is | |
d77de738 | 28599 | @code{true}, else it is @code{false}. |
f25efe50 | 28600 | Requires: @var{type} shall be a complete type, an array of complete types, |
d77de738 | 28601 | or (possibly cv-qualified) @code{void}. |
f25efe50 | 28602 | @enddefbuiltin |
d77de738 | 28603 | |
f25efe50 AA |
28604 | @defbuiltin{bool __is_trivial (@var{type})} |
28605 | If @var{type} is a trivial type ([basic.types]) the trait is | |
d77de738 | 28606 | @code{true}, else it is @code{false}. |
f25efe50 | 28607 | Requires: @var{type} shall be a complete type, an array of complete types, |
d77de738 | 28608 | or (possibly cv-qualified) @code{void}. |
f25efe50 | 28609 | @enddefbuiltin |
d77de738 | 28610 | |
f25efe50 AA |
28611 | @defbuiltin{bool __is_union (@var{type})} |
28612 | If @var{type} is a cv union type ([basic.compound]) the trait is | |
d77de738 | 28613 | @code{true}, else it is @code{false}. |
f25efe50 | 28614 | @enddefbuiltin |
d77de738 | 28615 | |
f25efe50 AA |
28616 | @defbuiltin{bool __underlying_type (@var{type})} |
28617 | The underlying type of @var{type}. | |
28618 | Requires: @var{type} shall be an enumeration type ([dcl.enum]). | |
28619 | @enddefbuiltin | |
d77de738 | 28620 | |
f25efe50 | 28621 | @defbuiltin{bool __integer_pack (@var{length})} |
d77de738 ML |
28622 | When used as the pattern of a pack expansion within a template |
28623 | definition, expands to a template argument pack containing integers | |
f25efe50 AA |
28624 | from @code{0} to @code{@var{length}-1}. This is provided for |
28625 | efficient implementation of @code{std::make_integer_sequence}. | |
28626 | @enddefbuiltin | |
d77de738 ML |
28627 | |
28628 | ||
28629 | @node C++ Concepts | |
28630 | @section C++ Concepts | |
28631 | ||
28632 | C++ concepts provide much-improved support for generic programming. In | |
28633 | particular, they allow the specification of constraints on template arguments. | |
28634 | The constraints are used to extend the usual overloading and partial | |
28635 | specialization capabilities of the language, allowing generic data structures | |
28636 | and algorithms to be ``refined'' based on their properties rather than their | |
28637 | type names. | |
28638 | ||
28639 | The following keywords are reserved for concepts. | |
28640 | ||
28641 | @table @code | |
f25efe50 | 28642 | @kindex assumes |
d77de738 ML |
28643 | @item assumes |
28644 | States an expression as an assumption, and if possible, verifies that the | |
28645 | assumption is valid. For example, @code{assume(n > 0)}. | |
28646 | ||
f25efe50 | 28647 | @kindex axiom |
d77de738 ML |
28648 | @item axiom |
28649 | Introduces an axiom definition. Axioms introduce requirements on values. | |
28650 | ||
da9140b9 | 28651 | @kindex forall |
d77de738 ML |
28652 | @item forall |
28653 | Introduces a universally quantified object in an axiom. For example, | |
da9140b9 | 28654 | @code{forall (int n) n + 0 == n}. |
d77de738 | 28655 | |
da9140b9 | 28656 | @kindex concept |
d77de738 ML |
28657 | @item concept |
28658 | Introduces a concept definition. Concepts are sets of syntactic and semantic | |
28659 | requirements on types and their values. | |
28660 | ||
f25efe50 | 28661 | @kindex requires |
d77de738 ML |
28662 | @item requires |
28663 | Introduces constraints on template arguments or requirements for a member | |
28664 | function of a class template. | |
d77de738 ML |
28665 | @end table |
28666 | ||
28667 | The front end also exposes a number of internal mechanism that can be used | |
28668 | to simplify the writing of type traits. Note that some of these traits are | |
28669 | likely to be removed in the future. | |
28670 | ||
f25efe50 AA |
28671 | @defbuiltin{bool __is_same (@var{type1}, @var{type2})} |
28672 | A binary type trait: @code{true} whenever the @var{type1} and | |
28673 | @var{type2} refer to the same type. | |
28674 | @enddefbuiltin | |
d77de738 ML |
28675 | |
28676 | ||
28677 | @node Deprecated Features | |
28678 | @section Deprecated Features | |
28679 | ||
28680 | In the past, the GNU C++ compiler was extended to experiment with new | |
28681 | features, at a time when the C++ language was still evolving. Now that | |
28682 | the C++ standard is complete, some of those features are superseded by | |
28683 | superior alternatives. Using the old features might cause a warning in | |
28684 | some cases that the feature will be dropped in the future. In other | |
28685 | cases, the feature might be gone already. | |
28686 | ||
28687 | G++ allows a virtual function returning @samp{void *} to be overridden | |
28688 | by one returning a different pointer type. This extension to the | |
28689 | covariant return type rules is now deprecated and will be removed from a | |
28690 | future version. | |
28691 | ||
28692 | The use of default arguments in function pointers, function typedefs | |
28693 | and other places where they are not permitted by the standard is | |
28694 | deprecated and will be removed from a future version of G++. | |
28695 | ||
28696 | G++ allows floating-point literals to appear in integral constant expressions, | |
28697 | e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} } | |
28698 | This extension is deprecated and will be removed from a future version. | |
28699 | ||
28700 | G++ allows static data members of const floating-point type to be declared | |
28701 | with an initializer in a class definition. The standard only allows | |
28702 | initializers for static members of const integral types and const | |
28703 | enumeration types so this extension has been deprecated and will be removed | |
28704 | from a future version. | |
28705 | ||
28706 | G++ allows attributes to follow a parenthesized direct initializer, | |
28707 | e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension | |
28708 | has been ignored since G++ 3.3 and is deprecated. | |
28709 | ||
28710 | G++ allows anonymous structs and unions to have members that are not | |
28711 | public non-static data members (i.e.@: fields). These extensions are | |
28712 | deprecated. | |
28713 | ||
28714 | @node Backwards Compatibility | |
28715 | @section Backwards Compatibility | |
28716 | @cindex Backwards Compatibility | |
28717 | @cindex ARM [Annotated C++ Reference Manual] | |
28718 | ||
28719 | Now that there is a definitive ISO standard C++, G++ has a specification | |
28720 | to adhere to. The C++ language evolved over time, and features that | |
28721 | used to be acceptable in previous drafts of the standard, such as the ARM | |
28722 | [Annotated C++ Reference Manual], are no longer accepted. In order to allow | |
28723 | compilation of C++ written to such drafts, G++ contains some backwards | |
28724 | compatibilities. @emph{All such backwards compatibility features are | |
28725 | liable to disappear in future versions of G++.} They should be considered | |
28726 | deprecated. @xref{Deprecated Features}. | |
28727 | ||
28728 | @table @code | |
28729 | ||
28730 | @item Implicit C language | |
28731 | Old C system header files did not contain an @code{extern "C" @{@dots{}@}} | |
28732 | scope to set the language. On such systems, all system header files are | |
28733 | implicitly scoped inside a C language scope. Such headers must | |
28734 | correctly prototype function argument types, there is no leeway for | |
28735 | @code{()} to indicate an unspecified set of arguments. | |
28736 | ||
28737 | @end table | |
28738 | ||
28739 | @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd | |
28740 | @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr |