1 c Copyright (C) 1988-2021 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @chapter Extensions to the C Language Family
8 @cindex extensions, C language
9 @cindex C language extensions
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@.
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++.
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++.
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
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
79 * Return Address:: Getting the return or frame address of a function.
80 * Vector Extensions:: Using vector instructions through built-in functions.
81 * Offsetof:: Special syntax for implementing @code{offsetof}.
82 * __sync Builtins:: Legacy built-in functions for atomic memory access.
83 * __atomic Builtins:: Atomic built-in functions with memory model.
84 * Integer Overflow Builtins:: Built-in functions to perform arithmetics and
85 arithmetic overflow checking.
86 * x86 specific memory model extensions for transactional memory:: x86 memory models.
87 * Object Size Checking:: Built-in functions for limited buffer overflow
89 * Other Builtins:: Other built-in functions.
90 * Target Builtins:: Built-in functions specific to particular targets.
91 * Target Format Checks:: Format checks specific to particular targets.
92 * Pragmas:: Pragmas accepted by GCC.
93 * Unnamed Fields:: Unnamed struct/union fields within structs/unions.
94 * Thread-Local:: Per-thread variables.
95 * Binary constants:: Binary constants using the @samp{0b} prefix.
99 @section Statements and Declarations in Expressions
100 @cindex statements inside expressions
101 @cindex declarations inside expressions
102 @cindex expressions containing statements
103 @cindex macros, statements in expressions
105 @c the above section title wrapped and causes an underfull hbox.. i
106 @c changed it from "within" to "in". --mew 4feb93
107 A compound statement enclosed in parentheses may appear as an expression
108 in GNU C@. This allows you to use loops, switches, and local variables
109 within an expression.
111 Recall that a compound statement is a sequence of statements surrounded
112 by braces; in this construct, parentheses go around the braces. For
116 (@{ int y = foo (); int z;
123 is a valid (though slightly more complex than necessary) expression
124 for the absolute value of @code{foo ()}.
126 The last thing in the compound statement should be an expression
127 followed by a semicolon; the value of this subexpression serves as the
128 value of the entire construct. (If you use some other kind of statement
129 last within the braces, the construct has type @code{void}, and thus
130 effectively no value.)
132 This feature is especially useful in making macro definitions ``safe'' (so
133 that they evaluate each operand exactly once). For example, the
134 ``maximum'' function is commonly defined as a macro in standard C as
138 #define max(a,b) ((a) > (b) ? (a) : (b))
142 @cindex side effects, macro argument
143 But this definition computes either @var{a} or @var{b} twice, with bad
144 results if the operand has side effects. In GNU C, if you know the
145 type of the operands (here taken as @code{int}), you can avoid this
146 problem by defining the macro as follows:
149 #define maxint(a,b) \
150 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
153 Note that introducing variable declarations (as we do in @code{maxint}) can
154 cause variable shadowing, so while this example using the @code{max} macro
155 produces correct results:
157 int _a = 1, _b = 2, c;
161 this example using maxint will not:
163 int _a = 1, _b = 2, c;
167 This problem may for instance occur when we use this pattern recursively, like
171 #define maxint3(a, b, c) \
172 (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @})
175 Embedded statements are not allowed in constant expressions, such as
176 the value of an enumeration constant, the width of a bit-field, or
177 the initial value of a static variable.
179 If you don't know the type of the operand, you can still do this, but you
180 must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
182 In G++, the result value of a statement expression undergoes array and
183 function pointer decay, and is returned by value to the enclosing
184 expression. For instance, if @code{A} is a class, then
193 constructs a temporary @code{A} object to hold the result of the
194 statement expression, and that is used to invoke @code{Foo}.
195 Therefore the @code{this} pointer observed by @code{Foo} is not the
198 In a statement expression, any temporaries created within a statement
199 are destroyed at that statement's end. This makes statement
200 expressions inside macros slightly different from function calls. In
201 the latter case temporaries introduced during argument evaluation are
202 destroyed at the end of the statement that includes the function
203 call. In the statement expression case they are destroyed during
204 the statement expression. For instance,
207 #define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
208 template<typename T> T function(T a) @{ T b = a; return b + 3; @}
218 has different places where temporaries are destroyed. For the
219 @code{macro} case, the temporary @code{X} is destroyed just after
220 the initialization of @code{b}. In the @code{function} case that
221 temporary is destroyed when the function returns.
223 These considerations mean that it is probably a bad idea to use
224 statement expressions of this form in header files that are designed to
225 work with C++. (Note that some versions of the GNU C Library contained
226 header files using statement expressions that lead to precisely this
229 Jumping into a statement expression with @code{goto} or using a
230 @code{switch} statement outside the statement expression with a
231 @code{case} or @code{default} label inside the statement expression is
232 not permitted. Jumping into a statement expression with a computed
233 @code{goto} (@pxref{Labels as Values}) has undefined behavior.
234 Jumping out of a statement expression is permitted, but if the
235 statement expression is part of a larger expression then it is
236 unspecified which other subexpressions of that expression have been
237 evaluated except where the language definition requires certain
238 subexpressions to be evaluated before or after the statement
239 expression. A @code{break} or @code{continue} statement inside of
240 a statement expression used in @code{while}, @code{do} or @code{for}
241 loop or @code{switch} statement condition
242 or @code{for} statement init or increment expressions jumps to an
243 outer loop or @code{switch} statement if any (otherwise it is an error),
244 rather than to the loop or @code{switch} statement in whose condition
245 or init or increment expression it appears.
246 In any case, as with a function call, the evaluation of a
247 statement expression is not interleaved with the evaluation of other
248 parts of the containing expression. For example,
251 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
255 calls @code{foo} and @code{bar1} and does not call @code{baz} but
256 may or may not call @code{bar2}. If @code{bar2} is called, it is
257 called after @code{foo} and before @code{bar1}.
260 @section Locally Declared Labels
262 @cindex macros, local labels
264 GCC allows you to declare @dfn{local labels} in any nested block
265 scope. A local label is just like an ordinary label, but you can
266 only reference it (with a @code{goto} statement, or by taking its
267 address) within the block in which it is declared.
269 A local label declaration looks like this:
272 __label__ @var{label};
279 __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
282 Local label declarations must come at the beginning of the block,
283 before any ordinary declarations or statements.
285 The label declaration defines the label @emph{name}, but does not define
286 the label itself. You must do this in the usual way, with
287 @code{@var{label}:}, within the statements of the statement expression.
289 The local label feature is useful for complex macros. If a macro
290 contains nested loops, a @code{goto} can be useful for breaking out of
291 them. However, an ordinary label whose scope is the whole function
292 cannot be used: if the macro can be expanded several times in one
293 function, the label is multiply defined in that function. A
294 local label avoids this problem. For example:
297 #define SEARCH(value, array, target) \
300 typeof (target) _SEARCH_target = (target); \
301 typeof (*(array)) *_SEARCH_array = (array); \
304 for (i = 0; i < max; i++) \
305 for (j = 0; j < max; j++) \
306 if (_SEARCH_array[i][j] == _SEARCH_target) \
307 @{ (value) = i; goto found; @} \
313 This could also be written using a statement expression:
316 #define SEARCH(array, target) \
319 typeof (target) _SEARCH_target = (target); \
320 typeof (*(array)) *_SEARCH_array = (array); \
323 for (i = 0; i < max; i++) \
324 for (j = 0; j < max; j++) \
325 if (_SEARCH_array[i][j] == _SEARCH_target) \
326 @{ value = i; goto found; @} \
333 Local label declarations also make the labels they declare visible to
334 nested functions, if there are any. @xref{Nested Functions}, for details.
336 @node Labels as Values
337 @section Labels as Values
338 @cindex labels as values
339 @cindex computed gotos
340 @cindex goto with computed label
341 @cindex address of a label
343 You can get the address of a label defined in the current function
344 (or a containing function) with the unary operator @samp{&&}. The
345 value has type @code{void *}. This value is a constant and can be used
346 wherever a constant of that type is valid. For example:
354 To use these values, you need to be able to jump to one. This is done
355 with the computed goto statement@footnote{The analogous feature in
356 Fortran is called an assigned goto, but that name seems inappropriate in
357 C, where one can do more than simply store label addresses in label
358 variables.}, @code{goto *@var{exp};}. For example,
365 Any expression of type @code{void *} is allowed.
367 One way of using these constants is in initializing a static array that
368 serves as a jump table:
371 static void *array[] = @{ &&foo, &&bar, &&hack @};
375 Then you can select a label with indexing, like this:
382 Note that this does not check whether the subscript is in bounds---array
383 indexing in C never does that.
385 Such an array of label values serves a purpose much like that of the
386 @code{switch} statement. The @code{switch} statement is cleaner, so
387 use that rather than an array unless the problem does not fit a
388 @code{switch} statement very well.
390 Another use of label values is in an interpreter for threaded code.
391 The labels within the interpreter function can be stored in the
392 threaded code for super-fast dispatching.
394 You may not use this mechanism to jump to code in a different function.
395 If you do that, totally unpredictable things happen. The best way to
396 avoid this is to store the label address only in automatic variables and
397 never pass it as an argument.
399 An alternate way to write the above example is
402 static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
404 goto *(&&foo + array[i]);
408 This is more friendly to code living in shared libraries, as it reduces
409 the number of dynamic relocations that are needed, and by consequence,
410 allows the data to be read-only.
411 This alternative with label differences is not supported for the AVR target,
412 please use the first approach for AVR programs.
414 The @code{&&foo} expressions for the same label might have different
415 values if the containing function is inlined or cloned. If a program
416 relies on them being always the same,
417 @code{__attribute__((__noinline__,__noclone__))} should be used to
418 prevent inlining and cloning. If @code{&&foo} is used in a static
419 variable initializer, inlining and cloning is forbidden.
421 @node Nested Functions
422 @section Nested Functions
423 @cindex nested functions
424 @cindex downward funargs
427 A @dfn{nested function} is a function defined inside another function.
428 Nested functions are supported as an extension in GNU C, but are not
429 supported by GNU C++.
431 The nested function's name is local to the block where it is defined.
432 For example, here we define a nested function named @code{square}, and
437 foo (double a, double b)
439 double square (double z) @{ return z * z; @}
441 return square (a) + square (b);
446 The nested function can access all the variables of the containing
447 function that are visible at the point of its definition. This is
448 called @dfn{lexical scoping}. For example, here we show a nested
449 function which uses an inherited variable named @code{offset}:
453 bar (int *array, int offset, int size)
455 int access (int *array, int index)
456 @{ return array[index + offset]; @}
459 for (i = 0; i < size; i++)
460 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
465 Nested function definitions are permitted within functions in the places
466 where variable definitions are allowed; that is, in any block, mixed
467 with the other declarations and statements in the block.
469 It is possible to call the nested function from outside the scope of its
470 name by storing its address or passing the address to another function:
473 hack (int *array, int size)
475 void store (int index, int value)
476 @{ array[index] = value; @}
478 intermediate (store, size);
482 Here, the function @code{intermediate} receives the address of
483 @code{store} as an argument. If @code{intermediate} calls @code{store},
484 the arguments given to @code{store} are used to store into @code{array}.
485 But this technique works only so long as the containing function
486 (@code{hack}, in this example) does not exit.
488 If you try to call the nested function through its address after the
489 containing function exits, all hell breaks loose. If you try
490 to call it after a containing scope level exits, and if it refers
491 to some of the variables that are no longer in scope, you may be lucky,
492 but it's not wise to take the risk. If, however, the nested function
493 does not refer to anything that has gone out of scope, you should be
496 GCC implements taking the address of a nested function using a technique
497 called @dfn{trampolines}. This technique was described in
498 @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
499 C++ Conference Proceedings, October 17-21, 1988).
501 A nested function can jump to a label inherited from a containing
502 function, provided the label is explicitly declared in the containing
503 function (@pxref{Local Labels}). Such a jump returns instantly to the
504 containing function, exiting the nested function that did the
505 @code{goto} and any intermediate functions as well. Here is an example:
509 bar (int *array, int offset, int size)
512 int access (int *array, int index)
516 return array[index + offset];
520 for (i = 0; i < size; i++)
521 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
525 /* @r{Control comes here from @code{access}
526 if it detects an error.} */
533 A nested function always has no linkage. Declaring one with
534 @code{extern} or @code{static} is erroneous. If you need to declare the nested function
535 before its definition, use @code{auto} (which is otherwise meaningless
536 for function declarations).
539 bar (int *array, int offset, int size)
542 auto int access (int *, int);
544 int access (int *array, int index)
548 return array[index + offset];
555 @section Nonlocal Gotos
556 @cindex nonlocal gotos
558 GCC provides the built-in functions @code{__builtin_setjmp} and
559 @code{__builtin_longjmp} which are similar to, but not interchangeable
560 with, the C library functions @code{setjmp} and @code{longjmp}.
561 The built-in versions are used internally by GCC's libraries
562 to implement exception handling on some targets. You should use the
563 standard C library functions declared in @code{<setjmp.h>} in user code
564 instead of the builtins.
566 The built-in versions of these functions use GCC's normal
567 mechanisms to save and restore registers using the stack on function
568 entry and exit. The jump buffer argument @var{buf} holds only the
569 information needed to restore the stack frame, rather than the entire
570 set of saved register values.
572 An important caveat is that GCC arranges to save and restore only
573 those registers known to the specific architecture variant being
574 compiled for. This can make @code{__builtin_setjmp} and
575 @code{__builtin_longjmp} more efficient than their library
576 counterparts in some cases, but it can also cause incorrect and
577 mysterious behavior when mixing with code that uses the full register
580 You should declare the jump buffer argument @var{buf} to the
581 built-in functions as:
585 intptr_t @var{buf}[5];
588 @deftypefn {Built-in Function} {int} __builtin_setjmp (intptr_t *@var{buf})
589 This function saves the current stack context in @var{buf}.
590 @code{__builtin_setjmp} returns 0 when returning directly,
591 and 1 when returning from @code{__builtin_longjmp} using the same
595 @deftypefn {Built-in Function} {void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})
596 This function restores the stack context in @var{buf},
597 saved by a previous call to @code{__builtin_setjmp}. After
598 @code{__builtin_longjmp} is finished, the program resumes execution as
599 if the matching @code{__builtin_setjmp} returns the value @var{val},
602 Because @code{__builtin_longjmp} depends on the function return
603 mechanism to restore the stack context, it cannot be called
604 from the same function calling @code{__builtin_setjmp} to
605 initialize @var{buf}. It can only be called from a function called
606 (directly or indirectly) from the function calling @code{__builtin_setjmp}.
609 @node Constructing Calls
610 @section Constructing Function Calls
611 @cindex constructing calls
612 @cindex forwarding calls
614 Using the built-in functions described below, you can record
615 the arguments a function received, and call another function
616 with the same arguments, without knowing the number or types
619 You can also record the return value of that function call,
620 and later return that value, without knowing what data type
621 the function tried to return (as long as your caller expects
624 However, these built-in functions may interact badly with some
625 sophisticated features or other extensions of the language. It
626 is, therefore, not recommended to use them outside very simple
627 functions acting as mere forwarders for their arguments.
629 @deftypefn {Built-in Function} {void *} __builtin_apply_args ()
630 This built-in function returns a pointer to data
631 describing how to perform a call with the same arguments as are passed
632 to the current function.
634 The function saves the arg pointer register, structure value address,
635 and all registers that might be used to pass arguments to a function
636 into a block of memory allocated on the stack. Then it returns the
637 address of that block.
640 @deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
641 This built-in function invokes @var{function}
642 with a copy of the parameters described by @var{arguments}
645 The value of @var{arguments} should be the value returned by
646 @code{__builtin_apply_args}. The argument @var{size} specifies the size
647 of the stack argument data, in bytes.
649 This function returns a pointer to data describing
650 how to return whatever value is returned by @var{function}. The data
651 is saved in a block of memory allocated on the stack.
653 It is not always simple to compute the proper value for @var{size}. The
654 value is used by @code{__builtin_apply} to compute the amount of data
655 that should be pushed on the stack and copied from the incoming argument
659 @deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
660 This built-in function returns the value described by @var{result} from
661 the containing function. You should specify, for @var{result}, a value
662 returned by @code{__builtin_apply}.
665 @deftypefn {Built-in Function} {} __builtin_va_arg_pack ()
666 This built-in function represents all anonymous arguments of an inline
667 function. It can be used only in inline functions that are always
668 inlined, never compiled as a separate function, such as those using
669 @code{__attribute__ ((__always_inline__))} or
670 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
671 It must be only passed as last argument to some other function
672 with variable arguments. This is useful for writing small wrapper
673 inlines for variable argument functions, when using preprocessor
674 macros is undesirable. For example:
676 extern int myprintf (FILE *f, const char *format, ...);
677 extern inline __attribute__ ((__gnu_inline__)) int
678 myprintf (FILE *f, const char *format, ...)
680 int r = fprintf (f, "myprintf: ");
683 int s = fprintf (f, format, __builtin_va_arg_pack ());
691 @deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len ()
692 This built-in function returns the number of anonymous arguments of
693 an inline function. It can be used only in inline functions that
694 are always inlined, never compiled as a separate function, such
695 as those using @code{__attribute__ ((__always_inline__))} or
696 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
697 For example following does link- or run-time checking of open
698 arguments for optimized code:
701 extern inline __attribute__((__gnu_inline__)) int
702 myopen (const char *path, int oflag, ...)
704 if (__builtin_va_arg_pack_len () > 1)
705 warn_open_too_many_arguments ();
707 if (__builtin_constant_p (oflag))
709 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
711 warn_open_missing_mode ();
712 return __open_2 (path, oflag);
714 return open (path, oflag, __builtin_va_arg_pack ());
717 if (__builtin_va_arg_pack_len () < 1)
718 return __open_2 (path, oflag);
720 return open (path, oflag, __builtin_va_arg_pack ());
727 @section Referring to a Type with @code{typeof}
730 @cindex macros, types of arguments
732 Another way to refer to the type of an expression is with @code{typeof}.
733 The syntax of using of this keyword looks like @code{sizeof}, but the
734 construct acts semantically like a type name defined with @code{typedef}.
736 There are two ways of writing the argument to @code{typeof}: with an
737 expression or with a type. Here is an example with an expression:
744 This assumes that @code{x} is an array of pointers to functions;
745 the type described is that of the values of the functions.
747 Here is an example with a typename as the argument:
754 Here the type described is that of pointers to @code{int}.
756 If you are writing a header file that must work when included in ISO C
757 programs, write @code{__typeof__} instead of @code{typeof}.
758 @xref{Alternate Keywords}.
760 A @code{typeof} construct can be used anywhere a typedef name can be
761 used. For example, you can use it in a declaration, in a cast, or inside
762 of @code{sizeof} or @code{typeof}.
764 The operand of @code{typeof} is evaluated for its side effects if and
765 only if it is an expression of variably modified type or the name of
768 @code{typeof} is often useful in conjunction with
769 statement expressions (@pxref{Statement Exprs}).
770 Here is how the two together can
771 be used to define a safe ``maximum'' macro which operates on any
772 arithmetic type and evaluates each of its arguments exactly once:
776 (@{ typeof (a) _a = (a); \
777 typeof (b) _b = (b); \
778 _a > _b ? _a : _b; @})
781 @cindex underscores in variables in macros
782 @cindex @samp{_} in variables in macros
783 @cindex local variables in macros
784 @cindex variables, local, in macros
785 @cindex macros, local variables in
787 The reason for using names that start with underscores for the local
788 variables is to avoid conflicts with variable names that occur within the
789 expressions that are substituted for @code{a} and @code{b}. Eventually we
790 hope to design a new form of declaration syntax that allows you to declare
791 variables whose scopes start only after their initializers; this will be a
792 more reliable way to prevent such conflicts.
795 Some more examples of the use of @code{typeof}:
799 This declares @code{y} with the type of what @code{x} points to.
806 This declares @code{y} as an array of such values.
813 This declares @code{y} as an array of pointers to characters:
816 typeof (typeof (char *)[4]) y;
820 It is equivalent to the following traditional C declaration:
826 To see the meaning of the declaration using @code{typeof}, and why it
827 might be a useful way to write, rewrite it with these macros:
830 #define pointer(T) typeof(T *)
831 #define array(T, N) typeof(T [N])
835 Now the declaration can be rewritten this way:
838 array (pointer (char), 4) y;
842 Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
843 pointers to @code{char}.
846 In GNU C, but not GNU C++, you may also declare the type of a variable
847 as @code{__auto_type}. In that case, the declaration must declare
848 only one variable, whose declarator must just be an identifier, the
849 declaration must be initialized, and the type of the variable is
850 determined by the initializer; the name of the variable is not in
851 scope until after the initializer. (In C++, you should use C++11
852 @code{auto} for this purpose.) Using @code{__auto_type}, the
853 ``maximum'' macro above could be written as:
857 (@{ __auto_type _a = (a); \
858 __auto_type _b = (b); \
859 _a > _b ? _a : _b; @})
862 Using @code{__auto_type} instead of @code{typeof} has two advantages:
865 @item Each argument to the macro appears only once in the expansion of
866 the macro. This prevents the size of the macro expansion growing
867 exponentially when calls to such macros are nested inside arguments of
870 @item If the argument to the macro has variably modified type, it is
871 evaluated only once when using @code{__auto_type}, but twice if
872 @code{typeof} is used.
876 @section Conditionals with Omitted Operands
877 @cindex conditional expressions, extensions
878 @cindex omitted middle-operands
879 @cindex middle-operands, omitted
880 @cindex extensions, @code{?:}
881 @cindex @code{?:} extensions
883 The middle operand in a conditional expression may be omitted. Then
884 if the first operand is nonzero, its value is the value of the conditional
887 Therefore, the expression
894 has the value of @code{x} if that is nonzero; otherwise, the value of
897 This example is perfectly equivalent to
903 @cindex side effect in @code{?:}
904 @cindex @code{?:} side effect
906 In this simple case, the ability to omit the middle operand is not
907 especially useful. When it becomes useful is when the first operand does,
908 or may (if it is a macro argument), contain a side effect. Then repeating
909 the operand in the middle would perform the side effect twice. Omitting
910 the middle operand uses the value already computed without the undesirable
911 effects of recomputing it.
914 @section 128-bit Integers
915 @cindex @code{__int128} data types
917 As an extension the integer scalar type @code{__int128} is supported for
918 targets which have an integer mode wide enough to hold 128 bits.
919 Simply write @code{__int128} for a signed 128-bit integer, or
920 @code{unsigned __int128} for an unsigned 128-bit integer. There is no
921 support in GCC for expressing an integer constant of type @code{__int128}
922 for targets with @code{long long} integer less than 128 bits wide.
925 @section Double-Word Integers
926 @cindex @code{long long} data types
927 @cindex double-word arithmetic
928 @cindex multiprecision arithmetic
929 @cindex @code{LL} integer suffix
930 @cindex @code{ULL} integer suffix
932 ISO C99 and ISO C++11 support data types for integers that are at least
933 64 bits wide, and as an extension GCC supports them in C90 and C++98 modes.
934 Simply write @code{long long int} for a signed integer, or
935 @code{unsigned long long int} for an unsigned integer. To make an
936 integer constant of type @code{long long int}, add the suffix @samp{LL}
937 to the integer. To make an integer constant of type @code{unsigned long
938 long int}, add the suffix @samp{ULL} to the integer.
940 You can use these types in arithmetic like any other integer types.
941 Addition, subtraction, and bitwise boolean operations on these types
942 are open-coded on all types of machines. Multiplication is open-coded
943 if the machine supports a fullword-to-doubleword widening multiply
944 instruction. Division and shifts are open-coded only on machines that
945 provide special support. The operations that are not open-coded use
946 special library routines that come with GCC@.
948 There may be pitfalls when you use @code{long long} types for function
949 arguments without function prototypes. If a function
950 expects type @code{int} for its argument, and you pass a value of type
951 @code{long long int}, confusion results because the caller and the
952 subroutine disagree about the number of bytes for the argument.
953 Likewise, if the function expects @code{long long int} and you pass
954 @code{int}. The best way to avoid such problems is to use prototypes.
957 @section Complex Numbers
958 @cindex complex numbers
959 @cindex @code{_Complex} keyword
960 @cindex @code{__complex__} keyword
962 ISO C99 supports complex floating data types, and as an extension GCC
963 supports them in C90 mode and in C++. GCC also supports complex integer data
964 types which are not part of ISO C99. You can declare complex types
965 using the keyword @code{_Complex}. As an extension, the older GNU
966 keyword @code{__complex__} is also supported.
968 For example, @samp{_Complex double x;} declares @code{x} as a
969 variable whose real part and imaginary part are both of type
970 @code{double}. @samp{_Complex short int y;} declares @code{y} to
971 have real and imaginary parts of type @code{short int}; this is not
972 likely to be useful, but it shows that the set of complex types is
975 To write a constant with a complex data type, use the suffix @samp{i} or
976 @samp{j} (either one; they are equivalent). For example, @code{2.5fi}
977 has type @code{_Complex float} and @code{3i} has type
978 @code{_Complex int}. Such a constant always has a pure imaginary
979 value, but you can form any complex value you like by adding one to a
980 real constant. This is a GNU extension; if you have an ISO C99
981 conforming C library (such as the GNU C Library), and want to construct complex
982 constants of floating type, you should include @code{<complex.h>} and
983 use the macros @code{I} or @code{_Complex_I} instead.
985 The ISO C++14 library also defines the @samp{i} suffix, so C++14 code
986 that includes the @samp{<complex>} header cannot use @samp{i} for the
987 GNU extension. The @samp{j} suffix still has the GNU meaning.
989 @cindex @code{__real__} keyword
990 @cindex @code{__imag__} keyword
991 To extract the real part of a complex-valued expression @var{exp}, write
992 @code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
993 extract the imaginary part. This is a GNU extension; for values of
994 floating type, you should use the ISO C99 functions @code{crealf},
995 @code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
996 @code{cimagl}, declared in @code{<complex.h>} and also provided as
997 built-in functions by GCC@.
999 @cindex complex conjugation
1000 The operator @samp{~} performs complex conjugation when used on a value
1001 with a complex type. This is a GNU extension; for values of
1002 floating type, you should use the ISO C99 functions @code{conjf},
1003 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
1004 provided as built-in functions by GCC@.
1006 GCC can allocate complex automatic variables in a noncontiguous
1007 fashion; it's even possible for the real part to be in a register while
1008 the imaginary part is on the stack (or vice versa). Only the DWARF
1009 debug info format can represent this, so use of DWARF is recommended.
1010 If you are using the stabs debug info format, GCC describes a noncontiguous
1011 complex variable as if it were two separate variables of noncomplex type.
1012 If the variable's actual name is @code{foo}, the two fictitious
1013 variables are named @code{foo$real} and @code{foo$imag}. You can
1014 examine and set these two fictitious variables with your debugger.
1016 @node Floating Types
1017 @section Additional Floating Types
1018 @cindex additional floating types
1019 @cindex @code{_Float@var{n}} data types
1020 @cindex @code{_Float@var{n}x} data types
1021 @cindex @code{__float80} data type
1022 @cindex @code{__float128} data type
1023 @cindex @code{__ibm128} data type
1024 @cindex @code{w} floating point suffix
1025 @cindex @code{q} floating point suffix
1026 @cindex @code{W} floating point suffix
1027 @cindex @code{Q} floating point suffix
1029 ISO/IEC TS 18661-3:2015 defines C support for additional floating
1030 types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
1031 these type names; the set of types supported depends on the target
1032 architecture. These types are not supported when compiling C++.
1033 Constants with these types use suffixes @code{f@var{n}} or
1034 @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
1035 names can be used together with @code{_Complex} to declare complex
1038 As an extension, GNU C and GNU C++ support additional floating
1039 types, which are not supported by all targets.
1041 @item @code{__float128} is available on i386, x86_64, IA-64, and
1042 hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
1043 the vector scalar (VSX) instruction set. @code{__float128} supports
1044 the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64
1045 other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
1046 On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
1049 @item @code{__float80} is available on the i386, x86_64, and IA-64
1050 targets, and supports the 80-bit (@code{XFmode}) floating type. It is
1051 an alias for the type name @code{_Float64x} on these targets.
1053 @item @code{__ibm128} is available on PowerPC targets, and provides
1054 access to the IBM extended double format which is the current format
1055 used for @code{long double}. When @code{long double} transitions to
1056 @code{__float128} on PowerPC in the future, @code{__ibm128} will remain
1057 for use in conversions between the two types.
1060 Support for these additional types includes the arithmetic operators:
1061 add, subtract, multiply, divide; unary arithmetic operators;
1062 relational operators; equality operators; and conversions to and from
1063 integer and other floating types. Use a suffix @samp{w} or @samp{W}
1064 in a literal constant of type @code{__float80} or type
1065 @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}.
1067 In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
1068 on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
1069 expected in future versions of GCC that @code{_Float128} and @code{__float128}
1070 will be enabled automatically.
1072 The @code{_Float128} type is supported on all systems where
1073 @code{__float128} is supported or where @code{long double} has the
1074 IEEE binary128 format. The @code{_Float64x} type is supported on all
1075 systems where @code{__float128} is supported. The @code{_Float32}
1076 type is supported on all systems supporting IEEE binary32; the
1077 @code{_Float64} and @code{_Float32x} types are supported on all systems
1078 supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
1079 systems by default, on ARM systems when the IEEE format for 16-bit
1080 floating-point types is selected with @option{-mfp16-format=ieee} and,
1081 for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently
1082 support @code{_Float128x} on any systems.
1084 On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
1085 types using the corresponding internal complex type, @code{XCmode} for
1086 @code{__float80} type and @code{TCmode} for @code{__float128} type:
1089 typedef _Complex float __attribute__((mode(TC))) _Complex128;
1090 typedef _Complex float __attribute__((mode(XC))) _Complex80;
1093 On the PowerPC Linux VSX targets, you can declare complex types using
1094 the corresponding internal complex type, @code{KCmode} for
1095 @code{__float128} type and @code{ICmode} for @code{__ibm128} type:
1098 typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
1099 typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
1102 @node Half-Precision
1103 @section Half-Precision Floating Point
1104 @cindex half-precision floating point
1105 @cindex @code{__fp16} data type
1106 @cindex @code{__Float16} data type
1108 On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
1109 point via the @code{__fp16} type defined in the ARM C Language Extensions.
1110 On ARM systems, you must enable this type explicitly with the
1111 @option{-mfp16-format} command-line option in order to use it.
1112 On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit)
1113 floating point via the @code{_Float16} type. For C++, x86 provides a builtin
1114 type named @code{_Float16} which contains same data format as C.
1116 ARM targets support two incompatible representations for half-precision
1117 floating-point values. You must choose one of the representations and
1118 use it consistently in your program.
1120 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
1121 This format can represent normalized values in the range of @math{2^{-14}} to 65504.
1122 There are 11 bits of significand precision, approximately 3
1125 Specifying @option{-mfp16-format=alternative} selects the ARM
1126 alternative format. This representation is similar to the IEEE
1127 format, but does not support infinities or NaNs. Instead, the range
1128 of exponents is extended, so that this format can represent normalized
1129 values in the range of @math{2^{-14}} to 131008.
1131 The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
1132 not require use of the @option{-mfp16-format} command-line option.
1134 The @code{__fp16} type may only be used as an argument to intrinsics defined
1135 in @code{<arm_fp16.h>}, or as a storage format. For purposes of
1136 arithmetic and other operations, @code{__fp16} values in C or C++
1137 expressions are automatically promoted to @code{float}.
1139 The ARM target provides hardware support for conversions between
1140 @code{__fp16} and @code{float} values
1141 as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
1142 hardware support for conversions between @code{__fp16} and @code{double}
1143 values. GCC generates code using these hardware instructions if you
1144 compile with options to select an FPU that provides them;
1145 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
1146 in addition to the @option{-mfp16-format} option to select
1147 a half-precision format.
1149 Language-level support for the @code{__fp16} data type is
1150 independent of whether GCC generates code using hardware floating-point
1151 instructions. In cases where hardware support is not specified, GCC
1152 implements conversions between @code{__fp16} and other types as library
1155 It is recommended that portable code use the @code{_Float16} type defined
1156 by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
1158 On x86 targets with SSE2 enabled, without @option{-mavx512fp16},
1159 all operations will be emulated by software emulation and the @code{float}
1160 instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the
1161 intermediate result of the operation as 32-bit precision. This may lead to
1162 inconsistent behavior between software emulation and AVX512-FP16 instructions.
1163 Using @option{-fexcess-precision=16} will force round back after each operation.
1165 Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of
1166 software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round
1167 after each operation. The same is true with @option{-fexcess-precision=standard}
1168 and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse},
1169 @option{-fexcess-precision=standard} alone does the same thing as before,
1170 It is useful for code that does not have @code{_Float16} and runs on the x87
1174 @section Decimal Floating Types
1175 @cindex decimal floating types
1176 @cindex @code{_Decimal32} data type
1177 @cindex @code{_Decimal64} data type
1178 @cindex @code{_Decimal128} data type
1179 @cindex @code{df} integer suffix
1180 @cindex @code{dd} integer suffix
1181 @cindex @code{dl} integer suffix
1182 @cindex @code{DF} integer suffix
1183 @cindex @code{DD} integer suffix
1184 @cindex @code{DL} integer suffix
1186 As an extension, GNU C supports decimal floating types as
1187 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
1188 floating types in GCC will evolve as the draft technical report changes.
1189 Calling conventions for any target might also change. Not all targets
1190 support decimal floating types.
1192 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
1193 @code{_Decimal128}. They use a radix of ten, unlike the floating types
1194 @code{float}, @code{double}, and @code{long double} whose radix is not
1195 specified by the C standard but is usually two.
1197 Support for decimal floating types includes the arithmetic operators
1198 add, subtract, multiply, divide; unary arithmetic operators;
1199 relational operators; equality operators; and conversions to and from
1200 integer and other floating types. Use a suffix @samp{df} or
1201 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1202 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1205 GCC support of decimal float as specified by the draft technical report
1210 When the value of a decimal floating type cannot be represented in the
1211 integer type to which it is being converted, the result is undefined
1212 rather than the result value specified by the draft technical report.
1215 GCC does not provide the C library functionality associated with
1216 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1217 @file{wchar.h}, which must come from a separate C library implementation.
1218 Because of this the GNU C compiler does not define macro
1219 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1220 the technical report.
1223 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1224 are supported by the DWARF debug information format.
1230 ISO C99 and ISO C++17 support floating-point numbers written not only in
1231 the usual decimal notation, such as @code{1.55e1}, but also numbers such as
1232 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
1233 supports this in C90 mode (except in some cases when strictly
1234 conforming) and in C++98, C++11 and C++14 modes. In that format the
1235 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1236 mandatory. The exponent is a decimal number that indicates the power of
1237 2 by which the significant part is multiplied. Thus @samp{0x1.f} is
1244 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1245 is the same as @code{1.55e1}.
1247 Unlike for floating-point numbers in the decimal notation the exponent
1248 is always required in the hexadecimal notation. Otherwise the compiler
1249 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
1250 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1251 extension for floating-point constants of type @code{float}.
1254 @section Fixed-Point Types
1255 @cindex fixed-point types
1256 @cindex @code{_Fract} data type
1257 @cindex @code{_Accum} data type
1258 @cindex @code{_Sat} data type
1259 @cindex @code{hr} fixed-suffix
1260 @cindex @code{r} fixed-suffix
1261 @cindex @code{lr} fixed-suffix
1262 @cindex @code{llr} fixed-suffix
1263 @cindex @code{uhr} fixed-suffix
1264 @cindex @code{ur} fixed-suffix
1265 @cindex @code{ulr} fixed-suffix
1266 @cindex @code{ullr} fixed-suffix
1267 @cindex @code{hk} fixed-suffix
1268 @cindex @code{k} fixed-suffix
1269 @cindex @code{lk} fixed-suffix
1270 @cindex @code{llk} fixed-suffix
1271 @cindex @code{uhk} fixed-suffix
1272 @cindex @code{uk} fixed-suffix
1273 @cindex @code{ulk} fixed-suffix
1274 @cindex @code{ullk} fixed-suffix
1275 @cindex @code{HR} fixed-suffix
1276 @cindex @code{R} fixed-suffix
1277 @cindex @code{LR} fixed-suffix
1278 @cindex @code{LLR} fixed-suffix
1279 @cindex @code{UHR} fixed-suffix
1280 @cindex @code{UR} fixed-suffix
1281 @cindex @code{ULR} fixed-suffix
1282 @cindex @code{ULLR} fixed-suffix
1283 @cindex @code{HK} fixed-suffix
1284 @cindex @code{K} fixed-suffix
1285 @cindex @code{LK} fixed-suffix
1286 @cindex @code{LLK} fixed-suffix
1287 @cindex @code{UHK} fixed-suffix
1288 @cindex @code{UK} fixed-suffix
1289 @cindex @code{ULK} fixed-suffix
1290 @cindex @code{ULLK} fixed-suffix
1292 As an extension, GNU C supports fixed-point types as
1293 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
1294 types in GCC will evolve as the draft technical report changes.
1295 Calling conventions for any target might also change. Not all targets
1296 support fixed-point types.
1298 The fixed-point types are
1299 @code{short _Fract},
1302 @code{long long _Fract},
1303 @code{unsigned short _Fract},
1304 @code{unsigned _Fract},
1305 @code{unsigned long _Fract},
1306 @code{unsigned long long _Fract},
1307 @code{_Sat short _Fract},
1309 @code{_Sat long _Fract},
1310 @code{_Sat long long _Fract},
1311 @code{_Sat unsigned short _Fract},
1312 @code{_Sat unsigned _Fract},
1313 @code{_Sat unsigned long _Fract},
1314 @code{_Sat unsigned long long _Fract},
1315 @code{short _Accum},
1318 @code{long long _Accum},
1319 @code{unsigned short _Accum},
1320 @code{unsigned _Accum},
1321 @code{unsigned long _Accum},
1322 @code{unsigned long long _Accum},
1323 @code{_Sat short _Accum},
1325 @code{_Sat long _Accum},
1326 @code{_Sat long long _Accum},
1327 @code{_Sat unsigned short _Accum},
1328 @code{_Sat unsigned _Accum},
1329 @code{_Sat unsigned long _Accum},
1330 @code{_Sat unsigned long long _Accum}.
1332 Fixed-point data values contain fractional and optional integral parts.
1333 The format of fixed-point data varies and depends on the target machine.
1335 Support for fixed-point types includes:
1338 prefix and postfix increment and decrement operators (@code{++}, @code{--})
1340 unary arithmetic operators (@code{+}, @code{-}, @code{!})
1342 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1344 binary shift operators (@code{<<}, @code{>>})
1346 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1348 equality operators (@code{==}, @code{!=})
1350 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1351 @code{<<=}, @code{>>=})
1353 conversions to and from integer, floating-point, or fixed-point types
1356 Use a suffix in a fixed-point literal constant:
1358 @item @samp{hr} or @samp{HR} for @code{short _Fract} and
1359 @code{_Sat short _Fract}
1360 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1361 @item @samp{lr} or @samp{LR} for @code{long _Fract} and
1362 @code{_Sat long _Fract}
1363 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1364 @code{_Sat long long _Fract}
1365 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1366 @code{_Sat unsigned short _Fract}
1367 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1368 @code{_Sat unsigned _Fract}
1369 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1370 @code{_Sat unsigned long _Fract}
1371 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1372 and @code{_Sat unsigned long long _Fract}
1373 @item @samp{hk} or @samp{HK} for @code{short _Accum} and
1374 @code{_Sat short _Accum}
1375 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1376 @item @samp{lk} or @samp{LK} for @code{long _Accum} and
1377 @code{_Sat long _Accum}
1378 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1379 @code{_Sat long long _Accum}
1380 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1381 @code{_Sat unsigned short _Accum}
1382 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1383 @code{_Sat unsigned _Accum}
1384 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1385 @code{_Sat unsigned long _Accum}
1386 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1387 and @code{_Sat unsigned long long _Accum}
1390 GCC support of fixed-point types as specified by the draft technical report
1395 Pragmas to control overflow and rounding behaviors are not implemented.
1398 Fixed-point types are supported by the DWARF debug information format.
1400 @node Named Address Spaces
1401 @section Named Address Spaces
1402 @cindex Named Address Spaces
1404 As an extension, GNU C supports named address spaces as
1405 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
1406 address spaces in GCC will evolve as the draft technical report
1407 changes. Calling conventions for any target might also change. At
1408 present, only the AVR, M32C, PRU, RL78, and x86 targets support
1409 address spaces other than the generic address space.
1411 Address space identifiers may be used exactly like any other C type
1412 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1413 document for more details.
1415 @anchor{AVR Named Address Spaces}
1416 @subsection AVR Named Address Spaces
1418 On the AVR target, there are several address spaces that can be used
1419 in order to put read-only data into the flash memory and access that
1420 data by means of the special instructions @code{LPM} or @code{ELPM}
1421 needed to read from flash.
1423 Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
1424 flash memory by means of @code{LD*} instructions because the flash
1425 memory is mapped into the RAM address space. There is @emph{no need}
1426 for language extensions like @code{__flash} or attribute
1427 @ref{AVR Variable Attributes,,@code{progmem}}.
1428 The default linker description files for these devices cater for that
1429 feature and @code{.rodata} stays in flash: The compiler just generates
1430 @code{LD*} instructions, and the linker script adds core specific
1431 offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
1432 @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
1433 See @ref{AVR Options} for a list of respective devices.
1435 For devices not in @code{avrtiny} or @code{avrxmega3},
1436 any data including read-only data is located in RAM (the generic
1437 address space) because flash memory is not visible in the RAM address
1438 space. In order to locate read-only data in flash memory @emph{and}
1439 to generate the right instructions to access this data without
1440 using (inline) assembler code, special address spaces are needed.
1444 @cindex @code{__flash} AVR Named Address Spaces
1445 The @code{__flash} qualifier locates data in the
1446 @code{.progmem.data} section. Data is read using the @code{LPM}
1447 instruction. Pointers to this address space are 16 bits wide.
1454 @cindex @code{__flash1} AVR Named Address Spaces
1455 @cindex @code{__flash2} AVR Named Address Spaces
1456 @cindex @code{__flash3} AVR Named Address Spaces
1457 @cindex @code{__flash4} AVR Named Address Spaces
1458 @cindex @code{__flash5} AVR Named Address Spaces
1459 These are 16-bit address spaces locating data in section
1460 @code{.progmem@var{N}.data} where @var{N} refers to
1461 address space @code{__flash@var{N}}.
1462 The compiler sets the @code{RAMPZ} segment register appropriately
1463 before reading data by means of the @code{ELPM} instruction.
1466 @cindex @code{__memx} AVR Named Address Spaces
1467 This is a 24-bit address space that linearizes flash and RAM:
1468 If the high bit of the address is set, data is read from
1469 RAM using the lower two bytes as RAM address.
1470 If the high bit of the address is clear, data is read from flash
1471 with @code{RAMPZ} set according to the high byte of the address.
1472 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1474 Objects in this address space are located in @code{.progmemx.data}.
1480 char my_read (const __flash char ** p)
1482 /* p is a pointer to RAM that points to a pointer to flash.
1483 The first indirection of p reads that flash pointer
1484 from RAM and the second indirection reads a char from this
1490 /* Locate array[] in flash memory */
1491 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1497 /* Return 17 by reading from flash memory */
1498 return array[array[i]];
1503 For each named address space supported by avr-gcc there is an equally
1504 named but uppercase built-in macro defined.
1505 The purpose is to facilitate testing if respective address space
1506 support is available or not:
1510 const __flash int var = 1;
1517 #include <avr/pgmspace.h> /* From AVR-LibC */
1519 const int var PROGMEM = 1;
1523 return (int) pgm_read_word (&var);
1525 #endif /* __FLASH */
1529 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1530 locates data in flash but
1531 accesses to these data read from generic address space, i.e.@:
1533 so that you need special accessors like @code{pgm_read_byte}
1534 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1535 together with attribute @code{progmem}.
1538 @b{Limitations and caveats}
1542 Reading across the 64@tie{}KiB section boundary of
1543 the @code{__flash} or @code{__flash@var{N}} address spaces
1544 shows undefined behavior. The only address space that
1545 supports reading across the 64@tie{}KiB flash segment boundaries is
1549 If you use one of the @code{__flash@var{N}} address spaces
1550 you must arrange your linker script to locate the
1551 @code{.progmem@var{N}.data} sections according to your needs.
1554 Any data or pointers to the non-generic address spaces must
1555 be qualified as @code{const}, i.e.@: as read-only data.
1556 This still applies if the data in one of these address
1557 spaces like software version number or calibration lookup table are intended to
1558 be changed after load time by, say, a boot loader. In this case
1559 the right qualification is @code{const} @code{volatile} so that the compiler
1560 must not optimize away known values or insert them
1561 as immediates into operands of instructions.
1564 The following code initializes a variable @code{pfoo}
1565 located in static storage with a 24-bit address:
1567 extern const __memx char foo;
1568 const __memx void *pfoo = &foo;
1572 On the reduced Tiny devices like ATtiny40, no address spaces are supported.
1573 Just use vanilla C / C++ code without overhead as outlined above.
1574 Attribute @code{progmem} is supported but works differently,
1575 see @ref{AVR Variable Attributes}.
1579 @subsection M32C Named Address Spaces
1580 @cindex @code{__far} M32C Named Address Spaces
1582 On the M32C target, with the R8C and M16C CPU variants, variables
1583 qualified with @code{__far} are accessed using 32-bit addresses in
1584 order to access memory beyond the first 64@tie{}Ki bytes. If
1585 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1588 @subsection PRU Named Address Spaces
1589 @cindex @code{__regio_symbol} PRU Named Address Spaces
1591 On the PRU target, variables qualified with @code{__regio_symbol} are
1592 aliases used to access the special I/O CPU registers. They must be
1593 declared as @code{extern} because such variables will not be allocated in
1594 any data memory. They must also be marked as @code{volatile}, and can
1595 only be 32-bit integer types. The only names those variables can have
1596 are @code{__R30} and @code{__R31}, representing respectively the
1597 @code{R30} and @code{R31} special I/O CPU registers. Hence the following
1598 example is the only valid usage of @code{__regio_symbol}:
1601 extern volatile __regio_symbol uint32_t __R30;
1602 extern volatile __regio_symbol uint32_t __R31;
1605 @subsection RL78 Named Address Spaces
1606 @cindex @code{__far} RL78 Named Address Spaces
1608 On the RL78 target, variables qualified with @code{__far} are accessed
1609 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1610 addresses. Non-far variables are assumed to appear in the topmost
1611 64@tie{}KiB of the address space.
1613 @subsection x86 Named Address Spaces
1614 @cindex x86 named address spaces
1616 On the x86 target, variables may be declared as being relative
1617 to the @code{%fs} or @code{%gs} segments.
1622 @cindex @code{__seg_fs} x86 named address space
1623 @cindex @code{__seg_gs} x86 named address space
1624 The object is accessed with the respective segment override prefix.
1626 The respective segment base must be set via some method specific to
1627 the operating system. Rather than require an expensive system call
1628 to retrieve the segment base, these address spaces are not considered
1629 to be subspaces of the generic (flat) address space. This means that
1630 explicit casts are required to convert pointers between these address
1631 spaces and the generic address space. In practice the application
1632 should cast to @code{uintptr_t} and apply the segment base offset
1633 that it installed previously.
1635 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1636 defined when these address spaces are supported.
1640 @section Arrays of Length Zero
1641 @cindex arrays of length zero
1642 @cindex zero-length arrays
1643 @cindex length-zero arrays
1644 @cindex flexible array members
1646 Declaring zero-length arrays is allowed in GNU C as an extension.
1647 A zero-length array can be useful as the last element of a structure
1648 that is really a header for a variable-length object:
1656 struct line *thisline = (struct line *)
1657 malloc (sizeof (struct line) + this_length);
1658 thisline->length = this_length;
1661 Although the size of a zero-length array is zero, an array member of
1662 this kind may increase the size of the enclosing type as a result of tail
1663 padding. The offset of a zero-length array member from the beginning
1664 of the enclosing structure is the same as the offset of an array with
1665 one or more elements of the same type. The alignment of a zero-length
1666 array is the same as the alignment of its elements.
1668 Declaring zero-length arrays in other contexts, including as interior
1669 members of structure objects or as non-member objects, is discouraged.
1670 Accessing elements of zero-length arrays declared in such contexts is
1671 undefined and may be diagnosed.
1673 In the absence of the zero-length array extension, in ISO C90
1674 the @code{contents} array in the example above would typically be declared
1675 to have a single element. Unlike a zero-length array which only contributes
1676 to the size of the enclosing structure for the purposes of alignment,
1677 a one-element array always occupies at least as much space as a single
1678 object of the type. Although using one-element arrays this way is
1679 discouraged, GCC handles accesses to trailing one-element array members
1680 analogously to zero-length arrays.
1682 The preferred mechanism to declare variable-length types like
1683 @code{struct line} above is the ISO C99 @dfn{flexible array member},
1684 with slightly different syntax and semantics:
1688 Flexible array members are written as @code{contents[]} without
1692 Flexible array members have incomplete type, and so the @code{sizeof}
1693 operator may not be applied. As a quirk of the original implementation
1694 of zero-length arrays, @code{sizeof} evaluates to zero.
1697 Flexible array members may only appear as the last member of a
1698 @code{struct} that is otherwise non-empty.
1701 A structure containing a flexible array member, or a union containing
1702 such a structure (possibly recursively), may not be a member of a
1703 structure or an element of an array. (However, these uses are
1704 permitted by GCC as extensions.)
1707 Non-empty initialization of zero-length
1708 arrays is treated like any case where there are more initializer
1709 elements than the array holds, in that a suitable warning about ``excess
1710 elements in array'' is given, and the excess elements (all of them, in
1711 this case) are ignored.
1713 GCC allows static initialization of flexible array members.
1714 This is equivalent to defining a new structure containing the original
1715 structure followed by an array of sufficient size to contain the data.
1716 E.g.@: in the following, @code{f1} is constructed as if it were declared
1722 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1725 struct f1 f1; int data[3];
1726 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1730 The convenience of this extension is that @code{f1} has the desired
1731 type, eliminating the need to consistently refer to @code{f2.f1}.
1733 This has symmetry with normal static arrays, in that an array of
1734 unknown size is also written with @code{[]}.
1736 Of course, this extension only makes sense if the extra data comes at
1737 the end of a top-level object, as otherwise we would be overwriting
1738 data at subsequent offsets. To avoid undue complication and confusion
1739 with initialization of deeply nested arrays, we simply disallow any
1740 non-empty initialization except when the structure is the top-level
1741 object. For example:
1744 struct foo @{ int x; int y[]; @};
1745 struct bar @{ struct foo z; @};
1747 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1748 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1749 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1750 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1753 @node Empty Structures
1754 @section Structures with No Members
1755 @cindex empty structures
1756 @cindex zero-size structures
1758 GCC permits a C structure to have no members:
1765 The structure has size zero. In C++, empty structures are part
1766 of the language. G++ treats empty structures as if they had a single
1767 member of type @code{char}.
1769 @node Variable Length
1770 @section Arrays of Variable Length
1771 @cindex variable-length arrays
1772 @cindex arrays of variable length
1775 Variable-length automatic arrays are allowed in ISO C99, and as an
1776 extension GCC accepts them in C90 mode and in C++. These arrays are
1777 declared like any other automatic arrays, but with a length that is not
1778 a constant expression. The storage is allocated at the point of
1779 declaration and deallocated when the block scope containing the declaration
1785 concat_fopen (char *s1, char *s2, char *mode)
1787 char str[strlen (s1) + strlen (s2) + 1];
1790 return fopen (str, mode);
1794 @cindex scope of a variable length array
1795 @cindex variable-length array scope
1796 @cindex deallocating variable length arrays
1797 Jumping or breaking out of the scope of the array name deallocates the
1798 storage. Jumping into the scope is not allowed; you get an error
1801 @cindex variable-length array in a structure
1802 As an extension, GCC accepts variable-length arrays as a member of
1803 a structure or a union. For example:
1809 struct S @{ int x[n]; @};
1813 @cindex @code{alloca} vs variable-length arrays
1814 You can use the function @code{alloca} to get an effect much like
1815 variable-length arrays. The function @code{alloca} is available in
1816 many other C implementations (but not in all). On the other hand,
1817 variable-length arrays are more elegant.
1819 There are other differences between these two methods. Space allocated
1820 with @code{alloca} exists until the containing @emph{function} returns.
1821 The space for a variable-length array is deallocated as soon as the array
1822 name's scope ends, unless you also use @code{alloca} in this scope.
1824 You can also use variable-length arrays as arguments to functions:
1828 tester (int len, char data[len][len])
1834 The length of an array is computed once when the storage is allocated
1835 and is remembered for the scope of the array in case you access it with
1838 If you want to pass the array first and the length afterward, you can
1839 use a forward declaration in the parameter list---another GNU extension.
1843 tester (int len; char data[len][len], int len)
1849 @cindex parameter forward declaration
1850 The @samp{int len} before the semicolon is a @dfn{parameter forward
1851 declaration}, and it serves the purpose of making the name @code{len}
1852 known when the declaration of @code{data} is parsed.
1854 You can write any number of such parameter forward declarations in the
1855 parameter list. They can be separated by commas or semicolons, but the
1856 last one must end with a semicolon, which is followed by the ``real''
1857 parameter declarations. Each forward declaration must match a ``real''
1858 declaration in parameter name and data type. ISO C99 does not support
1859 parameter forward declarations.
1861 @node Variadic Macros
1862 @section Macros with a Variable Number of Arguments.
1863 @cindex variable number of arguments
1864 @cindex macro with variable arguments
1865 @cindex rest argument (in macro)
1866 @cindex variadic macros
1868 In the ISO C standard of 1999, a macro can be declared to accept a
1869 variable number of arguments much as a function can. The syntax for
1870 defining the macro is similar to that of a function. Here is an
1874 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1878 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1879 such a macro, it represents the zero or more tokens until the closing
1880 parenthesis that ends the invocation, including any commas. This set of
1881 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1882 wherever it appears. See the CPP manual for more information.
1884 GCC has long supported variadic macros, and used a different syntax that
1885 allowed you to give a name to the variable arguments just like any other
1886 argument. Here is an example:
1889 #define debug(format, args...) fprintf (stderr, format, args)
1893 This is in all ways equivalent to the ISO C example above, but arguably
1894 more readable and descriptive.
1896 GNU CPP has two further variadic macro extensions, and permits them to
1897 be used with either of the above forms of macro definition.
1899 In standard C, you are not allowed to leave the variable argument out
1900 entirely; but you are allowed to pass an empty argument. For example,
1901 this invocation is invalid in ISO C, because there is no comma after
1908 GNU CPP permits you to completely omit the variable arguments in this
1909 way. In the above examples, the compiler would complain, though since
1910 the expansion of the macro still has the extra comma after the format
1913 To help solve this problem, CPP behaves specially for variable arguments
1914 used with the token paste operator, @samp{##}. If instead you write
1917 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1921 and if the variable arguments are omitted or empty, the @samp{##}
1922 operator causes the preprocessor to remove the comma before it. If you
1923 do provide some variable arguments in your macro invocation, GNU CPP
1924 does not complain about the paste operation and instead places the
1925 variable arguments after the comma. Just like any other pasted macro
1926 argument, these arguments are not macro expanded.
1928 @node Escaped Newlines
1929 @section Slightly Looser Rules for Escaped Newlines
1930 @cindex escaped newlines
1931 @cindex newlines (escaped)
1933 The preprocessor treatment of escaped newlines is more relaxed
1934 than that specified by the C90 standard, which requires the newline
1935 to immediately follow a backslash.
1936 GCC's implementation allows whitespace in the form
1937 of spaces, horizontal and vertical tabs, and form feeds between the
1938 backslash and the subsequent newline. The preprocessor issues a
1939 warning, but treats it as a valid escaped newline and combines the two
1940 lines to form a single logical line. This works within comments and
1941 tokens, as well as between tokens. Comments are @emph{not} treated as
1942 whitespace for the purposes of this relaxation, since they have not
1943 yet been replaced with spaces.
1946 @section Non-Lvalue Arrays May Have Subscripts
1947 @cindex subscripting
1948 @cindex arrays, non-lvalue
1950 @cindex subscripting and function values
1951 In ISO C99, arrays that are not lvalues still decay to pointers, and
1952 may be subscripted, although they may not be modified or used after
1953 the next sequence point and the unary @samp{&} operator may not be
1954 applied to them. As an extension, GNU C allows such arrays to be
1955 subscripted in C90 mode, though otherwise they do not decay to
1956 pointers outside C99 mode. For example,
1957 this is valid in GNU C though not valid in C90:
1961 struct foo @{int a[4];@};
1967 return f().a[index];
1973 @section Arithmetic on @code{void}- and Function-Pointers
1974 @cindex void pointers, arithmetic
1975 @cindex void, size of pointer to
1976 @cindex function pointers, arithmetic
1977 @cindex function, size of pointer to
1979 In GNU C, addition and subtraction operations are supported on pointers to
1980 @code{void} and on pointers to functions. This is done by treating the
1981 size of a @code{void} or of a function as 1.
1983 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1984 and on function types, and returns 1.
1986 @opindex Wpointer-arith
1987 The option @option{-Wpointer-arith} requests a warning if these extensions
1990 @node Variadic Pointer Args
1991 @section Pointer Arguments in Variadic Functions
1992 @cindex pointer arguments in variadic functions
1993 @cindex variadic functions, pointer arguments
1995 Standard C requires that pointer types used with @code{va_arg} in
1996 functions with variable argument lists either must be compatible with
1997 that of the actual argument, or that one type must be a pointer to
1998 @code{void} and the other a pointer to a character type. GNU C
1999 implements the POSIX XSI extension that additionally permits the use
2000 of @code{va_arg} with a pointer type to receive arguments of any other
2003 In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
2004 to consume an argument of any pointer type.
2006 @node Pointers to Arrays
2007 @section Pointers to Arrays with Qualifiers Work as Expected
2008 @cindex pointers to arrays
2009 @cindex const qualifier
2011 In GNU C, pointers to arrays with qualifiers work similar to pointers
2012 to other qualified types. For example, a value of type @code{int (*)[5]}
2013 can be used to initialize a variable of type @code{const int (*)[5]}.
2014 These types are incompatible in ISO C because the @code{const} qualifier
2015 is formally attached to the element type of the array and not the
2020 transpose (int N, int M, double out[M][N], const double in[N][M]);
2024 transpose(3, 2, y, x);
2028 @section Non-Constant Initializers
2029 @cindex initializers, non-constant
2030 @cindex non-constant initializers
2032 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
2033 automatic variable are not required to be constant expressions in GNU C@.
2034 Here is an example of an initializer with run-time varying elements:
2037 foo (float f, float g)
2039 float beat_freqs[2] = @{ f-g, f+g @};
2044 @node Compound Literals
2045 @section Compound Literals
2046 @cindex constructor expressions
2047 @cindex initializations in expressions
2048 @cindex structures, constructor expression
2049 @cindex expressions, constructor
2050 @cindex compound literals
2051 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
2053 A compound literal looks like a cast of a brace-enclosed aggregate
2054 initializer list. Its value is an object of the type specified in
2055 the cast, containing the elements specified in the initializer.
2056 Unlike the result of a cast, a compound literal is an lvalue. ISO
2057 C99 and later support compound literals. As an extension, GCC
2058 supports compound literals also in C90 mode and in C++, although
2059 as explained below, the C++ semantics are somewhat different.
2061 Usually, the specified type of a compound literal is a structure. Assume
2062 that @code{struct foo} and @code{structure} are declared as shown:
2065 struct foo @{int a; char b[2];@} structure;
2069 Here is an example of constructing a @code{struct foo} with a compound literal:
2072 structure = ((struct foo) @{x + y, 'a', 0@});
2076 This is equivalent to writing the following:
2080 struct foo temp = @{x + y, 'a', 0@};
2085 You can also construct an array, though this is dangerous in C++, as
2086 explained below. If all the elements of the compound literal are
2087 (made up of) simple constant expressions suitable for use in
2088 initializers of objects of static storage duration, then the compound
2089 literal can be coerced to a pointer to its first element and used in
2090 such an initializer, as shown here:
2093 char **foo = (char *[]) @{ "x", "y", "z" @};
2096 Compound literals for scalar types and union types are also allowed. In
2097 the following example the variable @code{i} is initialized to the value
2098 @code{2}, the result of incrementing the unnamed object created by
2099 the compound literal.
2102 int i = ++(int) @{ 1 @};
2105 As a GNU extension, GCC allows initialization of objects with static storage
2106 duration by compound literals (which is not possible in ISO C99 because
2107 the initializer is not a constant).
2108 It is handled as if the object were initialized only with the brace-enclosed
2109 list if the types of the compound literal and the object match.
2110 The elements of the compound literal must be constant.
2111 If the object being initialized has array type of unknown size, the size is
2112 determined by the size of the compound literal.
2115 static struct foo x = (struct foo) @{1, 'a', 'b'@};
2116 static int y[] = (int []) @{1, 2, 3@};
2117 static int z[] = (int [3]) @{1@};
2121 The above lines are equivalent to the following:
2123 static struct foo x = @{1, 'a', 'b'@};
2124 static int y[] = @{1, 2, 3@};
2125 static int z[] = @{1, 0, 0@};
2128 In C, a compound literal designates an unnamed object with static or
2129 automatic storage duration. In C++, a compound literal designates a
2130 temporary object that only lives until the end of its full-expression.
2131 As a result, well-defined C code that takes the address of a subobject
2132 of a compound literal can be undefined in C++, so G++ rejects
2133 the conversion of a temporary array to a pointer. For instance, if
2134 the array compound literal example above appeared inside a function,
2135 any subsequent use of @code{foo} in C++ would have undefined behavior
2136 because the lifetime of the array ends after the declaration of @code{foo}.
2138 As an optimization, G++ sometimes gives array compound literals longer
2139 lifetimes: when the array either appears outside a function or has
2140 a @code{const}-qualified type. If @code{foo} and its initializer had
2141 elements of type @code{char *const} rather than @code{char *}, or if
2142 @code{foo} were a global variable, the array would have static storage
2143 duration. But it is probably safest just to avoid the use of array
2144 compound literals in C++ code.
2146 @node Designated Inits
2147 @section Designated Initializers
2148 @cindex initializers with labeled elements
2149 @cindex labeled elements in initializers
2150 @cindex case labels in initializers
2151 @cindex designated initializers
2153 Standard C90 requires the elements of an initializer to appear in a fixed
2154 order, the same as the order of the elements in the array or structure
2157 In ISO C99 you can give the elements in any order, specifying the array
2158 indices or structure field names they apply to, and GNU C allows this as
2159 an extension in C90 mode as well. This extension is not
2160 implemented in GNU C++.
2162 To specify an array index, write
2163 @samp{[@var{index}] =} before the element value. For example,
2166 int a[6] = @{ [4] = 29, [2] = 15 @};
2173 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
2177 The index values must be constant expressions, even if the array being
2178 initialized is automatic.
2180 An alternative syntax for this that has been obsolete since GCC 2.5 but
2181 GCC still accepts is to write @samp{[@var{index}]} before the element
2182 value, with no @samp{=}.
2184 To initialize a range of elements to the same value, write
2185 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2186 extension. For example,
2189 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2193 If the value in it has side effects, the side effects happen only once,
2194 not for each initialized field by the range initializer.
2197 Note that the length of the array is the highest value specified
2200 In a structure initializer, specify the name of a field to initialize
2201 with @samp{.@var{fieldname} =} before the element value. For example,
2202 given the following structure,
2205 struct point @{ int x, y; @};
2209 the following initialization
2212 struct point p = @{ .y = yvalue, .x = xvalue @};
2219 struct point p = @{ xvalue, yvalue @};
2222 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2223 @samp{@var{fieldname}:}, as shown here:
2226 struct point p = @{ y: yvalue, x: xvalue @};
2229 Omitted fields are implicitly initialized the same as for objects
2230 that have static storage duration.
2233 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2234 @dfn{designator}. You can also use a designator (or the obsolete colon
2235 syntax) when initializing a union, to specify which element of the union
2236 should be used. For example,
2239 union foo @{ int i; double d; @};
2241 union foo f = @{ .d = 4 @};
2245 converts 4 to a @code{double} to store it in the union using
2246 the second element. By contrast, casting 4 to type @code{union foo}
2247 stores it into the union as the integer @code{i}, since it is
2248 an integer. @xref{Cast to Union}.
2250 You can combine this technique of naming elements with ordinary C
2251 initialization of successive elements. Each initializer element that
2252 does not have a designator applies to the next consecutive element of the
2253 array or structure. For example,
2256 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2263 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2266 Labeling the elements of an array initializer is especially useful
2267 when the indices are characters or belong to an @code{enum} type.
2272 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2273 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2276 @cindex designator lists
2277 You can also write a series of @samp{.@var{fieldname}} and
2278 @samp{[@var{index}]} designators before an @samp{=} to specify a
2279 nested subobject to initialize; the list is taken relative to the
2280 subobject corresponding to the closest surrounding brace pair. For
2281 example, with the @samp{struct point} declaration above:
2284 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2287 If the same field is initialized multiple times, or overlapping
2288 fields of a union are initialized, the value from the last
2289 initialization is used. When a field of a union is itself a structure,
2290 the entire structure from the last field initialized is used. If any previous
2291 initializer has side effect, it is unspecified whether the side effect
2292 happens or not. Currently, GCC discards the side-effecting
2293 initializer expressions and issues a warning.
2296 @section Case Ranges
2298 @cindex ranges in case statements
2300 You can specify a range of consecutive values in a single @code{case} label,
2304 case @var{low} ... @var{high}:
2308 This has the same effect as the proper number of individual @code{case}
2309 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2311 This feature is especially useful for ranges of ASCII character codes:
2317 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2318 it may be parsed wrong when you use it with integer values. For example,
2333 @section Cast to a Union Type
2334 @cindex cast to a union
2335 @cindex union, casting to a
2337 A cast to a union type is a C extension not available in C++. It looks
2338 just like ordinary casts with the constraint that the type specified is
2339 a union type. You can specify the type either with the @code{union}
2340 keyword or with a @code{typedef} name that refers to a union. The result
2341 of a cast to a union is a temporary rvalue of the union type with a member
2342 whose type matches that of the operand initialized to the value of
2343 the operand. The effect of a cast to a union is similar to a compound
2344 literal except that it yields an rvalue like standard casts do.
2345 @xref{Compound Literals}.
2347 Expressions that may be cast to the union type are those whose type matches
2348 at least one of the members of the union. Thus, given the following union
2352 union foo @{ int i; double d; @};
2359 both @code{x} and @code{y} can be cast to type @code{union foo} and
2360 the following assignments
2365 are shorthand equivalents of these
2367 z = (union foo) @{ .i = x @};
2368 z = (union foo) @{ .d = y @};
2371 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
2372 has no member of type @code{float}.
2374 Using the cast as the right-hand side of an assignment to a variable of
2375 union type is equivalent to storing in a member of the union with
2381 u = (union foo) x @equiv{} u.i = x
2382 u = (union foo) y @equiv{} u.d = y
2385 You can also use the union cast as a function argument:
2388 void hack (union foo);
2390 hack ((union foo) x);
2393 @node Mixed Labels and Declarations
2394 @section Mixed Declarations, Labels and Code
2395 @cindex mixed declarations and code
2396 @cindex declarations, mixed with code
2397 @cindex code, mixed with declarations
2399 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2400 within compound statements. ISO C2X allows labels to be
2401 placed before declarations and at the end of a compound statement.
2402 As an extension, GNU C also allows all this in C90 mode. For example,
2412 Each identifier is visible from where it is declared until the end of
2413 the enclosing block.
2415 @node Function Attributes
2416 @section Declaring Attributes of Functions
2417 @cindex function attributes
2418 @cindex declaring attributes of functions
2419 @cindex @code{volatile} applied to function
2420 @cindex @code{const} applied to function
2422 In GNU C and C++, you can use function attributes to specify certain
2423 function properties that may help the compiler optimize calls or
2424 check code more carefully for correctness. For example, you
2425 can use attributes to specify that a function never returns
2426 (@code{noreturn}), returns a value depending only on the values of
2427 its arguments (@code{const}), or has @code{printf}-style arguments
2430 You can also use attributes to control memory placement, code
2431 generation options or call/return conventions within the function
2432 being annotated. Many of these attributes are target-specific. For
2433 example, many targets support attributes for defining interrupt
2434 handler functions, which typically must follow special register usage
2435 and return conventions. Such attributes are described in the subsection
2436 for each target. However, a considerable number of attributes are
2437 supported by most, if not all targets. Those are described in
2438 the @ref{Common Function Attributes} section.
2440 Function attributes are introduced by the @code{__attribute__} keyword
2441 in the declaration of a function, followed by an attribute specification
2442 enclosed in double parentheses. You can specify multiple attributes in
2443 a declaration by separating them by commas within the double parentheses
2444 or by immediately following one attribute specification with another.
2445 @xref{Attribute Syntax}, for the exact rules on attribute syntax and
2446 placement. Compatible attribute specifications on distinct declarations
2447 of the same function are merged. An attribute specification that is not
2448 compatible with attributes already applied to a declaration of the same
2449 function is ignored with a warning.
2451 Some function attributes take one or more arguments that refer to
2452 the function's parameters by their positions within the function parameter
2453 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2454 Unless specified otherwise, positional arguments that specify properties
2455 of parameters with pointer types can also specify the same properties of
2456 the implicit C++ @code{this} argument in non-static member functions, and
2457 of parameters of reference to a pointer type. For ordinary functions,
2458 position one refers to the first parameter on the list. In C++ non-static
2459 member functions, position one refers to the implicit @code{this} pointer.
2460 The same restrictions and effects apply to function attributes used with
2461 ordinary functions or C++ member functions.
2463 GCC also supports attributes on
2464 variable declarations (@pxref{Variable Attributes}),
2465 labels (@pxref{Label Attributes}),
2466 enumerators (@pxref{Enumerator Attributes}),
2467 statements (@pxref{Statement Attributes}),
2468 and types (@pxref{Type Attributes}).
2470 There is some overlap between the purposes of attributes and pragmas
2471 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2472 found convenient to use @code{__attribute__} to achieve a natural
2473 attachment of attributes to their corresponding declarations, whereas
2474 @code{#pragma} is of use for compatibility with other compilers
2475 or constructs that do not naturally form part of the grammar.
2477 In addition to the attributes documented here,
2478 GCC plugins may provide their own attributes.
2481 * Common Function Attributes::
2482 * AArch64 Function Attributes::
2483 * AMD GCN Function Attributes::
2484 * ARC Function Attributes::
2485 * ARM Function Attributes::
2486 * AVR Function Attributes::
2487 * Blackfin Function Attributes::
2488 * BPF Function Attributes::
2489 * CR16 Function Attributes::
2490 * C-SKY Function Attributes::
2491 * Epiphany Function Attributes::
2492 * H8/300 Function Attributes::
2493 * IA-64 Function Attributes::
2494 * M32C Function Attributes::
2495 * M32R/D Function Attributes::
2496 * m68k Function Attributes::
2497 * MCORE Function Attributes::
2498 * MeP Function Attributes::
2499 * MicroBlaze Function Attributes::
2500 * Microsoft Windows Function Attributes::
2501 * MIPS Function Attributes::
2502 * MSP430 Function Attributes::
2503 * NDS32 Function Attributes::
2504 * Nios II Function Attributes::
2505 * Nvidia PTX Function Attributes::
2506 * PowerPC Function Attributes::
2507 * RISC-V Function Attributes::
2508 * RL78 Function Attributes::
2509 * RX Function Attributes::
2510 * S/390 Function Attributes::
2511 * SH Function Attributes::
2512 * Symbian OS Function Attributes::
2513 * V850 Function Attributes::
2514 * Visium Function Attributes::
2515 * x86 Function Attributes::
2516 * Xstormy16 Function Attributes::
2519 @node Common Function Attributes
2520 @subsection Common Function Attributes
2522 The following attributes are supported on most targets.
2525 @c Keep this table alphabetized by attribute name. Treat _ as space.
2528 @itemx access (@var{access-mode}, @var{ref-index})
2529 @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
2531 The @code{access} attribute enables the detection of invalid or unsafe
2532 accesses by functions to which they apply or their callers, as well as
2533 write-only accesses to objects that are never read from. Such accesses
2534 may be diagnosed by warnings such as @option{-Wstringop-overflow},
2535 @option{-Wuninitialized}, @option{-Wunused}, and others.
2537 The @code{access} attribute specifies that a function to whose by-reference
2538 arguments the attribute applies accesses the referenced object according to
2539 @var{access-mode}. The @var{access-mode} argument is required and must be
2540 one of four names: @code{read_only}, @code{read_write}, @code{write_only},
2541 or @code{none}. The remaining two are positional arguments.
2543 The required @var{ref-index} positional argument denotes a function
2544 argument of pointer (or in C++, reference) type that is subject to
2545 the access. The same pointer argument can be referenced by at most one
2546 distinct @code{access} attribute.
2548 The optional @var{size-index} positional argument denotes a function
2549 argument of integer type that specifies the maximum size of the access.
2550 The size is the number of elements of the type referenced by @var{ref-index},
2551 or the number of bytes when the pointer type is @code{void*}. When no
2552 @var{size-index} argument is specified, the pointer argument must be either
2553 null or point to a space that is suitably aligned and large for at least one
2554 object of the referenced type (this implies that a past-the-end pointer is
2555 not a valid argument). The actual size of the access may be less but it
2558 The @code{read_only} access mode specifies that the pointer to which it
2559 applies is used to read the referenced object but not write to it. Unless
2560 the argument specifying the size of the access denoted by @var{size-index}
2561 is zero, the referenced object must be initialized. The mode implies
2562 a stronger guarantee than the @code{const} qualifier which, when cast away
2563 from a pointer, does not prevent the pointed-to object from being modified.
2564 Examples of the use of the @code{read_only} access mode is the argument to
2565 the @code{puts} function, or the second and third arguments to
2566 the @code{memcpy} function.
2569 __attribute__ ((access (read_only, 1))) int puts (const char*);
2570 __attribute__ ((access (read_only, 2, 3))) void* memcpy (void*, const void*, size_t);
2573 The @code{read_write} access mode applies to arguments of pointer types
2574 without the @code{const} qualifier. It specifies that the pointer to which
2575 it applies is used to both read and write the referenced object. Unless
2576 the argument specifying the size of the access denoted by @var{size-index}
2577 is zero, the object referenced by the pointer must be initialized. An example
2578 of the use of the @code{read_write} access mode is the first argument to
2579 the @code{strcat} function.
2582 __attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*);
2585 The @code{write_only} access mode applies to arguments of pointer types
2586 without the @code{const} qualifier. It specifies that the pointer to which
2587 it applies is used to write to the referenced object but not read from it.
2588 The object referenced by the pointer need not be initialized. An example
2589 of the use of the @code{write_only} access mode is the first argument to
2590 the @code{strcpy} function, or the first two arguments to the @code{fgets}
2594 __attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*);
2595 __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*);
2598 The access mode @code{none} specifies that the pointer to which it applies
2599 is not used to access the referenced object at all. Unless the pointer is
2600 null the pointed-to object must exist and have at least the size as denoted
2601 by the @var{size-index} argument. The object need not be initialized.
2602 The mode is intended to be used as a means to help validate the expected
2603 object size, for example in functions that call @code{__builtin_object_size}.
2604 @xref{Object Size Checking}.
2606 @item alias ("@var{target}")
2607 @cindex @code{alias} function attribute
2608 The @code{alias} attribute causes the declaration to be emitted as an alias
2609 for another symbol, which must have been previously declared with the same
2610 type, and for variables, also the same size and alignment. Declaring an alias
2611 with a different type than the target is undefined and may be diagnosed. As
2612 an example, the following declarations:
2615 void __f () @{ /* @r{Do something.} */; @}
2616 void f () __attribute__ ((weak, alias ("__f")));
2620 define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
2621 for the target must be used. It is an error if @samp{__f} is not defined in
2622 the same translation unit.
2624 This attribute requires assembler and object file support,
2625 and may not be available on all targets.
2628 @itemx aligned (@var{alignment})
2629 @cindex @code{aligned} function attribute
2630 The @code{aligned} attribute specifies a minimum alignment for
2631 the first instruction of the function, measured in bytes. When specified,
2632 @var{alignment} must be an integer constant power of 2. Specifying no
2633 @var{alignment} argument implies the ideal alignment for the target.
2634 The @code{__alignof__} operator can be used to determine what that is
2635 (@pxref{Alignment}). The attribute has no effect when a definition for
2636 the function is not provided in the same translation unit.
2638 The attribute cannot be used to decrease the alignment of a function
2639 previously declared with a more restrictive alignment; only to increase
2640 it. Attempts to do otherwise are diagnosed. Some targets specify
2641 a minimum default alignment for functions that is greater than 1. On
2642 such targets, specifying a less restrictive alignment is silently ignored.
2643 Using the attribute overrides the effect of the @option{-falign-functions}
2644 (@pxref{Optimize Options}) option for this function.
2646 Note that the effectiveness of @code{aligned} attributes may be
2647 limited by inherent limitations in the system linker
2648 and/or object file format. On some systems, the
2649 linker is only able to arrange for functions to be aligned up to a
2650 certain maximum alignment. (For some linkers, the maximum supported
2651 alignment may be very very small.) See your linker documentation for
2652 further information.
2654 The @code{aligned} attribute can also be used for variables and fields
2655 (@pxref{Variable Attributes}.)
2657 @item alloc_align (@var{position})
2658 @cindex @code{alloc_align} function attribute
2659 The @code{alloc_align} attribute may be applied to a function that
2660 returns a pointer and takes at least one argument of an integer or
2662 It indicates that the returned pointer is aligned on a boundary given
2663 by the function argument at @var{position}. Meaningful alignments are
2664 powers of 2 greater than one. GCC uses this information to improve
2665 pointer alignment analysis.
2667 The function parameter denoting the allocated alignment is specified by
2668 one constant integer argument whose number is the argument of the attribute.
2669 Argument numbering starts at one.
2674 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2678 declares that @code{my_memalign} returns memory with minimum alignment
2679 given by parameter 1.
2681 @item alloc_size (@var{position})
2682 @itemx alloc_size (@var{position-1}, @var{position-2})
2683 @cindex @code{alloc_size} function attribute
2684 The @code{alloc_size} attribute may be applied to a function that
2685 returns a pointer and takes at least one argument of an integer or
2687 It indicates that the returned pointer points to memory whose size is
2688 given by the function argument at @var{position-1}, or by the product
2689 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2690 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2691 information to improve the results of @code{__builtin_object_size}.
2693 The function parameter(s) denoting the allocated size are specified by
2694 one or two integer arguments supplied to the attribute. The allocated size
2695 is either the value of the single function argument specified or the product
2696 of the two function arguments specified. Argument numbering starts at
2697 one for ordinary functions, and at two for C++ non-static member functions.
2702 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2703 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2707 declares that @code{my_calloc} returns memory of the size given by
2708 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2709 of the size given by parameter 2.
2712 @cindex @code{always_inline} function attribute
2713 Generally, functions are not inlined unless optimization is specified.
2714 For functions declared inline, this attribute inlines the function
2715 independent of any restrictions that otherwise apply to inlining.
2716 Failure to inline such a function is diagnosed as an error.
2717 Note that if such a function is called indirectly the compiler may
2718 or may not inline it depending on optimization level and a failure
2719 to inline an indirect call may or may not be diagnosed.
2722 @cindex @code{artificial} function attribute
2723 This attribute is useful for small inline wrappers that if possible
2724 should appear during debugging as a unit. Depending on the debug
2725 info format it either means marking the function as artificial
2726 or using the caller location for all instructions within the inlined
2729 @item assume_aligned (@var{alignment})
2730 @itemx assume_aligned (@var{alignment}, @var{offset})
2731 @cindex @code{assume_aligned} function attribute
2732 The @code{assume_aligned} attribute may be applied to a function that
2733 returns a pointer. It indicates that the returned pointer is aligned
2734 on a boundary given by @var{alignment}. If the attribute has two
2735 arguments, the second argument is misalignment @var{offset}. Meaningful
2736 values of @var{alignment} are powers of 2 greater than one. Meaningful
2737 values of @var{offset} are greater than zero and less than @var{alignment}.
2742 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2743 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2747 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2748 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2752 @cindex @code{cold} function attribute
2753 The @code{cold} attribute on functions is used to inform the compiler that
2754 the function is unlikely to be executed. The function is optimized for
2755 size rather than speed and on many targets it is placed into a special
2756 subsection of the text section so all cold functions appear close together,
2757 improving code locality of non-cold parts of program. The paths leading
2758 to calls of cold functions within code are marked as unlikely by the branch
2759 prediction mechanism. It is thus useful to mark functions used to handle
2760 unlikely conditions, such as @code{perror}, as cold to improve optimization
2761 of hot functions that do call marked functions in rare occasions.
2763 When profile feedback is available, via @option{-fprofile-use}, cold functions
2764 are automatically detected and this attribute is ignored.
2767 @cindex @code{const} function attribute
2768 @cindex functions that have no side effects
2769 Calls to functions whose return value is not affected by changes to
2770 the observable state of the program and that have no observable effects
2771 on such state other than to return a value may lend themselves to
2772 optimizations such as common subexpression elimination. Declaring such
2773 functions with the @code{const} attribute allows GCC to avoid emitting
2774 some calls in repeated invocations of the function with the same argument
2780 int square (int) __attribute__ ((const));
2784 tells GCC that subsequent calls to function @code{square} with the same
2785 argument value can be replaced by the result of the first call regardless
2786 of the statements in between.
2788 The @code{const} attribute prohibits a function from reading objects
2789 that affect its return value between successive invocations. However,
2790 functions declared with the attribute can safely read objects that do
2791 not change their return value, such as non-volatile constants.
2793 The @code{const} attribute imposes greater restrictions on a function's
2794 definition than the similar @code{pure} attribute. Declaring the same
2795 function with both the @code{const} and the @code{pure} attribute is
2796 diagnosed. Because a const function cannot have any observable side
2797 effects it does not make sense for it to return @code{void}. Declaring
2798 such a function is diagnosed.
2800 @cindex pointer arguments
2801 Note that a function that has pointer arguments and examines the data
2802 pointed to must @emph{not} be declared @code{const} if the pointed-to
2803 data might change between successive invocations of the function. In
2804 general, since a function cannot distinguish data that might change
2805 from data that cannot, const functions should never take pointer or,
2806 in C++, reference arguments. Likewise, a function that calls a non-const
2807 function usually must not be const itself.
2811 @itemx constructor (@var{priority})
2812 @itemx destructor (@var{priority})
2813 @cindex @code{constructor} function attribute
2814 @cindex @code{destructor} function attribute
2815 The @code{constructor} attribute causes the function to be called
2816 automatically before execution enters @code{main ()}. Similarly, the
2817 @code{destructor} attribute causes the function to be called
2818 automatically after @code{main ()} completes or @code{exit ()} is
2819 called. Functions with these attributes are useful for
2820 initializing data that is used implicitly during the execution of
2823 On some targets the attributes also accept an integer argument to
2824 specify a priority to control the order in which constructor and
2825 destructor functions are run. A constructor
2826 with a smaller priority number runs before a constructor with a larger
2827 priority number; the opposite relationship holds for destructors. Note
2828 that priorities 0-100 are reserved. So, if you have a constructor that
2829 allocates a resource and a destructor that deallocates the same
2830 resource, both functions typically have the same priority. The
2831 priorities for constructor and destructor functions are the same as
2832 those specified for namespace-scope C++ objects (@pxref{C++ Attributes}).
2833 However, at present, the order in which constructors for C++ objects
2834 with static storage duration and functions decorated with attribute
2835 @code{constructor} are invoked is unspecified. In mixed declarations,
2836 attribute @code{init_priority} can be used to impose a specific ordering.
2838 Using the argument forms of the @code{constructor} and @code{destructor}
2839 attributes on targets where the feature is not supported is rejected with
2843 @itemx copy (@var{function})
2844 @cindex @code{copy} function attribute
2845 The @code{copy} attribute applies the set of attributes with which
2846 @var{function} has been declared to the declaration of the function
2847 to which the attribute is applied. The attribute is designed for
2848 libraries that define aliases or function resolvers that are expected
2849 to specify the same set of attributes as their targets. The @code{copy}
2850 attribute can be used with functions, variables, or types. However,
2851 the kind of symbol to which the attribute is applied (either function
2852 or variable) must match the kind of symbol to which the argument refers.
2853 The @code{copy} attribute copies only syntactic and semantic attributes
2854 but not attributes that affect a symbol's linkage or visibility such as
2855 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2856 and @code{target_clones} attribute are also not copied.
2857 @xref{Common Type Attributes}.
2858 @xref{Common Variable Attributes}.
2860 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2861 and @code{copy} attributes to define an alias named @var{alloc} for function
2862 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2863 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2864 the same type as the target function. As a result of the @code{copy}
2865 attribute the alias also shares the same attributes as the target.
2868 #define StrongAlias(TargetFunc, AliasDecl) \
2869 extern __typeof__ (TargetFunc) AliasDecl \
2870 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2872 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2873 void* allocate (size_t);
2874 StrongAlias (allocate, alloc);
2878 @itemx deprecated (@var{msg})
2879 @cindex @code{deprecated} function attribute
2880 The @code{deprecated} attribute results in a warning if the function
2881 is used anywhere in the source file. This is useful when identifying
2882 functions that are expected to be removed in a future version of a
2883 program. The warning also includes the location of the declaration
2884 of the deprecated function, to enable users to easily find further
2885 information about why the function is deprecated, or what they should
2886 do instead. Note that the warnings only occurs for uses:
2889 int old_fn () __attribute__ ((deprecated));
2891 int (*fn_ptr)() = old_fn;
2895 results in a warning on line 3 but not line 2. The optional @var{msg}
2896 argument, which must be a string, is printed in the warning if
2899 The @code{deprecated} attribute can also be used for variables and
2900 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2902 The message attached to the attribute is affected by the setting of
2903 the @option{-fmessage-length} option.
2906 @itemx unavailable (@var{msg})
2907 @cindex @code{unavailable} function attribute
2908 The @code{unavailable} attribute results in an error if the function
2909 is used anywhere in the source file. This is useful when identifying
2910 functions that have been removed from a particular variation of an
2911 interface. Other than emitting an error rather than a warning, the
2912 @code{unavailable} attribute behaves in the same manner as
2915 The @code{unavailable} attribute can also be used for variables and
2916 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2918 @item error ("@var{message}")
2919 @itemx warning ("@var{message}")
2920 @cindex @code{error} function attribute
2921 @cindex @code{warning} function attribute
2922 If the @code{error} or @code{warning} attribute
2923 is used on a function declaration and a call to such a function
2924 is not eliminated through dead code elimination or other optimizations,
2925 an error or warning (respectively) that includes @var{message} is diagnosed.
2927 for compile-time checking, especially together with @code{__builtin_constant_p}
2928 and inline functions where checking the inline function arguments is not
2929 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2931 While it is possible to leave the function undefined and thus invoke
2932 a link failure (to define the function with
2933 a message in @code{.gnu.warning*} section),
2934 when using these attributes the problem is diagnosed
2935 earlier and with exact location of the call even in presence of inline
2936 functions or when not emitting debugging information.
2938 @item externally_visible
2939 @cindex @code{externally_visible} function attribute
2940 This attribute, attached to a global variable or function, nullifies
2941 the effect of the @option{-fwhole-program} command-line option, so the
2942 object remains visible outside the current compilation unit.
2944 If @option{-fwhole-program} is used together with @option{-flto} and
2945 @command{gold} is used as the linker plugin,
2946 @code{externally_visible} attributes are automatically added to functions
2947 (not variable yet due to a current @command{gold} issue)
2948 that are accessed outside of LTO objects according to resolution file
2949 produced by @command{gold}.
2950 For other linkers that cannot generate resolution file,
2951 explicit @code{externally_visible} attributes are still necessary.
2954 @cindex @code{flatten} function attribute
2955 Generally, inlining into a function is limited. For a function marked with
2956 this attribute, every call inside this function is inlined, if possible.
2957 Functions declared with attribute @code{noinline} and similar are not
2958 inlined. Whether the function itself is considered for inlining depends
2959 on its size and the current inlining parameters.
2961 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2962 @cindex @code{format} function attribute
2963 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2965 The @code{format} attribute specifies that a function takes @code{printf},
2966 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2967 should be type-checked against a format string. For example, the
2972 my_printf (void *my_object, const char *my_format, ...)
2973 __attribute__ ((format (printf, 2, 3)));
2977 causes the compiler to check the arguments in calls to @code{my_printf}
2978 for consistency with the @code{printf} style format string argument
2981 The parameter @var{archetype} determines how the format string is
2982 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2983 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2984 @code{strfmon}. (You can also use @code{__printf__},
2985 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2986 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2987 @code{ms_strftime} are also present.
2988 @var{archetype} values such as @code{printf} refer to the formats accepted
2989 by the system's C runtime library,
2990 while values prefixed with @samp{gnu_} always refer
2991 to the formats accepted by the GNU C Library. On Microsoft Windows
2992 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2993 @file{msvcrt.dll} library.
2994 The parameter @var{string-index}
2995 specifies which argument is the format string argument (starting
2996 from 1), while @var{first-to-check} is the number of the first
2997 argument to check against the format string. For functions
2998 where the arguments are not available to be checked (such as
2999 @code{vprintf}), specify the third parameter as zero. In this case the
3000 compiler only checks the format string for consistency. For
3001 @code{strftime} formats, the third parameter is required to be zero.
3002 Since non-static C++ methods have an implicit @code{this} argument, the
3003 arguments of such methods should be counted from two, not one, when
3004 giving values for @var{string-index} and @var{first-to-check}.
3006 In the example above, the format string (@code{my_format}) is the second
3007 argument of the function @code{my_print}, and the arguments to check
3008 start with the third argument, so the correct parameters for the format
3009 attribute are 2 and 3.
3011 @opindex ffreestanding
3012 @opindex fno-builtin
3013 The @code{format} attribute allows you to identify your own functions
3014 that take format strings as arguments, so that GCC can check the
3015 calls to these functions for errors. The compiler always (unless
3016 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
3017 for the standard library functions @code{printf}, @code{fprintf},
3018 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
3019 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
3020 warnings are requested (using @option{-Wformat}), so there is no need to
3021 modify the header file @file{stdio.h}. In C99 mode, the functions
3022 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
3023 @code{vsscanf} are also checked. Except in strictly conforming C
3024 standard modes, the X/Open function @code{strfmon} is also checked as
3025 are @code{printf_unlocked} and @code{fprintf_unlocked}.
3026 @xref{C Dialect Options,,Options Controlling C Dialect}.
3028 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
3029 recognized in the same context. Declarations including these format attributes
3030 are parsed for correct syntax, however the result of checking of such format
3031 strings is not yet defined, and is not carried out by this version of the
3034 The target may also provide additional types of format checks.
3035 @xref{Target Format Checks,,Format Checks Specific to Particular
3038 @item format_arg (@var{string-index})
3039 @cindex @code{format_arg} function attribute
3040 @opindex Wformat-nonliteral
3041 The @code{format_arg} attribute specifies that a function takes one or
3042 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
3043 @code{strfmon} style function and modifies it (for example, to translate
3044 it into another language), so the result can be passed to a
3045 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
3046 function (with the remaining arguments to the format function the same
3047 as they would have been for the unmodified string). Multiple
3048 @code{format_arg} attributes may be applied to the same function, each
3049 designating a distinct parameter as a format string. For example, the
3054 my_dgettext (char *my_domain, const char *my_format)
3055 __attribute__ ((format_arg (2)));
3059 causes the compiler to check the arguments in calls to a @code{printf},
3060 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
3061 format string argument is a call to the @code{my_dgettext} function, for
3062 consistency with the format string argument @code{my_format}. If the
3063 @code{format_arg} attribute had not been specified, all the compiler
3064 could tell in such calls to format functions would be that the format
3065 string argument is not constant; this would generate a warning when
3066 @option{-Wformat-nonliteral} is used, but the calls could not be checked
3067 without the attribute.
3069 In calls to a function declared with more than one @code{format_arg}
3070 attribute, each with a distinct argument value, the corresponding
3071 actual function arguments are checked against all format strings
3072 designated by the attributes. This capability is designed to support
3073 the GNU @code{ngettext} family of functions.
3075 The parameter @var{string-index} specifies which argument is the format
3076 string argument (starting from one). Since non-static C++ methods have
3077 an implicit @code{this} argument, the arguments of such methods should
3078 be counted from two.
3080 The @code{format_arg} attribute allows you to identify your own
3081 functions that modify format strings, so that GCC can check the
3082 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
3083 type function whose operands are a call to one of your own function.
3084 The compiler always treats @code{gettext}, @code{dgettext}, and
3085 @code{dcgettext} in this manner except when strict ISO C support is
3086 requested by @option{-ansi} or an appropriate @option{-std} option, or
3087 @option{-ffreestanding} or @option{-fno-builtin}
3088 is used. @xref{C Dialect Options,,Options
3089 Controlling C Dialect}.
3091 For Objective-C dialects, the @code{format-arg} attribute may refer to an
3092 @code{NSString} reference for compatibility with the @code{format} attribute
3095 The target may also allow additional types in @code{format-arg} attributes.
3096 @xref{Target Format Checks,,Format Checks Specific to Particular
3100 @cindex @code{gnu_inline} function attribute
3101 This attribute should be used with a function that is also declared
3102 with the @code{inline} keyword. It directs GCC to treat the function
3103 as if it were defined in gnu90 mode even when compiling in C99 or
3106 If the function is declared @code{extern}, then this definition of the
3107 function is used only for inlining. In no case is the function
3108 compiled as a standalone function, not even if you take its address
3109 explicitly. Such an address becomes an external reference, as if you
3110 had only declared the function, and had not defined it. This has
3111 almost the effect of a macro. The way to use this is to put a
3112 function definition in a header file with this attribute, and put
3113 another copy of the function, without @code{extern}, in a library
3114 file. The definition in the header file causes most calls to the
3115 function to be inlined. If any uses of the function remain, they
3116 refer to the single copy in the library. Note that the two
3117 definitions of the functions need not be precisely the same, although
3118 if they do not have the same effect your program may behave oddly.
3120 In C, if the function is neither @code{extern} nor @code{static}, then
3121 the function is compiled as a standalone function, as well as being
3122 inlined where possible.
3124 This is how GCC traditionally handled functions declared
3125 @code{inline}. Since ISO C99 specifies a different semantics for
3126 @code{inline}, this function attribute is provided as a transition
3127 measure and as a useful feature in its own right. This attribute is
3128 available in GCC 4.1.3 and later. It is available if either of the
3129 preprocessor macros @code{__GNUC_GNU_INLINE__} or
3130 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
3131 Function is As Fast As a Macro}.
3133 In C++, this attribute does not depend on @code{extern} in any way,
3134 but it still requires the @code{inline} keyword to enable its special
3138 @cindex @code{hot} function attribute
3139 The @code{hot} attribute on a function is used to inform the compiler that
3140 the function is a hot spot of the compiled program. The function is
3141 optimized more aggressively and on many targets it is placed into a special
3142 subsection of the text section so all hot functions appear close together,
3145 When profile feedback is available, via @option{-fprofile-use}, hot functions
3146 are automatically detected and this attribute is ignored.
3148 @item ifunc ("@var{resolver}")
3149 @cindex @code{ifunc} function attribute
3150 @cindex indirect functions
3151 @cindex functions that are dynamically resolved
3152 The @code{ifunc} attribute is used to mark a function as an indirect
3153 function using the STT_GNU_IFUNC symbol type extension to the ELF
3154 standard. This allows the resolution of the symbol value to be
3155 determined dynamically at load time, and an optimized version of the
3156 routine to be selected for the particular processor or other system
3157 characteristics determined then. To use this attribute, first define
3158 the implementation functions available, and a resolver function that
3159 returns a pointer to the selected implementation function. The
3160 implementation functions' declarations must match the API of the
3161 function being implemented. The resolver should be declared to
3162 be a function taking no arguments and returning a pointer to
3163 a function of the same type as the implementation. For example:
3166 void *my_memcpy (void *dst, const void *src, size_t len)
3172 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3174 return my_memcpy; // we will just always select this routine
3179 The exported header file declaring the function the user calls would
3183 extern void *memcpy (void *, const void *, size_t);
3187 allowing the user to call @code{memcpy} as a regular function, unaware of
3188 the actual implementation. Finally, the indirect function needs to be
3189 defined in the same translation unit as the resolver function:
3192 void *memcpy (void *, const void *, size_t)
3193 __attribute__ ((ifunc ("resolve_memcpy")));
3196 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3197 of the resolver function. A C++ resolver for a non-static member function
3198 of class @code{C} should be declared to return a pointer to a non-member
3199 function taking pointer to @code{C} as the first argument, followed by
3200 the same arguments as of the implementation function. G++ checks
3201 the signatures of the two functions and issues
3202 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3203 for the necessary cast from a pointer to the implementation member function
3204 to the type of the corresponding non-member function use
3205 the @option{-Wno-pmf-conversions} option. For example:
3211 int debug_impl (int);
3212 int optimized_impl (int);
3214 typedef int Func (S*, int);
3216 static Func* resolver ();
3219 int interface (int);
3222 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3223 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3225 S::Func* S::resolver ()
3227 int (S::*pimpl) (int)
3228 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3230 // Cast triggers -Wno-pmf-conversions.
3231 return reinterpret_cast<Func*>(pimpl);
3234 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3237 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3238 and GNU C Library version 2.11.1 are required to use this feature.
3241 @itemx interrupt_handler
3242 Many GCC back ends support attributes to indicate that a function is
3243 an interrupt handler, which tells the compiler to generate function
3244 entry and exit sequences that differ from those from regular
3245 functions. The exact syntax and behavior are target-specific;
3246 refer to the following subsections for details.
3249 @cindex @code{leaf} function attribute
3250 Calls to external functions with this attribute must return to the
3251 current compilation unit only by return or by exception handling. In
3252 particular, a leaf function is not allowed to invoke callback functions
3253 passed to it from the current compilation unit, directly call functions
3254 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3255 might still call functions from other compilation units and thus they
3256 are not necessarily leaf in the sense that they contain no function
3259 The attribute is intended for library functions to improve dataflow
3260 analysis. The compiler takes the hint that any data not escaping the
3261 current compilation unit cannot be used or modified by the leaf
3262 function. For example, the @code{sin} function is a leaf function, but
3263 @code{qsort} is not.
3265 Note that leaf functions might indirectly run a signal handler defined
3266 in the current compilation unit that uses static variables. Similarly,
3267 when lazy symbol resolution is in effect, leaf functions might invoke
3268 indirect functions whose resolver function or implementation function is
3269 defined in the current compilation unit and uses static variables. There
3270 is no standard-compliant way to write such a signal handler, resolver
3271 function, or implementation function, and the best that you can do is to
3272 remove the @code{leaf} attribute or mark all such static variables
3273 @code{volatile}. Lastly, for ELF-based systems that support symbol
3274 interposition, care should be taken that functions defined in the
3275 current compilation unit do not unexpectedly interpose other symbols
3276 based on the defined standards mode and defined feature test macros;
3277 otherwise an inadvertent callback would be added.
3279 The attribute has no effect on functions defined within the current
3280 compilation unit. This is to allow easy merging of multiple compilation
3281 units into one, for example, by using the link-time optimization. For
3282 this reason the attribute is not allowed on types to annotate indirect
3286 @item malloc (@var{deallocator})
3287 @item malloc (@var{deallocator}, @var{ptr-index})
3288 @cindex @code{malloc} function attribute
3289 @cindex functions that behave like malloc
3290 Attribute @code{malloc} indicates that a function is @code{malloc}-like,
3291 i.e., that the pointer @var{P} returned by the function cannot alias any
3292 other pointer valid when the function returns, and moreover no
3293 pointers to valid objects occur in any storage addressed by @var{P}. In
3294 addition, the GCC predicts that a function with the attribute returns
3295 non-null in most cases.
3297 Independently, the form of the attribute with one or two arguments
3298 associates @code{deallocator} as a suitable deallocation function for
3299 pointers returned from the @code{malloc}-like function. @var{ptr-index}
3300 denotes the positional argument to which when the pointer is passed in
3301 calls to @code{deallocator} has the effect of deallocating it.
3303 Using the attribute with no arguments is designed to improve optimization
3304 by relying on the aliasing property it implies. Functions like @code{malloc}
3305 and @code{calloc} have this property because they return a pointer to
3306 uninitialized or zeroed-out, newly obtained storage. However, functions
3307 like @code{realloc} do not have this property, as they may return pointers
3308 to storage containing pointers to existing objects. Additionally, since
3309 all such functions are assumed to return null only infrequently, callers
3310 can be optimized based on that assumption.
3312 Associating a function with a @var{deallocator} helps detect calls to
3313 mismatched allocation and deallocation functions and diagnose them under
3314 the control of options such as @option{-Wmismatched-dealloc}. It also
3315 makes it possible to diagnose attempts to deallocate objects that were not
3316 allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate
3317 that an allocation function both satisifies the nonaliasing property and
3318 has a deallocator associated with it, both the plain form of the attribute
3319 and the one with the @var{deallocator} argument must be used. The same
3320 function can be both an allocator and a deallocator. Since inlining one
3321 of the associated functions but not the other could result in apparent
3322 mismatches, this form of attribute @code{malloc} is not accepted on inline
3323 functions. For the same reason, using the attribute prevents both
3324 the allocation and deallocation functions from being expanded inline.
3326 For example, besides stating that the functions return pointers that do
3327 not alias any others, the following declarations make @code{fclose}
3328 a suitable deallocator for pointers returned from all functions except
3329 @code{popen}, and @code{pclose} as the only suitable deallocator for
3330 pointers returned from @code{popen}. The deallocator functions must
3331 be declared before they can be referenced in the attribute.
3337 __attribute__ ((malloc, malloc (fclose, 1)))
3338 FILE* fdopen (int, const char*);
3339 __attribute__ ((malloc, malloc (fclose, 1)))
3340 FILE* fopen (const char*, const char*);
3341 __attribute__ ((malloc, malloc (fclose, 1)))
3342 FILE* fmemopen(void *, size_t, const char *);
3343 __attribute__ ((malloc, malloc (pclose, 1)))
3344 FILE* popen (const char*, const char*);
3345 __attribute__ ((malloc, malloc (fclose, 1)))
3346 FILE* tmpfile (void);
3349 The warnings guarded by @option{-fanalyzer} respect allocation and
3350 deallocation pairs marked with the @code{malloc}. In particular:
3355 The analyzer will emit a @option{-Wanalyzer-mismatching-deallocation}
3356 diagnostic if there is an execution path in which the result of an
3357 allocation call is passed to a different deallocator.
3360 The analyzer will emit a @option{-Wanalyzer-double-free}
3361 diagnostic if there is an execution path in which a value is passed
3362 more than once to a deallocation call.
3365 The analyzer will consider the possibility that an allocation function
3366 could fail and return NULL. It will emit
3367 @option{-Wanalyzer-possible-null-dereference} and
3368 @option{-Wanalyzer-possible-null-argument} diagnostics if there are
3369 execution paths in which an unchecked result of an allocation call is
3370 dereferenced or passed to a function requiring a non-null argument.
3371 If the allocator always returns non-null, use
3372 @code{__attribute__ ((returns_nonnull))} to suppress these warnings.
3375 char *xstrdup (const char *)
3376 __attribute__((malloc (free), returns_nonnull));
3380 The analyzer will emit a @option{-Wanalyzer-use-after-free}
3381 diagnostic if there is an execution path in which the memory passed
3382 by pointer to a deallocation call is used after the deallocation.
3385 The analyzer will emit a @option{-Wanalyzer-malloc-leak} diagnostic if
3386 there is an execution path in which the result of an allocation call
3387 is leaked (without being passed to the deallocation function).
3390 The analyzer will emit a @option{-Wanalyzer-free-of-non-heap} diagnostic
3391 if a deallocation function is used on a global or on-stack variable.
3395 The analyzer assumes that deallocators can gracefully handle the @code{NULL}
3396 pointer. If this is not the case, the deallocator can be marked with
3397 @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit
3398 a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
3399 in which the deallocator is called with NULL.
3402 @cindex @code{no_icf} function attribute
3403 This function attribute prevents a functions from being merged with another
3404 semantically equivalent function.
3406 @item no_instrument_function
3407 @cindex @code{no_instrument_function} function attribute
3408 @opindex finstrument-functions
3411 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3412 given, profiling function calls are
3413 generated at entry and exit of most user-compiled functions.
3414 Functions with this attribute are not so instrumented.
3416 @item no_profile_instrument_function
3417 @cindex @code{no_profile_instrument_function} function attribute
3418 The @code{no_profile_instrument_function} attribute on functions is used
3419 to inform the compiler that it should not process any profile feedback based
3420 optimization code instrumentation.
3423 @cindex @code{no_reorder} function attribute
3424 Do not reorder functions or variables marked @code{no_reorder}
3425 against each other or top level assembler statements the executable.
3426 The actual order in the program will depend on the linker command
3427 line. Static variables marked like this are also not removed.
3428 This has a similar effect
3429 as the @option{-fno-toplevel-reorder} option, but only applies to the
3432 @item no_sanitize ("@var{sanitize_option}")
3433 @cindex @code{no_sanitize} function attribute
3434 The @code{no_sanitize} attribute on functions is used
3435 to inform the compiler that it should not do sanitization of any option
3436 mentioned in @var{sanitize_option}. A list of values acceptable by
3437 the @option{-fsanitize} option can be provided.
3440 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3441 f () @{ /* @r{Do something.} */; @}
3442 void __attribute__ ((no_sanitize ("alignment,object-size")))
3443 g () @{ /* @r{Do something.} */; @}
3446 @item no_sanitize_address
3447 @itemx no_address_safety_analysis
3448 @cindex @code{no_sanitize_address} function attribute
3449 The @code{no_sanitize_address} attribute on functions is used
3450 to inform the compiler that it should not instrument memory accesses
3451 in the function when compiling with the @option{-fsanitize=address} option.
3452 The @code{no_address_safety_analysis} is a deprecated alias of the
3453 @code{no_sanitize_address} attribute, new code should use
3454 @code{no_sanitize_address}.
3456 @item no_sanitize_thread
3457 @cindex @code{no_sanitize_thread} function attribute
3458 The @code{no_sanitize_thread} attribute on functions is used
3459 to inform the compiler that it should not instrument memory accesses
3460 in the function when compiling with the @option{-fsanitize=thread} option.
3462 @item no_sanitize_undefined
3463 @cindex @code{no_sanitize_undefined} function attribute
3464 The @code{no_sanitize_undefined} attribute on functions is used
3465 to inform the compiler that it should not check for undefined behavior
3466 in the function when compiling with the @option{-fsanitize=undefined} option.
3468 @item no_sanitize_coverage
3469 @cindex @code{no_sanitize_coverage} function attribute
3470 The @code{no_sanitize_coverage} attribute on functions is used
3471 to inform the compiler that it should not do coverage-guided
3472 fuzzing code instrumentation (@option{-fsanitize-coverage}).
3474 @item no_split_stack
3475 @cindex @code{no_split_stack} function attribute
3476 @opindex fsplit-stack
3477 If @option{-fsplit-stack} is given, functions have a small
3478 prologue which decides whether to split the stack. Functions with the
3479 @code{no_split_stack} attribute do not have that prologue, and thus
3480 may run with only a small amount of stack space available.
3482 @item no_stack_limit
3483 @cindex @code{no_stack_limit} function attribute
3484 This attribute locally overrides the @option{-fstack-limit-register}
3485 and @option{-fstack-limit-symbol} command-line options; it has the effect
3486 of disabling stack limit checking in the function it applies to.
3489 @cindex @code{noclone} function attribute
3490 This function attribute prevents a function from being considered for
3491 cloning---a mechanism that produces specialized copies of functions
3492 and which is (currently) performed by interprocedural constant
3496 @cindex @code{noinline} function attribute
3497 This function attribute prevents a function from being considered for
3499 @c Don't enumerate the optimizations by name here; we try to be
3500 @c future-compatible with this mechanism.
3501 If the function does not have side effects, there are optimizations
3502 other than inlining that cause function calls to be optimized away,
3503 although the function call is live. To keep such calls from being
3510 (@pxref{Extended Asm}) in the called function, to serve as a special
3514 @cindex @code{noipa} function attribute
3515 Disable interprocedural optimizations between the function with this
3516 attribute and its callers, as if the body of the function is not available
3517 when optimizing callers and the callers are unavailable when optimizing
3518 the body. This attribute implies @code{noinline}, @code{noclone} and
3519 @code{no_icf} attributes. However, this attribute is not equivalent
3520 to a combination of other attributes, because its purpose is to suppress
3521 existing and future optimizations employing interprocedural analysis,
3522 including those that do not have an attribute suitable for disabling
3523 them individually. This attribute is supported mainly for the purpose
3524 of testing the compiler.
3527 @itemx nonnull (@var{arg-index}, @dots{})
3528 @cindex @code{nonnull} function attribute
3529 @cindex functions with non-null pointer arguments
3530 The @code{nonnull} attribute may be applied to a function that takes at
3531 least one argument of a pointer type. It indicates that the referenced
3532 arguments must be non-null pointers. For instance, the declaration:
3536 my_memcpy (void *dest, const void *src, size_t len)
3537 __attribute__((nonnull (1, 2)));
3541 informs the compiler that, in calls to @code{my_memcpy}, arguments
3542 @var{dest} and @var{src} must be non-null.
3544 The attribute has an effect both on functions calls and function definitions.
3548 @item If the compiler determines that a null pointer is
3549 passed in an argument slot marked as non-null, and the
3550 @option{-Wnonnull} option is enabled, a warning is issued.
3551 @xref{Warning Options}.
3552 @item The @option{-fisolate-erroneous-paths-attribute} option can be
3553 specified to have GCC transform calls with null arguments to non-null
3554 functions into traps. @xref{Optimize Options}.
3555 @item The compiler may also perform optimizations based on the
3556 knowledge that certain function arguments cannot be null. These
3557 optimizations can be disabled by the
3558 @option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}.
3561 For function definitions:
3563 @item If the compiler determines that a function parameter that is
3564 marked with nonnull is compared with null, and
3565 @option{-Wnonnull-compare} option is enabled, a warning is issued.
3566 @xref{Warning Options}.
3567 @item The compiler may also perform optimizations based on the
3568 knowledge that @code{nonnul} parameters cannot be null. This can
3569 currently not be disabled other than by removing the nonnull
3573 If no @var{arg-index} is given to the @code{nonnull} attribute,
3574 all pointer arguments are marked as non-null. To illustrate, the
3575 following declaration is equivalent to the previous example:
3579 my_memcpy (void *dest, const void *src, size_t len)
3580 __attribute__((nonnull));
3584 @cindex @code{noplt} function attribute
3585 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3586 Calls to functions marked with this attribute in position-independent code
3591 /* Externally defined function foo. */
3592 int foo () __attribute__ ((noplt));
3595 main (/* @r{@dots{}} */)
3604 The @code{noplt} attribute on function @code{foo}
3605 tells the compiler to assume that
3606 the function @code{foo} is externally defined and that the call to
3607 @code{foo} must avoid the PLT
3608 in position-independent code.
3610 In position-dependent code, a few targets also convert calls to
3611 functions that are marked to not use the PLT to use the GOT instead.
3614 @cindex @code{noreturn} function attribute
3615 @cindex functions that never return
3616 A few standard library functions, such as @code{abort} and @code{exit},
3617 cannot return. GCC knows this automatically. Some programs define
3618 their own functions that never return. You can declare them
3619 @code{noreturn} to tell the compiler this fact. For example,
3623 void fatal () __attribute__ ((noreturn));
3626 fatal (/* @r{@dots{}} */)
3628 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3634 The @code{noreturn} keyword tells the compiler to assume that
3635 @code{fatal} cannot return. It can then optimize without regard to what
3636 would happen if @code{fatal} ever did return. This makes slightly
3637 better code. More importantly, it helps avoid spurious warnings of
3638 uninitialized variables.
3640 The @code{noreturn} keyword does not affect the exceptional path when that
3641 applies: a @code{noreturn}-marked function may still return to the caller
3642 by throwing an exception or calling @code{longjmp}.
3644 In order to preserve backtraces, GCC will never turn calls to
3645 @code{noreturn} functions into tail calls.
3647 Do not assume that registers saved by the calling function are
3648 restored before calling the @code{noreturn} function.
3650 It does not make sense for a @code{noreturn} function to have a return
3651 type other than @code{void}.
3654 @cindex @code{nothrow} function attribute
3655 The @code{nothrow} attribute is used to inform the compiler that a
3656 function cannot throw an exception. For example, most functions in
3657 the standard C library can be guaranteed not to throw an exception
3658 with the notable exceptions of @code{qsort} and @code{bsearch} that
3659 take function pointer arguments.
3661 @item optimize (@var{level}, @dots{})
3662 @item optimize (@var{string}, @dots{})
3663 @cindex @code{optimize} function attribute
3664 The @code{optimize} attribute is used to specify that a function is to
3665 be compiled with different optimization options than specified on the
3666 command line. The optimize attribute arguments of a function behave
3667 behave as if appended to the command-line.
3669 Valid arguments are constant non-negative integers and
3670 strings. Each numeric argument specifies an optimization @var{level}.
3671 Each @var{string} argument consists of one or more comma-separated
3672 substrings. Each substring that begins with the letter @code{O} refers
3673 to an optimization option such as @option{-O0} or @option{-Os}. Other
3674 substrings are taken as suffixes to the @code{-f} prefix jointly
3675 forming the name of an optimization option. @xref{Optimize Options}.
3677 @samp{#pragma GCC optimize} can be used to set optimization options
3678 for more than one function. @xref{Function Specific Option Pragmas},
3679 for details about the pragma.
3681 Providing multiple strings as arguments separated by commas to specify
3682 multiple options is equivalent to separating the option suffixes with
3683 a comma (@samp{,}) within a single string. Spaces are not permitted
3686 Not every optimization option that starts with the @var{-f} prefix
3687 specified by the attribute necessarily has an effect on the function.
3688 The @code{optimize} attribute should be used for debugging purposes only.
3689 It is not suitable in production code.
3691 @item patchable_function_entry
3692 @cindex @code{patchable_function_entry} function attribute
3693 @cindex extra NOP instructions at the function entry point
3694 In case the target's text segment can be made writable at run time by
3695 any means, padding the function entry with a number of NOPs can be
3696 used to provide a universal tool for instrumentation.
3698 The @code{patchable_function_entry} function attribute can be used to
3699 change the number of NOPs to any desired value. The two-value syntax
3700 is the same as for the command-line switch
3701 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3702 the function entry point before the @var{M}th NOP instruction.
3703 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3706 If patchable function entries are enabled globally using the command-line
3707 option @option{-fpatchable-function-entry=N,M}, then you must disable
3708 instrumentation on all functions that are part of the instrumentation
3709 framework with the attribute @code{patchable_function_entry (0)}
3710 to prevent recursion.
3713 @cindex @code{pure} function attribute
3714 @cindex functions that have no side effects
3716 Calls to functions that have no observable effects on the state of
3717 the program other than to return a value may lend themselves to optimizations
3718 such as common subexpression elimination. Declaring such functions with
3719 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3720 invocations of the function with the same argument values.
3722 The @code{pure} attribute prohibits a function from modifying the state
3723 of the program that is observable by means other than inspecting
3724 the function's return value. However, functions declared with the @code{pure}
3725 attribute can safely read any non-volatile objects, and modify the value of
3726 objects in a way that does not affect their return value or the observable
3727 state of the program.
3732 int hash (char *) __attribute__ ((pure));
3736 tells GCC that subsequent calls to the function @code{hash} with the same
3737 string can be replaced by the result of the first call provided the state
3738 of the program observable by @code{hash}, including the contents of the array
3739 itself, does not change in between. Even though @code{hash} takes a non-const
3740 pointer argument it must not modify the array it points to, or any other object
3741 whose value the rest of the program may depend on. However, the caller may
3742 safely change the contents of the array between successive calls to
3743 the function (doing so disables the optimization). The restriction also
3744 applies to member objects referenced by the @code{this} pointer in C++
3745 non-static member functions.
3747 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3748 Interesting non-pure functions are functions with infinite loops or those
3749 depending on volatile memory or other system resource, that may change between
3750 consecutive calls (such as the standard C @code{feof} function in
3751 a multithreading environment).
3753 The @code{pure} attribute imposes similar but looser restrictions on
3754 a function's definition than the @code{const} attribute: @code{pure}
3755 allows the function to read any non-volatile memory, even if it changes
3756 in between successive invocations of the function. Declaring the same
3757 function with both the @code{pure} and the @code{const} attribute is
3758 diagnosed. Because a pure function cannot have any observable side
3759 effects it does not make sense for such a function to return @code{void}.
3760 Declaring such a function is diagnosed.
3762 @item returns_nonnull
3763 @cindex @code{returns_nonnull} function attribute
3764 The @code{returns_nonnull} attribute specifies that the function
3765 return value should be a non-null pointer. For instance, the declaration:
3769 mymalloc (size_t len) __attribute__((returns_nonnull));
3773 lets the compiler optimize callers based on the knowledge
3774 that the return value will never be null.
3777 @cindex @code{returns_twice} function attribute
3778 @cindex functions that return more than once
3779 The @code{returns_twice} attribute tells the compiler that a function may
3780 return more than one time. The compiler ensures that all registers
3781 are dead before calling such a function and emits a warning about
3782 the variables that may be clobbered after the second return from the
3783 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3784 The @code{longjmp}-like counterpart of such function, if any, might need
3785 to be marked with the @code{noreturn} attribute.
3787 @item section ("@var{section-name}")
3788 @cindex @code{section} function attribute
3789 @cindex functions in arbitrary sections
3790 Normally, the compiler places the code it generates in the @code{text} section.
3791 Sometimes, however, you need additional sections, or you need certain
3792 particular functions to appear in special sections. The @code{section}
3793 attribute specifies that a function lives in a particular section.
3794 For example, the declaration:
3797 extern void foobar (void) __attribute__ ((section ("bar")));
3801 puts the function @code{foobar} in the @code{bar} section.
3803 Some file formats do not support arbitrary sections so the @code{section}
3804 attribute is not available on all platforms.
3805 If you need to map the entire contents of a module to a particular
3806 section, consider using the facilities of the linker instead.
3809 @itemx sentinel (@var{position})
3810 @cindex @code{sentinel} function attribute
3811 This function attribute indicates that an argument in a call to the function
3812 is expected to be an explicit @code{NULL}. The attribute is only valid on
3813 variadic functions. By default, the sentinel is expected to be the last
3814 argument of the function call. If the optional @var{position} argument
3815 is specified to the attribute, the sentinel must be located at
3816 @var{position} counting backwards from the end of the argument list.
3819 __attribute__ ((sentinel))
3821 __attribute__ ((sentinel(0)))
3824 The attribute is automatically set with a position of 0 for the built-in
3825 functions @code{execl} and @code{execlp}. The built-in function
3826 @code{execle} has the attribute set with a position of 1.
3828 A valid @code{NULL} in this context is defined as zero with any object
3829 pointer type. If your system defines the @code{NULL} macro with
3830 an integer type then you need to add an explicit cast. During
3831 installation GCC replaces the system @code{<stddef.h>} header with
3832 a copy that redefines NULL appropriately.
3834 The warnings for missing or incorrect sentinels are enabled with
3838 @itemx simd("@var{mask}")
3839 @cindex @code{simd} function attribute
3840 This attribute enables creation of one or more function versions that
3841 can process multiple arguments using SIMD instructions from a
3842 single invocation. Specifying this attribute allows compiler to
3843 assume that such versions are available at link time (provided
3844 in the same or another translation unit). Generated versions are
3845 target-dependent and described in the corresponding Vector ABI document. For
3846 x86_64 target this document can be found
3847 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3849 The optional argument @var{mask} may have the value
3850 @code{notinbranch} or @code{inbranch},
3851 and instructs the compiler to generate non-masked or masked
3852 clones correspondingly. By default, all clones are generated.
3854 If the attribute is specified and @code{#pragma omp declare simd} is
3855 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3856 switch is specified, then the attribute is ignored.
3859 @cindex @code{stack_protect} function attribute
3860 This attribute adds stack protection code to the function if
3861 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3862 or @option{-fstack-protector-explicit} are set.
3864 @item no_stack_protector
3865 @cindex @code{no_stack_protector} function attribute
3866 This attribute prevents stack protection code for the function.
3868 @item target (@var{string}, @dots{})
3869 @cindex @code{target} function attribute
3870 Multiple target back ends implement the @code{target} attribute
3871 to specify that a function is to
3872 be compiled with different target options than specified on the
3873 command line. The original target command-line options are ignored.
3874 One or more strings can be provided as arguments.
3875 Each string consists of one or more comma-separated suffixes to
3876 the @code{-m} prefix jointly forming the name of a machine-dependent
3877 option. @xref{Submodel Options,,Machine-Dependent Options}.
3879 The @code{target} attribute can be used for instance to have a function
3880 compiled with a different ISA (instruction set architecture) than the
3881 default. @samp{#pragma GCC target} can be used to specify target-specific
3882 options for more than one function. @xref{Function Specific Option Pragmas},
3883 for details about the pragma.
3885 For instance, on an x86, you could declare one function with the
3886 @code{target("sse4.1,arch=core2")} attribute and another with
3887 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3888 compiling the first function with @option{-msse4.1} and
3889 @option{-march=core2} options, and the second function with
3890 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3891 to make sure that a function is only invoked on a machine that
3892 supports the particular ISA it is compiled for (for example by using
3893 @code{cpuid} on x86 to determine what feature bits and architecture
3897 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3898 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3901 Providing multiple strings as arguments separated by commas to specify
3902 multiple options is equivalent to separating the option suffixes with
3903 a comma (@samp{,}) within a single string. Spaces are not permitted
3906 The options supported are specific to each target; refer to @ref{x86
3907 Function Attributes}, @ref{PowerPC Function Attributes},
3908 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
3909 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
3912 @item symver ("@var{name2}@@@var{nodename}")
3913 @cindex @code{symver} function attribute
3914 On ELF targets this attribute creates a symbol version. The @var{name2} part
3915 of the parameter is the actual name of the symbol by which it will be
3916 externally referenced. The @code{nodename} portion should be the name of a
3917 node specified in the version script supplied to the linker when building a
3918 shared library. Versioned symbol must be defined and must be exported with
3922 __attribute__ ((__symver__ ("foo@@VERS_1"))) int
3928 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
3931 One can also define multiple version for a given symbol
3932 (starting from binutils 2.35).
3935 __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
3936 int symver_foo_v1 (void)
3941 This example creates a symbol name @code{symver_foo_v1}
3942 which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
3944 If you have an older release of binutils, then symbol alias needs to
3948 __attribute__ ((__symver__ ("foo@@VERS_2")))
3954 __attribute__ ((__symver__ ("foo@@VERS_3")))
3955 __attribute__ ((alias ("foo_v1")))
3956 int symver_foo_v1 (void);
3959 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
3960 addition to creating a symbol version (as if
3961 @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
3962 to resolve @var{name2} by the linker.
3964 @item target_clones (@var{options})
3965 @cindex @code{target_clones} function attribute
3966 The @code{target_clones} attribute is used to specify that a function
3967 be cloned into multiple versions compiled with different target options
3968 than specified on the command line. The supported options and restrictions
3969 are the same as for @code{target} attribute.
3971 For instance, on an x86, you could compile a function with
3972 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
3973 one compiled with @option{-msse4.1} and another with @option{-mavx}.
3975 On a PowerPC, you can compile a function with
3976 @code{target_clones("cpu=power9,default")}. GCC will create two
3977 function clones, one compiled with @option{-mcpu=power9} and another
3978 with the default options. GCC must be configured to use GLIBC 2.23 or
3979 newer in order to use the @code{target_clones} attribute.
3981 It also creates a resolver function (see
3982 the @code{ifunc} attribute above) that dynamically selects a clone
3983 suitable for current architecture. The resolver is created only if there
3984 is a usage of a function with @code{target_clones} attribute.
3986 Note that any subsequent call of a function without @code{target_clone}
3987 from a @code{target_clone} caller will not lead to copying
3988 (target clone) of the called function.
3989 If you want to enforce such behaviour,
3990 we recommend declaring the calling function with the @code{flatten} attribute?
3993 @cindex @code{unused} function attribute
3994 This attribute, attached to a function, means that the function is meant
3995 to be possibly unused. GCC does not produce a warning for this
3999 @cindex @code{used} function attribute
4000 This attribute, attached to a function, means that code must be emitted
4001 for the function even if it appears that the function is not referenced.
4002 This is useful, for example, when the function is referenced only in
4005 When applied to a member function of a C++ class template, the
4006 attribute also means that the function is instantiated if the
4007 class itself is instantiated.
4010 @cindex @code{retain} function attribute
4011 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
4012 will save the function from linker garbage collection. To support
4013 this behavior, functions that have not been placed in specific sections
4014 (e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
4015 option), will be placed in new, unique sections.
4017 This additional functionality requires Binutils version 2.36 or later.
4019 @item visibility ("@var{visibility_type}")
4020 @cindex @code{visibility} function attribute
4021 This attribute affects the linkage of the declaration to which it is attached.
4022 It can be applied to variables (@pxref{Common Variable Attributes}) and types
4023 (@pxref{Common Type Attributes}) as well as functions.
4025 There are four supported @var{visibility_type} values: default,
4026 hidden, protected or internal visibility.
4029 void __attribute__ ((visibility ("protected")))
4030 f () @{ /* @r{Do something.} */; @}
4031 int i __attribute__ ((visibility ("hidden")));
4034 The possible values of @var{visibility_type} correspond to the
4035 visibility settings in the ELF gABI.
4038 @c keep this list of visibilities in alphabetical order.
4041 Default visibility is the normal case for the object file format.
4042 This value is available for the visibility attribute to override other
4043 options that may change the assumed visibility of entities.
4045 On ELF, default visibility means that the declaration is visible to other
4046 modules and, in shared libraries, means that the declared entity may be
4049 On Darwin, default visibility means that the declaration is visible to
4052 Default visibility corresponds to ``external linkage'' in the language.
4055 Hidden visibility indicates that the entity declared has a new
4056 form of linkage, which we call ``hidden linkage''. Two
4057 declarations of an object with hidden linkage refer to the same object
4058 if they are in the same shared object.
4061 Internal visibility is like hidden visibility, but with additional
4062 processor specific semantics. Unless otherwise specified by the
4063 psABI, GCC defines internal visibility to mean that a function is
4064 @emph{never} called from another module. Compare this with hidden
4065 functions which, while they cannot be referenced directly by other
4066 modules, can be referenced indirectly via function pointers. By
4067 indicating that a function cannot be called from outside the module,
4068 GCC may for instance omit the load of a PIC register since it is known
4069 that the calling function loaded the correct value.
4072 Protected visibility is like default visibility except that it
4073 indicates that references within the defining module bind to the
4074 definition in that module. That is, the declared entity cannot be
4075 overridden by another module.
4079 All visibilities are supported on many, but not all, ELF targets
4080 (supported when the assembler supports the @samp{.visibility}
4081 pseudo-op). Default visibility is supported everywhere. Hidden
4082 visibility is supported on Darwin targets.
4084 The visibility attribute should be applied only to declarations that
4085 would otherwise have external linkage. The attribute should be applied
4086 consistently, so that the same entity should not be declared with
4087 different settings of the attribute.
4089 In C++, the visibility attribute applies to types as well as functions
4090 and objects, because in C++ types have linkage. A class must not have
4091 greater visibility than its non-static data member types and bases,
4092 and class members default to the visibility of their class. Also, a
4093 declaration without explicit visibility is limited to the visibility
4096 In C++, you can mark member functions and static member variables of a
4097 class with the visibility attribute. This is useful if you know a
4098 particular method or static member variable should only be used from
4099 one shared object; then you can mark it hidden while the rest of the
4100 class has default visibility. Care must be taken to avoid breaking
4101 the One Definition Rule; for example, it is usually not useful to mark
4102 an inline method as hidden without marking the whole class as hidden.
4104 A C++ namespace declaration can also have the visibility attribute.
4107 namespace nspace1 __attribute__ ((visibility ("protected")))
4108 @{ /* @r{Do something.} */; @}
4111 This attribute applies only to the particular namespace body, not to
4112 other definitions of the same namespace; it is equivalent to using
4113 @samp{#pragma GCC visibility} before and after the namespace
4114 definition (@pxref{Visibility Pragmas}).
4116 In C++, if a template argument has limited visibility, this
4117 restriction is implicitly propagated to the template instantiation.
4118 Otherwise, template instantiations and specializations default to the
4119 visibility of their template.
4121 If both the template and enclosing class have explicit visibility, the
4122 visibility from the template is used.
4124 @item warn_unused_result
4125 @cindex @code{warn_unused_result} function attribute
4126 The @code{warn_unused_result} attribute causes a warning to be emitted
4127 if a caller of the function with this attribute does not use its
4128 return value. This is useful for functions where not checking
4129 the result is either a security problem or always a bug, such as
4133 int fn () __attribute__ ((warn_unused_result));
4136 if (fn () < 0) return -1;
4143 results in warning on line 5.
4146 @cindex @code{weak} function attribute
4147 The @code{weak} attribute causes a declaration of an external symbol
4148 to be emitted as a weak symbol rather than a global. This is primarily
4149 useful in defining library functions that can be overridden in user code,
4150 though it can also be used with non-function declarations. The overriding
4151 symbol must have the same type as the weak symbol. In addition, if it
4152 designates a variable it must also have the same size and alignment as
4153 the weak symbol. Weak symbols are supported for ELF targets, and also
4154 for a.out targets when using the GNU assembler and linker.
4157 @itemx weakref ("@var{target}")
4158 @cindex @code{weakref} function attribute
4159 The @code{weakref} attribute marks a declaration as a weak reference.
4160 Without arguments, it should be accompanied by an @code{alias} attribute
4161 naming the target symbol. Alternatively, @var{target} may be given as
4162 an argument to @code{weakref} itself, naming the target definition of
4163 the alias. The @var{target} must have the same type as the declaration.
4164 In addition, if it designates a variable it must also have the same size
4165 and alignment as the declaration. In either form of the declaration
4166 @code{weakref} implicitly marks the declared symbol as @code{weak}. Without
4167 a @var{target} given as an argument to @code{weakref} or to @code{alias},
4168 @code{weakref} is equivalent to @code{weak} (in that case the declaration
4169 may be @code{extern}).
4172 /* Given the declaration: */
4173 extern int y (void);
4175 /* the following... */
4176 static int x (void) __attribute__ ((weakref ("y")));
4178 /* is equivalent to... */
4179 static int x (void) __attribute__ ((weakref, alias ("y")));
4181 /* or, alternatively, to... */
4182 static int x (void) __attribute__ ((weakref));
4183 static int x (void) __attribute__ ((alias ("y")));
4186 A weak reference is an alias that does not by itself require a
4187 definition to be given for the target symbol. If the target symbol is
4188 only referenced through weak references, then it becomes a @code{weak}
4189 undefined symbol. If it is directly referenced, however, then such
4190 strong references prevail, and a definition is required for the
4191 symbol, not necessarily in the same translation unit.
4193 The effect is equivalent to moving all references to the alias to a
4194 separate translation unit, renaming the alias to the aliased symbol,
4195 declaring it as weak, compiling the two separate translation units and
4196 performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
4198 A declaration to which @code{weakref} is attached and that is associated
4199 with a named @code{target} must be @code{static}.
4201 @item zero_call_used_regs ("@var{choice}")
4202 @cindex @code{zero_call_used_regs} function attribute
4204 The @code{zero_call_used_regs} attribute causes the compiler to zero
4205 a subset of all call-used registers@footnote{A ``call-used'' register
4206 is a register whose contents can be changed by a function call;
4207 therefore, a caller cannot assume that the register has the same contents
4208 on return from the function as it had before calling the function. Such
4209 registers are also called ``call-clobbered'', ``caller-saved'', or
4210 ``volatile''.} at function return.
4211 This is used to increase program security by either mitigating
4212 Return-Oriented Programming (ROP) attacks or preventing information leakage
4215 In order to satisfy users with different security needs and control the
4216 run-time overhead at the same time, the @var{choice} parameter provides a
4217 flexible way to choose the subset of the call-used registers to be zeroed.
4218 The three basic values of @var{choice} are:
4222 @samp{skip} doesn't zero any call-used registers.
4225 @samp{used} only zeros call-used registers that are used in the function.
4226 A ``used'' register is one whose content has been set or referenced in
4230 @samp{all} zeros all call-used registers.
4233 In addition to these three basic choices, it is possible to modify
4234 @samp{used} or @samp{all} as follows:
4238 Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
4241 Adding @samp{-arg} restricts the zeroing to registers that can sometimes
4242 be used to pass function arguments. This includes all argument registers
4243 defined by the platform's calling conversion, regardless of whether the
4244 function uses those registers for function arguments or not.
4247 The modifiers can be used individually or together. If they are used
4248 together, they must appear in the order above.
4250 The full list of @var{choice}s is therefore:
4254 doesn't zero any call-used register.
4257 only zeros call-used registers that are used in the function.
4260 only zeros call-used general purpose registers that are used in the function.
4263 only zeros call-used registers that are used in the function and pass arguments.
4266 only zeros call-used general purpose registers that are used in the function
4270 zeros all call-used registers.
4273 zeros all call-used general purpose registers.
4276 zeros all call-used registers that pass arguments.
4279 zeros all call-used general purpose registers that pass
4283 Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
4284 and @samp{all-gpr-arg} are mainly used for ROP mitigation.
4286 The default for the attribute is controlled by @option{-fzero-call-used-regs}.
4289 @c This is the end of the target-independent attribute table
4291 @node AArch64 Function Attributes
4292 @subsection AArch64 Function Attributes
4294 The following target-specific function attributes are available for the
4295 AArch64 target. For the most part, these options mirror the behavior of
4296 similar command-line options (@pxref{AArch64 Options}), but on a
4300 @item general-regs-only
4301 @cindex @code{general-regs-only} function attribute, AArch64
4302 Indicates that no floating-point or Advanced SIMD registers should be
4303 used when generating code for this function. If the function explicitly
4304 uses floating-point code, then the compiler gives an error. This is
4305 the same behavior as that of the command-line option
4306 @option{-mgeneral-regs-only}.
4308 @item fix-cortex-a53-835769
4309 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
4310 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
4311 applied to this function. To explicitly disable the workaround for this
4312 function specify the negated form: @code{no-fix-cortex-a53-835769}.
4313 This corresponds to the behavior of the command line options
4314 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
4317 @cindex @code{cmodel=} function attribute, AArch64
4318 Indicates that code should be generated for a particular code model for
4319 this function. The behavior and permissible arguments are the same as
4320 for the command line option @option{-mcmodel=}.
4323 @itemx no-strict-align
4324 @cindex @code{strict-align} function attribute, AArch64
4325 @code{strict-align} indicates that the compiler should not assume that unaligned
4326 memory references are handled by the system. To allow the compiler to assume
4327 that aligned memory references are handled by the system, the inverse attribute
4328 @code{no-strict-align} can be specified. The behavior is same as for the
4329 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
4331 @item omit-leaf-frame-pointer
4332 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
4333 Indicates that the frame pointer should be omitted for a leaf function call.
4334 To keep the frame pointer, the inverse attribute
4335 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
4336 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
4337 and @option{-mno-omit-leaf-frame-pointer}.
4340 @cindex @code{tls-dialect=} function attribute, AArch64
4341 Specifies the TLS dialect to use for this function. The behavior and
4342 permissible arguments are the same as for the command-line option
4343 @option{-mtls-dialect=}.
4346 @cindex @code{arch=} function attribute, AArch64
4347 Specifies the architecture version and architectural extensions to use
4348 for this function. The behavior and permissible arguments are the same as
4349 for the @option{-march=} command-line option.
4352 @cindex @code{tune=} function attribute, AArch64
4353 Specifies the core for which to tune the performance of this function.
4354 The behavior and permissible arguments are the same as for the @option{-mtune=}
4355 command-line option.
4358 @cindex @code{cpu=} function attribute, AArch64
4359 Specifies the core for which to tune the performance of this function and also
4360 whose architectural features to use. The behavior and valid arguments are the
4361 same as for the @option{-mcpu=} command-line option.
4363 @item sign-return-address
4364 @cindex @code{sign-return-address} function attribute, AArch64
4365 Select the function scope on which return address signing will be applied. The
4366 behavior and permissible arguments are the same as for the command-line option
4367 @option{-msign-return-address=}. The default value is @code{none}. This
4368 attribute is deprecated. The @code{branch-protection} attribute should
4371 @item branch-protection
4372 @cindex @code{branch-protection} function attribute, AArch64
4373 Select the function scope on which branch protection will be applied. The
4374 behavior and permissible arguments are the same as for the command-line option
4375 @option{-mbranch-protection=}. The default value is @code{none}.
4377 @item outline-atomics
4378 @cindex @code{outline-atomics} function attribute, AArch64
4379 Enable or disable calls to out-of-line helpers to implement atomic operations.
4380 This corresponds to the behavior of the command line options
4381 @option{-moutline-atomics} and @option{-mno-outline-atomics}.
4385 The above target attributes can be specified as follows:
4388 __attribute__((target("@var{attr-string}")))
4396 where @code{@var{attr-string}} is one of the attribute strings specified above.
4398 Additionally, the architectural extension string may be specified on its
4399 own. This can be used to turn on and off particular architectural extensions
4400 without having to specify a particular architecture version or core. Example:
4403 __attribute__((target("+crc+nocrypto")))
4411 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4412 extension and disables the @code{crypto} extension for the function @code{foo}
4413 without modifying an existing @option{-march=} or @option{-mcpu} option.
4415 Multiple target function attributes can be specified by separating them with
4416 a comma. For example:
4418 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
4426 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
4427 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
4429 @subsubsection Inlining rules
4430 Specifying target attributes on individual functions or performing link-time
4431 optimization across translation units compiled with different target options
4432 can affect function inlining rules:
4434 In particular, a caller function can inline a callee function only if the
4435 architectural features available to the callee are a subset of the features
4436 available to the caller.
4437 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
4438 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
4439 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
4440 because the all the architectural features that function @code{bar} requires
4441 are available to function @code{foo}. Conversely, function @code{bar} cannot
4442 inline function @code{foo}.
4444 Additionally inlining a function compiled with @option{-mstrict-align} into a
4445 function compiled without @code{-mstrict-align} is not allowed.
4446 However, inlining a function compiled without @option{-mstrict-align} into a
4447 function compiled with @option{-mstrict-align} is allowed.
4449 Note that CPU tuning options and attributes such as the @option{-mcpu=},
4450 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
4451 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
4452 architectural feature rules specified above.
4454 @node AMD GCN Function Attributes
4455 @subsection AMD GCN Function Attributes
4457 These function attributes are supported by the AMD GCN back end:
4460 @item amdgpu_hsa_kernel
4461 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
4462 This attribute indicates that the corresponding function should be compiled as
4463 a kernel function, that is an entry point that can be invoked from the host
4464 via the HSA runtime library. By default functions are only callable only from
4465 other GCN functions.
4467 This attribute is implicitly applied to any function named @code{main}, using
4470 Kernel functions may return an integer value, which will be written to a
4471 conventional place within the HSA "kernargs" region.
4473 The attribute parameters configure what values are passed into the kernel
4474 function by the GPU drivers, via the initial register state. Some values are
4475 used by the compiler, and therefore forced on. Enabling other options may
4476 break assumptions in the compiler and/or run-time libraries.
4479 @item private_segment_buffer
4480 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4484 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4488 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4491 @item kernarg_segment_ptr
4492 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4493 locate the kernel arguments, "kernargs").
4496 Set @code{enable_sgpr_dispatch_id} flag.
4498 @item flat_scratch_init
4499 Set @code{enable_sgpr_flat_scratch_init} flag.
4501 @item private_segment_size
4502 Set @code{enable_sgpr_private_segment_size} flag.
4504 @item grid_workgroup_count_X
4505 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4506 use OpenACC/OpenMP).
4508 @item grid_workgroup_count_Y
4509 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4511 @item grid_workgroup_count_Z
4512 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4514 @item workgroup_id_X
4515 Set @code{enable_sgpr_workgroup_id_x} flag.
4517 @item workgroup_id_Y
4518 Set @code{enable_sgpr_workgroup_id_y} flag.
4520 @item workgroup_id_Z
4521 Set @code{enable_sgpr_workgroup_id_z} flag.
4523 @item workgroup_info
4524 Set @code{enable_sgpr_workgroup_info} flag.
4526 @item private_segment_wave_offset
4527 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4528 (required to locate the stack).
4530 @item work_item_id_X
4531 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4533 @item work_item_id_Y
4534 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4537 @item work_item_id_Z
4538 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4544 @node ARC Function Attributes
4545 @subsection ARC Function Attributes
4547 These function attributes are supported by the ARC back end:
4551 @cindex @code{interrupt} function attribute, ARC
4552 Use this attribute to indicate
4553 that the specified function is an interrupt handler. The compiler generates
4554 function entry and exit sequences suitable for use in an interrupt handler
4555 when this attribute is present.
4557 On the ARC, you must specify the kind of interrupt to be handled
4558 in a parameter to the interrupt attribute like this:
4561 void f () __attribute__ ((interrupt ("ilink1")));
4564 Permissible values for this parameter are: @w{@code{ilink1}} and
4565 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
4566 @w{@code{firq}} for ARCv2 architecture.
4571 @cindex @code{long_call} function attribute, ARC
4572 @cindex @code{medium_call} function attribute, ARC
4573 @cindex @code{short_call} function attribute, ARC
4574 @cindex indirect calls, ARC
4575 These attributes specify how a particular function is called.
4576 These attributes override the
4577 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4578 command-line switches and @code{#pragma long_calls} settings.
4580 For ARC, a function marked with the @code{long_call} attribute is
4581 always called using register-indirect jump-and-link instructions,
4582 thereby enabling the called function to be placed anywhere within the
4583 32-bit address space. A function marked with the @code{medium_call}
4584 attribute will always be close enough to be called with an unconditional
4585 branch-and-link instruction, which has a 25-bit offset from
4586 the call site. A function marked with the @code{short_call}
4587 attribute will always be close enough to be called with a conditional
4588 branch-and-link instruction, which has a 21-bit offset from
4592 @cindex @code{jli_always} function attribute, ARC
4593 Forces a particular function to be called using @code{jli}
4594 instruction. The @code{jli} instruction makes use of a table stored
4595 into @code{.jlitab} section, which holds the location of the functions
4596 which are addressed using this instruction.
4599 @cindex @code{jli_fixed} function attribute, ARC
4600 Identical like the above one, but the location of the function in the
4601 @code{jli} table is known and given as an attribute parameter.
4604 @cindex @code{secure_call} function attribute, ARC
4605 This attribute allows one to mark secure-code functions that are
4606 callable from normal mode. The location of the secure call function
4607 into the @code{sjli} table needs to be passed as argument.
4610 @cindex @code{naked} function attribute, ARC
4611 This attribute allows the compiler to construct the requisite function
4612 declaration, while allowing the body of the function to be assembly
4613 code. The specified function will not have prologue/epilogue
4614 sequences generated by the compiler. Only basic @code{asm} statements
4615 can safely be included in naked functions (@pxref{Basic Asm}). While
4616 using extended @code{asm} or a mixture of basic @code{asm} and C code
4617 may appear to work, they cannot be depended upon to work reliably and
4622 @node ARM Function Attributes
4623 @subsection ARM Function Attributes
4625 These function attributes are supported for ARM targets:
4629 @item general-regs-only
4630 @cindex @code{general-regs-only} function attribute, ARM
4631 Indicates that no floating-point or Advanced SIMD registers should be
4632 used when generating code for this function. If the function explicitly
4633 uses floating-point code, then the compiler gives an error. This is
4634 the same behavior as that of the command-line option
4635 @option{-mgeneral-regs-only}.
4638 @cindex @code{interrupt} function attribute, ARM
4639 Use this attribute to indicate
4640 that the specified function is an interrupt handler. The compiler generates
4641 function entry and exit sequences suitable for use in an interrupt handler
4642 when this attribute is present.
4644 You can specify the kind of interrupt to be handled by
4645 adding an optional parameter to the interrupt attribute like this:
4648 void f () __attribute__ ((interrupt ("IRQ")));
4652 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4653 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4655 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4656 may be called with a word-aligned stack pointer.
4659 @cindex @code{isr} function attribute, ARM
4660 Use this attribute on ARM to write Interrupt Service Routines. This is an
4661 alias to the @code{interrupt} attribute above.
4665 @cindex @code{long_call} function attribute, ARM
4666 @cindex @code{short_call} function attribute, ARM
4667 @cindex indirect calls, ARM
4668 These attributes specify how a particular function is called.
4669 These attributes override the
4670 @option{-mlong-calls} (@pxref{ARM Options})
4671 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4672 @code{long_call} attribute indicates that the function might be far
4673 away from the call site and require a different (more expensive)
4674 calling sequence. The @code{short_call} attribute always places
4675 the offset to the function from the call site into the @samp{BL}
4676 instruction directly.
4679 @cindex @code{naked} function attribute, ARM
4680 This attribute allows the compiler to construct the
4681 requisite function declaration, while allowing the body of the
4682 function to be assembly code. The specified function will not have
4683 prologue/epilogue sequences generated by the compiler. Only basic
4684 @code{asm} statements can safely be included in naked functions
4685 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4686 basic @code{asm} and C code may appear to work, they cannot be
4687 depended upon to work reliably and are not supported.
4690 @cindex @code{pcs} function attribute, ARM
4692 The @code{pcs} attribute can be used to control the calling convention
4693 used for a function on ARM. The attribute takes an argument that specifies
4694 the calling convention to use.
4696 When compiling using the AAPCS ABI (or a variant of it) then valid
4697 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4698 order to use a variant other than @code{"aapcs"} then the compiler must
4699 be permitted to use the appropriate co-processor registers (i.e., the
4700 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4704 /* Argument passed in r0, and result returned in r0+r1. */
4705 double f2d (float) __attribute__((pcs("aapcs")));
4708 Variadic functions always use the @code{"aapcs"} calling convention and
4709 the compiler rejects attempts to specify an alternative.
4711 @item target (@var{options})
4712 @cindex @code{target} function attribute
4713 As discussed in @ref{Common Function Attributes}, this attribute
4714 allows specification of target-specific compilation options.
4716 On ARM, the following options are allowed:
4720 @cindex @code{target("thumb")} function attribute, ARM
4721 Force code generation in the Thumb (T16/T32) ISA, depending on the
4725 @cindex @code{target("arm")} function attribute, ARM
4726 Force code generation in the ARM (A32) ISA.
4728 Functions from different modes can be inlined in the caller's mode.
4731 @cindex @code{target("fpu=")} function attribute, ARM
4732 Specifies the fpu for which to tune the performance of this function.
4733 The behavior and permissible arguments are the same as for the @option{-mfpu=}
4734 command-line option.
4737 @cindex @code{arch=} function attribute, ARM
4738 Specifies the architecture version and architectural extensions to use
4739 for this function. The behavior and permissible arguments are the same as
4740 for the @option{-march=} command-line option.
4742 The above target attributes can be specified as follows:
4745 __attribute__((target("arch=armv8-a+crc")))
4753 Additionally, the architectural extension string may be specified on its
4754 own. This can be used to turn on and off particular architectural extensions
4755 without having to specify a particular architecture version or core. Example:
4758 __attribute__((target("+crc+nocrypto")))
4766 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4767 extension and disables the @code{crypto} extension for the function @code{foo}
4768 without modifying an existing @option{-march=} or @option{-mcpu} option.
4774 @node AVR Function Attributes
4775 @subsection AVR Function Attributes
4777 These function attributes are supported by the AVR back end:
4781 @cindex @code{interrupt} function attribute, AVR
4782 Use this attribute to indicate
4783 that the specified function is an interrupt handler. The compiler generates
4784 function entry and exit sequences suitable for use in an interrupt handler
4785 when this attribute is present.
4787 On the AVR, the hardware globally disables interrupts when an
4788 interrupt is executed. The first instruction of an interrupt handler
4789 declared with this attribute is a @code{SEI} instruction to
4790 re-enable interrupts. See also the @code{signal} function attribute
4791 that does not insert a @code{SEI} instruction. If both @code{signal} and
4792 @code{interrupt} are specified for the same function, @code{signal}
4793 is silently ignored.
4796 @cindex @code{naked} function attribute, AVR
4797 This attribute allows the compiler to construct the
4798 requisite function declaration, while allowing the body of the
4799 function to be assembly code. The specified function will not have
4800 prologue/epilogue sequences generated by the compiler. Only basic
4801 @code{asm} statements can safely be included in naked functions
4802 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4803 basic @code{asm} and C code may appear to work, they cannot be
4804 depended upon to work reliably and are not supported.
4807 @cindex @code{no_gccisr} function attribute, AVR
4808 Do not use @code{__gcc_isr} pseudo instructions in a function with
4809 the @code{interrupt} or @code{signal} attribute aka. interrupt
4810 service routine (ISR).
4811 Use this attribute if the preamble of the ISR prologue should always read
4815 in __tmp_reg__, __SREG__
4819 and accordingly for the postamble of the epilogue --- no matter whether
4820 the mentioned registers are actually used in the ISR or not.
4821 Situations where you might want to use this attribute include:
4824 Code that (effectively) clobbers bits of @code{SREG} other than the
4825 @code{I}-flag by writing to the memory location of @code{SREG}.
4827 Code that uses inline assembler to jump to a different function which
4828 expects (parts of) the prologue code as outlined above to be present.
4830 To disable @code{__gcc_isr} generation for the whole compilation unit,
4831 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
4835 @cindex @code{OS_main} function attribute, AVR
4836 @cindex @code{OS_task} function attribute, AVR
4837 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
4838 do not save/restore any call-saved register in their prologue/epilogue.
4840 The @code{OS_main} attribute can be used when there @emph{is
4841 guarantee} that interrupts are disabled at the time when the function
4842 is entered. This saves resources when the stack pointer has to be
4843 changed to set up a frame for local variables.
4845 The @code{OS_task} attribute can be used when there is @emph{no
4846 guarantee} that interrupts are disabled at that time when the function
4847 is entered like for, e@.g@. task functions in a multi-threading operating
4848 system. In that case, changing the stack pointer register is
4849 guarded by save/clear/restore of the global interrupt enable flag.
4851 The differences to the @code{naked} function attribute are:
4853 @item @code{naked} functions do not have a return instruction whereas
4854 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
4855 @code{RETI} return instruction.
4856 @item @code{naked} functions do not set up a frame for local variables
4857 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
4862 @cindex @code{signal} function attribute, AVR
4863 Use this attribute on the AVR to indicate that the specified
4864 function is an interrupt handler. The compiler generates function
4865 entry and exit sequences suitable for use in an interrupt handler when this
4866 attribute is present.
4868 See also the @code{interrupt} function attribute.
4870 The AVR hardware globally disables interrupts when an interrupt is executed.
4871 Interrupt handler functions defined with the @code{signal} attribute
4872 do not re-enable interrupts. It is save to enable interrupts in a
4873 @code{signal} handler. This ``save'' only applies to the code
4874 generated by the compiler and not to the IRQ layout of the
4875 application which is responsibility of the application.
4877 If both @code{signal} and @code{interrupt} are specified for the same
4878 function, @code{signal} is silently ignored.
4881 @node Blackfin Function Attributes
4882 @subsection Blackfin Function Attributes
4884 These function attributes are supported by the Blackfin back end:
4888 @item exception_handler
4889 @cindex @code{exception_handler} function attribute
4890 @cindex exception handler functions, Blackfin
4891 Use this attribute on the Blackfin to indicate that the specified function
4892 is an exception handler. The compiler generates function entry and
4893 exit sequences suitable for use in an exception handler when this
4894 attribute is present.
4896 @item interrupt_handler
4897 @cindex @code{interrupt_handler} function attribute, Blackfin
4898 Use this attribute to
4899 indicate that the specified function is an interrupt handler. The compiler
4900 generates function entry and exit sequences suitable for use in an
4901 interrupt handler when this attribute is present.
4904 @cindex @code{kspisusp} function attribute, Blackfin
4905 @cindex User stack pointer in interrupts on the Blackfin
4906 When used together with @code{interrupt_handler}, @code{exception_handler}
4907 or @code{nmi_handler}, code is generated to load the stack pointer
4908 from the USP register in the function prologue.
4911 @cindex @code{l1_text} function attribute, Blackfin
4912 This attribute specifies a function to be placed into L1 Instruction
4913 SRAM@. The function is put into a specific section named @code{.l1.text}.
4914 With @option{-mfdpic}, function calls with a such function as the callee
4915 or caller uses inlined PLT.
4918 @cindex @code{l2} function attribute, Blackfin
4919 This attribute specifies a function to be placed into L2
4920 SRAM. The function is put into a specific section named
4921 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
4926 @cindex indirect calls, Blackfin
4927 @cindex @code{longcall} function attribute, Blackfin
4928 @cindex @code{shortcall} function attribute, Blackfin
4929 The @code{longcall} attribute
4930 indicates that the function might be far away from the call site and
4931 require a different (more expensive) calling sequence. The
4932 @code{shortcall} attribute indicates that the function is always close
4933 enough for the shorter calling sequence to be used. These attributes
4934 override the @option{-mlongcall} switch.
4937 @cindex @code{nesting} function attribute, Blackfin
4938 @cindex Allow nesting in an interrupt handler on the Blackfin processor
4939 Use this attribute together with @code{interrupt_handler},
4940 @code{exception_handler} or @code{nmi_handler} to indicate that the function
4941 entry code should enable nested interrupts or exceptions.
4944 @cindex @code{nmi_handler} function attribute, Blackfin
4945 @cindex NMI handler functions on the Blackfin processor
4946 Use this attribute on the Blackfin to indicate that the specified function
4947 is an NMI handler. The compiler generates function entry and
4948 exit sequences suitable for use in an NMI handler when this
4949 attribute is present.
4952 @cindex @code{saveall} function attribute, Blackfin
4953 @cindex save all registers on the Blackfin
4954 Use this attribute to indicate that
4955 all registers except the stack pointer should be saved in the prologue
4956 regardless of whether they are used or not.
4959 @node BPF Function Attributes
4960 @subsection BPF Function Attributes
4962 These function attributes are supported by the BPF back end:
4966 @cindex @code{kernel helper}, function attribute, BPF
4967 use this attribute to indicate the specified function declaration is a
4968 kernel helper. The helper function is passed as an argument to the
4972 int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
4973 __attribute__ ((kernel_helper (4)));
4977 @node CR16 Function Attributes
4978 @subsection CR16 Function Attributes
4980 These function attributes are supported by the CR16 back end:
4984 @cindex @code{interrupt} function attribute, CR16
4985 Use this attribute to indicate
4986 that the specified function is an interrupt handler. The compiler generates
4987 function entry and exit sequences suitable for use in an interrupt handler
4988 when this attribute is present.
4991 @node C-SKY Function Attributes
4992 @subsection C-SKY Function Attributes
4994 These function attributes are supported by the C-SKY back end:
4999 @cindex @code{interrupt} function attribute, C-SKY
5000 @cindex @code{isr} function attribute, C-SKY
5001 Use these attributes to indicate that the specified function
5002 is an interrupt handler.
5003 The compiler generates function entry and exit sequences suitable for
5004 use in an interrupt handler when either of these attributes are present.
5006 Use of these options requires the @option{-mistack} command-line option
5007 to enable support for the necessary interrupt stack instructions. They
5008 are ignored with a warning otherwise. @xref{C-SKY Options}.
5011 @cindex @code{naked} function attribute, C-SKY
5012 This attribute allows the compiler to construct the
5013 requisite function declaration, while allowing the body of the
5014 function to be assembly code. The specified function will not have
5015 prologue/epilogue sequences generated by the compiler. Only basic
5016 @code{asm} statements can safely be included in naked functions
5017 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5018 basic @code{asm} and C code may appear to work, they cannot be
5019 depended upon to work reliably and are not supported.
5023 @node Epiphany Function Attributes
5024 @subsection Epiphany Function Attributes
5026 These function attributes are supported by the Epiphany back end:
5030 @cindex @code{disinterrupt} function attribute, Epiphany
5031 This attribute causes the compiler to emit
5032 instructions to disable interrupts for the duration of the given
5035 @item forwarder_section
5036 @cindex @code{forwarder_section} function attribute, Epiphany
5037 This attribute modifies the behavior of an interrupt handler.
5038 The interrupt handler may be in external memory which cannot be
5039 reached by a branch instruction, so generate a local memory trampoline
5040 to transfer control. The single parameter identifies the section where
5041 the trampoline is placed.
5044 @cindex @code{interrupt} function attribute, Epiphany
5045 Use this attribute to indicate
5046 that the specified function is an interrupt handler. The compiler generates
5047 function entry and exit sequences suitable for use in an interrupt handler
5048 when this attribute is present. It may also generate
5049 a special section with code to initialize the interrupt vector table.
5051 On Epiphany targets one or more optional parameters can be added like this:
5054 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
5057 Permissible values for these parameters are: @w{@code{reset}},
5058 @w{@code{software_exception}}, @w{@code{page_miss}},
5059 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
5060 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
5061 Multiple parameters indicate that multiple entries in the interrupt
5062 vector table should be initialized for this function, i.e.@: for each
5063 parameter @w{@var{name}}, a jump to the function is emitted in
5064 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
5065 entirely, in which case no interrupt vector table entry is provided.
5067 Note that interrupts are enabled inside the function
5068 unless the @code{disinterrupt} attribute is also specified.
5070 The following examples are all valid uses of these attributes on
5073 void __attribute__ ((interrupt)) universal_handler ();
5074 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
5075 void __attribute__ ((interrupt ("dma0, dma1")))
5076 universal_dma_handler ();
5077 void __attribute__ ((interrupt ("timer0"), disinterrupt))
5078 fast_timer_handler ();
5079 void __attribute__ ((interrupt ("dma0, dma1"),
5080 forwarder_section ("tramp")))
5081 external_dma_handler ();
5086 @cindex @code{long_call} function attribute, Epiphany
5087 @cindex @code{short_call} function attribute, Epiphany
5088 @cindex indirect calls, Epiphany
5089 These attributes specify how a particular function is called.
5090 These attributes override the
5091 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
5092 command-line switch and @code{#pragma long_calls} settings.
5096 @node H8/300 Function Attributes
5097 @subsection H8/300 Function Attributes
5099 These function attributes are available for H8/300 targets:
5102 @item function_vector
5103 @cindex @code{function_vector} function attribute, H8/300
5104 Use this attribute on the H8/300, H8/300H, and H8S to indicate
5105 that the specified function should be called through the function vector.
5106 Calling a function through the function vector reduces code size; however,
5107 the function vector has a limited size (maximum 128 entries on the H8/300
5108 and 64 entries on the H8/300H and H8S)
5109 and shares space with the interrupt vector.
5111 @item interrupt_handler
5112 @cindex @code{interrupt_handler} function attribute, H8/300
5113 Use this attribute on the H8/300, H8/300H, and H8S to
5114 indicate that the specified function is an interrupt handler. The compiler
5115 generates function entry and exit sequences suitable for use in an
5116 interrupt handler when this attribute is present.
5119 @cindex @code{saveall} function attribute, H8/300
5120 @cindex save all registers on the H8/300, H8/300H, and H8S
5121 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
5122 all registers except the stack pointer should be saved in the prologue
5123 regardless of whether they are used or not.
5126 @node IA-64 Function Attributes
5127 @subsection IA-64 Function Attributes
5129 These function attributes are supported on IA-64 targets:
5132 @item syscall_linkage
5133 @cindex @code{syscall_linkage} function attribute, IA-64
5134 This attribute is used to modify the IA-64 calling convention by marking
5135 all input registers as live at all function exits. This makes it possible
5136 to restart a system call after an interrupt without having to save/restore
5137 the input registers. This also prevents kernel data from leaking into
5141 @cindex @code{version_id} function attribute, IA-64
5142 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
5143 symbol to contain a version string, thus allowing for function level
5144 versioning. HP-UX system header files may use function level versioning
5145 for some system calls.
5148 extern int foo () __attribute__((version_id ("20040821")));
5152 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
5155 @node M32C Function Attributes
5156 @subsection M32C Function Attributes
5158 These function attributes are supported by the M32C back end:
5162 @cindex @code{bank_switch} function attribute, M32C
5163 When added to an interrupt handler with the M32C port, causes the
5164 prologue and epilogue to use bank switching to preserve the registers
5165 rather than saving them on the stack.
5167 @item fast_interrupt
5168 @cindex @code{fast_interrupt} function attribute, M32C
5169 Use this attribute on the M32C port to indicate that the specified
5170 function is a fast interrupt handler. This is just like the
5171 @code{interrupt} attribute, except that @code{freit} is used to return
5172 instead of @code{reit}.
5174 @item function_vector
5175 @cindex @code{function_vector} function attribute, M16C/M32C
5176 On M16C/M32C targets, the @code{function_vector} attribute declares a
5177 special page subroutine call function. Use of this attribute reduces
5178 the code size by 2 bytes for each call generated to the
5179 subroutine. The argument to the attribute is the vector number entry
5180 from the special page vector table which contains the 16 low-order
5181 bits of the subroutine's entry address. Each vector table has special
5182 page number (18 to 255) that is used in @code{jsrs} instructions.
5183 Jump addresses of the routines are generated by adding 0x0F0000 (in
5184 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
5185 2-byte addresses set in the vector table. Therefore you need to ensure
5186 that all the special page vector routines should get mapped within the
5187 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
5190 In the following example 2 bytes are saved for each call to
5191 function @code{foo}.
5194 void foo (void) __attribute__((function_vector(0x18)));
5205 If functions are defined in one file and are called in another file,
5206 then be sure to write this declaration in both files.
5208 This attribute is ignored for R8C target.
5211 @cindex @code{interrupt} function attribute, M32C
5212 Use this attribute to indicate
5213 that the specified function is an interrupt handler. The compiler generates
5214 function entry and exit sequences suitable for use in an interrupt handler
5215 when this attribute is present.
5218 @node M32R/D Function Attributes
5219 @subsection M32R/D Function Attributes
5221 These function attributes are supported by the M32R/D back end:
5225 @cindex @code{interrupt} function attribute, M32R/D
5226 Use this attribute to indicate
5227 that the specified function is an interrupt handler. The compiler generates
5228 function entry and exit sequences suitable for use in an interrupt handler
5229 when this attribute is present.
5231 @item model (@var{model-name})
5232 @cindex @code{model} function attribute, M32R/D
5233 @cindex function addressability on the M32R/D
5235 On the M32R/D, use this attribute to set the addressability of an
5236 object, and of the code generated for a function. The identifier
5237 @var{model-name} is one of @code{small}, @code{medium}, or
5238 @code{large}, representing each of the code models.
5240 Small model objects live in the lower 16MB of memory (so that their
5241 addresses can be loaded with the @code{ld24} instruction), and are
5242 callable with the @code{bl} instruction.
5244 Medium model objects may live anywhere in the 32-bit address space (the
5245 compiler generates @code{seth/add3} instructions to load their addresses),
5246 and are callable with the @code{bl} instruction.
5248 Large model objects may live anywhere in the 32-bit address space (the
5249 compiler generates @code{seth/add3} instructions to load their addresses),
5250 and may not be reachable with the @code{bl} instruction (the compiler
5251 generates the much slower @code{seth/add3/jl} instruction sequence).
5254 @node m68k Function Attributes
5255 @subsection m68k Function Attributes
5257 These function attributes are supported by the m68k back end:
5261 @itemx interrupt_handler
5262 @cindex @code{interrupt} function attribute, m68k
5263 @cindex @code{interrupt_handler} function attribute, m68k
5264 Use this attribute to
5265 indicate that the specified function is an interrupt handler. The compiler
5266 generates function entry and exit sequences suitable for use in an
5267 interrupt handler when this attribute is present. Either name may be used.
5269 @item interrupt_thread
5270 @cindex @code{interrupt_thread} function attribute, fido
5271 Use this attribute on fido, a subarchitecture of the m68k, to indicate
5272 that the specified function is an interrupt handler that is designed
5273 to run as a thread. The compiler omits generate prologue/epilogue
5274 sequences and replaces the return instruction with a @code{sleep}
5275 instruction. This attribute is available only on fido.
5278 @node MCORE Function Attributes
5279 @subsection MCORE Function Attributes
5281 These function attributes are supported by the MCORE back end:
5285 @cindex @code{naked} function attribute, MCORE
5286 This attribute allows the compiler to construct the
5287 requisite function declaration, while allowing the body of the
5288 function to be assembly code. The specified function will not have
5289 prologue/epilogue sequences generated by the compiler. Only basic
5290 @code{asm} statements can safely be included in naked functions
5291 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5292 basic @code{asm} and C code may appear to work, they cannot be
5293 depended upon to work reliably and are not supported.
5296 @node MeP Function Attributes
5297 @subsection MeP Function Attributes
5299 These function attributes are supported by the MeP back end:
5303 @cindex @code{disinterrupt} function attribute, MeP
5304 On MeP targets, this attribute causes the compiler to emit
5305 instructions to disable interrupts for the duration of the given
5309 @cindex @code{interrupt} function attribute, MeP
5310 Use this attribute to indicate
5311 that the specified function is an interrupt handler. The compiler generates
5312 function entry and exit sequences suitable for use in an interrupt handler
5313 when this attribute is present.
5316 @cindex @code{near} function attribute, MeP
5317 This attribute causes the compiler to assume the called
5318 function is close enough to use the normal calling convention,
5319 overriding the @option{-mtf} command-line option.
5322 @cindex @code{far} function attribute, MeP
5323 On MeP targets this causes the compiler to use a calling convention
5324 that assumes the called function is too far away for the built-in
5328 @cindex @code{vliw} function attribute, MeP
5329 The @code{vliw} attribute tells the compiler to emit
5330 instructions in VLIW mode instead of core mode. Note that this
5331 attribute is not allowed unless a VLIW coprocessor has been configured
5332 and enabled through command-line options.
5335 @node MicroBlaze Function Attributes
5336 @subsection MicroBlaze Function Attributes
5338 These function attributes are supported on MicroBlaze targets:
5341 @item save_volatiles
5342 @cindex @code{save_volatiles} function attribute, MicroBlaze
5343 Use this attribute to indicate that the function is
5344 an interrupt handler. All volatile registers (in addition to non-volatile
5345 registers) are saved in the function prologue. If the function is a leaf
5346 function, only volatiles used by the function are saved. A normal function
5347 return is generated instead of a return from interrupt.
5350 @cindex @code{break_handler} function attribute, MicroBlaze
5351 @cindex break handler functions
5352 Use this attribute to indicate that
5353 the specified function is a break handler. The compiler generates function
5354 entry and exit sequences suitable for use in an break handler when this
5355 attribute is present. The return from @code{break_handler} is done through
5356 the @code{rtbd} instead of @code{rtsd}.
5359 void f () __attribute__ ((break_handler));
5362 @item interrupt_handler
5363 @itemx fast_interrupt
5364 @cindex @code{interrupt_handler} function attribute, MicroBlaze
5365 @cindex @code{fast_interrupt} function attribute, MicroBlaze
5366 These attributes indicate that the specified function is an interrupt
5367 handler. Use the @code{fast_interrupt} attribute to indicate handlers
5368 used in low-latency interrupt mode, and @code{interrupt_handler} for
5369 interrupts that do not use low-latency handlers. In both cases, GCC
5370 emits appropriate prologue code and generates a return from the handler
5371 using @code{rtid} instead of @code{rtsd}.
5374 @node Microsoft Windows Function Attributes
5375 @subsection Microsoft Windows Function Attributes
5377 The following attributes are available on Microsoft Windows and Symbian OS
5382 @cindex @code{dllexport} function attribute
5383 @cindex @code{__declspec(dllexport)}
5384 On Microsoft Windows targets and Symbian OS targets the
5385 @code{dllexport} attribute causes the compiler to provide a global
5386 pointer to a pointer in a DLL, so that it can be referenced with the
5387 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
5388 name is formed by combining @code{_imp__} and the function or variable
5391 You can use @code{__declspec(dllexport)} as a synonym for
5392 @code{__attribute__ ((dllexport))} for compatibility with other
5395 On systems that support the @code{visibility} attribute, this
5396 attribute also implies ``default'' visibility. It is an error to
5397 explicitly specify any other visibility.
5399 GCC's default behavior is to emit all inline functions with the
5400 @code{dllexport} attribute. Since this can cause object file-size bloat,
5401 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
5402 ignore the attribute for inlined functions unless the
5403 @option{-fkeep-inline-functions} flag is used instead.
5405 The attribute is ignored for undefined symbols.
5407 When applied to C++ classes, the attribute marks defined non-inlined
5408 member functions and static data members as exports. Static consts
5409 initialized in-class are not marked unless they are also defined
5412 For Microsoft Windows targets there are alternative methods for
5413 including the symbol in the DLL's export table such as using a
5414 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
5415 the @option{--export-all} linker flag.
5418 @cindex @code{dllimport} function attribute
5419 @cindex @code{__declspec(dllimport)}
5420 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
5421 attribute causes the compiler to reference a function or variable via
5422 a global pointer to a pointer that is set up by the DLL exporting the
5423 symbol. The attribute implies @code{extern}. On Microsoft Windows
5424 targets, the pointer name is formed by combining @code{_imp__} and the
5425 function or variable name.
5427 You can use @code{__declspec(dllimport)} as a synonym for
5428 @code{__attribute__ ((dllimport))} for compatibility with other
5431 On systems that support the @code{visibility} attribute, this
5432 attribute also implies ``default'' visibility. It is an error to
5433 explicitly specify any other visibility.
5435 Currently, the attribute is ignored for inlined functions. If the
5436 attribute is applied to a symbol @emph{definition}, an error is reported.
5437 If a symbol previously declared @code{dllimport} is later defined, the
5438 attribute is ignored in subsequent references, and a warning is emitted.
5439 The attribute is also overridden by a subsequent declaration as
5442 When applied to C++ classes, the attribute marks non-inlined
5443 member functions and static data members as imports. However, the
5444 attribute is ignored for virtual methods to allow creation of vtables
5447 On the SH Symbian OS target the @code{dllimport} attribute also has
5448 another affect---it can cause the vtable and run-time type information
5449 for a class to be exported. This happens when the class has a
5450 dllimported constructor or a non-inline, non-pure virtual function
5451 and, for either of those two conditions, the class also has an inline
5452 constructor or destructor and has a key function that is defined in
5453 the current translation unit.
5455 For Microsoft Windows targets the use of the @code{dllimport}
5456 attribute on functions is not necessary, but provides a small
5457 performance benefit by eliminating a thunk in the DLL@. The use of the
5458 @code{dllimport} attribute on imported variables can be avoided by passing the
5459 @option{--enable-auto-import} switch to the GNU linker. As with
5460 functions, using the attribute for a variable eliminates a thunk in
5463 One drawback to using this attribute is that a pointer to a
5464 @emph{variable} marked as @code{dllimport} cannot be used as a constant
5465 address. However, a pointer to a @emph{function} with the
5466 @code{dllimport} attribute can be used as a constant initializer; in
5467 this case, the address of a stub function in the import lib is
5468 referenced. On Microsoft Windows targets, the attribute can be disabled
5469 for functions by setting the @option{-mnop-fun-dllimport} flag.
5472 @node MIPS Function Attributes
5473 @subsection MIPS Function Attributes
5475 These function attributes are supported by the MIPS back end:
5479 @cindex @code{interrupt} function attribute, MIPS
5480 Use this attribute to indicate that the specified function is an interrupt
5481 handler. The compiler generates function entry and exit sequences suitable
5482 for use in an interrupt handler when this attribute is present.
5483 An optional argument is supported for the interrupt attribute which allows
5484 the interrupt mode to be described. By default GCC assumes the external
5485 interrupt controller (EIC) mode is in use, this can be explicitly set using
5486 @code{eic}. When interrupts are non-masked then the requested Interrupt
5487 Priority Level (IPL) is copied to the current IPL which has the effect of only
5488 enabling higher priority interrupts. To use vectored interrupt mode use
5489 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
5490 the behavior of the non-masked interrupt support and GCC will arrange to mask
5491 all interrupts from sw0 up to and including the specified interrupt vector.
5493 You can use the following attributes to modify the behavior
5494 of an interrupt handler:
5496 @item use_shadow_register_set
5497 @cindex @code{use_shadow_register_set} function attribute, MIPS
5498 Assume that the handler uses a shadow register set, instead of
5499 the main general-purpose registers. An optional argument @code{intstack} is
5500 supported to indicate that the shadow register set contains a valid stack
5503 @item keep_interrupts_masked
5504 @cindex @code{keep_interrupts_masked} function attribute, MIPS
5505 Keep interrupts masked for the whole function. Without this attribute,
5506 GCC tries to reenable interrupts for as much of the function as it can.
5508 @item use_debug_exception_return
5509 @cindex @code{use_debug_exception_return} function attribute, MIPS
5510 Return using the @code{deret} instruction. Interrupt handlers that don't
5511 have this attribute return using @code{eret} instead.
5514 You can use any combination of these attributes, as shown below:
5516 void __attribute__ ((interrupt)) v0 ();
5517 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5518 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5519 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5520 void __attribute__ ((interrupt, use_shadow_register_set,
5521 keep_interrupts_masked)) v4 ();
5522 void __attribute__ ((interrupt, use_shadow_register_set,
5523 use_debug_exception_return)) v5 ();
5524 void __attribute__ ((interrupt, keep_interrupts_masked,
5525 use_debug_exception_return)) v6 ();
5526 void __attribute__ ((interrupt, use_shadow_register_set,
5527 keep_interrupts_masked,
5528 use_debug_exception_return)) v7 ();
5529 void __attribute__ ((interrupt("eic"))) v8 ();
5530 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5537 @cindex indirect calls, MIPS
5538 @cindex @code{long_call} function attribute, MIPS
5539 @cindex @code{short_call} function attribute, MIPS
5540 @cindex @code{near} function attribute, MIPS
5541 @cindex @code{far} function attribute, MIPS
5542 These attributes specify how a particular function is called on MIPS@.
5543 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5544 command-line switch. The @code{long_call} and @code{far} attributes are
5545 synonyms, and cause the compiler to always call
5546 the function by first loading its address into a register, and then using
5547 the contents of that register. The @code{short_call} and @code{near}
5548 attributes are synonyms, and have the opposite
5549 effect; they specify that non-PIC calls should be made using the more
5550 efficient @code{jal} instruction.
5554 @cindex @code{mips16} function attribute, MIPS
5555 @cindex @code{nomips16} function attribute, MIPS
5557 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5558 function attributes to locally select or turn off MIPS16 code generation.
5559 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5560 while MIPS16 code generation is disabled for functions with the
5561 @code{nomips16} attribute. These attributes override the
5562 @option{-mips16} and @option{-mno-mips16} options on the command line
5563 (@pxref{MIPS Options}).
5565 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5566 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5567 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5568 may interact badly with some GCC extensions such as @code{__builtin_apply}
5569 (@pxref{Constructing Calls}).
5571 @item micromips, MIPS
5572 @itemx nomicromips, MIPS
5573 @cindex @code{micromips} function attribute
5574 @cindex @code{nomicromips} function attribute
5576 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5577 function attributes to locally select or turn off microMIPS code generation.
5578 A function with the @code{micromips} attribute is emitted as microMIPS code,
5579 while microMIPS code generation is disabled for functions with the
5580 @code{nomicromips} attribute. These attributes override the
5581 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5582 (@pxref{MIPS Options}).
5584 When compiling files containing mixed microMIPS and non-microMIPS code, the
5585 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5587 not that within individual functions. Mixed microMIPS and non-microMIPS code
5588 may interact badly with some GCC extensions such as @code{__builtin_apply}
5589 (@pxref{Constructing Calls}).
5592 @cindex @code{nocompression} function attribute, MIPS
5593 On MIPS targets, you can use the @code{nocompression} function attribute
5594 to locally turn off MIPS16 and microMIPS code generation. This attribute
5595 overrides the @option{-mips16} and @option{-mmicromips} options on the
5596 command line (@pxref{MIPS Options}).
5599 @node MSP430 Function Attributes
5600 @subsection MSP430 Function Attributes
5602 These function attributes are supported by the MSP430 back end:
5606 @cindex @code{critical} function attribute, MSP430
5607 Critical functions disable interrupts upon entry and restore the
5608 previous interrupt state upon exit. Critical functions cannot also
5609 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5611 The MSP430 hardware ensures that interrupts are disabled on entry to
5612 @code{interrupt} functions, and restores the previous interrupt state
5613 on exit. The @code{critical} attribute is therefore redundant on
5614 @code{interrupt} functions.
5617 @cindex @code{interrupt} function attribute, MSP430
5618 Use this attribute to indicate
5619 that the specified function is an interrupt handler. The compiler generates
5620 function entry and exit sequences suitable for use in an interrupt handler
5621 when this attribute is present.
5623 You can provide an argument to the interrupt
5624 attribute which specifies a name or number. If the argument is a
5625 number it indicates the slot in the interrupt vector table (0 - 31) to
5626 which this handler should be assigned. If the argument is a name it
5627 is treated as a symbolic name for the vector slot. These names should
5628 match up with appropriate entries in the linker script. By default
5629 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5630 @code{reset} for vector 31 are recognized.
5633 @cindex @code{naked} function attribute, MSP430
5634 This attribute allows the compiler to construct the
5635 requisite function declaration, while allowing the body of the
5636 function to be assembly code. The specified function will not have
5637 prologue/epilogue sequences generated by the compiler. Only basic
5638 @code{asm} statements can safely be included in naked functions
5639 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5640 basic @code{asm} and C code may appear to work, they cannot be
5641 depended upon to work reliably and are not supported.
5644 @cindex @code{reentrant} function attribute, MSP430
5645 Reentrant functions disable interrupts upon entry and enable them
5646 upon exit. Reentrant functions cannot also have the @code{naked}
5647 or @code{critical} attributes. They can have the @code{interrupt}
5651 @cindex @code{wakeup} function attribute, MSP430
5652 This attribute only applies to interrupt functions. It is silently
5653 ignored if applied to a non-interrupt function. A wakeup interrupt
5654 function will rouse the processor from any low-power state that it
5655 might be in when the function exits.
5660 @cindex @code{lower} function attribute, MSP430
5661 @cindex @code{upper} function attribute, MSP430
5662 @cindex @code{either} function attribute, MSP430
5663 On the MSP430 target these attributes can be used to specify whether
5664 the function or variable should be placed into low memory, high
5665 memory, or the placement should be left to the linker to decide. The
5666 attributes are only significant if compiling for the MSP430X
5667 architecture in the large memory model.
5669 The attributes work in conjunction with a linker script that has been
5670 augmented to specify where to place sections with a @code{.lower} and
5671 a @code{.upper} prefix. So, for example, as well as placing the
5672 @code{.data} section, the script also specifies the placement of a
5673 @code{.lower.data} and a @code{.upper.data} section. The intention
5674 is that @code{lower} sections are placed into a small but easier to
5675 access memory region and the upper sections are placed into a larger, but
5676 slower to access, region.
5678 The @code{either} attribute is special. It tells the linker to place
5679 the object into the corresponding @code{lower} section if there is
5680 room for it. If there is insufficient room then the object is placed
5681 into the corresponding @code{upper} section instead. Note that the
5682 placement algorithm is not very sophisticated. It does not attempt to
5683 find an optimal packing of the @code{lower} sections. It just makes
5684 one pass over the objects and does the best that it can. Using the
5685 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5686 options can help the packing, however, since they produce smaller,
5687 easier to pack regions.
5690 @node NDS32 Function Attributes
5691 @subsection NDS32 Function Attributes
5693 These function attributes are supported by the NDS32 back end:
5697 @cindex @code{exception} function attribute
5698 @cindex exception handler functions, NDS32
5699 Use this attribute on the NDS32 target to indicate that the specified function
5700 is an exception handler. The compiler will generate corresponding sections
5701 for use in an exception handler.
5704 @cindex @code{interrupt} function attribute, NDS32
5705 On NDS32 target, this attribute indicates that the specified function
5706 is an interrupt handler. The compiler generates corresponding sections
5707 for use in an interrupt handler. You can use the following attributes
5708 to modify the behavior:
5711 @cindex @code{nested} function attribute, NDS32
5712 This interrupt service routine is interruptible.
5714 @cindex @code{not_nested} function attribute, NDS32
5715 This interrupt service routine is not interruptible.
5717 @cindex @code{nested_ready} function attribute, NDS32
5718 This interrupt service routine is interruptible after @code{PSW.GIE}
5719 (global interrupt enable) is set. This allows interrupt service routine to
5720 finish some short critical code before enabling interrupts.
5722 @cindex @code{save_all} function attribute, NDS32
5723 The system will help save all registers into stack before entering
5726 @cindex @code{partial_save} function attribute, NDS32
5727 The system will help save caller registers into stack before entering
5732 @cindex @code{naked} function attribute, NDS32
5733 This attribute allows the compiler to construct the
5734 requisite function declaration, while allowing the body of the
5735 function to be assembly code. The specified function will not have
5736 prologue/epilogue sequences generated by the compiler. Only basic
5737 @code{asm} statements can safely be included in naked functions
5738 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5739 basic @code{asm} and C code may appear to work, they cannot be
5740 depended upon to work reliably and are not supported.
5743 @cindex @code{reset} function attribute, NDS32
5744 @cindex reset handler functions
5745 Use this attribute on the NDS32 target to indicate that the specified function
5746 is a reset handler. The compiler will generate corresponding sections
5747 for use in a reset handler. You can use the following attributes
5748 to provide extra exception handling:
5751 @cindex @code{nmi} function attribute, NDS32
5752 Provide a user-defined function to handle NMI exception.
5754 @cindex @code{warm} function attribute, NDS32
5755 Provide a user-defined function to handle warm reset exception.
5759 @node Nios II Function Attributes
5760 @subsection Nios II Function Attributes
5762 These function attributes are supported by the Nios II back end:
5765 @item target (@var{options})
5766 @cindex @code{target} function attribute
5767 As discussed in @ref{Common Function Attributes}, this attribute
5768 allows specification of target-specific compilation options.
5770 When compiling for Nios II, the following options are allowed:
5773 @item custom-@var{insn}=@var{N}
5774 @itemx no-custom-@var{insn}
5775 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
5776 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
5777 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
5778 custom instruction with encoding @var{N} when generating code that uses
5779 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
5780 the custom instruction @var{insn}.
5781 These target attributes correspond to the
5782 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
5783 command-line options, and support the same set of @var{insn} keywords.
5784 @xref{Nios II Options}, for more information.
5786 @item custom-fpu-cfg=@var{name}
5787 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
5788 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
5789 command-line option, to select a predefined set of custom instructions
5791 @xref{Nios II Options}, for more information.
5795 @node Nvidia PTX Function Attributes
5796 @subsection Nvidia PTX Function Attributes
5798 These function attributes are supported by the Nvidia PTX back end:
5802 @cindex @code{kernel} attribute, Nvidia PTX
5803 This attribute indicates that the corresponding function should be compiled
5804 as a kernel function, which can be invoked from the host via the CUDA RT
5806 By default functions are only callable only from other PTX functions.
5808 Kernel functions must have @code{void} return type.
5811 @node PowerPC Function Attributes
5812 @subsection PowerPC Function Attributes
5814 These function attributes are supported by the PowerPC back end:
5819 @cindex indirect calls, PowerPC
5820 @cindex @code{longcall} function attribute, PowerPC
5821 @cindex @code{shortcall} function attribute, PowerPC
5822 The @code{longcall} attribute
5823 indicates that the function might be far away from the call site and
5824 require a different (more expensive) calling sequence. The
5825 @code{shortcall} attribute indicates that the function is always close
5826 enough for the shorter calling sequence to be used. These attributes
5827 override both the @option{-mlongcall} switch and
5828 the @code{#pragma longcall} setting.
5830 @xref{RS/6000 and PowerPC Options}, for more information on whether long
5831 calls are necessary.
5833 @item target (@var{options})
5834 @cindex @code{target} function attribute
5835 As discussed in @ref{Common Function Attributes}, this attribute
5836 allows specification of target-specific compilation options.
5838 On the PowerPC, the following options are allowed:
5843 @cindex @code{target("altivec")} function attribute, PowerPC
5844 Generate code that uses (does not use) AltiVec instructions. In
5845 32-bit code, you cannot enable AltiVec instructions unless
5846 @option{-mabi=altivec} is used on the command line.
5850 @cindex @code{target("cmpb")} function attribute, PowerPC
5851 Generate code that uses (does not use) the compare bytes instruction
5852 implemented on the POWER6 processor and other processors that support
5853 the PowerPC V2.05 architecture.
5857 @cindex @code{target("dlmzb")} function attribute, PowerPC
5858 Generate code that uses (does not use) the string-search @samp{dlmzb}
5859 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
5860 generated by default when targeting those processors.
5864 @cindex @code{target("fprnd")} function attribute, PowerPC
5865 Generate code that uses (does not use) the FP round to integer
5866 instructions implemented on the POWER5+ processor and other processors
5867 that support the PowerPC V2.03 architecture.
5871 @cindex @code{target("hard-dfp")} function attribute, PowerPC
5872 Generate code that uses (does not use) the decimal floating-point
5873 instructions implemented on some POWER processors.
5877 @cindex @code{target("isel")} function attribute, PowerPC
5878 Generate code that uses (does not use) ISEL instruction.
5882 @cindex @code{target("mfcrf")} function attribute, PowerPC
5883 Generate code that uses (does not use) the move from condition
5884 register field instruction implemented on the POWER4 processor and
5885 other processors that support the PowerPC V2.01 architecture.
5889 @cindex @code{target("mulhw")} function attribute, PowerPC
5890 Generate code that uses (does not use) the half-word multiply and
5891 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
5892 These instructions are generated by default when targeting those
5897 @cindex @code{target("multiple")} function attribute, PowerPC
5898 Generate code that uses (does not use) the load multiple word
5899 instructions and the store multiple word instructions.
5903 @cindex @code{target("update")} function attribute, PowerPC
5904 Generate code that uses (does not use) the load or store instructions
5905 that update the base register to the address of the calculated memory
5910 @cindex @code{target("popcntb")} function attribute, PowerPC
5911 Generate code that uses (does not use) the popcount and double-precision
5912 FP reciprocal estimate instruction implemented on the POWER5
5913 processor and other processors that support the PowerPC V2.02
5918 @cindex @code{target("popcntd")} function attribute, PowerPC
5919 Generate code that uses (does not use) the popcount instruction
5920 implemented on the POWER7 processor and other processors that support
5921 the PowerPC V2.06 architecture.
5923 @item powerpc-gfxopt
5924 @itemx no-powerpc-gfxopt
5925 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
5926 Generate code that uses (does not use) the optional PowerPC
5927 architecture instructions in the Graphics group, including
5928 floating-point select.
5931 @itemx no-powerpc-gpopt
5932 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
5933 Generate code that uses (does not use) the optional PowerPC
5934 architecture instructions in the General Purpose group, including
5935 floating-point square root.
5937 @item recip-precision
5938 @itemx no-recip-precision
5939 @cindex @code{target("recip-precision")} function attribute, PowerPC
5940 Assume (do not assume) that the reciprocal estimate instructions
5941 provide higher-precision estimates than is mandated by the PowerPC
5946 @cindex @code{target("string")} function attribute, PowerPC
5947 Generate code that uses (does not use) the load string instructions
5948 and the store string word instructions to save multiple registers and
5949 do small block moves.
5953 @cindex @code{target("vsx")} function attribute, PowerPC
5954 Generate code that uses (does not use) vector/scalar (VSX)
5955 instructions, and also enable the use of built-in functions that allow
5956 more direct access to the VSX instruction set. In 32-bit code, you
5957 cannot enable VSX or AltiVec instructions unless
5958 @option{-mabi=altivec} is used on the command line.
5962 @cindex @code{target("friz")} function attribute, PowerPC
5963 Generate (do not generate) the @code{friz} instruction when the
5964 @option{-funsafe-math-optimizations} option is used to optimize
5965 rounding a floating-point value to 64-bit integer and back to floating
5966 point. The @code{friz} instruction does not return the same value if
5967 the floating-point number is too large to fit in an integer.
5969 @item avoid-indexed-addresses
5970 @itemx no-avoid-indexed-addresses
5971 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
5972 Generate code that tries to avoid (not avoid) the use of indexed load
5973 or store instructions.
5977 @cindex @code{target("paired")} function attribute, PowerPC
5978 Generate code that uses (does not use) the generation of PAIRED simd
5983 @cindex @code{target("longcall")} function attribute, PowerPC
5984 Generate code that assumes (does not assume) that all calls are far
5985 away so that a longer more expensive calling sequence is required.
5988 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
5989 Specify the architecture to generate code for when compiling the
5990 function. If you select the @code{target("cpu=power7")} attribute when
5991 generating 32-bit code, VSX and AltiVec instructions are not generated
5992 unless you use the @option{-mabi=altivec} option on the command line.
5994 @item tune=@var{TUNE}
5995 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
5996 Specify the architecture to tune for when compiling the function. If
5997 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
5998 you do specify the @code{target("cpu=@var{CPU}")} attribute,
5999 compilation tunes for the @var{CPU} architecture, and not the
6000 default tuning specified on the command line.
6003 On the PowerPC, the inliner does not inline a
6004 function that has different target options than the caller, unless the
6005 callee has a subset of the target options of the caller.
6008 @node RISC-V Function Attributes
6009 @subsection RISC-V Function Attributes
6011 These function attributes are supported by the RISC-V back end:
6015 @cindex @code{naked} function attribute, RISC-V
6016 This attribute allows the compiler to construct the
6017 requisite function declaration, while allowing the body of the
6018 function to be assembly code. The specified function will not have
6019 prologue/epilogue sequences generated by the compiler. Only basic
6020 @code{asm} statements can safely be included in naked functions
6021 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6022 basic @code{asm} and C code may appear to work, they cannot be
6023 depended upon to work reliably and are not supported.
6026 @cindex @code{interrupt} function attribute, RISC-V
6027 Use this attribute to indicate that the specified function is an interrupt
6028 handler. The compiler generates function entry and exit sequences suitable
6029 for use in an interrupt handler when this attribute is present.
6031 You can specify the kind of interrupt to be handled by adding an optional
6032 parameter to the interrupt attribute like this:
6035 void f (void) __attribute__ ((interrupt ("user")));
6038 Permissible values for this parameter are @code{user}, @code{supervisor},
6039 and @code{machine}. If there is no parameter, then it defaults to
6043 @node RL78 Function Attributes
6044 @subsection RL78 Function Attributes
6046 These function attributes are supported by the RL78 back end:
6050 @itemx brk_interrupt
6051 @cindex @code{interrupt} function attribute, RL78
6052 @cindex @code{brk_interrupt} function attribute, RL78
6053 These attributes indicate
6054 that the specified function is an interrupt handler. The compiler generates
6055 function entry and exit sequences suitable for use in an interrupt handler
6056 when this attribute is present.
6058 Use @code{brk_interrupt} instead of @code{interrupt} for
6059 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
6060 that must end with @code{RETB} instead of @code{RETI}).
6063 @cindex @code{naked} function attribute, RL78
6064 This attribute allows the compiler to construct the
6065 requisite function declaration, while allowing the body of the
6066 function to be assembly code. The specified function will not have
6067 prologue/epilogue sequences generated by the compiler. Only basic
6068 @code{asm} statements can safely be included in naked functions
6069 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6070 basic @code{asm} and C code may appear to work, they cannot be
6071 depended upon to work reliably and are not supported.
6074 @node RX Function Attributes
6075 @subsection RX Function Attributes
6077 These function attributes are supported by the RX back end:
6080 @item fast_interrupt
6081 @cindex @code{fast_interrupt} function attribute, RX
6082 Use this attribute on the RX port to indicate that the specified
6083 function is a fast interrupt handler. This is just like the
6084 @code{interrupt} attribute, except that @code{freit} is used to return
6085 instead of @code{reit}.
6088 @cindex @code{interrupt} function attribute, RX
6089 Use this attribute to indicate
6090 that the specified function is an interrupt handler. The compiler generates
6091 function entry and exit sequences suitable for use in an interrupt handler
6092 when this attribute is present.
6094 On RX and RL78 targets, you may specify one or more vector numbers as arguments
6095 to the attribute, as well as naming an alternate table name.
6096 Parameters are handled sequentially, so one handler can be assigned to
6097 multiple entries in multiple tables. One may also pass the magic
6098 string @code{"$default"} which causes the function to be used for any
6099 unfilled slots in the current table.
6101 This example shows a simple assignment of a function to one vector in
6102 the default table (note that preprocessor macros may be used for
6103 chip-specific symbolic vector names):
6105 void __attribute__ ((interrupt (5))) txd1_handler ();
6108 This example assigns a function to two slots in the default table
6109 (using preprocessor macros defined elsewhere) and makes it the default
6110 for the @code{dct} table:
6112 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
6117 @cindex @code{naked} function attribute, RX
6118 This attribute allows the compiler to construct the
6119 requisite function declaration, while allowing the body of the
6120 function to be assembly code. The specified function will not have
6121 prologue/epilogue sequences generated by the compiler. Only basic
6122 @code{asm} statements can safely be included in naked functions
6123 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6124 basic @code{asm} and C code may appear to work, they cannot be
6125 depended upon to work reliably and are not supported.
6128 @cindex @code{vector} function attribute, RX
6129 This RX attribute is similar to the @code{interrupt} attribute, including its
6130 parameters, but does not make the function an interrupt-handler type
6131 function (i.e.@: it retains the normal C function calling ABI). See the
6132 @code{interrupt} attribute for a description of its arguments.
6135 @node S/390 Function Attributes
6136 @subsection S/390 Function Attributes
6138 These function attributes are supported on the S/390:
6141 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
6142 @cindex @code{hotpatch} function attribute, S/390
6144 On S/390 System z targets, you can use this function attribute to
6145 make GCC generate a ``hot-patching'' function prologue. If the
6146 @option{-mhotpatch=} command-line option is used at the same time,
6147 the @code{hotpatch} attribute takes precedence. The first of the
6148 two arguments specifies the number of halfwords to be added before
6149 the function label. A second argument can be used to specify the
6150 number of halfwords to be added after the function label. For
6151 both arguments the maximum allowed value is 1000000.
6153 If both arguments are zero, hotpatching is disabled.
6155 @item target (@var{options})
6156 @cindex @code{target} function attribute
6157 As discussed in @ref{Common Function Attributes}, this attribute
6158 allows specification of target-specific compilation options.
6160 On S/390, the following options are supported:
6168 @item warn-framesize=
6180 @itemx no-packed-stack
6182 @itemx no-small-exec
6185 @item warn-dynamicstack
6186 @itemx no-warn-dynamicstack
6189 The options work exactly like the S/390 specific command line
6190 options (without the prefix @option{-m}) except that they do not
6191 change any feature macros. For example,
6194 @code{target("no-vx")}
6197 does not undefine the @code{__VEC__} macro.
6200 @node SH Function Attributes
6201 @subsection SH Function Attributes
6203 These function attributes are supported on the SH family of processors:
6206 @item function_vector
6207 @cindex @code{function_vector} function attribute, SH
6208 @cindex calling functions through the function vector on SH2A
6209 On SH2A targets, this attribute declares a function to be called using the
6210 TBR relative addressing mode. The argument to this attribute is the entry
6211 number of the same function in a vector table containing all the TBR
6212 relative addressable functions. For correct operation the TBR must be setup
6213 accordingly to point to the start of the vector table before any functions with
6214 this attribute are invoked. Usually a good place to do the initialization is
6215 the startup routine. The TBR relative vector table can have at max 256 function
6216 entries. The jumps to these functions are generated using a SH2A specific,
6217 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
6218 from GNU binutils version 2.7 or later for this attribute to work correctly.
6220 In an application, for a function being called once, this attribute
6221 saves at least 8 bytes of code; and if other successive calls are being
6222 made to the same function, it saves 2 bytes of code per each of these
6225 @item interrupt_handler
6226 @cindex @code{interrupt_handler} function attribute, SH
6227 Use this attribute to
6228 indicate that the specified function is an interrupt handler. The compiler
6229 generates function entry and exit sequences suitable for use in an
6230 interrupt handler when this attribute is present.
6232 @item nosave_low_regs
6233 @cindex @code{nosave_low_regs} function attribute, SH
6234 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
6235 function should not save and restore registers R0..R7. This can be used on SH3*
6236 and SH4* targets that have a second R0..R7 register bank for non-reentrant
6240 @cindex @code{renesas} function attribute, SH
6241 On SH targets this attribute specifies that the function or struct follows the
6245 @cindex @code{resbank} function attribute, SH
6246 On the SH2A target, this attribute enables the high-speed register
6247 saving and restoration using a register bank for @code{interrupt_handler}
6248 routines. Saving to the bank is performed automatically after the CPU
6249 accepts an interrupt that uses a register bank.
6251 The nineteen 32-bit registers comprising general register R0 to R14,
6252 control register GBR, and system registers MACH, MACL, and PR and the
6253 vector table address offset are saved into a register bank. Register
6254 banks are stacked in first-in last-out (FILO) sequence. Restoration
6255 from the bank is executed by issuing a RESBANK instruction.
6258 @cindex @code{sp_switch} function attribute, SH
6259 Use this attribute on the SH to indicate an @code{interrupt_handler}
6260 function should switch to an alternate stack. It expects a string
6261 argument that names a global variable holding the address of the
6266 void f () __attribute__ ((interrupt_handler,
6267 sp_switch ("alt_stack")));
6271 @cindex @code{trap_exit} function attribute, SH
6272 Use this attribute on the SH for an @code{interrupt_handler} to return using
6273 @code{trapa} instead of @code{rte}. This attribute expects an integer
6274 argument specifying the trap number to be used.
6277 @cindex @code{trapa_handler} function attribute, SH
6278 On SH targets this function attribute is similar to @code{interrupt_handler}
6279 but it does not save and restore all registers.
6282 @node Symbian OS Function Attributes
6283 @subsection Symbian OS Function Attributes
6285 @xref{Microsoft Windows Function Attributes}, for discussion of the
6286 @code{dllexport} and @code{dllimport} attributes.
6288 @node V850 Function Attributes
6289 @subsection V850 Function Attributes
6291 The V850 back end supports these function attributes:
6295 @itemx interrupt_handler
6296 @cindex @code{interrupt} function attribute, V850
6297 @cindex @code{interrupt_handler} function attribute, V850
6298 Use these attributes to indicate
6299 that the specified function is an interrupt handler. The compiler generates
6300 function entry and exit sequences suitable for use in an interrupt handler
6301 when either attribute is present.
6304 @node Visium Function Attributes
6305 @subsection Visium Function Attributes
6307 These function attributes are supported by the Visium back end:
6311 @cindex @code{interrupt} function attribute, Visium
6312 Use this attribute to indicate
6313 that the specified function is an interrupt handler. The compiler generates
6314 function entry and exit sequences suitable for use in an interrupt handler
6315 when this attribute is present.
6318 @node x86 Function Attributes
6319 @subsection x86 Function Attributes
6321 These function attributes are supported by the x86 back end:
6325 @cindex @code{cdecl} function attribute, x86-32
6326 @cindex functions that pop the argument stack on x86-32
6328 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
6329 assume that the calling function pops off the stack space used to
6330 pass arguments. This is
6331 useful to override the effects of the @option{-mrtd} switch.
6334 @cindex @code{fastcall} function attribute, x86-32
6335 @cindex functions that pop the argument stack on x86-32
6336 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
6337 pass the first argument (if of integral type) in the register ECX and
6338 the second argument (if of integral type) in the register EDX@. Subsequent
6339 and other typed arguments are passed on the stack. The called function
6340 pops the arguments off the stack. If the number of arguments is variable all
6341 arguments are pushed on the stack.
6344 @cindex @code{thiscall} function attribute, x86-32
6345 @cindex functions that pop the argument stack on x86-32
6346 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
6347 pass the first argument (if of integral type) in the register ECX.
6348 Subsequent and other typed arguments are passed on the stack. The called
6349 function pops the arguments off the stack.
6350 If the number of arguments is variable all arguments are pushed on the
6352 The @code{thiscall} attribute is intended for C++ non-static member functions.
6353 As a GCC extension, this calling convention can be used for C functions
6354 and for static member methods.
6358 @cindex @code{ms_abi} function attribute, x86
6359 @cindex @code{sysv_abi} function attribute, x86
6361 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
6362 to indicate which calling convention should be used for a function. The
6363 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
6364 while the @code{sysv_abi} attribute tells the compiler to use the System V
6365 ELF ABI, which is used on GNU/Linux and other systems. The default is to use
6366 the Microsoft ABI when targeting Windows. On all other systems, the default
6367 is the System V ELF ABI.
6369 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
6370 requires the @option{-maccumulate-outgoing-args} option.
6372 @item callee_pop_aggregate_return (@var{number})
6373 @cindex @code{callee_pop_aggregate_return} function attribute, x86
6375 On x86-32 targets, you can use this attribute to control how
6376 aggregates are returned in memory. If the caller is responsible for
6377 popping the hidden pointer together with the rest of the arguments, specify
6378 @var{number} equal to zero. If callee is responsible for popping the
6379 hidden pointer, specify @var{number} equal to one.
6381 The default x86-32 ABI assumes that the callee pops the
6382 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
6383 the compiler assumes that the
6384 caller pops the stack for hidden pointer.
6386 @item ms_hook_prologue
6387 @cindex @code{ms_hook_prologue} function attribute, x86
6389 On 32-bit and 64-bit x86 targets, you can use
6390 this function attribute to make GCC generate the ``hot-patching'' function
6391 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
6395 @cindex @code{naked} function attribute, x86
6396 This attribute allows the compiler to construct the
6397 requisite function declaration, while allowing the body of the
6398 function to be assembly code. The specified function will not have
6399 prologue/epilogue sequences generated by the compiler. Only basic
6400 @code{asm} statements can safely be included in naked functions
6401 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6402 basic @code{asm} and C code may appear to work, they cannot be
6403 depended upon to work reliably and are not supported.
6405 @item regparm (@var{number})
6406 @cindex @code{regparm} function attribute, x86
6407 @cindex functions that are passed arguments in registers on x86-32
6408 On x86-32 targets, the @code{regparm} attribute causes the compiler to
6409 pass arguments number one to @var{number} if they are of integral type
6410 in registers EAX, EDX, and ECX instead of on the stack. Functions that
6411 take a variable number of arguments continue to be passed all of their
6412 arguments on the stack.
6414 Beware that on some ELF systems this attribute is unsuitable for
6415 global functions in shared libraries with lazy binding (which is the
6416 default). Lazy binding sends the first call via resolving code in
6417 the loader, which might assume EAX, EDX and ECX can be clobbered, as
6418 per the standard calling conventions. Solaris 8 is affected by this.
6419 Systems with the GNU C Library version 2.1 or higher
6420 and FreeBSD are believed to be
6421 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
6422 disabled with the linker or the loader if desired, to avoid the
6426 @cindex @code{sseregparm} function attribute, x86
6427 On x86-32 targets with SSE support, the @code{sseregparm} attribute
6428 causes the compiler to pass up to 3 floating-point arguments in
6429 SSE registers instead of on the stack. Functions that take a
6430 variable number of arguments continue to pass all of their
6431 floating-point arguments on the stack.
6433 @item force_align_arg_pointer
6434 @cindex @code{force_align_arg_pointer} function attribute, x86
6435 On x86 targets, the @code{force_align_arg_pointer} attribute may be
6436 applied to individual function definitions, generating an alternate
6437 prologue and epilogue that realigns the run-time stack if necessary.
6438 This supports mixing legacy codes that run with a 4-byte aligned stack
6439 with modern codes that keep a 16-byte stack for SSE compatibility.
6442 @cindex @code{stdcall} function attribute, x86-32
6443 @cindex functions that pop the argument stack on x86-32
6444 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
6445 assume that the called function pops off the stack space used to
6446 pass arguments, unless it takes a variable number of arguments.
6448 @item no_caller_saved_registers
6449 @cindex @code{no_caller_saved_registers} function attribute, x86
6450 Use this attribute to indicate that the specified function has no
6451 caller-saved registers. That is, all registers are callee-saved. For
6452 example, this attribute can be used for a function called from an
6453 interrupt handler. The compiler generates proper function entry and
6454 exit sequences to save and restore any modified registers, except for
6455 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
6456 states, the GCC option @option{-mgeneral-regs-only} should be used to
6457 compile functions with @code{no_caller_saved_registers} attribute.
6460 @cindex @code{interrupt} function attribute, x86
6461 Use this attribute to indicate that the specified function is an
6462 interrupt handler or an exception handler (depending on parameters passed
6463 to the function, explained further). The compiler generates function
6464 entry and exit sequences suitable for use in an interrupt handler when
6465 this attribute is present. The @code{IRET} instruction, instead of the
6466 @code{RET} instruction, is used to return from interrupt handlers. All
6467 registers, except for the EFLAGS register which is restored by the
6468 @code{IRET} instruction, are preserved by the compiler. Since GCC
6469 doesn't preserve SSE, MMX nor x87 states, the GCC option
6470 @option{-mgeneral-regs-only} should be used to compile interrupt and
6473 Any interruptible-without-stack-switch code must be compiled with
6474 @option{-mno-red-zone} since interrupt handlers can and will, because
6475 of the hardware design, touch the red zone.
6477 An interrupt handler must be declared with a mandatory pointer
6481 struct interrupt_frame;
6483 __attribute__ ((interrupt))
6485 f (struct interrupt_frame *frame)
6491 and you must define @code{struct interrupt_frame} as described in the
6494 Exception handlers differ from interrupt handlers because the system
6495 pushes an error code on the stack. An exception handler declaration is
6496 similar to that for an interrupt handler, but with a different mandatory
6497 function signature. The compiler arranges to pop the error code off the
6498 stack before the @code{IRET} instruction.
6502 typedef unsigned long long int uword_t;
6504 typedef unsigned int uword_t;
6507 struct interrupt_frame;
6509 __attribute__ ((interrupt))
6511 f (struct interrupt_frame *frame, uword_t error_code)
6517 Exception handlers should only be used for exceptions that push an error
6518 code; you should use an interrupt handler in other cases. The system
6519 will crash if the wrong kind of handler is used.
6521 @item target (@var{options})
6522 @cindex @code{target} function attribute
6523 As discussed in @ref{Common Function Attributes}, this attribute
6524 allows specification of target-specific compilation options.
6526 On the x86, the following options are allowed:
6530 @cindex @code{target("3dnow")} function attribute, x86
6531 Enable/disable the generation of the 3DNow!@: instructions.
6535 @cindex @code{target("3dnowa")} function attribute, x86
6536 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6540 @cindex @code{target("abm")} function attribute, x86
6541 Enable/disable the generation of the advanced bit instructions.
6545 @cindex @code{target("adx")} function attribute, x86
6546 Enable/disable the generation of the ADX instructions.
6550 @cindex @code{target("aes")} function attribute, x86
6551 Enable/disable the generation of the AES instructions.
6555 @cindex @code{target("avx")} function attribute, x86
6556 Enable/disable the generation of the AVX instructions.
6560 @cindex @code{target("avx2")} function attribute, x86
6561 Enable/disable the generation of the AVX2 instructions.
6564 @itemx no-avx5124fmaps
6565 @cindex @code{target("avx5124fmaps")} function attribute, x86
6566 Enable/disable the generation of the AVX5124FMAPS instructions.
6569 @itemx no-avx5124vnniw
6570 @cindex @code{target("avx5124vnniw")} function attribute, x86
6571 Enable/disable the generation of the AVX5124VNNIW instructions.
6574 @itemx no-avx512bitalg
6575 @cindex @code{target("avx512bitalg")} function attribute, x86
6576 Enable/disable the generation of the AVX512BITALG instructions.
6580 @cindex @code{target("avx512bw")} function attribute, x86
6581 Enable/disable the generation of the AVX512BW instructions.
6585 @cindex @code{target("avx512cd")} function attribute, x86
6586 Enable/disable the generation of the AVX512CD instructions.
6590 @cindex @code{target("avx512dq")} function attribute, x86
6591 Enable/disable the generation of the AVX512DQ instructions.
6595 @cindex @code{target("avx512er")} function attribute, x86
6596 Enable/disable the generation of the AVX512ER instructions.
6600 @cindex @code{target("avx512f")} function attribute, x86
6601 Enable/disable the generation of the AVX512F instructions.
6604 @itemx no-avx512ifma
6605 @cindex @code{target("avx512ifma")} function attribute, x86
6606 Enable/disable the generation of the AVX512IFMA instructions.
6610 @cindex @code{target("avx512pf")} function attribute, x86
6611 Enable/disable the generation of the AVX512PF instructions.
6614 @itemx no-avx512vbmi
6615 @cindex @code{target("avx512vbmi")} function attribute, x86
6616 Enable/disable the generation of the AVX512VBMI instructions.
6619 @itemx no-avx512vbmi2
6620 @cindex @code{target("avx512vbmi2")} function attribute, x86
6621 Enable/disable the generation of the AVX512VBMI2 instructions.
6625 @cindex @code{target("avx512vl")} function attribute, x86
6626 Enable/disable the generation of the AVX512VL instructions.
6629 @itemx no-avx512vnni
6630 @cindex @code{target("avx512vnni")} function attribute, x86
6631 Enable/disable the generation of the AVX512VNNI instructions.
6633 @item avx512vpopcntdq
6634 @itemx no-avx512vpopcntdq
6635 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6636 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6640 @cindex @code{target("bmi")} function attribute, x86
6641 Enable/disable the generation of the BMI instructions.
6645 @cindex @code{target("bmi2")} function attribute, x86
6646 Enable/disable the generation of the BMI2 instructions.
6650 @cindex @code{target("cldemote")} function attribute, x86
6651 Enable/disable the generation of the CLDEMOTE instructions.
6654 @itemx no-clflushopt
6655 @cindex @code{target("clflushopt")} function attribute, x86
6656 Enable/disable the generation of the CLFLUSHOPT instructions.
6660 @cindex @code{target("clwb")} function attribute, x86
6661 Enable/disable the generation of the CLWB instructions.
6665 @cindex @code{target("clzero")} function attribute, x86
6666 Enable/disable the generation of the CLZERO instructions.
6670 @cindex @code{target("crc32")} function attribute, x86
6671 Enable/disable the generation of the CRC32 instructions.
6675 @cindex @code{target("cx16")} function attribute, x86
6676 Enable/disable the generation of the CMPXCHG16B instructions.
6679 @cindex @code{target("default")} function attribute, x86
6680 @xref{Function Multiversioning}, where it is used to specify the
6681 default function version.
6685 @cindex @code{target("f16c")} function attribute, x86
6686 Enable/disable the generation of the F16C instructions.
6690 @cindex @code{target("fma")} function attribute, x86
6691 Enable/disable the generation of the FMA instructions.
6695 @cindex @code{target("fma4")} function attribute, x86
6696 Enable/disable the generation of the FMA4 instructions.
6700 @cindex @code{target("fsgsbase")} function attribute, x86
6701 Enable/disable the generation of the FSGSBASE instructions.
6705 @cindex @code{target("fxsr")} function attribute, x86
6706 Enable/disable the generation of the FXSR instructions.
6710 @cindex @code{target("gfni")} function attribute, x86
6711 Enable/disable the generation of the GFNI instructions.
6715 @cindex @code{target("hle")} function attribute, x86
6716 Enable/disable the generation of the HLE instruction prefixes.
6720 @cindex @code{target("lwp")} function attribute, x86
6721 Enable/disable the generation of the LWP instructions.
6725 @cindex @code{target("lzcnt")} function attribute, x86
6726 Enable/disable the generation of the LZCNT instructions.
6730 @cindex @code{target("mmx")} function attribute, x86
6731 Enable/disable the generation of the MMX instructions.
6735 @cindex @code{target("movbe")} function attribute, x86
6736 Enable/disable the generation of the MOVBE instructions.
6740 @cindex @code{target("movdir64b")} function attribute, x86
6741 Enable/disable the generation of the MOVDIR64B instructions.
6745 @cindex @code{target("movdiri")} function attribute, x86
6746 Enable/disable the generation of the MOVDIRI instructions.
6750 @cindex @code{target("mwait")} function attribute, x86
6751 Enable/disable the generation of the MWAIT and MONITOR instructions.
6755 @cindex @code{target("mwaitx")} function attribute, x86
6756 Enable/disable the generation of the MWAITX instructions.
6760 @cindex @code{target("pclmul")} function attribute, x86
6761 Enable/disable the generation of the PCLMUL instructions.
6765 @cindex @code{target("pconfig")} function attribute, x86
6766 Enable/disable the generation of the PCONFIG instructions.
6770 @cindex @code{target("pku")} function attribute, x86
6771 Enable/disable the generation of the PKU instructions.
6775 @cindex @code{target("popcnt")} function attribute, x86
6776 Enable/disable the generation of the POPCNT instruction.
6779 @itemx no-prefetchwt1
6780 @cindex @code{target("prefetchwt1")} function attribute, x86
6781 Enable/disable the generation of the PREFETCHWT1 instructions.
6785 @cindex @code{target("prfchw")} function attribute, x86
6786 Enable/disable the generation of the PREFETCHW instruction.
6790 @cindex @code{target("ptwrite")} function attribute, x86
6791 Enable/disable the generation of the PTWRITE instructions.
6795 @cindex @code{target("rdpid")} function attribute, x86
6796 Enable/disable the generation of the RDPID instructions.
6800 @cindex @code{target("rdrnd")} function attribute, x86
6801 Enable/disable the generation of the RDRND instructions.
6805 @cindex @code{target("rdseed")} function attribute, x86
6806 Enable/disable the generation of the RDSEED instructions.
6810 @cindex @code{target("rtm")} function attribute, x86
6811 Enable/disable the generation of the RTM instructions.
6815 @cindex @code{target("sahf")} function attribute, x86
6816 Enable/disable the generation of the SAHF instructions.
6820 @cindex @code{target("sgx")} function attribute, x86
6821 Enable/disable the generation of the SGX instructions.
6825 @cindex @code{target("sha")} function attribute, x86
6826 Enable/disable the generation of the SHA instructions.
6830 @cindex @code{target("shstk")} function attribute, x86
6831 Enable/disable the shadow stack built-in functions from CET.
6835 @cindex @code{target("sse")} function attribute, x86
6836 Enable/disable the generation of the SSE instructions.
6840 @cindex @code{target("sse2")} function attribute, x86
6841 Enable/disable the generation of the SSE2 instructions.
6845 @cindex @code{target("sse3")} function attribute, x86
6846 Enable/disable the generation of the SSE3 instructions.
6850 @cindex @code{target("sse4")} function attribute, x86
6851 Enable/disable the generation of the SSE4 instructions (both SSE4.1
6856 @cindex @code{target("sse4.1")} function attribute, x86
6857 Enable/disable the generation of the sse4.1 instructions.
6861 @cindex @code{target("sse4.2")} function attribute, x86
6862 Enable/disable the generation of the sse4.2 instructions.
6866 @cindex @code{target("sse4a")} function attribute, x86
6867 Enable/disable the generation of the SSE4A instructions.
6871 @cindex @code{target("ssse3")} function attribute, x86
6872 Enable/disable the generation of the SSSE3 instructions.
6876 @cindex @code{target("tbm")} function attribute, x86
6877 Enable/disable the generation of the TBM instructions.
6881 @cindex @code{target("vaes")} function attribute, x86
6882 Enable/disable the generation of the VAES instructions.
6885 @itemx no-vpclmulqdq
6886 @cindex @code{target("vpclmulqdq")} function attribute, x86
6887 Enable/disable the generation of the VPCLMULQDQ instructions.
6891 @cindex @code{target("waitpkg")} function attribute, x86
6892 Enable/disable the generation of the WAITPKG instructions.
6896 @cindex @code{target("wbnoinvd")} function attribute, x86
6897 Enable/disable the generation of the WBNOINVD instructions.
6901 @cindex @code{target("xop")} function attribute, x86
6902 Enable/disable the generation of the XOP instructions.
6906 @cindex @code{target("xsave")} function attribute, x86
6907 Enable/disable the generation of the XSAVE instructions.
6911 @cindex @code{target("xsavec")} function attribute, x86
6912 Enable/disable the generation of the XSAVEC instructions.
6916 @cindex @code{target("xsaveopt")} function attribute, x86
6917 Enable/disable the generation of the XSAVEOPT instructions.
6921 @cindex @code{target("xsaves")} function attribute, x86
6922 Enable/disable the generation of the XSAVES instructions.
6926 @cindex @code{target("amx-tile")} function attribute, x86
6927 Enable/disable the generation of the AMX-TILE instructions.
6931 @cindex @code{target("amx-int8")} function attribute, x86
6932 Enable/disable the generation of the AMX-INT8 instructions.
6936 @cindex @code{target("amx-bf16")} function attribute, x86
6937 Enable/disable the generation of the AMX-BF16 instructions.
6941 @cindex @code{target("uintr")} function attribute, x86
6942 Enable/disable the generation of the UINTR instructions.
6946 @cindex @code{target("hreset")} function attribute, x86
6947 Enable/disable the generation of the HRESET instruction.
6951 @cindex @code{target("kl")} function attribute, x86
6952 Enable/disable the generation of the KEYLOCKER instructions.
6956 @cindex @code{target("widekl")} function attribute, x86
6957 Enable/disable the generation of the WIDEKL instructions.
6961 @cindex @code{target("avxvnni")} function attribute, x86
6962 Enable/disable the generation of the AVXVNNI instructions.
6966 @cindex @code{target("cld")} function attribute, x86
6967 Enable/disable the generation of the CLD before string moves.
6969 @item fancy-math-387
6970 @itemx no-fancy-math-387
6971 @cindex @code{target("fancy-math-387")} function attribute, x86
6972 Enable/disable the generation of the @code{sin}, @code{cos}, and
6973 @code{sqrt} instructions on the 387 floating-point unit.
6977 @cindex @code{target("ieee-fp")} function attribute, x86
6978 Enable/disable the generation of floating point that depends on IEEE arithmetic.
6980 @item inline-all-stringops
6981 @itemx no-inline-all-stringops
6982 @cindex @code{target("inline-all-stringops")} function attribute, x86
6983 Enable/disable inlining of string operations.
6985 @item inline-stringops-dynamically
6986 @itemx no-inline-stringops-dynamically
6987 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
6988 Enable/disable the generation of the inline code to do small string
6989 operations and calling the library routines for large operations.
6991 @item align-stringops
6992 @itemx no-align-stringops
6993 @cindex @code{target("align-stringops")} function attribute, x86
6994 Do/do not align destination of inlined string operations.
6998 @cindex @code{target("recip")} function attribute, x86
6999 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
7000 instructions followed an additional Newton-Raphson step instead of
7001 doing a floating-point division.
7003 @item general-regs-only
7004 @cindex @code{target("general-regs-only")} function attribute, x86
7005 Generate code which uses only the general registers.
7007 @item arch=@var{ARCH}
7008 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
7009 Specify the architecture to generate code for in compiling the function.
7011 @item tune=@var{TUNE}
7012 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
7013 Specify the architecture to tune for in compiling the function.
7015 @item fpmath=@var{FPMATH}
7016 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
7017 Specify which floating-point unit to use. You must specify the
7018 @code{target("fpmath=sse,387")} option as
7019 @code{target("fpmath=sse+387")} because the comma would separate
7022 @item prefer-vector-width=@var{OPT}
7023 @cindex @code{prefer-vector-width} function attribute, x86
7024 On x86 targets, the @code{prefer-vector-width} attribute informs the
7025 compiler to use @var{OPT}-bit vector width in instructions
7026 instead of the default on the selected platform.
7028 Valid @var{OPT} values are:
7032 No extra limitations applied to GCC other than defined by the selected platform.
7035 Prefer 128-bit vector width for instructions.
7038 Prefer 256-bit vector width for instructions.
7041 Prefer 512-bit vector width for instructions.
7044 On the x86, the inliner does not inline a
7045 function that has different target options than the caller, unless the
7046 callee has a subset of the target options of the caller. For example
7047 a function declared with @code{target("sse3")} can inline a function
7048 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
7051 @item indirect_branch("@var{choice}")
7052 @cindex @code{indirect_branch} function attribute, x86
7053 On x86 targets, the @code{indirect_branch} attribute causes the compiler
7054 to convert indirect call and jump with @var{choice}. @samp{keep}
7055 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
7056 call and jump to call and return thunk. @samp{thunk-inline} converts
7057 indirect call and jump to inlined call and return thunk.
7058 @samp{thunk-extern} converts indirect call and jump to external call
7059 and return thunk provided in a separate object file.
7061 @item function_return("@var{choice}")
7062 @cindex @code{function_return} function attribute, x86
7063 On x86 targets, the @code{function_return} attribute causes the compiler
7064 to convert function return with @var{choice}. @samp{keep} keeps function
7065 return unmodified. @samp{thunk} converts function return to call and
7066 return thunk. @samp{thunk-inline} converts function return to inlined
7067 call and return thunk. @samp{thunk-extern} converts function return to
7068 external call and return thunk provided in a separate object file.
7071 @cindex @code{nocf_check} function attribute
7072 The @code{nocf_check} attribute on a function is used to inform the
7073 compiler that the function's prologue should not be instrumented when
7074 compiled with the @option{-fcf-protection=branch} option. The
7075 compiler assumes that the function's address is a valid target for a
7076 control-flow transfer.
7078 The @code{nocf_check} attribute on a type of pointer to function is
7079 used to inform the compiler that a call through the pointer should
7080 not be instrumented when compiled with the
7081 @option{-fcf-protection=branch} option. The compiler assumes
7082 that the function's address from the pointer is a valid target for
7083 a control-flow transfer. A direct function call through a function
7084 name is assumed to be a safe call thus direct calls are not
7085 instrumented by the compiler.
7087 The @code{nocf_check} attribute is applied to an object's type.
7088 In case of assignment of a function address or a function pointer to
7089 another pointer, the attribute is not carried over from the right-hand
7090 object's type; the type of left-hand object stays unchanged. The
7091 compiler checks for @code{nocf_check} attribute mismatch and reports
7092 a warning in case of mismatch.
7096 int foo (void) __attribute__(nocf_check);
7097 void (*foo1)(void) __attribute__(nocf_check);
7100 /* foo's address is assumed to be valid. */
7104 /* This call site is not checked for control-flow
7108 /* A warning is issued about attribute mismatch. */
7111 /* This call site is still not checked. */
7114 /* This call site is checked. */
7117 /* A warning is issued about attribute mismatch. */
7120 /* This call site is still checked. */
7128 @cindex @code{cf_check} function attribute, x86
7130 The @code{cf_check} attribute on a function is used to inform the
7131 compiler that ENDBR instruction should be placed at the function
7132 entry when @option{-fcf-protection=branch} is enabled.
7134 @item indirect_return
7135 @cindex @code{indirect_return} function attribute, x86
7137 The @code{indirect_return} attribute can be applied to a function,
7138 as well as variable or type of function pointer to inform the
7139 compiler that the function may return via indirect branch.
7141 @item fentry_name("@var{name}")
7142 @cindex @code{fentry_name} function attribute, x86
7143 On x86 targets, the @code{fentry_name} attribute sets the function to
7144 call on function entry when function instrumentation is enabled
7145 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
7146 nop sequence is generated.
7148 @item fentry_section("@var{name}")
7149 @cindex @code{fentry_section} function attribute, x86
7150 On x86 targets, the @code{fentry_section} attribute sets the name
7151 of the section to record function entry instrumentation calls in when
7152 enabled with @option{-pg -mrecord-mcount}
7156 @node Xstormy16 Function Attributes
7157 @subsection Xstormy16 Function Attributes
7159 These function attributes are supported by the Xstormy16 back end:
7163 @cindex @code{interrupt} function attribute, Xstormy16
7164 Use this attribute to indicate
7165 that the specified function is an interrupt handler. The compiler generates
7166 function entry and exit sequences suitable for use in an interrupt handler
7167 when this attribute is present.
7170 @node Variable Attributes
7171 @section Specifying Attributes of Variables
7172 @cindex attribute of variables
7173 @cindex variable attributes
7175 The keyword @code{__attribute__} allows you to specify special properties
7176 of variables, function parameters, or structure, union, and, in C++, class
7177 members. This @code{__attribute__} keyword is followed by an attribute
7178 specification enclosed in double parentheses. Some attributes are currently
7179 defined generically for variables. Other attributes are defined for
7180 variables on particular target systems. Other attributes are available
7181 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
7182 enumerators (@pxref{Enumerator Attributes}), statements
7183 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
7184 Other front ends might define more attributes
7185 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
7187 @xref{Attribute Syntax}, for details of the exact syntax for using
7191 * Common Variable Attributes::
7192 * ARC Variable Attributes::
7193 * AVR Variable Attributes::
7194 * Blackfin Variable Attributes::
7195 * H8/300 Variable Attributes::
7196 * IA-64 Variable Attributes::
7197 * M32R/D Variable Attributes::
7198 * MeP Variable Attributes::
7199 * Microsoft Windows Variable Attributes::
7200 * MSP430 Variable Attributes::
7201 * Nvidia PTX Variable Attributes::
7202 * PowerPC Variable Attributes::
7203 * RL78 Variable Attributes::
7204 * V850 Variable Attributes::
7205 * x86 Variable Attributes::
7206 * Xstormy16 Variable Attributes::
7209 @node Common Variable Attributes
7210 @subsection Common Variable Attributes
7212 The following attributes are supported on most targets.
7216 @item alias ("@var{target}")
7217 @cindex @code{alias} variable attribute
7218 The @code{alias} variable attribute causes the declaration to be emitted
7219 as an alias for another symbol known as an @dfn{alias target}. Except
7220 for top-level qualifiers the alias target must have the same type as
7221 the alias. For instance, the following
7225 extern int __attribute__ ((alias ("var_target"))) var_alias;
7229 defines @code{var_alias} to be an alias for the @code{var_target} variable.
7231 It is an error if the alias target is not defined in the same translation
7234 Note that in the absence of the attribute GCC assumes that distinct
7235 declarations with external linkage denote distinct objects. Using both
7236 the alias and the alias target to access the same object is undefined
7237 in a translation unit without a declaration of the alias with the attribute.
7239 This attribute requires assembler and object file support, and may not be
7240 available on all targets.
7242 @cindex @code{aligned} variable attribute
7244 @itemx aligned (@var{alignment})
7245 The @code{aligned} attribute specifies a minimum alignment for the variable
7246 or structure field, measured in bytes. When specified, @var{alignment} must
7247 be an integer constant power of 2. Specifying no @var{alignment} argument
7248 implies the maximum alignment for the target, which is often, but by no
7249 means always, 8 or 16 bytes.
7251 For example, the declaration:
7254 int x __attribute__ ((aligned (16))) = 0;
7258 causes the compiler to allocate the global variable @code{x} on a
7259 16-byte boundary. On a 68040, this could be used in conjunction with
7260 an @code{asm} expression to access the @code{move16} instruction which
7261 requires 16-byte aligned operands.
7263 You can also specify the alignment of structure fields. For example, to
7264 create a double-word aligned @code{int} pair, you could write:
7267 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
7271 This is an alternative to creating a union with a @code{double} member,
7272 which forces the union to be double-word aligned.
7274 As in the preceding examples, you can explicitly specify the alignment
7275 (in bytes) that you wish the compiler to use for a given variable or
7276 structure field. Alternatively, you can leave out the alignment factor
7277 and just ask the compiler to align a variable or field to the
7278 default alignment for the target architecture you are compiling for.
7279 The default alignment is sufficient for all scalar types, but may not be
7280 enough for all vector types on a target that supports vector operations.
7281 The default alignment is fixed for a particular target ABI.
7283 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
7284 which is the largest alignment ever used for any data type on the
7285 target machine you are compiling for. For example, you could write:
7288 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
7291 The compiler automatically sets the alignment for the declared
7292 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
7293 often make copy operations more efficient, because the compiler can
7294 use whatever instructions copy the biggest chunks of memory when
7295 performing copies to or from the variables or fields that you have
7296 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
7297 may change depending on command-line options.
7299 When used on a struct, or struct member, the @code{aligned} attribute can
7300 only increase the alignment; in order to decrease it, the @code{packed}
7301 attribute must be specified as well. When used as part of a typedef, the
7302 @code{aligned} attribute can both increase and decrease alignment, and
7303 specifying the @code{packed} attribute generates a warning.
7305 Note that the effectiveness of @code{aligned} attributes for static
7306 variables may be limited by inherent limitations in the system linker
7307 and/or object file format. On some systems, the linker is
7308 only able to arrange for variables to be aligned up to a certain maximum
7309 alignment. (For some linkers, the maximum supported alignment may
7310 be very very small.) If your linker is only able to align variables
7311 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
7312 in an @code{__attribute__} still only provides you with 8-byte
7313 alignment. See your linker documentation for further information.
7315 Stack variables are not affected by linker restrictions; GCC can properly
7316 align them on any target.
7318 The @code{aligned} attribute can also be used for functions
7319 (@pxref{Common Function Attributes}.)
7321 @cindex @code{warn_if_not_aligned} variable attribute
7322 @item warn_if_not_aligned (@var{alignment})
7323 This attribute specifies a threshold for the structure field, measured
7324 in bytes. If the structure field is aligned below the threshold, a
7325 warning will be issued. For example, the declaration:
7332 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
7337 causes the compiler to issue an warning on @code{struct foo}, like
7338 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
7339 The compiler also issues a warning, like @samp{warning: 'x' offset
7340 8 in 'struct foo' isn't aligned to 16}, when the structure field has
7341 the misaligned offset:
7344 struct __attribute__ ((aligned (16))) foo
7348 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
7352 This warning can be disabled by @option{-Wno-if-not-aligned}.
7353 The @code{warn_if_not_aligned} attribute can also be used for types
7354 (@pxref{Common Type Attributes}.)
7356 @item alloc_size (@var{position})
7357 @itemx alloc_size (@var{position-1}, @var{position-2})
7358 @cindex @code{alloc_size} variable attribute
7359 The @code{alloc_size} variable attribute may be applied to the declaration
7360 of a pointer to a function that returns a pointer and takes at least one
7361 argument of an integer type. It indicates that the returned pointer points
7362 to an object whose size is given by the function argument at @var{position},
7363 or by the product of the arguments at @var{position-1} and @var{position-2}.
7364 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
7365 sizes are diagnosed when detected. GCC uses this information to improve
7366 the results of @code{__builtin_object_size}.
7368 For instance, the following declarations
7371 typedef __attribute__ ((alloc_size (1, 2))) void*
7372 (*calloc_ptr) (size_t, size_t);
7373 typedef __attribute__ ((alloc_size (1))) void*
7374 (*malloc_ptr) (size_t);
7378 specify that @code{calloc_ptr} is a pointer of a function that, like
7379 the standard C function @code{calloc}, returns an object whose size
7380 is given by the product of arguments 1 and 2, and similarly, that
7381 @code{malloc_ptr}, like the standard C function @code{malloc},
7382 returns an object whose size is given by argument 1 to the function.
7384 @item cleanup (@var{cleanup_function})
7385 @cindex @code{cleanup} variable attribute
7386 The @code{cleanup} attribute runs a function when the variable goes
7387 out of scope. This attribute can only be applied to auto function
7388 scope variables; it may not be applied to parameters or variables
7389 with static storage duration. The function must take one parameter,
7390 a pointer to a type compatible with the variable. The return value
7391 of the function (if any) is ignored.
7393 If @option{-fexceptions} is enabled, then @var{cleanup_function}
7394 is run during the stack unwinding that happens during the
7395 processing of the exception. Note that the @code{cleanup} attribute
7396 does not allow the exception to be caught, only to perform an action.
7397 It is undefined what happens if @var{cleanup_function} does not
7402 @cindex @code{common} variable attribute
7403 @cindex @code{nocommon} variable attribute
7406 The @code{common} attribute requests GCC to place a variable in
7407 ``common'' storage. The @code{nocommon} attribute requests the
7408 opposite---to allocate space for it directly.
7410 These attributes override the default chosen by the
7411 @option{-fno-common} and @option{-fcommon} flags respectively.
7414 @itemx copy (@var{variable})
7415 @cindex @code{copy} variable attribute
7416 The @code{copy} attribute applies the set of attributes with which
7417 @var{variable} has been declared to the declaration of the variable
7418 to which the attribute is applied. The attribute is designed for
7419 libraries that define aliases that are expected to specify the same
7420 set of attributes as the aliased symbols. The @code{copy} attribute
7421 can be used with variables, functions or types. However, the kind
7422 of symbol to which the attribute is applied (either varible or
7423 function) must match the kind of symbol to which the argument refers.
7424 The @code{copy} attribute copies only syntactic and semantic attributes
7425 but not attributes that affect a symbol's linkage or visibility such as
7426 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7427 attribute is also not copied. @xref{Common Function Attributes}.
7428 @xref{Common Type Attributes}.
7431 @itemx deprecated (@var{msg})
7432 @cindex @code{deprecated} variable attribute
7433 The @code{deprecated} attribute results in a warning if the variable
7434 is used anywhere in the source file. This is useful when identifying
7435 variables that are expected to be removed in a future version of a
7436 program. The warning also includes the location of the declaration
7437 of the deprecated variable, to enable users to easily find further
7438 information about why the variable is deprecated, or what they should
7439 do instead. Note that the warning only occurs for uses:
7442 extern int old_var __attribute__ ((deprecated));
7444 int new_fn () @{ return old_var; @}
7448 results in a warning on line 3 but not line 2. The optional @var{msg}
7449 argument, which must be a string, is printed in the warning if
7452 The @code{deprecated} attribute can also be used for functions and
7453 types (@pxref{Common Function Attributes},
7454 @pxref{Common Type Attributes}).
7456 The message attached to the attribute is affected by the setting of
7457 the @option{-fmessage-length} option.
7460 @itemx unavailable (@var{msg})
7461 @cindex @code{unavailable} variable attribute
7462 The @code{unavailable} attribute indicates that the variable so marked
7463 is not available, if it is used anywhere in the source file. It behaves
7464 in the same manner as the @code{deprecated} attribute except that the
7465 compiler will emit an error rather than a warning.
7467 It is expected that items marked as @code{deprecated} will eventually be
7468 withdrawn from interfaces, and then become unavailable. This attribute
7469 allows for marking them appropriately.
7471 The @code{unavailable} attribute can also be used for functions and
7472 types (@pxref{Common Function Attributes},
7473 @pxref{Common Type Attributes}).
7475 @item mode (@var{mode})
7476 @cindex @code{mode} variable attribute
7477 This attribute specifies the data type for the declaration---whichever
7478 type corresponds to the mode @var{mode}. This in effect lets you
7479 request an integer or floating-point type according to its width.
7481 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
7482 for a list of the possible keywords for @var{mode}.
7483 You may also specify a mode of @code{byte} or @code{__byte__} to
7484 indicate the mode corresponding to a one-byte integer, @code{word} or
7485 @code{__word__} for the mode of a one-word integer, and @code{pointer}
7486 or @code{__pointer__} for the mode used to represent pointers.
7489 @cindex @code{nonstring} variable attribute
7490 The @code{nonstring} variable attribute specifies that an object or member
7491 declaration with type array of @code{char}, @code{signed char}, or
7492 @code{unsigned char}, or pointer to such a type is intended to store
7493 character arrays that do not necessarily contain a terminating @code{NUL}.
7494 This is useful in detecting uses of such arrays or pointers with functions
7495 that expect @code{NUL}-terminated strings, and to avoid warnings when such
7496 an array or pointer is used as an argument to a bounded string manipulation
7497 function such as @code{strncpy}. For example, without the attribute, GCC
7498 will issue a warning for the @code{strncpy} call below because it may
7499 truncate the copy without appending the terminating @code{NUL} character.
7500 Using the attribute makes it possible to suppress the warning. However,
7501 when the array is declared with the attribute the call to @code{strlen} is
7502 diagnosed because when the array doesn't contain a @code{NUL}-terminated
7503 string the call is undefined. To copy, compare, of search non-string
7504 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
7505 and other functions that operate on arrays of bytes. In addition,
7506 calling @code{strnlen} and @code{strndup} with such arrays is safe
7507 provided a suitable bound is specified, and not diagnosed.
7512 char name [32] __attribute__ ((nonstring));
7515 int f (struct Data *pd, const char *s)
7517 strncpy (pd->name, s, sizeof pd->name);
7519 return strlen (pd->name); // unsafe, gets a warning
7524 @cindex @code{packed} variable attribute
7525 The @code{packed} attribute specifies that a structure member should have
7526 the smallest possible alignment---one bit for a bit-field and one byte
7527 otherwise, unless a larger value is specified with the @code{aligned}
7528 attribute. The attribute does not apply to non-member objects.
7530 For example in the structure below, the member array @code{x} is packed
7531 so that it immediately follows @code{a} with no intervening padding:
7537 int x[2] __attribute__ ((packed));
7541 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
7542 @code{packed} attribute on bit-fields of type @code{char}. This has
7543 been fixed in GCC 4.4 but the change can lead to differences in the
7544 structure layout. See the documentation of
7545 @option{-Wpacked-bitfield-compat} for more information.
7547 @item section ("@var{section-name}")
7548 @cindex @code{section} variable attribute
7549 Normally, the compiler places the objects it generates in sections like
7550 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
7551 or you need certain particular variables to appear in special sections,
7552 for example to map to special hardware. The @code{section}
7553 attribute specifies that a variable (or function) lives in a particular
7554 section. For example, this small program uses several specific section names:
7557 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
7558 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
7559 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
7560 int init_data __attribute__ ((section ("INITDATA")));
7564 /* @r{Initialize stack pointer} */
7565 init_sp (stack + sizeof (stack));
7567 /* @r{Initialize initialized data} */
7568 memcpy (&init_data, &data, &edata - &data);
7570 /* @r{Turn on the serial ports} */
7577 Use the @code{section} attribute with
7578 @emph{global} variables and not @emph{local} variables,
7579 as shown in the example.
7581 You may use the @code{section} attribute with initialized or
7582 uninitialized global variables but the linker requires
7583 each object be defined once, with the exception that uninitialized
7584 variables tentatively go in the @code{common} (or @code{bss}) section
7585 and can be multiply ``defined''. Using the @code{section} attribute
7586 changes what section the variable goes into and may cause the
7587 linker to issue an error if an uninitialized variable has multiple
7588 definitions. You can force a variable to be initialized with the
7589 @option{-fno-common} flag or the @code{nocommon} attribute.
7591 Some file formats do not support arbitrary sections so the @code{section}
7592 attribute is not available on all platforms.
7593 If you need to map the entire contents of a module to a particular
7594 section, consider using the facilities of the linker instead.
7596 @item tls_model ("@var{tls_model}")
7597 @cindex @code{tls_model} variable attribute
7598 The @code{tls_model} attribute sets thread-local storage model
7599 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
7600 overriding @option{-ftls-model=} command-line switch on a per-variable
7602 The @var{tls_model} argument should be one of @code{global-dynamic},
7603 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
7605 Not all targets support this attribute.
7608 @cindex @code{unused} variable attribute
7609 This attribute, attached to a variable or structure field, means that
7610 the variable or field is meant to be possibly unused. GCC does not
7611 produce a warning for this variable or field.
7614 @cindex @code{used} variable attribute
7615 This attribute, attached to a variable with static storage, means that
7616 the variable must be emitted even if it appears that the variable is not
7619 When applied to a static data member of a C++ class template, the
7620 attribute also means that the member is instantiated if the
7621 class itself is instantiated.
7624 @cindex @code{retain} variable attribute
7625 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
7626 will save the variable from linker garbage collection. To support
7627 this behavior, variables that have not been placed in specific sections
7628 (e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
7629 will be placed in new, unique sections.
7631 This additional functionality requires Binutils version 2.36 or later.
7634 @cindex @code{uninitialized} variable attribute
7635 This attribute, attached to a variable with automatic storage, means that
7636 the variable should not be automatically initialized by the compiler when
7637 the option @code{-ftrivial-auto-var-init} presents.
7639 With the option @code{-ftrivial-auto-var-init}, all the automatic variables
7640 that do not have explicit initializers will be initialized by the compiler.
7641 These additional compiler initializations might incur run-time overhead,
7642 sometimes dramatically. This attribute can be used to mark some variables
7643 to be excluded from such automatical initialization in order to reduce runtime
7646 This attribute has no effect when the option @code{-ftrivial-auto-var-init}
7649 @item vector_size (@var{bytes})
7650 @cindex @code{vector_size} variable attribute
7651 This attribute specifies the vector size for the type of the declared
7652 variable, measured in bytes. The type to which it applies is known as
7653 the @dfn{base type}. The @var{bytes} argument must be a positive
7654 power-of-two multiple of the base type size. For example, the declaration:
7657 int foo __attribute__ ((vector_size (16)));
7661 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
7662 divided into @code{int} sized units. Assuming a 32-bit @code{int},
7663 @code{foo}'s type is a vector of four units of four bytes each, and
7664 the corresponding mode of @code{foo} is @code{V4SI}.
7665 @xref{Vector Extensions}, for details of manipulating vector variables.
7667 This attribute is only applicable to integral and floating scalars,
7668 although arrays, pointers, and function return values are allowed in
7669 conjunction with this construct.
7671 Aggregates with this attribute are invalid, even if they are of the same
7672 size as a corresponding scalar. For example, the declaration:
7675 struct S @{ int a; @};
7676 struct S __attribute__ ((vector_size (16))) foo;
7680 is invalid even if the size of the structure is the same as the size of
7683 @item visibility ("@var{visibility_type}")
7684 @cindex @code{visibility} variable attribute
7685 This attribute affects the linkage of the declaration to which it is attached.
7686 The @code{visibility} attribute is described in
7687 @ref{Common Function Attributes}.
7690 @cindex @code{weak} variable attribute
7691 The @code{weak} attribute is described in
7692 @ref{Common Function Attributes}.
7695 @cindex @code{noinit} variable attribute
7696 Any data with the @code{noinit} attribute will not be initialized by
7697 the C runtime startup code, or the program loader. Not initializing
7698 data in this way can reduce program startup times.
7700 This attribute is specific to ELF targets and relies on the linker
7701 script to place sections with the @code{.noinit} prefix in the right
7705 @cindex @code{persistent} variable attribute
7706 Any data with the @code{persistent} attribute will not be initialized by
7707 the C runtime startup code, but will be initialized by the program
7708 loader. This enables the value of the variable to @samp{persist}
7709 between processor resets.
7711 This attribute is specific to ELF targets and relies on the linker
7712 script to place the sections with the @code{.persistent} prefix in the
7713 right location. Specifically, some type of non-volatile, writeable
7716 @item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
7717 @cindex @code{objc_nullability} variable attribute
7718 This attribute applies to pointer variables only. It allows marking the
7719 pointer with one of four possible values describing the conditions under
7720 which the pointer might have a @code{nil} value. In most cases, the
7721 attribute is intended to be an internal representation for property and
7722 method nullability (specified by language keywords); it is not recommended
7725 When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
7726 known about the conditions in which the pointer might be @code{nil}. Making
7727 this state specific serves to avoid false positives in diagnostics.
7729 When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
7730 no meaning if it is @code{nil} and thus the compiler is free to emit
7731 diagnostics if it can be determined that the value will be @code{nil}.
7733 When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
7734 be @code{nil} and carry meaning as such.
7736 When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
7737 the context of property attribute lists) this describes the case in which a
7738 property setter may take the value @code{nil} (which perhaps causes the
7739 property to be reset in some manner to a default) but for which the property
7740 getter will never validly return @code{nil}.
7744 @node ARC Variable Attributes
7745 @subsection ARC Variable Attributes
7749 @cindex @code{aux} variable attribute, ARC
7750 The @code{aux} attribute is used to directly access the ARC's
7751 auxiliary register space from C. The auxilirary register number is
7752 given via attribute argument.
7756 @node AVR Variable Attributes
7757 @subsection AVR Variable Attributes
7761 @cindex @code{progmem} variable attribute, AVR
7762 The @code{progmem} attribute is used on the AVR to place read-only
7763 data in the non-volatile program memory (flash). The @code{progmem}
7764 attribute accomplishes this by putting respective variables into a
7765 section whose name starts with @code{.progmem}.
7767 This attribute works similar to the @code{section} attribute
7768 but adds additional checking.
7771 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers:
7772 @code{progmem} affects the location
7773 of the data but not how this data is accessed.
7774 In order to read data located with the @code{progmem} attribute
7775 (inline) assembler must be used.
7777 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
7778 #include <avr/pgmspace.h>
7780 /* Locate var in flash memory */
7781 const int var[2] PROGMEM = @{ 1, 2 @};
7783 int read_var (int i)
7785 /* Access var[] by accessor macro from avr/pgmspace.h */
7786 return (int) pgm_read_word (& var[i]);
7790 AVR is a Harvard architecture processor and data and read-only data
7791 normally resides in the data memory (RAM).
7793 See also the @ref{AVR Named Address Spaces} section for
7794 an alternate way to locate and access data in flash memory.
7796 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range:
7797 On such devices, there is no need for attribute @code{progmem} or
7798 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
7799 Just use standard C / C++. The compiler will generate @code{LD*}
7800 instructions. As flash memory is visible in the RAM address range,
7801 and the default linker script does @emph{not} locate @code{.rodata} in
7802 RAM, no special features are needed in order not to waste RAM for
7803 read-only data or to read from flash. You might even get slightly better
7805 avoiding @code{progmem} and @code{__flash}. This applies to devices from
7806 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
7809 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40:
7810 The compiler adds @code{0x4000}
7811 to the addresses of objects and declarations in @code{progmem} and locates
7812 the objects in flash memory, namely in section @code{.progmem.data}.
7813 The offset is needed because the flash memory is visible in the RAM
7814 address space starting at address @code{0x4000}.
7816 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
7817 no special functions or macros are needed.
7820 /* var is located in flash memory */
7821 extern const int var[2] __attribute__((progmem));
7823 int read_var (int i)
7829 Please notice that on these devices, there is no need for @code{progmem}
7835 @itemx io (@var{addr})
7836 @cindex @code{io} variable attribute, AVR
7837 Variables with the @code{io} attribute are used to address
7838 memory-mapped peripherals in the io address range.
7839 If an address is specified, the variable
7840 is assigned that address, and the value is interpreted as an
7841 address in the data address space.
7845 volatile int porta __attribute__((io (0x22)));
7848 The address specified in the address in the data address range.
7850 Otherwise, the variable it is not assigned an address, but the
7851 compiler will still use in/out instructions where applicable,
7852 assuming some other module assigns an address in the io address range.
7856 extern volatile int porta __attribute__((io));
7860 @itemx io_low (@var{addr})
7861 @cindex @code{io_low} variable attribute, AVR
7862 This is like the @code{io} attribute, but additionally it informs the
7863 compiler that the object lies in the lower half of the I/O area,
7864 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
7868 @itemx address (@var{addr})
7869 @cindex @code{address} variable attribute, AVR
7870 Variables with the @code{address} attribute are used to address
7871 memory-mapped peripherals that may lie outside the io address range.
7874 volatile int porta __attribute__((address (0x600)));
7878 @cindex @code{absdata} variable attribute, AVR
7879 Variables in static storage and with the @code{absdata} attribute can
7880 be accessed by the @code{LDS} and @code{STS} instructions which take
7885 This attribute is only supported for the reduced AVR Tiny core
7889 You must make sure that respective data is located in the
7890 address range @code{0x40}@dots{}@code{0xbf} accessible by
7891 @code{LDS} and @code{STS}. One way to achieve this as an
7892 appropriate linker description file.
7895 If the location does not fit the address range of @code{LDS}
7896 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
7899 @code{module.c:(.text+0x1c): warning: internal error: out of range error}
7904 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
7908 @node Blackfin Variable Attributes
7909 @subsection Blackfin Variable Attributes
7911 Three attributes are currently defined for the Blackfin.
7917 @cindex @code{l1_data} variable attribute, Blackfin
7918 @cindex @code{l1_data_A} variable attribute, Blackfin
7919 @cindex @code{l1_data_B} variable attribute, Blackfin
7920 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
7921 Variables with @code{l1_data} attribute are put into the specific section
7922 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
7923 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
7924 attribute are put into the specific section named @code{.l1.data.B}.
7927 @cindex @code{l2} variable attribute, Blackfin
7928 Use this attribute on the Blackfin to place the variable into L2 SRAM.
7929 Variables with @code{l2} attribute are put into the specific section
7930 named @code{.l2.data}.
7933 @node H8/300 Variable Attributes
7934 @subsection H8/300 Variable Attributes
7936 These variable attributes are available for H8/300 targets:
7940 @cindex @code{eightbit_data} variable attribute, H8/300
7941 @cindex eight-bit data on the H8/300, H8/300H, and H8S
7942 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
7943 variable should be placed into the eight-bit data section.
7944 The compiler generates more efficient code for certain operations
7945 on data in the eight-bit data area. Note the eight-bit data area is limited to
7948 You must use GAS and GLD from GNU binutils version 2.7 or later for
7949 this attribute to work correctly.
7952 @cindex @code{tiny_data} variable attribute, H8/300
7953 @cindex tiny data section on the H8/300H and H8S
7954 Use this attribute on the H8/300H and H8S to indicate that the specified
7955 variable should be placed into the tiny data section.
7956 The compiler generates more efficient code for loads and stores
7957 on data in the tiny data section. Note the tiny data area is limited to
7958 slightly under 32KB of data.
7962 @node IA-64 Variable Attributes
7963 @subsection IA-64 Variable Attributes
7965 The IA-64 back end supports the following variable attribute:
7968 @item model (@var{model-name})
7969 @cindex @code{model} variable attribute, IA-64
7971 On IA-64, use this attribute to set the addressability of an object.
7972 At present, the only supported identifier for @var{model-name} is
7973 @code{small}, indicating addressability via ``small'' (22-bit)
7974 addresses (so that their addresses can be loaded with the @code{addl}
7975 instruction). Caveat: such addressing is by definition not position
7976 independent and hence this attribute must not be used for objects
7977 defined by shared libraries.
7981 @node M32R/D Variable Attributes
7982 @subsection M32R/D Variable Attributes
7984 One attribute is currently defined for the M32R/D@.
7987 @item model (@var{model-name})
7988 @cindex @code{model-name} variable attribute, M32R/D
7989 @cindex variable addressability on the M32R/D
7990 Use this attribute on the M32R/D to set the addressability of an object.
7991 The identifier @var{model-name} is one of @code{small}, @code{medium},
7992 or @code{large}, representing each of the code models.
7994 Small model objects live in the lower 16MB of memory (so that their
7995 addresses can be loaded with the @code{ld24} instruction).
7997 Medium and large model objects may live anywhere in the 32-bit address space
7998 (the compiler generates @code{seth/add3} instructions to load their
8002 @node MeP Variable Attributes
8003 @subsection MeP Variable Attributes
8005 The MeP target has a number of addressing modes and busses. The
8006 @code{near} space spans the standard memory space's first 16 megabytes
8007 (24 bits). The @code{far} space spans the entire 32-bit memory space.
8008 The @code{based} space is a 128-byte region in the memory space that
8009 is addressed relative to the @code{$tp} register. The @code{tiny}
8010 space is a 65536-byte region relative to the @code{$gp} register. In
8011 addition to these memory regions, the MeP target has a separate 16-bit
8012 control bus which is specified with @code{cb} attributes.
8017 @cindex @code{based} variable attribute, MeP
8018 Any variable with the @code{based} attribute is assigned to the
8019 @code{.based} section, and is accessed with relative to the
8020 @code{$tp} register.
8023 @cindex @code{tiny} variable attribute, MeP
8024 Likewise, the @code{tiny} attribute assigned variables to the
8025 @code{.tiny} section, relative to the @code{$gp} register.
8028 @cindex @code{near} variable attribute, MeP
8029 Variables with the @code{near} attribute are assumed to have addresses
8030 that fit in a 24-bit addressing mode. This is the default for large
8031 variables (@code{-mtiny=4} is the default) but this attribute can
8032 override @code{-mtiny=} for small variables, or override @code{-ml}.
8035 @cindex @code{far} variable attribute, MeP
8036 Variables with the @code{far} attribute are addressed using a full
8037 32-bit address. Since this covers the entire memory space, this
8038 allows modules to make no assumptions about where variables might be
8042 @cindex @code{io} variable attribute, MeP
8043 @itemx io (@var{addr})
8044 Variables with the @code{io} attribute are used to address
8045 memory-mapped peripherals. If an address is specified, the variable
8046 is assigned that address, else it is not assigned an address (it is
8047 assumed some other module assigns an address). Example:
8050 int timer_count __attribute__((io(0x123)));
8054 @itemx cb (@var{addr})
8055 @cindex @code{cb} variable attribute, MeP
8056 Variables with the @code{cb} attribute are used to access the control
8057 bus, using special instructions. @code{addr} indicates the control bus
8061 int cpu_clock __attribute__((cb(0x123)));
8066 @node Microsoft Windows Variable Attributes
8067 @subsection Microsoft Windows Variable Attributes
8069 You can use these attributes on Microsoft Windows targets.
8070 @ref{x86 Variable Attributes} for additional Windows compatibility
8071 attributes available on all x86 targets.
8076 @cindex @code{dllimport} variable attribute
8077 @cindex @code{dllexport} variable attribute
8078 The @code{dllimport} and @code{dllexport} attributes are described in
8079 @ref{Microsoft Windows Function Attributes}.
8082 @cindex @code{selectany} variable attribute
8083 The @code{selectany} attribute causes an initialized global variable to
8084 have link-once semantics. When multiple definitions of the variable are
8085 encountered by the linker, the first is selected and the remainder are
8086 discarded. Following usage by the Microsoft compiler, the linker is told
8087 @emph{not} to warn about size or content differences of the multiple
8090 Although the primary usage of this attribute is for POD types, the
8091 attribute can also be applied to global C++ objects that are initialized
8092 by a constructor. In this case, the static initialization and destruction
8093 code for the object is emitted in each translation defining the object,
8094 but the calls to the constructor and destructor are protected by a
8095 link-once guard variable.
8097 The @code{selectany} attribute is only available on Microsoft Windows
8098 targets. You can use @code{__declspec (selectany)} as a synonym for
8099 @code{__attribute__ ((selectany))} for compatibility with other
8103 @cindex @code{shared} variable attribute
8104 On Microsoft Windows, in addition to putting variable definitions in a named
8105 section, the section can also be shared among all running copies of an
8106 executable or DLL@. For example, this small program defines shared data
8107 by putting it in a named section @code{shared} and marking the section
8111 int foo __attribute__((section ("shared"), shared)) = 0;
8116 /* @r{Read and write foo. All running
8117 copies see the same value.} */
8123 You may only use the @code{shared} attribute along with @code{section}
8124 attribute with a fully-initialized global definition because of the way
8125 linkers work. See @code{section} attribute for more information.
8127 The @code{shared} attribute is only available on Microsoft Windows@.
8131 @node MSP430 Variable Attributes
8132 @subsection MSP430 Variable Attributes
8137 @cindex @code{upper} variable attribute, MSP430
8138 @cindex @code{either} variable attribute, MSP430
8139 These attributes are the same as the MSP430 function attributes of the
8140 same name (@pxref{MSP430 Function Attributes}).
8143 @cindex @code{lower} variable attribute, MSP430
8144 This option behaves mostly the same as the MSP430 function attribute of the
8145 same name (@pxref{MSP430 Function Attributes}), but it has some additional
8148 If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
8149 the @code{section} attribute is applied to a variable, the compiler will
8150 generate 430X instructions to handle it. This is because the compiler has
8151 to assume that the variable could get placed in the upper memory region
8152 (above address 0xFFFF). Marking the variable with the @code{lower} attribute
8153 informs the compiler that the variable will be placed in lower memory so it
8154 is safe to use 430 instructions to handle it.
8156 In the case of the @code{section} attribute, the section name given
8157 will be used, and the @code{.lower} prefix will not be added.
8161 @node Nvidia PTX Variable Attributes
8162 @subsection Nvidia PTX Variable Attributes
8164 These variable attributes are supported by the Nvidia PTX back end:
8168 @cindex @code{shared} attribute, Nvidia PTX
8169 Use this attribute to place a variable in the @code{.shared} memory space.
8170 This memory space is private to each cooperative thread array; only threads
8171 within one thread block refer to the same instance of the variable.
8172 The runtime does not initialize variables in this memory space.
8175 @node PowerPC Variable Attributes
8176 @subsection PowerPC Variable Attributes
8178 Three attributes currently are defined for PowerPC configurations:
8179 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8181 @cindex @code{ms_struct} variable attribute, PowerPC
8182 @cindex @code{gcc_struct} variable attribute, PowerPC
8183 For full documentation of the struct attributes please see the
8184 documentation in @ref{x86 Variable Attributes}.
8186 @cindex @code{altivec} variable attribute, PowerPC
8187 For documentation of @code{altivec} attribute please see the
8188 documentation in @ref{PowerPC Type Attributes}.
8190 @node RL78 Variable Attributes
8191 @subsection RL78 Variable Attributes
8193 @cindex @code{saddr} variable attribute, RL78
8194 The RL78 back end supports the @code{saddr} variable attribute. This
8195 specifies placement of the corresponding variable in the SADDR area,
8196 which can be accessed more efficiently than the default memory region.
8198 @node V850 Variable Attributes
8199 @subsection V850 Variable Attributes
8201 These variable attributes are supported by the V850 back end:
8206 @cindex @code{sda} variable attribute, V850
8207 Use this attribute to explicitly place a variable in the small data area,
8208 which can hold up to 64 kilobytes.
8211 @cindex @code{tda} variable attribute, V850
8212 Use this attribute to explicitly place a variable in the tiny data area,
8213 which can hold up to 256 bytes in total.
8216 @cindex @code{zda} variable attribute, V850
8217 Use this attribute to explicitly place a variable in the first 32 kilobytes
8221 @node x86 Variable Attributes
8222 @subsection x86 Variable Attributes
8224 Two attributes are currently defined for x86 configurations:
8225 @code{ms_struct} and @code{gcc_struct}.
8230 @cindex @code{ms_struct} variable attribute, x86
8231 @cindex @code{gcc_struct} variable attribute, x86
8233 If @code{packed} is used on a structure, or if bit-fields are used,
8234 it may be that the Microsoft ABI lays out the structure differently
8235 than the way GCC normally does. Particularly when moving packed
8236 data between functions compiled with GCC and the native Microsoft compiler
8237 (either via function call or as data in a file), it may be necessary to access
8240 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8241 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8242 command-line options, respectively;
8243 see @ref{x86 Options}, for details of how structure layout is affected.
8244 @xref{x86 Type Attributes}, for information about the corresponding
8245 attributes on types.
8249 @node Xstormy16 Variable Attributes
8250 @subsection Xstormy16 Variable Attributes
8252 One attribute is currently defined for xstormy16 configurations:
8257 @cindex @code{below100} variable attribute, Xstormy16
8259 If a variable has the @code{below100} attribute (@code{BELOW100} is
8260 allowed also), GCC places the variable in the first 0x100 bytes of
8261 memory and use special opcodes to access it. Such variables are
8262 placed in either the @code{.bss_below100} section or the
8263 @code{.data_below100} section.
8267 @node Type Attributes
8268 @section Specifying Attributes of Types
8269 @cindex attribute of types
8270 @cindex type attributes
8272 The keyword @code{__attribute__} allows you to specify various special
8273 properties of types. Some type attributes apply only to structure and
8274 union types, and in C++, also class types, while others can apply to
8275 any type defined via a @code{typedef} declaration. Unless otherwise
8276 specified, the same restrictions and effects apply to attributes regardless
8277 of whether a type is a trivial structure or a C++ class with user-defined
8278 constructors, destructors, or a copy assignment.
8280 Other attributes are defined for functions (@pxref{Function Attributes}),
8281 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
8282 Attributes}), statements (@pxref{Statement Attributes}), and for variables
8283 (@pxref{Variable Attributes}).
8285 The @code{__attribute__} keyword is followed by an attribute specification
8286 enclosed in double parentheses.
8288 You may specify type attributes in an enum, struct or union type
8289 declaration or definition by placing them immediately after the
8290 @code{struct}, @code{union} or @code{enum} keyword. You can also place
8291 them just past the closing curly brace of the definition, but this is less
8292 preferred because logically the type should be fully defined at
8295 You can also include type attributes in a @code{typedef} declaration.
8296 @xref{Attribute Syntax}, for details of the exact syntax for using
8300 * Common Type Attributes::
8301 * ARC Type Attributes::
8302 * ARM Type Attributes::
8303 * BPF Type Attributes::
8304 * MeP Type Attributes::
8305 * PowerPC Type Attributes::
8306 * x86 Type Attributes::
8309 @node Common Type Attributes
8310 @subsection Common Type Attributes
8312 The following type attributes are supported on most targets.
8315 @cindex @code{aligned} type attribute
8317 @itemx aligned (@var{alignment})
8318 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
8319 variables of the specified type. When specified, @var{alignment} must be
8320 a power of 2. Specifying no @var{alignment} argument implies the maximum
8321 alignment for the target, which is often, but by no means always, 8 or 16
8322 bytes. For example, the declarations:
8325 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
8326 typedef int more_aligned_int __attribute__ ((aligned (8)));
8330 force the compiler to ensure (as far as it can) that each variable whose
8331 type is @code{struct S} or @code{more_aligned_int} is allocated and
8332 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
8333 variables of type @code{struct S} aligned to 8-byte boundaries allows
8334 the compiler to use the @code{ldd} and @code{std} (doubleword load and
8335 store) instructions when copying one variable of type @code{struct S} to
8336 another, thus improving run-time efficiency.
8338 Note that the alignment of any given @code{struct} or @code{union} type
8339 is required by the ISO C standard to be at least a perfect multiple of
8340 the lowest common multiple of the alignments of all of the members of
8341 the @code{struct} or @code{union} in question. This means that you @emph{can}
8342 effectively adjust the alignment of a @code{struct} or @code{union}
8343 type by attaching an @code{aligned} attribute to any one of the members
8344 of such a type, but the notation illustrated in the example above is a
8345 more obvious, intuitive, and readable way to request the compiler to
8346 adjust the alignment of an entire @code{struct} or @code{union} type.
8348 As in the preceding example, you can explicitly specify the alignment
8349 (in bytes) that you wish the compiler to use for a given @code{struct}
8350 or @code{union} type. Alternatively, you can leave out the alignment factor
8351 and just ask the compiler to align a type to the maximum
8352 useful alignment for the target machine you are compiling for. For
8353 example, you could write:
8356 struct __attribute__ ((aligned)) S @{ short f[3]; @};
8359 Whenever you leave out the alignment factor in an @code{aligned}
8360 attribute specification, the compiler automatically sets the alignment
8361 for the type to the largest alignment that is ever used for any data
8362 type on the target machine you are compiling for. Doing this can often
8363 make copy operations more efficient, because the compiler can use
8364 whatever instructions copy the biggest chunks of memory when performing
8365 copies to or from the variables that have types that you have aligned
8368 In the example above, if the size of each @code{short} is 2 bytes, then
8369 the size of the entire @code{struct S} type is 6 bytes. The smallest
8370 power of two that is greater than or equal to that is 8, so the
8371 compiler sets the alignment for the entire @code{struct S} type to 8
8374 Note that although you can ask the compiler to select a time-efficient
8375 alignment for a given type and then declare only individual stand-alone
8376 objects of that type, the compiler's ability to select a time-efficient
8377 alignment is primarily useful only when you plan to create arrays of
8378 variables having the relevant (efficiently aligned) type. If you
8379 declare or use arrays of variables of an efficiently-aligned type, then
8380 it is likely that your program also does pointer arithmetic (or
8381 subscripting, which amounts to the same thing) on pointers to the
8382 relevant type, and the code that the compiler generates for these
8383 pointer arithmetic operations is often more efficient for
8384 efficiently-aligned types than for other types.
8386 Note that the effectiveness of @code{aligned} attributes may be limited
8387 by inherent limitations in your linker. On many systems, the linker is
8388 only able to arrange for variables to be aligned up to a certain maximum
8389 alignment. (For some linkers, the maximum supported alignment may
8390 be very very small.) If your linker is only able to align variables
8391 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
8392 in an @code{__attribute__} still only provides you with 8-byte
8393 alignment. See your linker documentation for further information.
8395 When used on a struct, or struct member, the @code{aligned} attribute can
8396 only increase the alignment; in order to decrease it, the @code{packed}
8397 attribute must be specified as well. When used as part of a typedef, the
8398 @code{aligned} attribute can both increase and decrease alignment, and
8399 specifying the @code{packed} attribute generates a warning.
8401 @cindex @code{warn_if_not_aligned} type attribute
8402 @item warn_if_not_aligned (@var{alignment})
8403 This attribute specifies a threshold for the structure field, measured
8404 in bytes. If the structure field is aligned below the threshold, a
8405 warning will be issued. For example, the declaration:
8408 typedef unsigned long long __u64
8409 __attribute__((aligned (4), warn_if_not_aligned (8)));
8420 causes the compiler to issue an warning on @code{struct foo}, like
8421 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
8422 It is used to define @code{struct foo} in such a way that
8423 @code{struct foo} has the same layout and the structure field @code{x}
8424 has the same alignment when @code{__u64} is aligned at either 4 or
8425 8 bytes. Align @code{struct foo} to 8 bytes:
8428 struct __attribute__ ((aligned (8))) foo
8437 silences the warning. The compiler also issues a warning, like
8438 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
8439 when the structure field has the misaligned offset:
8442 struct __attribute__ ((aligned (8))) foo
8451 This warning can be disabled by @option{-Wno-if-not-aligned}.
8453 @item alloc_size (@var{position})
8454 @itemx alloc_size (@var{position-1}, @var{position-2})
8455 @cindex @code{alloc_size} type attribute
8456 The @code{alloc_size} type attribute may be applied to the definition
8457 of a type of a function that returns a pointer and takes at least one
8458 argument of an integer type. It indicates that the returned pointer
8459 points to an object whose size is given by the function argument at
8460 @var{position-1}, or by the product of the arguments at @var{position-1}
8461 and @var{position-2}. Meaningful sizes are positive values less than
8462 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
8463 this information to improve the results of @code{__builtin_object_size}.
8465 For instance, the following declarations
8468 typedef __attribute__ ((alloc_size (1, 2))) void*
8469 calloc_type (size_t, size_t);
8470 typedef __attribute__ ((alloc_size (1))) void*
8471 malloc_type (size_t);
8475 specify that @code{calloc_type} is a type of a function that, like
8476 the standard C function @code{calloc}, returns an object whose size
8477 is given by the product of arguments 1 and 2, and that
8478 @code{malloc_type}, like the standard C function @code{malloc},
8479 returns an object whose size is given by argument 1 to the function.
8482 @itemx copy (@var{expression})
8483 @cindex @code{copy} type attribute
8484 The @code{copy} attribute applies the set of attributes with which
8485 the type of the @var{expression} has been declared to the declaration
8486 of the type to which the attribute is applied. The attribute is
8487 designed for libraries that define aliases that are expected to
8488 specify the same set of attributes as the aliased symbols.
8489 The @code{copy} attribute can be used with types, variables, or
8490 functions. However, the kind of symbol to which the attribute is
8491 applied (either varible or function) must match the kind of symbol
8492 to which the argument refers.
8493 The @code{copy} attribute copies only syntactic and semantic attributes
8494 but not attributes that affect a symbol's linkage or visibility such as
8495 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
8496 attribute is also not copied. @xref{Common Function Attributes}.
8497 @xref{Common Variable Attributes}.
8499 For example, suppose @code{struct A} below is defined in some third
8500 party library header to have the alignment requirement @code{N} and
8501 to force a warning whenever a variable of the type is not so aligned
8502 due to attribute @code{packed}. Specifying the @code{copy} attribute
8503 on the definition on the unrelated @code{struct B} has the effect of
8504 copying all relevant attributes from the type referenced by the pointer
8505 expression to @code{struct B}.
8508 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
8509 A @{ /* @r{@dots{}} */ @};
8510 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
8514 @itemx deprecated (@var{msg})
8515 @cindex @code{deprecated} type attribute
8516 The @code{deprecated} attribute results in a warning if the type
8517 is used anywhere in the source file. This is useful when identifying
8518 types that are expected to be removed in a future version of a program.
8519 If possible, the warning also includes the location of the declaration
8520 of the deprecated type, to enable users to easily find further
8521 information about why the type is deprecated, or what they should do
8522 instead. Note that the warnings only occur for uses and then only
8523 if the type is being applied to an identifier that itself is not being
8524 declared as deprecated.
8527 typedef int T1 __attribute__ ((deprecated));
8531 typedef T1 T3 __attribute__ ((deprecated));
8532 T3 z __attribute__ ((deprecated));
8536 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
8537 warning is issued for line 4 because T2 is not explicitly
8538 deprecated. Line 5 has no warning because T3 is explicitly
8539 deprecated. Similarly for line 6. The optional @var{msg}
8540 argument, which must be a string, is printed in the warning if
8541 present. Control characters in the string will be replaced with
8542 escape sequences, and if the @option{-fmessage-length} option is set
8543 to 0 (its default value) then any newline characters will be ignored.
8545 The @code{deprecated} attribute can also be used for functions and
8546 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8548 The message attached to the attribute is affected by the setting of
8549 the @option{-fmessage-length} option.
8552 @itemx unavailable (@var{msg})
8553 @cindex @code{unavailable} type attribute
8554 The @code{unavailable} attribute behaves in the same manner as the
8555 @code{deprecated} one, but emits an error rather than a warning. It is
8556 used to indicate that a (perhaps previously @code{deprecated}) type is
8559 The @code{unavailable} attribute can also be used for functions and
8560 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8562 @item designated_init
8563 @cindex @code{designated_init} type attribute
8564 This attribute may only be applied to structure types. It indicates
8565 that any initialization of an object of this type must use designated
8566 initializers rather than positional initializers. The intent of this
8567 attribute is to allow the programmer to indicate that a structure's
8568 layout may change, and that therefore relying on positional
8569 initialization will result in future breakage.
8571 GCC emits warnings based on this attribute by default; use
8572 @option{-Wno-designated-init} to suppress them.
8575 @cindex @code{may_alias} type attribute
8576 Accesses through pointers to types with this attribute are not subject
8577 to type-based alias analysis, but are instead assumed to be able to alias
8578 any other type of objects.
8579 In the context of section 6.5 paragraph 7 of the C99 standard,
8580 an lvalue expression
8581 dereferencing such a pointer is treated like having a character type.
8582 See @option{-fstrict-aliasing} for more information on aliasing issues.
8583 This extension exists to support some vector APIs, in which pointers to
8584 one vector type are permitted to alias pointers to a different vector type.
8586 Note that an object of a type with this attribute does not have any
8592 typedef short __attribute__ ((__may_alias__)) short_a;
8598 short_a *b = (short_a *) &a;
8602 if (a == 0x12345678)
8610 If you replaced @code{short_a} with @code{short} in the variable
8611 declaration, the above program would abort when compiled with
8612 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
8615 @item mode (@var{mode})
8616 @cindex @code{mode} type attribute
8617 This attribute specifies the data type for the declaration---whichever
8618 type corresponds to the mode @var{mode}. This in effect lets you
8619 request an integer or floating-point type according to its width.
8621 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
8622 for a list of the possible keywords for @var{mode}.
8623 You may also specify a mode of @code{byte} or @code{__byte__} to
8624 indicate the mode corresponding to a one-byte integer, @code{word} or
8625 @code{__word__} for the mode of a one-word integer, and @code{pointer}
8626 or @code{__pointer__} for the mode used to represent pointers.
8629 @cindex @code{packed} type attribute
8630 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
8631 type definition, specifies that each of its members (other than zero-width
8632 bit-fields) is placed to minimize the memory required. This is equivalent
8633 to specifying the @code{packed} attribute on each of the members.
8635 @opindex fshort-enums
8636 When attached to an @code{enum} definition, the @code{packed} attribute
8637 indicates that the smallest integral type should be used.
8638 Specifying the @option{-fshort-enums} flag on the command line
8639 is equivalent to specifying the @code{packed}
8640 attribute on all @code{enum} definitions.
8642 In the following example @code{struct my_packed_struct}'s members are
8643 packed closely together, but the internal layout of its @code{s} member
8644 is not packed---to do that, @code{struct my_unpacked_struct} needs to
8648 struct my_unpacked_struct
8654 struct __attribute__ ((__packed__)) my_packed_struct
8658 struct my_unpacked_struct s;
8662 You may only specify the @code{packed} attribute on the definition
8663 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
8664 not on a @code{typedef} that does not also define the enumerated type,
8665 structure, union, or class.
8667 @item scalar_storage_order ("@var{endianness}")
8668 @cindex @code{scalar_storage_order} type attribute
8669 When attached to a @code{union} or a @code{struct}, this attribute sets
8670 the storage order, aka endianness, of the scalar fields of the type, as
8671 well as the array fields whose component is scalar. The supported
8672 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
8673 has no effects on fields which are themselves a @code{union}, a @code{struct}
8674 or an array whose component is a @code{union} or a @code{struct}, and it is
8675 possible for these fields to have a different scalar storage order than the
8678 Note that neither pointer nor vector fields are considered scalar fields in
8679 this context, so the attribute has no effects on these fields.
8681 This attribute is supported only for targets that use a uniform default
8682 scalar storage order (fortunately, most of them), i.e.@: targets that store
8683 the scalars either all in big-endian or all in little-endian.
8685 Additional restrictions are enforced for types with the reverse scalar
8686 storage order with regard to the scalar storage order of the target:
8689 @item Taking the address of a scalar field of a @code{union} or a
8690 @code{struct} with reverse scalar storage order is not permitted and yields
8692 @item Taking the address of an array field, whose component is scalar, of
8693 a @code{union} or a @code{struct} with reverse scalar storage order is
8694 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
8696 @item Taking the address of a @code{union} or a @code{struct} with reverse
8697 scalar storage order is permitted.
8700 These restrictions exist because the storage order attribute is lost when
8701 the address of a scalar or the address of an array with scalar component is
8702 taken, so storing indirectly through this address generally does not work.
8703 The second case is nevertheless allowed to be able to perform a block copy
8704 from or to the array.
8706 Moreover, the use of type punning or aliasing to toggle the storage order
8707 is not supported; that is to say, if a given scalar object can be accessed
8708 through distinct types that assign a different storage order to it, then the
8709 behavior is undefined.
8711 @item transparent_union
8712 @cindex @code{transparent_union} type attribute
8714 This attribute, attached to a @code{union} type definition, indicates
8715 that any function parameter having that union type causes calls to that
8716 function to be treated in a special way.
8718 First, the argument corresponding to a transparent union type can be of
8719 any type in the union; no cast is required. Also, if the union contains
8720 a pointer type, the corresponding argument can be a null pointer
8721 constant or a void pointer expression; and if the union contains a void
8722 pointer type, the corresponding argument can be any pointer expression.
8723 If the union member type is a pointer, qualifiers like @code{const} on
8724 the referenced type must be respected, just as with normal pointer
8727 Second, the argument is passed to the function using the calling
8728 conventions of the first member of the transparent union, not the calling
8729 conventions of the union itself. All members of the union must have the
8730 same machine representation; this is necessary for this argument passing
8733 Transparent unions are designed for library functions that have multiple
8734 interfaces for compatibility reasons. For example, suppose the
8735 @code{wait} function must accept either a value of type @code{int *} to
8736 comply with POSIX, or a value of type @code{union wait *} to comply with
8737 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
8738 @code{wait} would accept both kinds of arguments, but it would also
8739 accept any other pointer type and this would make argument type checking
8740 less useful. Instead, @code{<sys/wait.h>} might define the interface
8744 typedef union __attribute__ ((__transparent_union__))
8748 @} wait_status_ptr_t;
8750 pid_t wait (wait_status_ptr_t);
8754 This interface allows either @code{int *} or @code{union wait *}
8755 arguments to be passed, using the @code{int *} calling convention.
8756 The program can call @code{wait} with arguments of either type:
8759 int w1 () @{ int w; return wait (&w); @}
8760 int w2 () @{ union wait w; return wait (&w); @}
8764 With this interface, @code{wait}'s implementation might look like this:
8767 pid_t wait (wait_status_ptr_t p)
8769 return waitpid (-1, p.__ip, 0);
8774 @cindex @code{unused} type attribute
8775 When attached to a type (including a @code{union} or a @code{struct}),
8776 this attribute means that variables of that type are meant to appear
8777 possibly unused. GCC does not produce a warning for any variables of
8778 that type, even if the variable appears to do nothing. This is often
8779 the case with lock or thread classes, which are usually defined and then
8780 not referenced, but contain constructors and destructors that have
8781 nontrivial bookkeeping functions.
8783 @item vector_size (@var{bytes})
8784 @cindex @code{vector_size} type attribute
8785 This attribute specifies the vector size for the type, measured in bytes.
8786 The type to which it applies is known as the @dfn{base type}. The @var{bytes}
8787 argument must be a positive power-of-two multiple of the base type size. For
8788 example, the following declarations:
8791 typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
8792 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
8793 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
8797 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
8798 sized units. With @code{int} having a size of 4 bytes, the type defines
8799 a vector of eight units, four bytes each. The mode of variables of type
8800 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
8801 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
8802 an array of three such vectors. @xref{Vector Extensions}, for details of
8803 manipulating objects of vector types.
8805 This attribute is only applicable to integral and floating scalar types.
8806 In function declarations the attribute applies to the function return
8809 For example, the following:
8811 __attribute__ ((vector_size (16))) float get_flt_vec16 (void);
8813 declares @code{get_flt_vec16} to be a function returning a 16-byte vector
8814 with the base type @code{float}.
8817 @cindex @code{visibility} type attribute
8818 In C++, attribute visibility (@pxref{Function Attributes}) can also be
8819 applied to class, struct, union and enum types. Unlike other type
8820 attributes, the attribute must appear between the initial keyword and
8821 the name of the type; it cannot appear after the body of the type.
8823 Note that the type visibility is applied to vague linkage entities
8824 associated with the class (vtable, typeinfo node, etc.). In
8825 particular, if a class is thrown as an exception in one shared object
8826 and caught in another, the class must have default visibility.
8827 Otherwise the two shared objects are unable to use the same
8828 typeinfo node and exception handling will break.
8830 @item objc_root_class @r{(Objective-C and Objective-C++ only)}
8831 @cindex @code{objc_root_class} type attribute
8832 This attribute marks a class as being a root class, and thus allows
8833 the compiler to elide any warnings about a missing superclass and to
8834 make additional checks for mandatory methods as needed.
8838 To specify multiple attributes, separate them by commas within the
8839 double parentheses: for example, @samp{__attribute__ ((aligned (16),
8842 @node ARC Type Attributes
8843 @subsection ARC Type Attributes
8845 @cindex @code{uncached} type attribute, ARC
8846 Declaring objects with @code{uncached} allows you to exclude
8847 data-cache participation in load and store operations on those objects
8848 without involving the additional semantic implications of
8849 @code{volatile}. The @code{.di} instruction suffix is used for all
8850 loads and stores of data declared @code{uncached}.
8852 @node ARM Type Attributes
8853 @subsection ARM Type Attributes
8855 @cindex @code{notshared} type attribute, ARM
8856 On those ARM targets that support @code{dllimport} (such as Symbian
8857 OS), you can use the @code{notshared} attribute to indicate that the
8858 virtual table and other similar data for a class should not be
8859 exported from a DLL@. For example:
8862 class __declspec(notshared) C @{
8864 __declspec(dllimport) C();
8868 __declspec(dllexport)
8873 In this code, @code{C::C} is exported from the current DLL, but the
8874 virtual table for @code{C} is not exported. (You can use
8875 @code{__attribute__} instead of @code{__declspec} if you prefer, but
8876 most Symbian OS code uses @code{__declspec}.)
8878 @node BPF Type Attributes
8879 @subsection BPF Type Attributes
8881 @cindex @code{preserve_access_index} type attribute, BPF
8882 BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a
8883 @code{struct} or @code{union} type definition, indicates that CO-RE
8884 relocation information should be generated for any access to a variable
8885 of that type. The behavior is equivalent to the programmer manually
8886 wrapping every such access with @code{__builtin_preserve_access_index}.
8889 @node MeP Type Attributes
8890 @subsection MeP Type Attributes
8892 @cindex @code{based} type attribute, MeP
8893 @cindex @code{tiny} type attribute, MeP
8894 @cindex @code{near} type attribute, MeP
8895 @cindex @code{far} type attribute, MeP
8896 Many of the MeP variable attributes may be applied to types as well.
8897 Specifically, the @code{based}, @code{tiny}, @code{near}, and
8898 @code{far} attributes may be applied to either. The @code{io} and
8899 @code{cb} attributes may not be applied to types.
8901 @node PowerPC Type Attributes
8902 @subsection PowerPC Type Attributes
8904 Three attributes currently are defined for PowerPC configurations:
8905 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8907 @cindex @code{ms_struct} type attribute, PowerPC
8908 @cindex @code{gcc_struct} type attribute, PowerPC
8909 For full documentation of the @code{ms_struct} and @code{gcc_struct}
8910 attributes please see the documentation in @ref{x86 Type Attributes}.
8912 @cindex @code{altivec} type attribute, PowerPC
8913 The @code{altivec} attribute allows one to declare AltiVec vector data
8914 types supported by the AltiVec Programming Interface Manual. The
8915 attribute requires an argument to specify one of three vector types:
8916 @code{vector__}, @code{pixel__} (always followed by unsigned short),
8917 and @code{bool__} (always followed by unsigned).
8920 __attribute__((altivec(vector__)))
8921 __attribute__((altivec(pixel__))) unsigned short
8922 __attribute__((altivec(bool__))) unsigned
8925 These attributes mainly are intended to support the @code{__vector},
8926 @code{__pixel}, and @code{__bool} AltiVec keywords.
8928 @node x86 Type Attributes
8929 @subsection x86 Type Attributes
8931 Two attributes are currently defined for x86 configurations:
8932 @code{ms_struct} and @code{gcc_struct}.
8938 @cindex @code{ms_struct} type attribute, x86
8939 @cindex @code{gcc_struct} type attribute, x86
8941 If @code{packed} is used on a structure, or if bit-fields are used
8942 it may be that the Microsoft ABI packs them differently
8943 than GCC normally packs them. Particularly when moving packed
8944 data between functions compiled with GCC and the native Microsoft compiler
8945 (either via function call or as data in a file), it may be necessary to access
8948 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8949 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8950 command-line options, respectively;
8951 see @ref{x86 Options}, for details of how structure layout is affected.
8952 @xref{x86 Variable Attributes}, for information about the corresponding
8953 attributes on variables.
8957 @node Label Attributes
8958 @section Label Attributes
8959 @cindex Label Attributes
8961 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
8962 details of the exact syntax for using attributes. Other attributes are
8963 available for functions (@pxref{Function Attributes}), variables
8964 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
8965 statements (@pxref{Statement Attributes}), and for types
8966 (@pxref{Type Attributes}). A label attribute followed
8967 by a declaration appertains to the label and not the declaration.
8969 This example uses the @code{cold} label attribute to indicate the
8970 @code{ErrorHandling} branch is unlikely to be taken and that the
8971 @code{ErrorHandling} label is unused:
8975 asm goto ("some asm" : : : : NoError);
8977 /* This branch (the fall-through from the asm) is less commonly used */
8979 __attribute__((cold, unused)); /* Semi-colon is required here */
8984 printf("no error\n");
8990 @cindex @code{unused} label attribute
8991 This feature is intended for program-generated code that may contain
8992 unused labels, but which is compiled with @option{-Wall}. It is
8993 not normally appropriate to use in it human-written code, though it
8994 could be useful in cases where the code that jumps to the label is
8995 contained within an @code{#ifdef} conditional.
8998 @cindex @code{hot} label attribute
8999 The @code{hot} attribute on a label is used to inform the compiler that
9000 the path following the label is more likely than paths that are not so
9001 annotated. This attribute is used in cases where @code{__builtin_expect}
9002 cannot be used, for instance with computed goto or @code{asm goto}.
9005 @cindex @code{cold} label attribute
9006 The @code{cold} attribute on labels is used to inform the compiler that
9007 the path following the label is unlikely to be executed. This attribute
9008 is used in cases where @code{__builtin_expect} cannot be used, for instance
9009 with computed goto or @code{asm goto}.
9013 @node Enumerator Attributes
9014 @section Enumerator Attributes
9015 @cindex Enumerator Attributes
9017 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
9018 details of the exact syntax for using attributes. Other attributes are
9019 available for functions (@pxref{Function Attributes}), variables
9020 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
9021 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
9023 This example uses the @code{deprecated} enumerator attribute to indicate the
9024 @code{oldval} enumerator is deprecated:
9028 oldval __attribute__((deprecated)),
9041 @cindex @code{deprecated} enumerator attribute
9042 The @code{deprecated} attribute results in a warning if the enumerator
9043 is used anywhere in the source file. This is useful when identifying
9044 enumerators that are expected to be removed in a future version of a
9045 program. The warning also includes the location of the declaration
9046 of the deprecated enumerator, to enable users to easily find further
9047 information about why the enumerator is deprecated, or what they should
9048 do instead. Note that the warnings only occurs for uses.
9051 @cindex @code{unavailable} enumerator attribute
9052 The @code{unavailable} attribute results in an error if the enumerator
9053 is used anywhere in the source file. In other respects it behaves in the
9054 same manner as the @code{deprecated} attribute.
9058 @node Statement Attributes
9059 @section Statement Attributes
9060 @cindex Statement Attributes
9062 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
9063 for details of the exact syntax for using attributes. Other attributes are
9064 available for functions (@pxref{Function Attributes}), variables
9065 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
9066 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
9068 This example uses the @code{fallthrough} statement attribute to indicate that
9069 the @option{-Wimplicit-fallthrough} warning should not be emitted:
9076 __attribute__((fallthrough));
9084 @cindex @code{fallthrough} statement attribute
9085 The @code{fallthrough} attribute with a null statement serves as a
9086 fallthrough statement. It hints to the compiler that a statement
9087 that falls through to another case label, or user-defined label
9088 in a switch statement is intentional and thus the
9089 @option{-Wimplicit-fallthrough} warning must not trigger. The
9090 fallthrough attribute may appear at most once in each attribute
9091 list, and may not be mixed with other attributes. It can only
9092 be used in a switch statement (the compiler will issue an error
9093 otherwise), after a preceding statement and before a logically
9094 succeeding case label, or user-defined label.
9098 @node Attribute Syntax
9099 @section Attribute Syntax
9100 @cindex attribute syntax
9102 This section describes the syntax with which @code{__attribute__} may be
9103 used, and the constructs to which attribute specifiers bind, for the C
9104 language. Some details may vary for C++ and Objective-C@. Because of
9105 infelicities in the grammar for attributes, some forms described here
9106 may not be successfully parsed in all cases.
9108 There are some problems with the semantics of attributes in C++. For
9109 example, there are no manglings for attributes, although they may affect
9110 code generation, so problems may arise when attributed types are used in
9111 conjunction with templates or overloading. Similarly, @code{typeid}
9112 does not distinguish between types with different attributes. Support
9113 for attributes in C++ may be restricted in future to attributes on
9114 declarations only, but not on nested declarators.
9116 @xref{Function Attributes}, for details of the semantics of attributes
9117 applying to functions. @xref{Variable Attributes}, for details of the
9118 semantics of attributes applying to variables. @xref{Type Attributes},
9119 for details of the semantics of attributes applying to structure, union
9120 and enumerated types.
9121 @xref{Label Attributes}, for details of the semantics of attributes
9123 @xref{Enumerator Attributes}, for details of the semantics of attributes
9124 applying to enumerators.
9125 @xref{Statement Attributes}, for details of the semantics of attributes
9126 applying to statements.
9128 An @dfn{attribute specifier} is of the form
9129 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
9130 is a possibly empty comma-separated sequence of @dfn{attributes}, where
9131 each attribute is one of the following:
9135 Empty. Empty attributes are ignored.
9139 (which may be an identifier such as @code{unused}, or a reserved
9140 word such as @code{const}).
9143 An attribute name followed by a parenthesized list of
9144 parameters for the attribute.
9145 These parameters take one of the following forms:
9149 An identifier. For example, @code{mode} attributes use this form.
9152 An identifier followed by a comma and a non-empty comma-separated list
9153 of expressions. For example, @code{format} attributes use this form.
9156 A possibly empty comma-separated list of expressions. For example,
9157 @code{format_arg} attributes use this form with the list being a single
9158 integer constant expression, and @code{alias} attributes use this form
9159 with the list being a single string constant.
9163 An @dfn{attribute specifier list} is a sequence of one or more attribute
9164 specifiers, not separated by any other tokens.
9166 You may optionally specify attribute names with @samp{__}
9167 preceding and following the name.
9168 This allows you to use them in header files without
9169 being concerned about a possible macro of the same name. For example,
9170 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
9173 @subsubheading Label Attributes
9175 In GNU C, an attribute specifier list may appear after the colon following a
9176 label, other than a @code{case} or @code{default} label. GNU C++ only permits
9177 attributes on labels if the attribute specifier is immediately
9178 followed by a semicolon (i.e., the label applies to an empty
9179 statement). If the semicolon is missing, C++ label attributes are
9180 ambiguous, as it is permissible for a declaration, which could begin
9181 with an attribute list, to be labelled in C++. Declarations cannot be
9182 labelled in C90 or C99, so the ambiguity does not arise there.
9184 @subsubheading Enumerator Attributes
9186 In GNU C, an attribute specifier list may appear as part of an enumerator.
9187 The attribute goes after the enumeration constant, before @code{=}, if
9188 present. The optional attribute in the enumerator appertains to the
9189 enumeration constant. It is not possible to place the attribute after
9190 the constant expression, if present.
9192 @subsubheading Statement Attributes
9193 In GNU C, an attribute specifier list may appear as part of a null
9194 statement. The attribute goes before the semicolon.
9196 @subsubheading Type Attributes
9198 An attribute specifier list may appear as part of a @code{struct},
9199 @code{union} or @code{enum} specifier. It may go either immediately
9200 after the @code{struct}, @code{union} or @code{enum} keyword, or after
9201 the closing brace. The former syntax is preferred.
9202 Where attribute specifiers follow the closing brace, they are considered
9203 to relate to the structure, union or enumerated type defined, not to any
9204 enclosing declaration the type specifier appears in, and the type
9205 defined is not complete until after the attribute specifiers.
9206 @c Otherwise, there would be the following problems: a shift/reduce
9207 @c conflict between attributes binding the struct/union/enum and
9208 @c binding to the list of specifiers/qualifiers; and "aligned"
9209 @c attributes could use sizeof for the structure, but the size could be
9210 @c changed later by "packed" attributes.
9213 @subsubheading All other attributes
9215 Otherwise, an attribute specifier appears as part of a declaration,
9216 counting declarations of unnamed parameters and type names, and relates
9217 to that declaration (which may be nested in another declaration, for
9218 example in the case of a parameter declaration), or to a particular declarator
9219 within a declaration. Where an
9220 attribute specifier is applied to a parameter declared as a function or
9221 an array, it should apply to the function or array rather than the
9222 pointer to which the parameter is implicitly converted, but this is not
9223 yet correctly implemented.
9225 Any list of specifiers and qualifiers at the start of a declaration may
9226 contain attribute specifiers, whether or not such a list may in that
9227 context contain storage class specifiers. (Some attributes, however,
9228 are essentially in the nature of storage class specifiers, and only make
9229 sense where storage class specifiers may be used; for example,
9230 @code{section}.) There is one necessary limitation to this syntax: the
9231 first old-style parameter declaration in a function definition cannot
9232 begin with an attribute specifier, because such an attribute applies to
9233 the function instead by syntax described below (which, however, is not
9234 yet implemented in this case). In some other cases, attribute
9235 specifiers are permitted by this grammar but not yet supported by the
9236 compiler. All attribute specifiers in this place relate to the
9237 declaration as a whole. In the obsolescent usage where a type of
9238 @code{int} is implied by the absence of type specifiers, such a list of
9239 specifiers and qualifiers may be an attribute specifier list with no
9240 other specifiers or qualifiers.
9242 At present, the first parameter in a function prototype must have some
9243 type specifier that is not an attribute specifier; this resolves an
9244 ambiguity in the interpretation of @code{void f(int
9245 (__attribute__((foo)) x))}, but is subject to change. At present, if
9246 the parentheses of a function declarator contain only attributes then
9247 those attributes are ignored, rather than yielding an error or warning
9248 or implying a single parameter of type int, but this is subject to
9251 An attribute specifier list may appear immediately before a declarator
9252 (other than the first) in a comma-separated list of declarators in a
9253 declaration of more than one identifier using a single list of
9254 specifiers and qualifiers. Such attribute specifiers apply
9255 only to the identifier before whose declarator they appear. For
9259 __attribute__((noreturn)) void d0 (void),
9260 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
9265 the @code{noreturn} attribute applies to all the functions
9266 declared; the @code{format} attribute only applies to @code{d1}.
9268 An attribute specifier list may appear immediately before the comma,
9269 @code{=} or semicolon terminating the declaration of an identifier other
9270 than a function definition. Such attribute specifiers apply
9271 to the declared object or function. Where an
9272 assembler name for an object or function is specified (@pxref{Asm
9273 Labels}), the attribute must follow the @code{asm}
9276 An attribute specifier list may, in future, be permitted to appear after
9277 the declarator in a function definition (before any old-style parameter
9278 declarations or the function body).
9280 Attribute specifiers may be mixed with type qualifiers appearing inside
9281 the @code{[]} of a parameter array declarator, in the C99 construct by
9282 which such qualifiers are applied to the pointer to which the array is
9283 implicitly converted. Such attribute specifiers apply to the pointer,
9284 not to the array, but at present this is not implemented and they are
9287 An attribute specifier list may appear at the start of a nested
9288 declarator. At present, there are some limitations in this usage: the
9289 attributes correctly apply to the declarator, but for most individual
9290 attributes the semantics this implies are not implemented.
9291 When attribute specifiers follow the @code{*} of a pointer
9292 declarator, they may be mixed with any type qualifiers present.
9293 The following describes the formal semantics of this syntax. It makes the
9294 most sense if you are familiar with the formal specification of
9295 declarators in the ISO C standard.
9297 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
9298 D1}, where @code{T} contains declaration specifiers that specify a type
9299 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
9300 contains an identifier @var{ident}. The type specified for @var{ident}
9301 for derived declarators whose type does not include an attribute
9302 specifier is as in the ISO C standard.
9304 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
9305 and the declaration @code{T D} specifies the type
9306 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
9307 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
9308 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
9310 If @code{D1} has the form @code{*
9311 @var{type-qualifier-and-attribute-specifier-list} D}, and the
9312 declaration @code{T D} specifies the type
9313 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
9314 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
9315 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
9321 void (__attribute__((noreturn)) ****f) (void);
9325 specifies the type ``pointer to pointer to pointer to pointer to
9326 non-returning function returning @code{void}''. As another example,
9329 char *__attribute__((aligned(8))) *f;
9333 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
9334 Note again that this does not work with most attributes; for example,
9335 the usage of @samp{aligned} and @samp{noreturn} attributes given above
9336 is not yet supported.
9338 For compatibility with existing code written for compiler versions that
9339 did not implement attributes on nested declarators, some laxity is
9340 allowed in the placing of attributes. If an attribute that only applies
9341 to types is applied to a declaration, it is treated as applying to
9342 the type of that declaration. If an attribute that only applies to
9343 declarations is applied to the type of a declaration, it is treated
9344 as applying to that declaration; and, for compatibility with code
9345 placing the attributes immediately before the identifier declared, such
9346 an attribute applied to a function return type is treated as
9347 applying to the function type, and such an attribute applied to an array
9348 element type is treated as applying to the array type. If an
9349 attribute that only applies to function types is applied to a
9350 pointer-to-function type, it is treated as applying to the pointer
9351 target type; if such an attribute is applied to a function return type
9352 that is not a pointer-to-function type, it is treated as applying
9353 to the function type.
9355 @node Function Prototypes
9356 @section Prototypes and Old-Style Function Definitions
9357 @cindex function prototype declarations
9358 @cindex old-style function definitions
9359 @cindex promotion of formal parameters
9361 GNU C extends ISO C to allow a function prototype to override a later
9362 old-style non-prototype definition. Consider the following example:
9365 /* @r{Use prototypes unless the compiler is old-fashioned.} */
9372 /* @r{Prototype function declaration.} */
9373 int isroot P((uid_t));
9375 /* @r{Old-style function definition.} */
9377 isroot (x) /* @r{??? lossage here ???} */
9384 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
9385 not allow this example, because subword arguments in old-style
9386 non-prototype definitions are promoted. Therefore in this example the
9387 function definition's argument is really an @code{int}, which does not
9388 match the prototype argument type of @code{short}.
9390 This restriction of ISO C makes it hard to write code that is portable
9391 to traditional C compilers, because the programmer does not know
9392 whether the @code{uid_t} type is @code{short}, @code{int}, or
9393 @code{long}. Therefore, in cases like these GNU C allows a prototype
9394 to override a later old-style definition. More precisely, in GNU C, a
9395 function prototype argument type overrides the argument type specified
9396 by a later old-style definition if the former type is the same as the
9397 latter type before promotion. Thus in GNU C the above example is
9398 equivalent to the following:
9411 GNU C++ does not support old-style function definitions, so this
9412 extension is irrelevant.
9415 @section C++ Style Comments
9417 @cindex C++ comments
9418 @cindex comments, C++ style
9420 In GNU C, you may use C++ style comments, which start with @samp{//} and
9421 continue until the end of the line. Many other C implementations allow
9422 such comments, and they are included in the 1999 C standard. However,
9423 C++ style comments are not recognized if you specify an @option{-std}
9424 option specifying a version of ISO C before C99, or @option{-ansi}
9425 (equivalent to @option{-std=c90}).
9428 @section Dollar Signs in Identifier Names
9430 @cindex dollar signs in identifier names
9431 @cindex identifier names, dollar signs in
9433 In GNU C, you may normally use dollar signs in identifier names.
9434 This is because many traditional C implementations allow such identifiers.
9435 However, dollar signs in identifiers are not supported on a few target
9436 machines, typically because the target assembler does not allow them.
9438 @node Character Escapes
9439 @section The Character @key{ESC} in Constants
9441 You can use the sequence @samp{\e} in a string or character constant to
9442 stand for the ASCII character @key{ESC}.
9445 @section Determining the Alignment of Functions, Types or Variables
9447 @cindex type alignment
9448 @cindex variable alignment
9450 The keyword @code{__alignof__} determines the alignment requirement of
9451 a function, object, or a type, or the minimum alignment usually required
9452 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
9454 For example, if the target machine requires a @code{double} value to be
9455 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
9456 This is true on many RISC machines. On more traditional machine
9457 designs, @code{__alignof__ (double)} is 4 or even 2.
9459 Some machines never actually require alignment; they allow references to any
9460 data type even at an odd address. For these machines, @code{__alignof__}
9461 reports the smallest alignment that GCC gives the data type, usually as
9462 mandated by the target ABI.
9464 If the operand of @code{__alignof__} is an lvalue rather than a type,
9465 its value is the required alignment for its type, taking into account
9466 any minimum alignment specified by attribute @code{aligned}
9467 (@pxref{Common Variable Attributes}). For example, after this
9471 struct foo @{ int x; char y; @} foo1;
9475 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
9476 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
9477 It is an error to ask for the alignment of an incomplete type other
9480 If the operand of the @code{__alignof__} expression is a function,
9481 the expression evaluates to the alignment of the function which may
9482 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
9485 @section An Inline Function is As Fast As a Macro
9486 @cindex inline functions
9487 @cindex integrating function code
9489 @cindex macros, inline alternative
9491 By declaring a function inline, you can direct GCC to make
9492 calls to that function faster. One way GCC can achieve this is to
9493 integrate that function's code into the code for its callers. This
9494 makes execution faster by eliminating the function-call overhead; in
9495 addition, if any of the actual argument values are constant, their
9496 known values may permit simplifications at compile time so that not
9497 all of the inline function's code needs to be included. The effect on
9498 code size is less predictable; object code may be larger or smaller
9499 with function inlining, depending on the particular case. You can
9500 also direct GCC to try to integrate all ``simple enough'' functions
9501 into their callers with the option @option{-finline-functions}.
9503 GCC implements three different semantics of declaring a function
9504 inline. One is available with @option{-std=gnu89} or
9505 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
9506 on all inline declarations, another when
9508 @option{-std=gnu99} or an option for a later C version is used
9509 (without @option{-fgnu89-inline}), and the third
9510 is used when compiling C++.
9512 To declare a function inline, use the @code{inline} keyword in its
9513 declaration, like this:
9523 If you are writing a header file to be included in ISO C90 programs, write
9524 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
9526 The three types of inlining behave similarly in two important cases:
9527 when the @code{inline} keyword is used on a @code{static} function,
9528 like the example above, and when a function is first declared without
9529 using the @code{inline} keyword and then is defined with
9530 @code{inline}, like this:
9533 extern int inc (int *a);
9541 In both of these common cases, the program behaves the same as if you
9542 had not used the @code{inline} keyword, except for its speed.
9544 @cindex inline functions, omission of
9545 @opindex fkeep-inline-functions
9546 When a function is both inline and @code{static}, if all calls to the
9547 function are integrated into the caller, and the function's address is
9548 never used, then the function's own assembler code is never referenced.
9549 In this case, GCC does not actually output assembler code for the
9550 function, unless you specify the option @option{-fkeep-inline-functions}.
9551 If there is a nonintegrated call, then the function is compiled to
9552 assembler code as usual. The function must also be compiled as usual if
9553 the program refers to its address, because that cannot be inlined.
9556 Note that certain usages in a function definition can make it unsuitable
9557 for inline substitution. Among these usages are: variadic functions,
9558 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
9559 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
9560 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
9561 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
9562 function marked @code{inline} could not be substituted, and gives the
9563 reason for the failure.
9565 @cindex automatic @code{inline} for C++ member fns
9566 @cindex @code{inline} automatic for C++ member fns
9567 @cindex member fns, automatically @code{inline}
9568 @cindex C++ member fns, automatically @code{inline}
9569 @opindex fno-default-inline
9570 As required by ISO C++, GCC considers member functions defined within
9571 the body of a class to be marked inline even if they are
9572 not explicitly declared with the @code{inline} keyword. You can
9573 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
9574 Options,,Options Controlling C++ Dialect}.
9576 GCC does not inline any functions when not optimizing unless you specify
9577 the @samp{always_inline} attribute for the function, like this:
9580 /* @r{Prototype.} */
9581 inline void foo (const char) __attribute__((always_inline));
9584 The remainder of this section is specific to GNU C90 inlining.
9586 @cindex non-static inline function
9587 When an inline function is not @code{static}, then the compiler must assume
9588 that there may be calls from other source files; since a global symbol can
9589 be defined only once in any program, the function must not be defined in
9590 the other source files, so the calls therein cannot be integrated.
9591 Therefore, a non-@code{static} inline function is always compiled on its
9592 own in the usual fashion.
9594 If you specify both @code{inline} and @code{extern} in the function
9595 definition, then the definition is used only for inlining. In no case
9596 is the function compiled on its own, not even if you refer to its
9597 address explicitly. Such an address becomes an external reference, as
9598 if you had only declared the function, and had not defined it.
9600 This combination of @code{inline} and @code{extern} has almost the
9601 effect of a macro. The way to use it is to put a function definition in
9602 a header file with these keywords, and put another copy of the
9603 definition (lacking @code{inline} and @code{extern}) in a library file.
9604 The definition in the header file causes most calls to the function
9605 to be inlined. If any uses of the function remain, they refer to
9606 the single copy in the library.
9609 @section When is a Volatile Object Accessed?
9610 @cindex accessing volatiles
9611 @cindex volatile read
9612 @cindex volatile write
9613 @cindex volatile access
9615 C has the concept of volatile objects. These are normally accessed by
9616 pointers and used for accessing hardware or inter-thread
9617 communication. The standard encourages compilers to refrain from
9618 optimizations concerning accesses to volatile objects, but leaves it
9619 implementation defined as to what constitutes a volatile access. The
9620 minimum requirement is that at a sequence point all previous accesses
9621 to volatile objects have stabilized and no subsequent accesses have
9622 occurred. Thus an implementation is free to reorder and combine
9623 volatile accesses that occur between sequence points, but cannot do
9624 so for accesses across a sequence point. The use of volatile does
9625 not allow you to violate the restriction on updating objects multiple
9626 times between two sequence points.
9628 Accesses to non-volatile objects are not ordered with respect to
9629 volatile accesses. You cannot use a volatile object as a memory
9630 barrier to order a sequence of writes to non-volatile memory. For
9634 int *ptr = @var{something};
9636 *ptr = @var{something};
9641 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
9642 that the write to @var{*ptr} occurs by the time the update
9643 of @var{vobj} happens. If you need this guarantee, you must use
9644 a stronger memory barrier such as:
9647 int *ptr = @var{something};
9649 *ptr = @var{something};
9650 asm volatile ("" : : : "memory");
9654 A scalar volatile object is read when it is accessed in a void context:
9657 volatile int *src = @var{somevalue};
9661 Such expressions are rvalues, and GCC implements this as a
9662 read of the volatile object being pointed to.
9664 Assignments are also expressions and have an rvalue. However when
9665 assigning to a scalar volatile, the volatile object is not reread,
9666 regardless of whether the assignment expression's rvalue is used or
9667 not. If the assignment's rvalue is used, the value is that assigned
9668 to the volatile object. For instance, there is no read of @var{vobj}
9669 in all the following cases:
9674 vobj = @var{something};
9675 obj = vobj = @var{something};
9676 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
9677 obj = (@var{something}, vobj = @var{anotherthing});
9680 If you need to read the volatile object after an assignment has
9681 occurred, you must use a separate expression with an intervening
9684 As bit-fields are not individually addressable, volatile bit-fields may
9685 be implicitly read when written to, or when adjacent bit-fields are
9686 accessed. Bit-field operations may be optimized such that adjacent
9687 bit-fields are only partially accessed, if they straddle a storage unit
9688 boundary. For these reasons it is unwise to use volatile bit-fields to
9691 @node Using Assembly Language with C
9692 @section How to Use Inline Assembly Language in C Code
9693 @cindex @code{asm} keyword
9694 @cindex assembly language in C
9695 @cindex inline assembly language
9696 @cindex mixing assembly language and C
9698 The @code{asm} keyword allows you to embed assembler instructions
9699 within C code. GCC provides two forms of inline @code{asm}
9700 statements. A @dfn{basic @code{asm}} statement is one with no
9701 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
9702 statement (@pxref{Extended Asm}) includes one or more operands.
9703 The extended form is preferred for mixing C and assembly language
9704 within a function, but to include assembly language at
9705 top level you must use basic @code{asm}.
9707 You can also use the @code{asm} keyword to override the assembler name
9708 for a C symbol, or to place a C variable in a specific register.
9711 * Basic Asm:: Inline assembler without operands.
9712 * Extended Asm:: Inline assembler with operands.
9713 * Constraints:: Constraints for @code{asm} operands
9714 * Asm Labels:: Specifying the assembler name to use for a C symbol.
9715 * Explicit Register Variables:: Defining variables residing in specified
9717 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
9721 @subsection Basic Asm --- Assembler Instructions Without Operands
9722 @cindex basic @code{asm}
9723 @cindex assembly language in C, basic
9725 A basic @code{asm} statement has the following syntax:
9728 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
9731 The @code{asm} keyword is a GNU extension.
9732 When writing code that can be compiled with @option{-ansi} and the
9733 various @option{-std} options, use @code{__asm__} instead of
9734 @code{asm} (@pxref{Alternate Keywords}).
9736 @subsubheading Qualifiers
9739 The optional @code{volatile} qualifier has no effect.
9740 All basic @code{asm} blocks are implicitly volatile.
9743 If you use the @code{inline} qualifier, then for inlining purposes the size
9744 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
9748 @subsubheading Parameters
9751 @item AssemblerInstructions
9752 This is a literal string that specifies the assembler code. The string can
9753 contain any instructions recognized by the assembler, including directives.
9754 GCC does not parse the assembler instructions themselves and
9755 does not know what they mean or even whether they are valid assembler input.
9757 You may place multiple assembler instructions together in a single @code{asm}
9758 string, separated by the characters normally used in assembly code for the
9759 system. A combination that works in most places is a newline to break the
9760 line, plus a tab character (written as @samp{\n\t}).
9761 Some assemblers allow semicolons as a line separator. However,
9762 note that some assembler dialects use semicolons to start a comment.
9765 @subsubheading Remarks
9766 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
9767 smaller, safer, and more efficient code, and in most cases it is a
9768 better solution than basic @code{asm}. However, there are two
9769 situations where only basic @code{asm} can be used:
9773 Extended @code{asm} statements have to be inside a C
9774 function, so to write inline assembly language at file scope (``top-level''),
9775 outside of C functions, you must use basic @code{asm}.
9776 You can use this technique to emit assembler directives,
9777 define assembly language macros that can be invoked elsewhere in the file,
9778 or write entire functions in assembly language.
9779 Basic @code{asm} statements outside of functions may not use any
9784 with the @code{naked} attribute also require basic @code{asm}
9785 (@pxref{Function Attributes}).
9788 Safely accessing C data and calling functions from basic @code{asm} is more
9789 complex than it may appear. To access C data, it is better to use extended
9792 Do not expect a sequence of @code{asm} statements to remain perfectly
9793 consecutive after compilation. If certain instructions need to remain
9794 consecutive in the output, put them in a single multi-instruction @code{asm}
9795 statement. Note that GCC's optimizers can move @code{asm} statements
9796 relative to other code, including across jumps.
9798 @code{asm} statements may not perform jumps into other @code{asm} statements.
9799 GCC does not know about these jumps, and therefore cannot take
9800 account of them when deciding how to optimize. Jumps from @code{asm} to C
9801 labels are only supported in extended @code{asm}.
9803 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9804 assembly code when optimizing. This can lead to unexpected duplicate
9805 symbol errors during compilation if your assembly code defines symbols or
9808 @strong{Warning:} The C standards do not specify semantics for @code{asm},
9809 making it a potential source of incompatibilities between compilers. These
9810 incompatibilities may not produce compiler warnings/errors.
9812 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
9813 means there is no way to communicate to the compiler what is happening
9814 inside them. GCC has no visibility of symbols in the @code{asm} and may
9815 discard them as unreferenced. It also does not know about side effects of
9816 the assembler code, such as modifications to memory or registers. Unlike
9817 some compilers, GCC assumes that no changes to general purpose registers
9818 occur. This assumption may change in a future release.
9820 To avoid complications from future changes to the semantics and the
9821 compatibility issues between compilers, consider replacing basic @code{asm}
9822 with extended @code{asm}. See
9823 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
9824 from basic asm to extended asm} for information about how to perform this
9827 The compiler copies the assembler instructions in a basic @code{asm}
9828 verbatim to the assembly language output file, without
9829 processing dialects or any of the @samp{%} operators that are available with
9830 extended @code{asm}. This results in minor differences between basic
9831 @code{asm} strings and extended @code{asm} templates. For example, to refer to
9832 registers you might use @samp{%eax} in basic @code{asm} and
9833 @samp{%%eax} in extended @code{asm}.
9835 On targets such as x86 that support multiple assembler dialects,
9836 all basic @code{asm} blocks use the assembler dialect specified by the
9837 @option{-masm} command-line option (@pxref{x86 Options}).
9838 Basic @code{asm} provides no
9839 mechanism to provide different assembler strings for different dialects.
9841 For basic @code{asm} with non-empty assembler string GCC assumes
9842 the assembler block does not change any general purpose registers,
9843 but it may read or write any globally accessible variable.
9845 Here is an example of basic @code{asm} for i386:
9848 /* Note that this code will not compile with -masm=intel */
9849 #define DebugBreak() asm("int $3")
9853 @subsection Extended Asm - Assembler Instructions with C Expression Operands
9854 @cindex extended @code{asm}
9855 @cindex assembly language in C, extended
9857 With extended @code{asm} you can read and write C variables from
9858 assembler and perform jumps from assembler code to C labels.
9859 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
9860 the operand parameters after the assembler template:
9863 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9864 : @var{OutputOperands}
9865 @r{[} : @var{InputOperands}
9866 @r{[} : @var{Clobbers} @r{]} @r{]})
9868 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9869 : @var{OutputOperands}
9870 : @var{InputOperands}
9874 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
9877 The @code{asm} keyword is a GNU extension.
9878 When writing code that can be compiled with @option{-ansi} and the
9879 various @option{-std} options, use @code{__asm__} instead of
9880 @code{asm} (@pxref{Alternate Keywords}).
9882 @subsubheading Qualifiers
9886 The typical use of extended @code{asm} statements is to manipulate input
9887 values to produce output values. However, your @code{asm} statements may
9888 also produce side effects. If so, you may need to use the @code{volatile}
9889 qualifier to disable certain optimizations. @xref{Volatile}.
9892 If you use the @code{inline} qualifier, then for inlining purposes the size
9893 of the @code{asm} statement is taken as the smallest size possible
9894 (@pxref{Size of an asm}).
9897 This qualifier informs the compiler that the @code{asm} statement may
9898 perform a jump to one of the labels listed in the @var{GotoLabels}.
9902 @subsubheading Parameters
9904 @item AssemblerTemplate
9905 This is a literal string that is the template for the assembler code. It is a
9906 combination of fixed text and tokens that refer to the input, output,
9907 and goto parameters. @xref{AssemblerTemplate}.
9909 @item OutputOperands
9910 A comma-separated list of the C variables modified by the instructions in the
9911 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
9914 A comma-separated list of C expressions read by the instructions in the
9915 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
9918 A comma-separated list of registers or other values changed by the
9919 @var{AssemblerTemplate}, beyond those listed as outputs.
9920 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
9923 When you are using the @code{goto} form of @code{asm}, this section contains
9924 the list of all C labels to which the code in the
9925 @var{AssemblerTemplate} may jump.
9928 @code{asm} statements may not perform jumps into other @code{asm} statements,
9929 only to the listed @var{GotoLabels}.
9930 GCC's optimizers do not know about other jumps; therefore they cannot take
9931 account of them when deciding how to optimize.
9934 The total number of input + output + goto operands is limited to 30.
9936 @subsubheading Remarks
9937 The @code{asm} statement allows you to include assembly instructions directly
9938 within C code. This may help you to maximize performance in time-sensitive
9939 code or to access assembly instructions that are not readily available to C
9942 Note that extended @code{asm} statements must be inside a function. Only
9943 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
9944 Functions declared with the @code{naked} attribute also require basic
9945 @code{asm} (@pxref{Function Attributes}).
9947 While the uses of @code{asm} are many and varied, it may help to think of an
9948 @code{asm} statement as a series of low-level instructions that convert input
9949 parameters to output parameters. So a simple (if not particularly useful)
9950 example for i386 using @code{asm} might look like this:
9956 asm ("mov %1, %0\n\t"
9961 printf("%d\n", dst);
9964 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
9967 @subsubsection Volatile
9968 @cindex volatile @code{asm}
9969 @cindex @code{asm} volatile
9971 GCC's optimizers sometimes discard @code{asm} statements if they determine
9972 there is no need for the output variables. Also, the optimizers may move
9973 code out of loops if they believe that the code will always return the same
9974 result (i.e.@: none of its input values change between calls). Using the
9975 @code{volatile} qualifier disables these optimizations. @code{asm} statements
9976 that have no output operands and @code{asm goto} statements,
9977 are implicitly volatile.
9979 This i386 code demonstrates a case that does not use (or require) the
9980 @code{volatile} qualifier. If it is performing assertion checking, this code
9981 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
9982 unreferenced by any code. As a result, the optimizers can discard the
9983 @code{asm} statement, which in turn removes the need for the entire
9984 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
9985 isn't needed you allow the optimizers to produce the most efficient code
9989 void DoCheck(uint32_t dwSomeValue)
9993 // Assumes dwSomeValue is not zero.
10003 The next example shows a case where the optimizers can recognize that the input
10004 (@code{dwSomeValue}) never changes during the execution of the function and can
10005 therefore move the @code{asm} outside the loop to produce more efficient code.
10006 Again, using the @code{volatile} qualifier disables this type of optimization.
10009 void do_print(uint32_t dwSomeValue)
10013 for (uint32_t x=0; x < 5; x++)
10015 // Assumes dwSomeValue is not zero.
10018 : "r" (dwSomeValue)
10021 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
10026 The following example demonstrates a case where you need to use the
10027 @code{volatile} qualifier.
10028 It uses the x86 @code{rdtsc} instruction, which reads
10029 the computer's time-stamp counter. Without the @code{volatile} qualifier,
10030 the optimizers might assume that the @code{asm} block will always return the
10031 same value and therefore optimize away the second call.
10036 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
10037 "shl $32, %%rdx\n\t" // Shift the upper bits left.
10038 "or %%rdx, %0" // 'Or' in the lower bits.
10043 printf("msr: %llx\n", msr);
10045 // Do other work...
10047 // Reprint the timestamp
10048 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
10049 "shl $32, %%rdx\n\t" // Shift the upper bits left.
10050 "or %%rdx, %0" // 'Or' in the lower bits.
10055 printf("msr: %llx\n", msr);
10058 GCC's optimizers do not treat this code like the non-volatile code in the
10059 earlier examples. They do not move it out of loops or omit it on the
10060 assumption that the result from a previous call is still valid.
10062 Note that the compiler can move even @code{volatile asm} instructions relative
10063 to other code, including across jump instructions. For example, on many
10064 targets there is a system register that controls the rounding mode of
10065 floating-point operations. Setting it with a @code{volatile asm} statement,
10066 as in the following PowerPC example, does not work reliably.
10069 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
10073 The compiler may move the addition back before the @code{volatile asm}
10074 statement. To make it work as expected, add an artificial dependency to
10075 the @code{asm} by referencing a variable in the subsequent code, for
10079 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
10083 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
10084 assembly code when optimizing. This can lead to unexpected duplicate symbol
10085 errors during compilation if your @code{asm} code defines symbols or labels.
10087 (@pxref{AssemblerTemplate}) may help resolve this problem.
10089 @anchor{AssemblerTemplate}
10090 @subsubsection Assembler Template
10091 @cindex @code{asm} assembler template
10093 An assembler template is a literal string containing assembler instructions.
10094 The compiler replaces tokens in the template that refer
10095 to inputs, outputs, and goto labels,
10096 and then outputs the resulting string to the assembler. The
10097 string can contain any instructions recognized by the assembler, including
10098 directives. GCC does not parse the assembler instructions
10099 themselves and does not know what they mean or even whether they are valid
10100 assembler input. However, it does count the statements
10101 (@pxref{Size of an asm}).
10103 You may place multiple assembler instructions together in a single @code{asm}
10104 string, separated by the characters normally used in assembly code for the
10105 system. A combination that works in most places is a newline to break the
10106 line, plus a tab character to move to the instruction field (written as
10108 Some assemblers allow semicolons as a line separator. However, note
10109 that some assembler dialects use semicolons to start a comment.
10111 Do not expect a sequence of @code{asm} statements to remain perfectly
10112 consecutive after compilation, even when you are using the @code{volatile}
10113 qualifier. If certain instructions need to remain consecutive in the output,
10114 put them in a single multi-instruction @code{asm} statement.
10116 Accessing data from C programs without using input/output operands (such as
10117 by using global symbols directly from the assembler template) may not work as
10118 expected. Similarly, calling functions directly from an assembler template
10119 requires a detailed understanding of the target assembler and ABI.
10121 Since GCC does not parse the assembler template,
10122 it has no visibility of any
10123 symbols it references. This may result in GCC discarding those symbols as
10124 unreferenced unless they are also listed as input, output, or goto operands.
10126 @subsubheading Special format strings
10128 In addition to the tokens described by the input, output, and goto operands,
10129 these tokens have special meanings in the assembler template:
10133 Outputs a single @samp{%} into the assembler code.
10136 Outputs a number that is unique to each instance of the @code{asm}
10137 statement in the entire compilation. This option is useful when creating local
10138 labels and referring to them multiple times in a single template that
10139 generates multiple assembler instructions.
10144 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
10145 into the assembler code. When unescaped, these characters have special
10146 meaning to indicate multiple assembler dialects, as described below.
10149 @subsubheading Multiple assembler dialects in @code{asm} templates
10151 On targets such as x86, GCC supports multiple assembler dialects.
10152 The @option{-masm} option controls which dialect GCC uses as its
10153 default for inline assembler. The target-specific documentation for the
10154 @option{-masm} option contains the list of supported dialects, as well as the
10155 default dialect if the option is not specified. This information may be
10156 important to understand, since assembler code that works correctly when
10157 compiled using one dialect will likely fail if compiled using another.
10158 @xref{x86 Options}.
10160 If your code needs to support multiple assembler dialects (for example, if
10161 you are writing public headers that need to support a variety of compilation
10162 options), use constructs of this form:
10165 @{ dialect0 | dialect1 | dialect2... @}
10168 This construct outputs @code{dialect0}
10169 when using dialect #0 to compile the code,
10170 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
10171 braces than the number of dialects the compiler supports, the construct
10174 For example, if an x86 compiler supports two dialects
10175 (@samp{att}, @samp{intel}), an
10176 assembler template such as this:
10179 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
10183 is equivalent to one of
10186 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
10187 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
10190 Using that same compiler, this code:
10193 "xchg@{l@}\t@{%%@}ebx, %1"
10197 corresponds to either
10200 "xchgl\t%%ebx, %1" @r{/* att dialect */}
10201 "xchg\tebx, %1" @r{/* intel dialect */}
10204 There is no support for nesting dialect alternatives.
10206 @anchor{OutputOperands}
10207 @subsubsection Output Operands
10208 @cindex @code{asm} output operands
10210 An @code{asm} statement has zero or more output operands indicating the names
10211 of C variables modified by the assembler code.
10213 In this i386 example, @code{old} (referred to in the template string as
10214 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
10215 (@code{%2}) is an input:
10220 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
10221 "sbb %0,%0" // Use the CF to calculate old.
10222 : "=r" (old), "+rm" (*Base)
10229 Operands are separated by commas. Each operand has this format:
10232 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
10236 @item asmSymbolicName
10237 Specifies a symbolic name for the operand.
10238 Reference the name in the assembler template
10239 by enclosing it in square brackets
10240 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10241 that contains the definition. Any valid C variable name is acceptable,
10242 including names already defined in the surrounding code. No two operands
10243 within the same @code{asm} statement can use the same symbolic name.
10245 When not using an @var{asmSymbolicName}, use the (zero-based) position
10247 in the list of operands in the assembler template. For example if there are
10248 three output operands, use @samp{%0} in the template to refer to the first,
10249 @samp{%1} for the second, and @samp{%2} for the third.
10252 A string constant specifying constraints on the placement of the operand;
10253 @xref{Constraints}, for details.
10255 Output constraints must begin with either @samp{=} (a variable overwriting an
10256 existing value) or @samp{+} (when reading and writing). When using
10257 @samp{=}, do not assume the location contains the existing value
10258 on entry to the @code{asm}, except
10259 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
10261 After the prefix, there must be one or more additional constraints
10262 (@pxref{Constraints}) that describe where the value resides. Common
10263 constraints include @samp{r} for register and @samp{m} for memory.
10264 When you list more than one possible location (for example, @code{"=rm"}),
10265 the compiler chooses the most efficient one based on the current context.
10266 If you list as many alternates as the @code{asm} statement allows, you permit
10267 the optimizers to produce the best possible code.
10268 If you must use a specific register, but your Machine Constraints do not
10269 provide sufficient control to select the specific register you want,
10270 local register variables may provide a solution (@pxref{Local Register
10273 @item cvariablename
10274 Specifies a C lvalue expression to hold the output, typically a variable name.
10275 The enclosing parentheses are a required part of the syntax.
10279 When the compiler selects the registers to use to
10280 represent the output operands, it does not use any of the clobbered registers
10281 (@pxref{Clobbers and Scratch Registers}).
10283 Output operand expressions must be lvalues. The compiler cannot check whether
10284 the operands have data types that are reasonable for the instruction being
10285 executed. For output expressions that are not directly addressable (for
10286 example a bit-field), the constraint must allow a register. In that case, GCC
10287 uses the register as the output of the @code{asm}, and then stores that
10288 register into the output.
10290 Operands using the @samp{+} constraint modifier count as two operands
10291 (that is, both as input and output) towards the total maximum of 30 operands
10292 per @code{asm} statement.
10294 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
10295 operands that must not overlap an input. Otherwise,
10296 GCC may allocate the output operand in the same register as an unrelated
10297 input operand, on the assumption that the assembler code consumes its
10298 inputs before producing outputs. This assumption may be false if the assembler
10299 code actually consists of more than one instruction.
10301 The same problem can occur if one output parameter (@var{a}) allows a register
10302 constraint and another output parameter (@var{b}) allows a memory constraint.
10303 The code generated by GCC to access the memory address in @var{b} can contain
10304 registers which @emph{might} be shared by @var{a}, and GCC considers those
10305 registers to be inputs to the asm. As above, GCC assumes that such input
10306 registers are consumed before any outputs are written. This assumption may
10307 result in incorrect behavior if the @code{asm} statement writes to @var{a}
10309 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
10310 ensures that modifying @var{a} does not affect the address referenced by
10311 @var{b}. Otherwise, the location of @var{b}
10312 is undefined if @var{a} is modified before using @var{b}.
10314 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10315 instead of simply @samp{%2}). Typically these qualifiers are hardware
10316 dependent. The list of supported modifiers for x86 is found at
10317 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10319 If the C code that follows the @code{asm} makes no use of any of the output
10320 operands, use @code{volatile} for the @code{asm} statement to prevent the
10321 optimizers from discarding the @code{asm} statement as unneeded
10322 (see @ref{Volatile}).
10324 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
10325 references the first output operand as @code{%0} (were there a second, it
10326 would be @code{%1}, etc). The number of the first input operand is one greater
10327 than that of the last output operand. In this i386 example, that makes
10328 @code{Mask} referenced as @code{%1}:
10331 uint32_t Mask = 1234;
10340 That code overwrites the variable @code{Index} (@samp{=}),
10341 placing the value in a register (@samp{r}).
10342 Using the generic @samp{r} constraint instead of a constraint for a specific
10343 register allows the compiler to pick the register to use, which can result
10344 in more efficient code. This may not be possible if an assembler instruction
10345 requires a specific register.
10347 The following i386 example uses the @var{asmSymbolicName} syntax.
10349 same result as the code above, but some may consider it more readable or more
10350 maintainable since reordering index numbers is not necessary when adding or
10351 removing operands. The names @code{aIndex} and @code{aMask}
10352 are only used in this example to emphasize which
10353 names get used where.
10354 It is acceptable to reuse the names @code{Index} and @code{Mask}.
10357 uint32_t Mask = 1234;
10360 asm ("bsfl %[aMask], %[aIndex]"
10361 : [aIndex] "=r" (Index)
10362 : [aMask] "r" (Mask)
10366 Here are some more examples of output operands.
10373 asm ("mov %[e], %[d]"
10378 Here, @code{d} may either be in a register or in memory. Since the compiler
10379 might already have the current value of the @code{uint32_t} location
10380 pointed to by @code{e}
10381 in a register, you can enable it to choose the best location
10382 for @code{d} by specifying both constraints.
10384 @anchor{FlagOutputOperands}
10385 @subsubsection Flag Output Operands
10386 @cindex @code{asm} flag output operands
10388 Some targets have a special register that holds the ``flags'' for the
10389 result of an operation or comparison. Normally, the contents of that
10390 register are either unmodifed by the asm, or the @code{asm} statement is
10391 considered to clobber the contents.
10393 On some targets, a special form of output operand exists by which
10394 conditions in the flags register may be outputs of the asm. The set of
10395 conditions supported are target specific, but the general rule is that
10396 the output variable must be a scalar integer, and the value is boolean.
10397 When supported, the target defines the preprocessor symbol
10398 @code{__GCC_ASM_FLAG_OUTPUTS__}.
10400 Because of the special nature of the flag output operands, the constraint
10401 may not include alternatives.
10403 Most often, the target has only one flags register, and thus is an implied
10404 operand of many instructions. In this case, the operand should not be
10405 referenced within the assembler template via @code{%0} etc, as there's
10406 no corresponding text in the assembly language.
10411 The flag output constraints for the ARM family are of the form
10412 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
10413 conditions defined in the ARM ARM for @code{ConditionHolds}.
10417 Z flag set, or equal
10419 Z flag clear or not equal
10422 C flag set or unsigned greater than equal
10425 C flag clear or unsigned less than
10427 N flag set or ``minus''
10429 N flag clear or ``plus''
10431 V flag set or signed overflow
10435 unsigned greater than
10437 unsigned less than equal
10439 signed greater than equal
10443 signed greater than
10445 signed less than equal
10448 The flag output constraints are not supported in thumb1 mode.
10451 The flag output constraints for the x86 family are of the form
10452 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
10453 conditions defined in the ISA manual for @code{j@var{cc}} or
10454 @code{set@var{cc}}.
10458 ``above'' or unsigned greater than
10460 ``above or equal'' or unsigned greater than or equal
10462 ``below'' or unsigned less than
10464 ``below or equal'' or unsigned less than or equal
10469 ``equal'' or zero flag set
10471 signed greater than
10473 signed greater than or equal
10477 signed less than or equal
10498 ``not'' @var{flag}, or inverted versions of those above
10503 @anchor{InputOperands}
10504 @subsubsection Input Operands
10505 @cindex @code{asm} input operands
10506 @cindex @code{asm} expressions
10508 Input operands make values from C variables and expressions available to the
10511 Operands are separated by commas. Each operand has this format:
10514 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
10518 @item asmSymbolicName
10519 Specifies a symbolic name for the operand.
10520 Reference the name in the assembler template
10521 by enclosing it in square brackets
10522 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10523 that contains the definition. Any valid C variable name is acceptable,
10524 including names already defined in the surrounding code. No two operands
10525 within the same @code{asm} statement can use the same symbolic name.
10527 When not using an @var{asmSymbolicName}, use the (zero-based) position
10529 in the list of operands in the assembler template. For example if there are
10530 two output operands and three inputs,
10531 use @samp{%2} in the template to refer to the first input operand,
10532 @samp{%3} for the second, and @samp{%4} for the third.
10535 A string constant specifying constraints on the placement of the operand;
10536 @xref{Constraints}, for details.
10538 Input constraint strings may not begin with either @samp{=} or @samp{+}.
10539 When you list more than one possible location (for example, @samp{"irm"}),
10540 the compiler chooses the most efficient one based on the current context.
10541 If you must use a specific register, but your Machine Constraints do not
10542 provide sufficient control to select the specific register you want,
10543 local register variables may provide a solution (@pxref{Local Register
10546 Input constraints can also be digits (for example, @code{"0"}). This indicates
10547 that the specified input must be in the same place as the output constraint
10548 at the (zero-based) index in the output constraint list.
10549 When using @var{asmSymbolicName} syntax for the output operands,
10550 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
10553 This is the C variable or expression being passed to the @code{asm} statement
10554 as input. The enclosing parentheses are a required part of the syntax.
10558 When the compiler selects the registers to use to represent the input
10559 operands, it does not use any of the clobbered registers
10560 (@pxref{Clobbers and Scratch Registers}).
10562 If there are no output operands but there are input operands, place two
10563 consecutive colons where the output operands would go:
10566 __asm__ ("some instructions"
10567 : /* No outputs. */
10568 : "r" (Offset / 8));
10571 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
10572 (except for inputs tied to outputs). The compiler assumes that on exit from
10573 the @code{asm} statement these operands contain the same values as they
10574 had before executing the statement.
10575 It is @emph{not} possible to use clobbers
10576 to inform the compiler that the values in these inputs are changing. One
10577 common work-around is to tie the changing input variable to an output variable
10578 that never gets used. Note, however, that if the code that follows the
10579 @code{asm} statement makes no use of any of the output operands, the GCC
10580 optimizers may discard the @code{asm} statement as unneeded
10581 (see @ref{Volatile}).
10583 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10584 instead of simply @samp{%2}). Typically these qualifiers are hardware
10585 dependent. The list of supported modifiers for x86 is found at
10586 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10588 In this example using the fictitious @code{combine} instruction, the
10589 constraint @code{"0"} for input operand 1 says that it must occupy the same
10590 location as output operand 0. Only input operands may use numbers in
10591 constraints, and they must each refer to an output operand. Only a number (or
10592 the symbolic assembler name) in the constraint can guarantee that one operand
10593 is in the same place as another. The mere fact that @code{foo} is the value of
10594 both operands is not enough to guarantee that they are in the same place in
10595 the generated assembler code.
10598 asm ("combine %2, %0"
10600 : "0" (foo), "g" (bar));
10603 Here is an example using symbolic names.
10606 asm ("cmoveq %1, %2, %[result]"
10607 : [result] "=r"(result)
10608 : "r" (test), "r" (new), "[result]" (old));
10611 @anchor{Clobbers and Scratch Registers}
10612 @subsubsection Clobbers and Scratch Registers
10613 @cindex @code{asm} clobbers
10614 @cindex @code{asm} scratch registers
10616 While the compiler is aware of changes to entries listed in the output
10617 operands, the inline @code{asm} code may modify more than just the outputs. For
10618 example, calculations may require additional registers, or the processor may
10619 overwrite a register as a side effect of a particular assembler instruction.
10620 In order to inform the compiler of these changes, list them in the clobber
10621 list. Clobber list items are either register names or the special clobbers
10622 (listed below). Each clobber list item is a string constant
10623 enclosed in double quotes and separated by commas.
10625 Clobber descriptions may not in any way overlap with an input or output
10626 operand. For example, you may not have an operand describing a register class
10627 with one member when listing that register in the clobber list. Variables
10628 declared to live in specific registers (@pxref{Explicit Register
10629 Variables}) and used
10630 as @code{asm} input or output operands must have no part mentioned in the
10631 clobber description. In particular, there is no way to specify that input
10632 operands get modified without also specifying them as output operands.
10634 When the compiler selects which registers to use to represent input and output
10635 operands, it does not use any of the clobbered registers. As a result,
10636 clobbered registers are available for any use in the assembler code.
10638 Another restriction is that the clobber list should not contain the
10639 stack pointer register. This is because the compiler requires the
10640 value of the stack pointer to be the same after an @code{asm}
10641 statement as it was on entry to the statement. However, previous
10642 versions of GCC did not enforce this rule and allowed the stack
10643 pointer to appear in the list, with unclear semantics. This behavior
10644 is deprecated and listing the stack pointer may become an error in
10645 future versions of GCC@.
10647 Here is a realistic example for the VAX showing the use of clobbered
10651 asm volatile ("movc3 %0, %1, %2"
10652 : /* No outputs. */
10653 : "g" (from), "g" (to), "g" (count)
10654 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
10657 Also, there are two special clobber arguments:
10661 The @code{"cc"} clobber indicates that the assembler code modifies the flags
10662 register. On some machines, GCC represents the condition codes as a specific
10663 hardware register; @code{"cc"} serves to name this register.
10664 On other machines, condition code handling is different,
10665 and specifying @code{"cc"} has no effect. But
10666 it is valid no matter what the target.
10669 The @code{"memory"} clobber tells the compiler that the assembly code
10671 reads or writes to items other than those listed in the input and output
10672 operands (for example, accessing the memory pointed to by one of the input
10673 parameters). To ensure memory contains correct values, GCC may need to flush
10674 specific register values to memory before executing the @code{asm}. Further,
10675 the compiler does not assume that any values read from memory before an
10676 @code{asm} remain unchanged after that @code{asm}; it reloads them as
10678 Using the @code{"memory"} clobber effectively forms a read/write
10679 memory barrier for the compiler.
10681 Note that this clobber does not prevent the @emph{processor} from doing
10682 speculative reads past the @code{asm} statement. To prevent that, you need
10683 processor-specific fence instructions.
10687 Flushing registers to memory has performance implications and may be
10688 an issue for time-sensitive code. You can provide better information
10689 to GCC to avoid this, as shown in the following examples. At a
10690 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
10691 need to be flushed.
10693 Here is a fictitious sum of squares instruction, that takes two
10694 pointers to floating point values in memory and produces a floating
10695 point register output.
10696 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
10697 parameters, once to specify memory accessed, and once to specify a
10698 base register used by the @code{asm}. You won't normally be wasting a
10699 register by doing this as GCC can use the same register for both
10700 purposes. However, it would be foolish to use both @code{%1} and
10701 @code{%3} for @code{x} in this @code{asm} and expect them to be the
10702 same. In fact, @code{%3} may well not be a register. It might be a
10703 symbolic memory reference to the object pointed to by @code{x}.
10706 asm ("sumsq %0, %1, %2"
10708 : "r" (x), "r" (y), "m" (*x), "m" (*y));
10711 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
10712 Notice that the @code{x}, @code{y} and @code{z} pointer registers
10713 must be specified as input/output because the @code{asm} modifies
10717 asm ("vecmul %0, %1, %2"
10718 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
10719 : "m" (*x), "m" (*y));
10722 An x86 example where the string memory argument is of unknown length.
10726 : "=c" (count), "+D" (p)
10727 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
10730 If you know the above will only be reading a ten byte array then you
10731 could instead use a memory input like:
10732 @code{"m" (*(const char (*)[10]) p)}.
10734 Here is an example of a PowerPC vector scale implemented in assembly,
10735 complete with vector and condition code clobbers, and some initialized
10736 offset registers that are unchanged by the @code{asm}.
10740 dscal (size_t n, double *x, double alpha)
10742 asm ("/* lots of asm here */"
10743 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
10744 : "d" (alpha), "b" (32), "b" (48), "b" (64),
10745 "b" (80), "b" (96), "b" (112)
10747 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
10748 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
10752 Rather than allocating fixed registers via clobbers to provide scratch
10753 registers for an @code{asm} statement, an alternative is to define a
10754 variable and make it an early-clobber output as with @code{a2} and
10755 @code{a3} in the example below. This gives the compiler register
10756 allocator more freedom. You can also define a variable and make it an
10757 output tied to an input as with @code{a0} and @code{a1}, tied
10758 respectively to @code{ap} and @code{lda}. Of course, with tied
10759 outputs your @code{asm} can't use the input value after modifying the
10760 output register since they are one and the same register. What's
10761 more, if you omit the early-clobber on the output, it is possible that
10762 GCC might allocate the same register to another of the inputs if GCC
10763 could prove they had the same value on entry to the @code{asm}. This
10764 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
10765 might conceivably be known to have the value 16 and without an
10766 early-clobber share the same register as @code{%11}. On the other
10767 hand, @code{ap} can't be the same as any of the other inputs, so an
10768 early-clobber on @code{a0} is not needed. It is also not desirable in
10769 this case. An early-clobber on @code{a0} would cause GCC to allocate
10770 a separate register for the @code{"m" (*(const double (*)[]) ap)}
10771 input. Note that tying an input to an output is the way to set up an
10772 initialized temporary register modified by an @code{asm} statement.
10773 An input not tied to an output is assumed by GCC to be unchanged, for
10774 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
10775 use that register in following code if the value 16 happened to be
10776 needed. You can even use a normal @code{asm} output for a scratch if
10777 all inputs that might share the same register are consumed before the
10778 scratch is used. The VSX registers clobbered by the @code{asm}
10779 statement could have used this technique except for GCC's limit on the
10780 number of @code{asm} parameters.
10784 dgemv_kernel_4x4 (long n, const double *ap, long lda,
10785 const double *x, double *y, double alpha)
10794 /* lots of asm here */
10795 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
10796 "#a0=%3 a1=%4 a2=%5 a3=%6"
10798 "+m" (*(double (*)[n]) y),
10806 "m" (*(const double (*)[n]) x),
10807 "m" (*(const double (*)[]) ap),
10815 "vs32","vs33","vs34","vs35","vs36","vs37",
10816 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
10821 @anchor{GotoLabels}
10822 @subsubsection Goto Labels
10823 @cindex @code{asm} goto labels
10825 @code{asm goto} allows assembly code to jump to one or more C labels. The
10826 @var{GotoLabels} section in an @code{asm goto} statement contains
10828 list of all C labels to which the assembler code may jump. GCC assumes that
10829 @code{asm} execution falls through to the next statement (if this is not the
10830 case, consider using the @code{__builtin_unreachable} intrinsic after the
10831 @code{asm} statement). Optimization of @code{asm goto} may be improved by
10832 using the @code{hot} and @code{cold} label attributes (@pxref{Label
10835 If the assembler code does modify anything, use the @code{"memory"} clobber
10837 optimizers to flush all register values to memory and reload them if
10838 necessary after the @code{asm} statement.
10840 Also note that an @code{asm goto} statement is always implicitly
10841 considered volatile.
10843 Be careful when you set output operands inside @code{asm goto} only on
10844 some possible control flow paths. If you don't set up the output on
10845 given path and never use it on this path, it is okay. Otherwise, you
10846 should use @samp{+} constraint modifier meaning that the operand is
10847 input and output one. With this modifier you will have the correct
10848 values on all possible paths from the @code{asm goto}.
10850 To reference a label in the assembler template, prefix it with
10851 @samp{%l} (lowercase @samp{L}) followed by its (zero-based) position
10852 in @var{GotoLabels} plus the number of input and output operands.
10853 Output operand with constraint modifier @samp{+} is counted as two
10854 operands because it is considered as one output and one input operand.
10855 For example, if the @code{asm} has three inputs, one output operand
10856 with constraint modifier @samp{+} and one output operand with
10857 constraint modifier @samp{=} and references two labels, refer to the
10858 first label as @samp{%l6} and the second as @samp{%l7}).
10860 Alternately, you can reference labels using the actual C label name
10861 enclosed in brackets. For example, to reference a label named
10862 @code{carry}, you can use @samp{%l[carry]}. The label must still be
10863 listed in the @var{GotoLabels} section when using this approach. It
10864 is better to use the named references for labels as in this case you
10865 can avoid counting input and output operands and special treatment of
10866 output operands with constraint modifier @samp{+}.
10868 Here is an example of @code{asm goto} for i386:
10874 : /* No outputs. */
10875 : "r" (p1), "r" (p2)
10885 The following example shows an @code{asm goto} that uses a memory clobber.
10891 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
10892 : /* No outputs. */
10902 The following example shows an @code{asm goto} that uses an output.
10907 asm goto ("dec %0; jb %l[stop]"
10918 The following artificial example shows an @code{asm goto} that sets
10919 up an output only on one path inside the @code{asm goto}. Usage of
10920 constraint modifier @code{=} instead of @code{+} would be wrong as
10921 @code{factor} is used on all paths from the @code{asm goto}.
10927 asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0"
10933 return inp * factor; /* return 2 * inp or 0 if inp < 10 */
10937 @anchor{x86Operandmodifiers}
10938 @subsubsection x86 Operand Modifiers
10940 References to input, output, and goto operands in the assembler template
10941 of extended @code{asm} statements can use
10942 modifiers to affect the way the operands are formatted in
10943 the code output to the assembler. For example, the
10944 following code uses the @samp{h} and @samp{b} modifiers for x86:
10948 asm volatile ("xchg %h0, %b0" : "+a" (num) );
10952 These modifiers generate this assembler code:
10958 The rest of this discussion uses the following code for illustrative purposes.
10967 asm volatile goto ("some assembler instructions here"
10968 : /* No outputs. */
10969 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
10970 : /* No clobbers. */
10975 With no modifiers, this is what the output from the operands would be
10976 for the @samp{att} and @samp{intel} dialects of assembler:
10978 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
10979 @headitem Operand @tab @samp{att} @tab @samp{intel}
10988 @tab @code{OFFSET FLAT:.L3}
11000 The table below shows the list of supported modifiers and their effects.
11002 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
11003 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
11005 @tab Print an absolute memory reference.
11010 @tab Print the QImode name of the register.
11015 @tab print the opcode suffix of b.
11020 @tab Require a constant operand and print the constant expression with no punctuation.
11025 @tab print duplicated register operand for AVX instruction.
11027 @tab @code{%xmm0, %xmm0}
11028 @tab @code{xmm0, xmm0}
11030 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
11031 Otherwise mode is unspecified (VOIDmode).
11036 @tab Print the V16SFmode name of the register.
11041 @tab Print the QImode name for a ``high'' register.
11046 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
11047 high 8 bytes of SSE values. For a memref in (%rax), it generates
11049 @tab @code{8(%rax)}
11052 @tab Print the SImode name of the register.
11057 @tab Print the label name with no punctuation.
11062 @tab print the opcode suffix of l.
11072 @tab Print raw symbol name (without syntax-specific prefixes).
11077 @tab If used for a function, print the PLT suffix and generate PIC code.
11078 For example, emit @code{foo@@PLT} instead of 'foo' for the function
11079 foo(). If used for a constant, drop all syntax-specific prefixes and
11080 issue the bare constant. See @code{p} above.
11082 @tab Print the DImode name of the register.
11087 @tab print the opcode suffix of q.
11092 @tab print embedded rounding and sae.
11094 @tab @code{@{rn-sae@}, }
11095 @tab @code{, @{rn-sae@}}
11097 @tab print only sae.
11099 @tab @code{@{sae@}, }
11100 @tab @code{, @{sae@}}
11102 @tab print a shift double count, followed by the assemblers argument
11103 delimiterprint the opcode suffix of s.
11108 @tab print the opcode suffix of s.
11113 @tab print the V8SFmode name of the register.
11118 @tab print the opcode suffix of t.
11123 @tab print naked full integer register name without %.
11128 @tab Print the HImode name of the register.
11133 @tab print the opcode suffix of w.
11138 @tab print the V4SFmode name of the register.
11143 @tab print "st(0)" instead of "st" as a register.
11148 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
11153 @tab Like @code{z}, with special suffixes for x87 instructions.
11157 @anchor{x86floatingpointasmoperands}
11158 @subsubsection x86 Floating-Point @code{asm} Operands
11160 On x86 targets, there are several rules on the usage of stack-like registers
11161 in the operands of an @code{asm}. These rules apply only to the operands
11162 that are stack-like registers:
11166 Given a set of input registers that die in an @code{asm}, it is
11167 necessary to know which are implicitly popped by the @code{asm}, and
11168 which must be explicitly popped by GCC@.
11170 An input register that is implicitly popped by the @code{asm} must be
11171 explicitly clobbered, unless it is constrained to match an
11175 For any input register that is implicitly popped by an @code{asm}, it is
11176 necessary to know how to adjust the stack to compensate for the pop.
11177 If any non-popped input is closer to the top of the reg-stack than
11178 the implicitly popped register, it would not be possible to know what the
11179 stack looked like---it's not clear how the rest of the stack ``slides
11182 All implicitly popped input registers must be closer to the top of
11183 the reg-stack than any input that is not implicitly popped.
11185 It is possible that if an input dies in an @code{asm}, the compiler might
11186 use the input register for an output reload. Consider this example:
11189 asm ("foo" : "=t" (a) : "f" (b));
11193 This code says that input @code{b} is not popped by the @code{asm}, and that
11194 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
11195 deeper after the @code{asm} than it was before. But, it is possible that
11196 reload may think that it can use the same register for both the input and
11199 To prevent this from happening,
11200 if any input operand uses the @samp{f} constraint, all output register
11201 constraints must use the @samp{&} early-clobber modifier.
11203 The example above is correctly written as:
11206 asm ("foo" : "=&t" (a) : "f" (b));
11210 Some operands need to be in particular places on the stack. All
11211 output operands fall in this category---GCC has no other way to
11212 know which registers the outputs appear in unless you indicate
11213 this in the constraints.
11215 Output operands must specifically indicate which register an output
11216 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
11217 constraints must select a class with a single register.
11220 Output operands may not be ``inserted'' between existing stack registers.
11221 Since no 387 opcode uses a read/write operand, all output operands
11222 are dead before the @code{asm}, and are pushed by the @code{asm}.
11223 It makes no sense to push anywhere but the top of the reg-stack.
11225 Output operands must start at the top of the reg-stack: output
11226 operands may not ``skip'' a register.
11229 Some @code{asm} statements may need extra stack space for internal
11230 calculations. This can be guaranteed by clobbering stack registers
11231 unrelated to the inputs and outputs.
11236 takes one input, which is internally popped, and produces two outputs.
11239 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
11243 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
11244 and replaces them with one output. The @code{st(1)} clobber is necessary
11245 for the compiler to know that @code{fyl2xp1} pops both inputs.
11248 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
11251 @anchor{msp430Operandmodifiers}
11252 @subsubsection MSP430 Operand Modifiers
11254 The list below describes the supported modifiers and their effects for MSP430.
11256 @multitable @columnfractions .10 .90
11257 @headitem Modifier @tab Description
11258 @item @code{A} @tab Select low 16-bits of the constant/register/memory operand.
11259 @item @code{B} @tab Select high 16-bits of the constant/register/memory
11261 @item @code{C} @tab Select bits 32-47 of the constant/register/memory operand.
11262 @item @code{D} @tab Select bits 48-63 of the constant/register/memory operand.
11263 @item @code{H} @tab Equivalent to @code{B} (for backwards compatibility).
11264 @item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant
11266 @item @code{J} @tab Print an integer without a @code{#} prefix.
11267 @item @code{L} @tab Equivalent to @code{A} (for backwards compatibility).
11268 @item @code{O} @tab Offset of the current frame from the top of the stack.
11269 @item @code{Q} @tab Use the @code{A} instruction postfix.
11270 @item @code{R} @tab Inverse of condition code, for unsigned comparisons.
11271 @item @code{W} @tab Subtract 16 from the constant value.
11272 @item @code{X} @tab Use the @code{X} instruction postfix.
11273 @item @code{Y} @tab Subtract 4 from the constant value.
11274 @item @code{Z} @tab Subtract 1 from the constant value.
11275 @item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the
11276 instruction, depending on the mode.
11277 @item @code{d} @tab Offset 1 byte of a memory reference or constant value.
11278 @item @code{e} @tab Offset 3 bytes of a memory reference or constant value.
11279 @item @code{f} @tab Offset 5 bytes of a memory reference or constant value.
11280 @item @code{g} @tab Offset 7 bytes of a memory reference or constant value.
11281 @item @code{p} @tab Print the value of 2, raised to the power of the given
11282 constant. Used to select the specified bit position.
11283 @item @code{r} @tab Inverse of condition code, for signed comparisons.
11284 @item @code{x} @tab Equivialent to @code{X}, but only for pointers.
11292 @subsection Controlling Names Used in Assembler Code
11293 @cindex assembler names for identifiers
11294 @cindex names used in assembler code
11295 @cindex identifiers, names in assembler code
11297 You can specify the name to be used in the assembler code for a C
11298 function or variable by writing the @code{asm} (or @code{__asm__})
11299 keyword after the declarator.
11300 It is up to you to make sure that the assembler names you choose do not
11301 conflict with any other assembler symbols, or reference registers.
11303 @subsubheading Assembler names for data:
11305 This sample shows how to specify the assembler name for data:
11308 int foo asm ("myfoo") = 2;
11312 This specifies that the name to be used for the variable @code{foo} in
11313 the assembler code should be @samp{myfoo} rather than the usual
11316 On systems where an underscore is normally prepended to the name of a C
11317 variable, this feature allows you to define names for the
11318 linker that do not start with an underscore.
11320 GCC does not support using this feature with a non-static local variable
11321 since such variables do not have assembler names. If you are
11322 trying to put the variable in a particular register, see
11323 @ref{Explicit Register Variables}.
11325 @subsubheading Assembler names for functions:
11327 To specify the assembler name for functions, write a declaration for the
11328 function before its definition and put @code{asm} there, like this:
11331 int func (int x, int y) asm ("MYFUNC");
11333 int func (int x, int y)
11339 This specifies that the name to be used for the function @code{func} in
11340 the assembler code should be @code{MYFUNC}.
11342 @node Explicit Register Variables
11343 @subsection Variables in Specified Registers
11344 @anchor{Explicit Reg Vars}
11345 @cindex explicit register variables
11346 @cindex variables in specified registers
11347 @cindex specified registers
11349 GNU C allows you to associate specific hardware registers with C
11350 variables. In almost all cases, allowing the compiler to assign
11351 registers produces the best code. However under certain unusual
11352 circumstances, more precise control over the variable storage is
11355 Both global and local variables can be associated with a register. The
11356 consequences of performing this association are very different between
11357 the two, as explained in the sections below.
11360 * Global Register Variables:: Variables declared at global scope.
11361 * Local Register Variables:: Variables declared within a function.
11364 @node Global Register Variables
11365 @subsubsection Defining Global Register Variables
11366 @anchor{Global Reg Vars}
11367 @cindex global register variables
11368 @cindex registers, global variables in
11369 @cindex registers, global allocation
11371 You can define a global register variable and associate it with a specified
11372 register like this:
11375 register int *foo asm ("r12");
11379 Here @code{r12} is the name of the register that should be used. Note that
11380 this is the same syntax used for defining local register variables, but for
11381 a global variable the declaration appears outside a function. The
11382 @code{register} keyword is required, and cannot be combined with
11383 @code{static}. The register name must be a valid register name for the
11386 Do not use type qualifiers such as @code{const} and @code{volatile}, as
11387 the outcome may be contrary to expectations. In particular, using the
11388 @code{volatile} qualifier does not fully prevent the compiler from
11389 optimizing accesses to the register.
11391 Registers are a scarce resource on most systems and allowing the
11392 compiler to manage their usage usually results in the best code. However,
11393 under special circumstances it can make sense to reserve some globally.
11394 For example this may be useful in programs such as programming language
11395 interpreters that have a couple of global variables that are accessed
11398 After defining a global register variable, for the current compilation
11402 @item If the register is a call-saved register, call ABI is affected:
11403 the register will not be restored in function epilogue sequences after
11404 the variable has been assigned. Therefore, functions cannot safely
11405 return to callers that assume standard ABI.
11406 @item Conversely, if the register is a call-clobbered register, making
11407 calls to functions that use standard ABI may lose contents of the variable.
11408 Such calls may be created by the compiler even if none are evident in
11409 the original program, for example when libgcc functions are used to
11410 make up for unavailable instructions.
11411 @item Accesses to the variable may be optimized as usual and the register
11412 remains available for allocation and use in any computations, provided that
11413 observable values of the variable are not affected.
11414 @item If the variable is referenced in inline assembly, the type of access
11415 must be provided to the compiler via constraints (@pxref{Constraints}).
11416 Accesses from basic asms are not supported.
11419 Note that these points @emph{only} apply to code that is compiled with the
11420 definition. The behavior of code that is merely linked in (for example
11421 code from libraries) is not affected.
11423 If you want to recompile source files that do not actually use your global
11424 register variable so they do not use the specified register for any other
11425 purpose, you need not actually add the global register declaration to
11426 their source code. It suffices to specify the compiler option
11427 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
11430 @subsubheading Declaring the variable
11432 Global register variables cannot have initial values, because an
11433 executable file has no means to supply initial contents for a register.
11435 When selecting a register, choose one that is normally saved and
11436 restored by function calls on your machine. This ensures that code
11437 which is unaware of this reservation (such as library routines) will
11438 restore it before returning.
11440 On machines with register windows, be sure to choose a global
11441 register that is not affected magically by the function call mechanism.
11443 @subsubheading Using the variable
11445 @cindex @code{qsort}, and global register variables
11446 When calling routines that are not aware of the reservation, be
11447 cautious if those routines call back into code which uses them. As an
11448 example, if you call the system library version of @code{qsort}, it may
11449 clobber your registers during execution, but (if you have selected
11450 appropriate registers) it will restore them before returning. However
11451 it will @emph{not} restore them before calling @code{qsort}'s comparison
11452 function. As a result, global values will not reliably be available to
11453 the comparison function unless the @code{qsort} function itself is rebuilt.
11455 Similarly, it is not safe to access the global register variables from signal
11456 handlers or from more than one thread of control. Unless you recompile
11457 them specially for the task at hand, the system library routines may
11458 temporarily use the register for other things. Furthermore, since the register
11459 is not reserved exclusively for the variable, accessing it from handlers of
11460 asynchronous signals may observe unrelated temporary values residing in the
11463 @cindex register variable after @code{longjmp}
11464 @cindex global register after @code{longjmp}
11465 @cindex value after @code{longjmp}
11468 On most machines, @code{longjmp} restores to each global register
11469 variable the value it had at the time of the @code{setjmp}. On some
11470 machines, however, @code{longjmp} does not change the value of global
11471 register variables. To be portable, the function that called @code{setjmp}
11472 should make other arrangements to save the values of the global register
11473 variables, and to restore them in a @code{longjmp}. This way, the same
11474 thing happens regardless of what @code{longjmp} does.
11476 @node Local Register Variables
11477 @subsubsection Specifying Registers for Local Variables
11478 @anchor{Local Reg Vars}
11479 @cindex local variables, specifying registers
11480 @cindex specifying registers for local variables
11481 @cindex registers for local variables
11483 You can define a local register variable and associate it with a specified
11484 register like this:
11487 register int *foo asm ("r12");
11491 Here @code{r12} is the name of the register that should be used. Note
11492 that this is the same syntax used for defining global register variables,
11493 but for a local variable the declaration appears within a function. The
11494 @code{register} keyword is required, and cannot be combined with
11495 @code{static}. The register name must be a valid register name for the
11498 Do not use type qualifiers such as @code{const} and @code{volatile}, as
11499 the outcome may be contrary to expectations. In particular, when the
11500 @code{const} qualifier is used, the compiler may substitute the
11501 variable with its initializer in @code{asm} statements, which may cause
11502 the corresponding operand to appear in a different register.
11504 As with global register variables, it is recommended that you choose
11505 a register that is normally saved and restored by function calls on your
11506 machine, so that calls to library routines will not clobber it.
11508 The only supported use for this feature is to specify registers
11509 for input and output operands when calling Extended @code{asm}
11510 (@pxref{Extended Asm}). This may be necessary if the constraints for a
11511 particular machine don't provide sufficient control to select the desired
11512 register. To force an operand into a register, create a local variable
11513 and specify the register name after the variable's declaration. Then use
11514 the local variable for the @code{asm} operand and specify any constraint
11515 letter that matches the register:
11518 register int *p1 asm ("r0") = @dots{};
11519 register int *p2 asm ("r1") = @dots{};
11520 register int *result asm ("r0");
11521 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
11524 @emph{Warning:} In the above example, be aware that a register (for example
11525 @code{r0}) can be call-clobbered by subsequent code, including function
11526 calls and library calls for arithmetic operators on other variables (for
11527 example the initialization of @code{p2}). In this case, use temporary
11528 variables for expressions between the register assignments:
11532 register int *p1 asm ("r0") = @dots{};
11533 register int *p2 asm ("r1") = t1;
11534 register int *result asm ("r0");
11535 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
11538 Defining a register variable does not reserve the register. Other than
11539 when invoking the Extended @code{asm}, the contents of the specified
11540 register are not guaranteed. For this reason, the following uses
11541 are explicitly @emph{not} supported. If they appear to work, it is only
11542 happenstance, and may stop working as intended due to (seemingly)
11543 unrelated changes in surrounding code, or even minor changes in the
11544 optimization of a future version of gcc:
11547 @item Passing parameters to or from Basic @code{asm}
11548 @item Passing parameters to or from Extended @code{asm} without using input
11549 or output operands.
11550 @item Passing parameters to or from routines written in assembler (or
11551 other languages) using non-standard calling conventions.
11554 Some developers use Local Register Variables in an attempt to improve
11555 gcc's allocation of registers, especially in large functions. In this
11556 case the register name is essentially a hint to the register allocator.
11557 While in some instances this can generate better code, improvements are
11558 subject to the whims of the allocator/optimizers. Since there are no
11559 guarantees that your improvements won't be lost, this usage of Local
11560 Register Variables is discouraged.
11562 On the MIPS platform, there is related use for local register variables
11563 with slightly different characteristics (@pxref{MIPS Coprocessors,,
11564 Defining coprocessor specifics for MIPS targets, gccint,
11565 GNU Compiler Collection (GCC) Internals}).
11567 @node Size of an asm
11568 @subsection Size of an @code{asm}
11570 Some targets require that GCC track the size of each instruction used
11571 in order to generate correct code. Because the final length of the
11572 code produced by an @code{asm} statement is only known by the
11573 assembler, GCC must make an estimate as to how big it will be. It
11574 does this by counting the number of instructions in the pattern of the
11575 @code{asm} and multiplying that by the length of the longest
11576 instruction supported by that processor. (When working out the number
11577 of instructions, it assumes that any occurrence of a newline or of
11578 whatever statement separator character is supported by the assembler ---
11579 typically @samp{;} --- indicates the end of an instruction.)
11581 Normally, GCC's estimate is adequate to ensure that correct
11582 code is generated, but it is possible to confuse the compiler if you use
11583 pseudo instructions or assembler macros that expand into multiple real
11584 instructions, or if you use assembler directives that expand to more
11585 space in the object file than is needed for a single instruction.
11586 If this happens then the assembler may produce a diagnostic saying that
11587 a label is unreachable.
11589 @cindex @code{asm inline}
11590 This size is also used for inlining decisions. If you use @code{asm inline}
11591 instead of just @code{asm}, then for inlining purposes the size of the asm
11592 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
11594 @node Alternate Keywords
11595 @section Alternate Keywords
11596 @cindex alternate keywords
11597 @cindex keywords, alternate
11599 @option{-ansi} and the various @option{-std} options disable certain
11600 keywords. This causes trouble when you want to use GNU C extensions, or
11601 a general-purpose header file that should be usable by all programs,
11602 including ISO C programs. The keywords @code{asm}, @code{typeof} and
11603 @code{inline} are not available in programs compiled with
11604 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
11605 program compiled with @option{-std=c99} or a later standard). The
11607 @code{restrict} is only available when @option{-std=gnu99} (which will
11608 eventually be the default) or @option{-std=c99} (or the equivalent
11609 @option{-std=iso9899:1999}), or an option for a later standard
11612 The way to solve these problems is to put @samp{__} at the beginning and
11613 end of each problematical keyword. For example, use @code{__asm__}
11614 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
11616 Other C compilers won't accept these alternative keywords; if you want to
11617 compile with another compiler, you can define the alternate keywords as
11618 macros to replace them with the customary keywords. It looks like this:
11622 #define __asm__ asm
11626 @findex __extension__
11628 @option{-pedantic} and other options cause warnings for many GNU C extensions.
11630 prevent such warnings within one expression by writing
11631 @code{__extension__} before the expression. @code{__extension__} has no
11632 effect aside from this.
11634 @node Incomplete Enums
11635 @section Incomplete @code{enum} Types
11637 You can define an @code{enum} tag without specifying its possible values.
11638 This results in an incomplete type, much like what you get if you write
11639 @code{struct foo} without describing the elements. A later declaration
11640 that does specify the possible values completes the type.
11642 You cannot allocate variables or storage using the type while it is
11643 incomplete. However, you can work with pointers to that type.
11645 This extension may not be very useful, but it makes the handling of
11646 @code{enum} more consistent with the way @code{struct} and @code{union}
11649 This extension is not supported by GNU C++.
11651 @node Function Names
11652 @section Function Names as Strings
11653 @cindex @code{__func__} identifier
11654 @cindex @code{__FUNCTION__} identifier
11655 @cindex @code{__PRETTY_FUNCTION__} identifier
11657 GCC provides three magic constants that hold the name of the current
11658 function as a string. In C++11 and later modes, all three are treated
11659 as constant expressions and can be used in @code{constexpr} constexts.
11660 The first of these constants is @code{__func__}, which is part of
11663 The identifier @code{__func__} is implicitly declared by the translator
11664 as if, immediately following the opening brace of each function
11665 definition, the declaration
11668 static const char __func__[] = "function-name";
11672 appeared, where function-name is the name of the lexically-enclosing
11673 function. This name is the unadorned name of the function. As an
11674 extension, at file (or, in C++, namespace scope), @code{__func__}
11675 evaluates to the empty string.
11677 @code{__FUNCTION__} is another name for @code{__func__}, provided for
11678 backward compatibility with old versions of GCC.
11680 In C, @code{__PRETTY_FUNCTION__} is yet another name for
11681 @code{__func__}, except that at file scope (or, in C++, namespace scope),
11682 it evaluates to the string @code{"top level"}. In addition, in C++,
11683 @code{__PRETTY_FUNCTION__} contains the signature of the function as
11684 well as its bare name. For example, this program:
11687 extern "C" int printf (const char *, ...);
11693 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
11694 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
11712 __PRETTY_FUNCTION__ = void a::sub(int)
11715 These identifiers are variables, not preprocessor macros, and may not
11716 be used to initialize @code{char} arrays or be concatenated with string
11719 @node Return Address
11720 @section Getting the Return or Frame Address of a Function
11722 These functions may be used to get information about the callers of a
11725 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
11726 This function returns the return address of the current function, or of
11727 one of its callers. The @var{level} argument is number of frames to
11728 scan up the call stack. A value of @code{0} yields the return address
11729 of the current function, a value of @code{1} yields the return address
11730 of the caller of the current function, and so forth. When inlining
11731 the expected behavior is that the function returns the address of
11732 the function that is returned to. To work around this behavior use
11733 the @code{noinline} function attribute.
11735 The @var{level} argument must be a constant integer.
11737 On some machines it may be impossible to determine the return address of
11738 any function other than the current one; in such cases, or when the top
11739 of the stack has been reached, this function returns an unspecified
11740 value. In addition, @code{__builtin_frame_address} may be used
11741 to determine if the top of the stack has been reached.
11743 Additional post-processing of the returned value may be needed, see
11744 @code{__builtin_extract_return_addr}.
11746 The stored representation of the return address in memory may be different
11747 from the address returned by @code{__builtin_return_address}. For example,
11748 on AArch64 the stored address may be mangled with return address signing
11749 whereas the address returned by @code{__builtin_return_address} is not.
11751 Calling this function with a nonzero argument can have unpredictable
11752 effects, including crashing the calling program. As a result, calls
11753 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11754 option is in effect. Such calls should only be made in debugging
11757 On targets where code addresses are representable as @code{void *},
11759 void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
11761 gives the code address where the current function would return. For example,
11762 such an address may be used with @code{dladdr} or other interfaces that work
11763 with code addresses.
11766 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
11767 The address as returned by @code{__builtin_return_address} may have to be fed
11768 through this function to get the actual encoded address. For example, on the
11769 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
11770 platforms an offset has to be added for the true next instruction to be
11773 If no fixup is needed, this function simply passes through @var{addr}.
11776 @deftypefn {Built-in Function} {void *} __builtin_frob_return_addr (void *@var{addr})
11777 This function does the reverse of @code{__builtin_extract_return_addr}.
11780 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
11781 This function is similar to @code{__builtin_return_address}, but it
11782 returns the address of the function frame rather than the return address
11783 of the function. Calling @code{__builtin_frame_address} with a value of
11784 @code{0} yields the frame address of the current function, a value of
11785 @code{1} yields the frame address of the caller of the current function,
11788 The frame is the area on the stack that holds local variables and saved
11789 registers. The frame address is normally the address of the first word
11790 pushed on to the stack by the function. However, the exact definition
11791 depends upon the processor and the calling convention. If the processor
11792 has a dedicated frame pointer register, and the function has a frame,
11793 then @code{__builtin_frame_address} returns the value of the frame
11796 On some machines it may be impossible to determine the frame address of
11797 any function other than the current one; in such cases, or when the top
11798 of the stack has been reached, this function returns @code{0} if
11799 the first frame pointer is properly initialized by the startup code.
11801 Calling this function with a nonzero argument can have unpredictable
11802 effects, including crashing the calling program. As a result, calls
11803 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11804 option is in effect. Such calls should only be made in debugging
11808 @node Vector Extensions
11809 @section Using Vector Instructions through Built-in Functions
11811 On some targets, the instruction set contains SIMD vector instructions which
11812 operate on multiple values contained in one large register at the same time.
11813 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
11816 The first step in using these extensions is to provide the necessary data
11817 types. This should be done using an appropriate @code{typedef}:
11820 typedef int v4si __attribute__ ((vector_size (16)));
11824 The @code{int} type specifies the @dfn{base type}, while the attribute specifies
11825 the vector size for the variable, measured in bytes. For example, the
11826 declaration above causes the compiler to set the mode for the @code{v4si}
11827 type to be 16 bytes wide and divided into @code{int} sized units. For
11828 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
11829 corresponding mode of @code{foo} is @acronym{V4SI}.
11831 The @code{vector_size} attribute is only applicable to integral and
11832 floating scalars, although arrays, pointers, and function return values
11833 are allowed in conjunction with this construct. Only sizes that are
11834 positive power-of-two multiples of the base type size are currently allowed.
11836 All the basic integer types can be used as base types, both as signed
11837 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
11838 @code{long long}. In addition, @code{float} and @code{double} can be
11839 used to build floating-point vector types.
11841 Specifying a combination that is not valid for the current architecture
11842 causes GCC to synthesize the instructions using a narrower mode.
11843 For example, if you specify a variable of type @code{V4SI} and your
11844 architecture does not allow for this specific SIMD type, GCC
11845 produces code that uses 4 @code{SIs}.
11847 The types defined in this manner can be used with a subset of normal C
11848 operations. Currently, GCC allows using the following operators
11849 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
11851 The operations behave like C++ @code{valarrays}. Addition is defined as
11852 the addition of the corresponding elements of the operands. For
11853 example, in the code below, each of the 4 elements in @var{a} is
11854 added to the corresponding 4 elements in @var{b} and the resulting
11855 vector is stored in @var{c}.
11858 typedef int v4si __attribute__ ((vector_size (16)));
11865 Subtraction, multiplication, division, and the logical operations
11866 operate in a similar manner. Likewise, the result of using the unary
11867 minus or complement operators on a vector type is a vector whose
11868 elements are the negative or complemented values of the corresponding
11869 elements in the operand.
11871 It is possible to use shifting operators @code{<<}, @code{>>} on
11872 integer-type vectors. The operation is defined as following: @code{@{a0,
11873 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
11874 @dots{}, an >> bn@}}@. Vector operands must have the same number of
11877 For convenience, it is allowed to use a binary vector operation
11878 where one operand is a scalar. In that case the compiler transforms
11879 the scalar operand into a vector where each element is the scalar from
11880 the operation. The transformation happens only if the scalar could be
11881 safely converted to the vector-element type.
11882 Consider the following code.
11885 typedef int v4si __attribute__ ((vector_size (16)));
11890 a = b + 1; /* a = b + @{1,1,1,1@}; */
11891 a = 2 * b; /* a = @{2,2,2,2@} * b; */
11893 a = l + a; /* Error, cannot convert long to int. */
11896 Vectors can be subscripted as if the vector were an array with
11897 the same number of elements and base type. Out of bound accesses
11898 invoke undefined behavior at run time. Warnings for out of bound
11899 accesses for vector subscription can be enabled with
11900 @option{-Warray-bounds}.
11902 Vector comparison is supported with standard comparison
11903 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
11904 vector expressions of integer-type or real-type. Comparison between
11905 integer-type vectors and real-type vectors are not supported. The
11906 result of the comparison is a vector of the same width and number of
11907 elements as the comparison operands with a signed integral element
11910 Vectors are compared element-wise producing 0 when comparison is false
11911 and -1 (constant of the appropriate type where all bits are set)
11912 otherwise. Consider the following example.
11915 typedef int v4si __attribute__ ((vector_size (16)));
11917 v4si a = @{1,2,3,4@};
11918 v4si b = @{3,2,1,4@};
11921 c = a > b; /* The result would be @{0, 0,-1, 0@} */
11922 c = a == b; /* The result would be @{0,-1, 0,-1@} */
11925 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
11926 @code{b} and @code{c} are vectors of the same type and @code{a} is an
11927 integer vector with the same number of elements of the same size as @code{b}
11928 and @code{c}, computes all three arguments and creates a vector
11929 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
11930 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
11931 As in the case of binary operations, this syntax is also accepted when
11932 one of @code{b} or @code{c} is a scalar that is then transformed into a
11933 vector. If both @code{b} and @code{c} are scalars and the type of
11934 @code{true?b:c} has the same size as the element type of @code{a}, then
11935 @code{b} and @code{c} are converted to a vector type whose elements have
11936 this type and with the same number of elements as @code{a}.
11938 In C++, the logic operators @code{!, &&, ||} are available for vectors.
11939 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
11940 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
11941 For mixed operations between a scalar @code{s} and a vector @code{v},
11942 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
11943 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
11945 @findex __builtin_shuffle
11946 Vector shuffling is available using functions
11947 @code{__builtin_shuffle (vec, mask)} and
11948 @code{__builtin_shuffle (vec0, vec1, mask)}.
11949 Both functions construct a permutation of elements from one or two
11950 vectors and return a vector of the same type as the input vector(s).
11951 The @var{mask} is an integral vector with the same width (@var{W})
11952 and element count (@var{N}) as the output vector.
11954 The elements of the input vectors are numbered in memory ordering of
11955 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
11956 elements of @var{mask} are considered modulo @var{N} in the single-operand
11957 case and modulo @math{2*@var{N}} in the two-operand case.
11959 Consider the following example,
11962 typedef int v4si __attribute__ ((vector_size (16)));
11964 v4si a = @{1,2,3,4@};
11965 v4si b = @{5,6,7,8@};
11966 v4si mask1 = @{0,1,1,3@};
11967 v4si mask2 = @{0,4,2,5@};
11970 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
11971 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
11974 Note that @code{__builtin_shuffle} is intentionally semantically
11975 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
11977 You can declare variables and use them in function calls and returns, as
11978 well as in assignments and some casts. You can specify a vector type as
11979 a return type for a function. Vector types can also be used as function
11980 arguments. It is possible to cast from one vector type to another,
11981 provided they are of the same size (in fact, you can also cast vectors
11982 to and from other datatypes of the same size).
11984 You cannot operate between vectors of different lengths or different
11985 signedness without a cast.
11987 @findex __builtin_shufflevector
11988 Vector shuffling is available using the
11989 @code{__builtin_shufflevector (vec1, vec2, index...)}
11990 function. @var{vec1} and @var{vec2} must be expressions with
11991 vector type with a compatible element type. The result of
11992 @code{__builtin_shufflevector} is a vector with the same element type
11993 as @var{vec1} and @var{vec2} but that has an element count equal to
11994 the number of indices specified.
11996 The @var{index} arguments are a list of integers that specify the
11997 elements indices of the first two vectors that should be extracted and
11998 returned in a new vector. These element indices are numbered sequentially
11999 starting with the first vector, continuing into the second vector.
12000 An index of -1 can be used to indicate that the corresponding element in
12001 the returned vector is a don't care and can be freely chosen to optimized
12002 the generated code sequence performing the shuffle operation.
12004 Consider the following example,
12006 typedef int v4si __attribute__ ((vector_size (16)));
12007 typedef int v8si __attribute__ ((vector_size (32)));
12009 v8si a = @{1,-2,3,-4,5,-6,7,-8@};
12010 v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */
12011 v4si c = @{-2,-4,-6,-8@};
12012 v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */
12015 @findex __builtin_convertvector
12016 Vector conversion is available using the
12017 @code{__builtin_convertvector (vec, vectype)}
12018 function. @var{vec} must be an expression with integral or floating
12019 vector type and @var{vectype} an integral or floating vector type with the
12020 same number of elements. The result has @var{vectype} type and value of
12021 a C cast of every element of @var{vec} to the element type of @var{vectype}.
12023 Consider the following example,
12025 typedef int v4si __attribute__ ((vector_size (16)));
12026 typedef float v4sf __attribute__ ((vector_size (16)));
12027 typedef double v4df __attribute__ ((vector_size (32)));
12028 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
12030 v4si a = @{1,-2,3,-4@};
12031 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
12032 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
12033 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
12035 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
12036 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
12037 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
12038 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
12039 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
12042 @cindex vector types, using with x86 intrinsics
12043 Sometimes it is desirable to write code using a mix of generic vector
12044 operations (for clarity) and machine-specific vector intrinsics (to
12045 access vector instructions that are not exposed via generic built-ins).
12046 On x86, intrinsic functions for integer vectors typically use the same
12047 vector type @code{__m128i} irrespective of how they interpret the vector,
12048 making it necessary to cast their arguments and return values from/to
12049 other vector types. In C, you can make use of a @code{union} type:
12050 @c In C++ such type punning via a union is not allowed by the language
12052 #include <immintrin.h>
12054 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
12055 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
12065 for variables that can be used with both built-in operators and x86
12069 v128 x, y = @{ 0 @};
12070 memcpy (&x, ptr, sizeof x);
12072 x.mm = _mm_adds_epu8 (x.mm, y.mm);
12075 /* Instead of a variable, a compound literal may be used to pass the
12076 return value of an intrinsic call to a function expecting the union: */
12078 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
12079 @c This could be done implicitly with __attribute__((transparent_union)),
12080 @c but GCC does not accept it for unions of vector types (PR 88955).
12084 @section Support for @code{offsetof}
12085 @findex __builtin_offsetof
12087 GCC implements for both C and C++ a syntactic extension to implement
12088 the @code{offsetof} macro.
12092 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
12094 offsetof_member_designator:
12096 | offsetof_member_designator "." @code{identifier}
12097 | offsetof_member_designator "[" @code{expr} "]"
12100 This extension is sufficient such that
12103 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
12107 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
12108 may be dependent. In either case, @var{member} may consist of a single
12109 identifier, or a sequence of member accesses and array references.
12111 @node __sync Builtins
12112 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
12114 The following built-in functions
12115 are intended to be compatible with those described
12116 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
12117 section 7.4. As such, they depart from normal GCC practice by not using
12118 the @samp{__builtin_} prefix and also by being overloaded so that they
12119 work on multiple types.
12121 The definition given in the Intel documentation allows only for the use of
12122 the types @code{int}, @code{long}, @code{long long} or their unsigned
12123 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
12124 size other than the C type @code{_Bool} or the C++ type @code{bool}.
12125 Operations on pointer arguments are performed as if the operands were
12126 of the @code{uintptr_t} type. That is, they are not scaled by the size
12127 of the type to which the pointer points.
12129 These functions are implemented in terms of the @samp{__atomic}
12130 builtins (@pxref{__atomic Builtins}). They should not be used for new
12131 code which should use the @samp{__atomic} builtins instead.
12133 Not all operations are supported by all target processors. If a particular
12134 operation cannot be implemented on the target processor, a warning is
12135 generated and a call to an external function is generated. The external
12136 function carries the same name as the built-in version,
12137 with an additional suffix
12138 @samp{_@var{n}} where @var{n} is the size of the data type.
12140 @c ??? Should we have a mechanism to suppress this warning? This is almost
12141 @c useful for implementing the operation under the control of an external
12144 In most cases, these built-in functions are considered a @dfn{full barrier}.
12146 no memory operand is moved across the operation, either forward or
12147 backward. Further, instructions are issued as necessary to prevent the
12148 processor from speculating loads across the operation and from queuing stores
12149 after the operation.
12151 All of the routines are described in the Intel documentation to take
12152 ``an optional list of variables protected by the memory barrier''. It's
12153 not clear what is meant by that; it could mean that @emph{only} the
12154 listed variables are protected, or it could mean a list of additional
12155 variables to be protected. The list is ignored by GCC which treats it as
12156 empty. GCC interprets an empty list as meaning that all globally
12157 accessible variables should be protected.
12160 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
12161 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
12162 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
12163 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
12164 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
12165 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
12166 @findex __sync_fetch_and_add
12167 @findex __sync_fetch_and_sub
12168 @findex __sync_fetch_and_or
12169 @findex __sync_fetch_and_and
12170 @findex __sync_fetch_and_xor
12171 @findex __sync_fetch_and_nand
12172 These built-in functions perform the operation suggested by the name, and
12173 returns the value that had previously been in memory. That is, operations
12174 on integer operands have the following semantics. Operations on pointer
12175 arguments are performed as if the operands were of the @code{uintptr_t}
12176 type. That is, they are not scaled by the size of the type to which
12177 the pointer points.
12180 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
12181 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
12184 The object pointed to by the first argument must be of integer or pointer
12185 type. It must not be a boolean type.
12187 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
12188 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
12190 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
12191 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
12192 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
12193 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
12194 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
12195 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
12196 @findex __sync_add_and_fetch
12197 @findex __sync_sub_and_fetch
12198 @findex __sync_or_and_fetch
12199 @findex __sync_and_and_fetch
12200 @findex __sync_xor_and_fetch
12201 @findex __sync_nand_and_fetch
12202 These built-in functions perform the operation suggested by the name, and
12203 return the new value. That is, operations on integer operands have
12204 the following semantics. Operations on pointer operands are performed as
12205 if the operand's type were @code{uintptr_t}.
12208 @{ *ptr @var{op}= value; return *ptr; @}
12209 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
12212 The same constraints on arguments apply as for the corresponding
12213 @code{__sync_op_and_fetch} built-in functions.
12215 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
12216 as @code{*ptr = ~(*ptr & value)} instead of
12217 @code{*ptr = ~*ptr & value}.
12219 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
12220 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
12221 @findex __sync_bool_compare_and_swap
12222 @findex __sync_val_compare_and_swap
12223 These built-in functions perform an atomic compare and swap.
12224 That is, if the current
12225 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
12228 The ``bool'' version returns @code{true} if the comparison is successful and
12229 @var{newval} is written. The ``val'' version returns the contents
12230 of @code{*@var{ptr}} before the operation.
12232 @item __sync_synchronize (...)
12233 @findex __sync_synchronize
12234 This built-in function issues a full memory barrier.
12236 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
12237 @findex __sync_lock_test_and_set
12238 This built-in function, as described by Intel, is not a traditional test-and-set
12239 operation, but rather an atomic exchange operation. It writes @var{value}
12240 into @code{*@var{ptr}}, and returns the previous contents of
12243 Many targets have only minimal support for such locks, and do not support
12244 a full exchange operation. In this case, a target may support reduced
12245 functionality here by which the @emph{only} valid value to store is the
12246 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
12247 is implementation defined.
12249 This built-in function is not a full barrier,
12250 but rather an @dfn{acquire barrier}.
12251 This means that references after the operation cannot move to (or be
12252 speculated to) before the operation, but previous memory stores may not
12253 be globally visible yet, and previous memory loads may not yet be
12256 @item void __sync_lock_release (@var{type} *ptr, ...)
12257 @findex __sync_lock_release
12258 This built-in function releases the lock acquired by
12259 @code{__sync_lock_test_and_set}.
12260 Normally this means writing the constant 0 to @code{*@var{ptr}}.
12262 This built-in function is not a full barrier,
12263 but rather a @dfn{release barrier}.
12264 This means that all previous memory stores are globally visible, and all
12265 previous memory loads have been satisfied, but following memory reads
12266 are not prevented from being speculated to before the barrier.
12269 @node __atomic Builtins
12270 @section Built-in Functions for Memory Model Aware Atomic Operations
12272 The following built-in functions approximately match the requirements
12273 for the C++11 memory model. They are all
12274 identified by being prefixed with @samp{__atomic} and most are
12275 overloaded so that they work with multiple types.
12277 These functions are intended to replace the legacy @samp{__sync}
12278 builtins. The main difference is that the memory order that is requested
12279 is a parameter to the functions. New code should always use the
12280 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
12282 Note that the @samp{__atomic} builtins assume that programs will
12283 conform to the C++11 memory model. In particular, they assume
12284 that programs are free of data races. See the C++11 standard for
12285 detailed requirements.
12287 The @samp{__atomic} builtins can be used with any integral scalar or
12288 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
12289 types are also allowed if @samp{__int128} (@pxref{__int128}) is
12290 supported by the architecture.
12292 The four non-arithmetic functions (load, store, exchange, and
12293 compare_exchange) all have a generic version as well. This generic
12294 version works on any data type. It uses the lock-free built-in function
12295 if the specific data type size makes that possible; otherwise, an
12296 external call is left to be resolved at run time. This external call is
12297 the same format with the addition of a @samp{size_t} parameter inserted
12298 as the first parameter indicating the size of the object being pointed to.
12299 All objects must be the same size.
12301 There are 6 different memory orders that can be specified. These map
12302 to the C++11 memory orders with the same names, see the C++11 standard
12303 or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
12304 on atomic synchronization} for detailed definitions. Individual
12305 targets may also support additional memory orders for use on specific
12306 architectures. Refer to the target documentation for details of
12309 An atomic operation can both constrain code motion and
12310 be mapped to hardware instructions for synchronization between threads
12311 (e.g., a fence). To which extent this happens is controlled by the
12312 memory orders, which are listed here in approximately ascending order of
12313 strength. The description of each memory order is only meant to roughly
12314 illustrate the effects and is not a specification; see the C++11
12315 memory model for precise semantics.
12318 @item __ATOMIC_RELAXED
12319 Implies no inter-thread ordering constraints.
12320 @item __ATOMIC_CONSUME
12321 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
12322 memory order because of a deficiency in C++11's semantics for
12323 @code{memory_order_consume}.
12324 @item __ATOMIC_ACQUIRE
12325 Creates an inter-thread happens-before constraint from the release (or
12326 stronger) semantic store to this acquire load. Can prevent hoisting
12327 of code to before the operation.
12328 @item __ATOMIC_RELEASE
12329 Creates an inter-thread happens-before constraint to acquire (or stronger)
12330 semantic loads that read from this release store. Can prevent sinking
12331 of code to after the operation.
12332 @item __ATOMIC_ACQ_REL
12333 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
12334 @code{__ATOMIC_RELEASE}.
12335 @item __ATOMIC_SEQ_CST
12336 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
12339 Note that in the C++11 memory model, @emph{fences} (e.g.,
12340 @samp{__atomic_thread_fence}) take effect in combination with other
12341 atomic operations on specific memory locations (e.g., atomic loads);
12342 operations on specific memory locations do not necessarily affect other
12343 operations in the same way.
12345 Target architectures are encouraged to provide their own patterns for
12346 each of the atomic built-in functions. If no target is provided, the original
12347 non-memory model set of @samp{__sync} atomic built-in functions are
12348 used, along with any required synchronization fences surrounding it in
12349 order to achieve the proper behavior. Execution in this case is subject
12350 to the same restrictions as those built-in functions.
12352 If there is no pattern or mechanism to provide a lock-free instruction
12353 sequence, a call is made to an external routine with the same parameters
12354 to be resolved at run time.
12356 When implementing patterns for these built-in functions, the memory order
12357 parameter can be ignored as long as the pattern implements the most
12358 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
12359 orders execute correctly with this memory order but they may not execute as
12360 efficiently as they could with a more appropriate implementation of the
12361 relaxed requirements.
12363 Note that the C++11 standard allows for the memory order parameter to be
12364 determined at run time rather than at compile time. These built-in
12365 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
12366 than invoke a runtime library call or inline a switch statement. This is
12367 standard compliant, safe, and the simplest approach for now.
12369 The memory order parameter is a signed int, but only the lower 16 bits are
12370 reserved for the memory order. The remainder of the signed int is reserved
12371 for target use and should be 0. Use of the predefined atomic values
12372 ensures proper usage.
12374 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
12375 This built-in function implements an atomic load operation. It returns the
12376 contents of @code{*@var{ptr}}.
12378 The valid memory order variants are
12379 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
12380 and @code{__ATOMIC_CONSUME}.
12384 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
12385 This is the generic version of an atomic load. It returns the
12386 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
12390 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
12391 This built-in function implements an atomic store operation. It writes
12392 @code{@var{val}} into @code{*@var{ptr}}.
12394 The valid memory order variants are
12395 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
12399 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
12400 This is the generic version of an atomic store. It stores the value
12401 of @code{*@var{val}} into @code{*@var{ptr}}.
12405 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
12406 This built-in function implements an atomic exchange operation. It writes
12407 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
12410 The valid memory order variants are
12411 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
12412 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
12416 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
12417 This is the generic version of an atomic exchange. It stores the
12418 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
12419 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
12423 @deftypefn {Built-in Function} bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memorder, int failure_memorder)
12424 This built-in function implements an atomic compare and exchange operation.
12425 This compares the contents of @code{*@var{ptr}} with the contents of
12426 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
12427 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
12428 equal, the operation is a @emph{read} and the current contents of
12429 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
12430 for weak compare_exchange, which may fail spuriously, and @code{false} for
12431 the strong variation, which never fails spuriously. Many targets
12432 only offer the strong variation and ignore the parameter. When in doubt, use
12433 the strong variation.
12435 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
12436 and memory is affected according to the
12437 memory order specified by @var{success_memorder}. There are no
12438 restrictions on what memory order can be used here.
12440 Otherwise, @code{false} is returned and memory is affected according
12441 to @var{failure_memorder}. This memory order cannot be
12442 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
12443 stronger order than that specified by @var{success_memorder}.
12447 @deftypefn {Built-in Function} bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memorder, int failure_memorder)
12448 This built-in function implements the generic version of
12449 @code{__atomic_compare_exchange}. The function is virtually identical to
12450 @code{__atomic_compare_exchange_n}, except the desired value is also a
12455 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
12456 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
12457 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
12458 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
12459 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
12460 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
12461 These built-in functions perform the operation suggested by the name, and
12462 return the result of the operation. Operations on pointer arguments are
12463 performed as if the operands were of the @code{uintptr_t} type. That is,
12464 they are not scaled by the size of the type to which the pointer points.
12467 @{ *ptr @var{op}= val; return *ptr; @}
12468 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
12471 The object pointed to by the first argument must be of integer or pointer
12472 type. It must not be a boolean type. All memory orders are valid.
12476 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
12477 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
12478 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
12479 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
12480 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
12481 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
12482 These built-in functions perform the operation suggested by the name, and
12483 return the value that had previously been in @code{*@var{ptr}}. Operations
12484 on pointer arguments are performed as if the operands were of
12485 the @code{uintptr_t} type. That is, they are not scaled by the size of
12486 the type to which the pointer points.
12489 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
12490 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
12493 The same constraints on arguments apply as for the corresponding
12494 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
12498 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
12500 This built-in function performs an atomic test-and-set operation on
12501 the byte at @code{*@var{ptr}}. The byte is set to some implementation
12502 defined nonzero ``set'' value and the return value is @code{true} if and only
12503 if the previous contents were ``set''.
12504 It should be only used for operands of type @code{bool} or @code{char}. For
12505 other types only part of the value may be set.
12507 All memory orders are valid.
12511 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
12513 This built-in function performs an atomic clear operation on
12514 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
12515 It should be only used for operands of type @code{bool} or @code{char} and
12516 in conjunction with @code{__atomic_test_and_set}.
12517 For other types it may only clear partially. If the type is not @code{bool}
12518 prefer using @code{__atomic_store}.
12520 The valid memory order variants are
12521 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
12522 @code{__ATOMIC_RELEASE}.
12526 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
12528 This built-in function acts as a synchronization fence between threads
12529 based on the specified memory order.
12531 All memory orders are valid.
12535 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
12537 This built-in function acts as a synchronization fence between a thread
12538 and signal handlers based in the same thread.
12540 All memory orders are valid.
12544 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
12546 This built-in function returns @code{true} if objects of @var{size} bytes always
12547 generate lock-free atomic instructions for the target architecture.
12548 @var{size} must resolve to a compile-time constant and the result also
12549 resolves to a compile-time constant.
12551 @var{ptr} is an optional pointer to the object that may be used to determine
12552 alignment. A value of 0 indicates typical alignment should be used. The
12553 compiler may also ignore this parameter.
12556 if (__atomic_always_lock_free (sizeof (long long), 0))
12561 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
12563 This built-in function returns @code{true} if objects of @var{size} bytes always
12564 generate lock-free atomic instructions for the target architecture. If
12565 the built-in function is not known to be lock-free, a call is made to a
12566 runtime routine named @code{__atomic_is_lock_free}.
12568 @var{ptr} is an optional pointer to the object that may be used to determine
12569 alignment. A value of 0 indicates typical alignment should be used. The
12570 compiler may also ignore this parameter.
12573 @node Integer Overflow Builtins
12574 @section Built-in Functions to Perform Arithmetic with Overflow Checking
12576 The following built-in functions allow performing simple arithmetic operations
12577 together with checking whether the operations overflowed.
12579 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12580 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
12581 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
12582 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
12583 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
12584 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12585 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12587 These built-in functions promote the first two operands into infinite precision signed
12588 type and perform addition on those promoted operands. The result is then
12589 cast to the type the third pointer argument points to and stored there.
12590 If the stored result is equal to the infinite precision result, the built-in
12591 functions return @code{false}, otherwise they return @code{true}. As the addition is
12592 performed in infinite signed precision, these built-in functions have fully defined
12593 behavior for all argument values.
12595 The first built-in function allows arbitrary integral types for operands and
12596 the result type must be pointer to some integral type other than enumerated or
12597 boolean type, the rest of the built-in functions have explicit integer types.
12599 The compiler will attempt to use hardware instructions to implement
12600 these built-in functions where possible, like conditional jump on overflow
12601 after addition, conditional jump on carry etc.
12605 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12606 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
12607 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
12608 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
12609 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
12610 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12611 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12613 These built-in functions are similar to the add overflow checking built-in
12614 functions above, except they perform subtraction, subtract the second argument
12615 from the first one, instead of addition.
12619 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12620 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
12621 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
12622 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
12623 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
12624 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12625 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12627 These built-in functions are similar to the add overflow checking built-in
12628 functions above, except they perform multiplication, instead of addition.
12632 The following built-in functions allow checking if simple arithmetic operation
12635 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12636 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12637 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12639 These built-in functions are similar to @code{__builtin_add_overflow},
12640 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
12641 they don't store the result of the arithmetic operation anywhere and the
12642 last argument is not a pointer, but some expression with integral type other
12643 than enumerated or boolean type.
12645 The built-in functions promote the first two operands into infinite precision signed type
12646 and perform addition on those promoted operands. The result is then
12647 cast to the type of the third argument. If the cast result is equal to the infinite
12648 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
12649 The value of the third argument is ignored, just the side effects in the third argument
12650 are evaluated, and no integral argument promotions are performed on the last argument.
12651 If the third argument is a bit-field, the type used for the result cast has the
12652 precision and signedness of the given bit-field, rather than precision and signedness
12653 of the underlying type.
12655 For example, the following macro can be used to portably check, at
12656 compile-time, whether or not adding two constant integers will overflow,
12657 and perform the addition only when it is known to be safe and not to trigger
12658 a @option{-Woverflow} warning.
12661 #define INT_ADD_OVERFLOW_P(a, b) \
12662 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
12665 A = INT_MAX, B = 3,
12666 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
12667 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
12671 The compiler will attempt to use hardware instructions to implement
12672 these built-in functions where possible, like conditional jump on overflow
12673 after addition, conditional jump on carry etc.
12677 @node x86 specific memory model extensions for transactional memory
12678 @section x86-Specific Memory Model Extensions for Transactional Memory
12680 The x86 architecture supports additional memory ordering flags
12681 to mark critical sections for hardware lock elision.
12682 These must be specified in addition to an existing memory order to
12686 @item __ATOMIC_HLE_ACQUIRE
12687 Start lock elision on a lock variable.
12688 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
12689 @item __ATOMIC_HLE_RELEASE
12690 End lock elision on a lock variable.
12691 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
12694 When a lock acquire fails, it is required for good performance to abort
12695 the transaction quickly. This can be done with a @code{_mm_pause}.
12698 #include <immintrin.h> // For _mm_pause
12702 /* Acquire lock with lock elision */
12703 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
12704 _mm_pause(); /* Abort failed transaction */
12706 /* Free lock with lock elision */
12707 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
12710 @node Object Size Checking
12711 @section Object Size Checking Built-in Functions
12712 @findex __builtin_object_size
12713 @findex __builtin___memcpy_chk
12714 @findex __builtin___mempcpy_chk
12715 @findex __builtin___memmove_chk
12716 @findex __builtin___memset_chk
12717 @findex __builtin___strcpy_chk
12718 @findex __builtin___stpcpy_chk
12719 @findex __builtin___strncpy_chk
12720 @findex __builtin___strcat_chk
12721 @findex __builtin___strncat_chk
12722 @findex __builtin___sprintf_chk
12723 @findex __builtin___snprintf_chk
12724 @findex __builtin___vsprintf_chk
12725 @findex __builtin___vsnprintf_chk
12726 @findex __builtin___printf_chk
12727 @findex __builtin___vprintf_chk
12728 @findex __builtin___fprintf_chk
12729 @findex __builtin___vfprintf_chk
12731 GCC implements a limited buffer overflow protection mechanism that can
12732 prevent some buffer overflow attacks by determining the sizes of objects
12733 into which data is about to be written and preventing the writes when
12734 the size isn't sufficient. The built-in functions described below yield
12735 the best results when used together and when optimization is enabled.
12736 For example, to detect object sizes across function boundaries or to
12737 follow pointer assignments through non-trivial control flow they rely
12738 on various optimization passes enabled with @option{-O2}. However, to
12739 a limited extent, they can be used without optimization as well.
12741 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
12742 is a built-in construct that returns a constant number of bytes from
12743 @var{ptr} to the end of the object @var{ptr} pointer points to
12744 (if known at compile time). To determine the sizes of dynamically allocated
12745 objects the function relies on the allocation functions called to obtain
12746 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
12747 Function Attributes}). @code{__builtin_object_size} never evaluates
12748 its arguments for side effects. If there are any side effects in them, it
12749 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12750 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
12751 point to and all of them are known at compile time, the returned number
12752 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
12753 0 and minimum if nonzero. If it is not possible to determine which objects
12754 @var{ptr} points to at compile time, @code{__builtin_object_size} should
12755 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12756 for @var{type} 2 or 3.
12758 @var{type} is an integer constant from 0 to 3. If the least significant
12759 bit is clear, objects are whole variables, if it is set, a closest
12760 surrounding subobject is considered the object a pointer points to.
12761 The second bit determines if maximum or minimum of remaining bytes
12765 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
12766 char *p = &var.buf1[1], *q = &var.b;
12768 /* Here the object p points to is var. */
12769 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
12770 /* The subobject p points to is var.buf1. */
12771 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
12772 /* The object q points to is var. */
12773 assert (__builtin_object_size (q, 0)
12774 == (char *) (&var + 1) - (char *) &var.b);
12775 /* The subobject q points to is var.b. */
12776 assert (__builtin_object_size (q, 1) == sizeof (var.b));
12780 There are built-in functions added for many common string operation
12781 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
12782 built-in is provided. This built-in has an additional last argument,
12783 which is the number of bytes remaining in the object the @var{dest}
12784 argument points to or @code{(size_t) -1} if the size is not known.
12786 The built-in functions are optimized into the normal string functions
12787 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
12788 it is known at compile time that the destination object will not
12789 be overflowed. If the compiler can determine at compile time that the
12790 object will always be overflowed, it issues a warning.
12792 The intended use can be e.g.@:
12796 #define bos0(dest) __builtin_object_size (dest, 0)
12797 #define memcpy(dest, src, n) \
12798 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
12802 /* It is unknown what object p points to, so this is optimized
12803 into plain memcpy - no checking is possible. */
12804 memcpy (p, "abcde", n);
12805 /* Destination is known and length too. It is known at compile
12806 time there will be no overflow. */
12807 memcpy (&buf[5], "abcde", 5);
12808 /* Destination is known, but the length is not known at compile time.
12809 This will result in __memcpy_chk call that can check for overflow
12811 memcpy (&buf[5], "abcde", n);
12812 /* Destination is known and it is known at compile time there will
12813 be overflow. There will be a warning and __memcpy_chk call that
12814 will abort the program at run time. */
12815 memcpy (&buf[6], "abcde", 5);
12818 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
12819 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
12820 @code{strcat} and @code{strncat}.
12822 There are also checking built-in functions for formatted output functions.
12824 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
12825 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12826 const char *fmt, ...);
12827 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
12829 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12830 const char *fmt, va_list ap);
12833 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
12834 etc.@: functions and can contain implementation specific flags on what
12835 additional security measures the checking function might take, such as
12836 handling @code{%n} differently.
12838 The @var{os} argument is the object size @var{s} points to, like in the
12839 other built-in functions. There is a small difference in the behavior
12840 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
12841 optimized into the non-checking functions only if @var{flag} is 0, otherwise
12842 the checking function is called with @var{os} argument set to
12843 @code{(size_t) -1}.
12845 In addition to this, there are checking built-in functions
12846 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
12847 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
12848 These have just one additional argument, @var{flag}, right before
12849 format string @var{fmt}. If the compiler is able to optimize them to
12850 @code{fputc} etc.@: functions, it does, otherwise the checking function
12851 is called and the @var{flag} argument passed to it.
12853 @node Other Builtins
12854 @section Other Built-in Functions Provided by GCC
12855 @cindex built-in functions
12856 @findex __builtin_alloca
12857 @findex __builtin_alloca_with_align
12858 @findex __builtin_alloca_with_align_and_max
12859 @findex __builtin_call_with_static_chain
12860 @findex __builtin_extend_pointer
12861 @findex __builtin_fpclassify
12862 @findex __builtin_has_attribute
12863 @findex __builtin_isfinite
12864 @findex __builtin_isnormal
12865 @findex __builtin_isgreater
12866 @findex __builtin_isgreaterequal
12867 @findex __builtin_isinf_sign
12868 @findex __builtin_isless
12869 @findex __builtin_islessequal
12870 @findex __builtin_islessgreater
12871 @findex __builtin_isunordered
12872 @findex __builtin_object_size
12873 @findex __builtin_powi
12874 @findex __builtin_powif
12875 @findex __builtin_powil
12876 @findex __builtin_speculation_safe_value
13037 @findex fprintf_unlocked
13039 @findex fputs_unlocked
13148 @findex nexttowardf
13149 @findex nexttowardl
13157 @findex printf_unlocked
13188 @findex signbitd128
13189 @findex significand
13190 @findex significandf
13191 @findex significandl
13219 @findex strncasecmp
13263 GCC provides a large number of built-in functions other than the ones
13264 mentioned above. Some of these are for internal use in the processing
13265 of exceptions or variable-length argument lists and are not
13266 documented here because they may change from time to time; we do not
13267 recommend general use of these functions.
13269 The remaining functions are provided for optimization purposes.
13271 With the exception of built-ins that have library equivalents such as
13272 the standard C library functions discussed below, or that expand to
13273 library calls, GCC built-in functions are always expanded inline and
13274 thus do not have corresponding entry points and their address cannot
13275 be obtained. Attempting to use them in an expression other than
13276 a function call results in a compile-time error.
13278 @opindex fno-builtin
13279 GCC includes built-in versions of many of the functions in the standard
13280 C library. These functions come in two forms: one whose names start with
13281 the @code{__builtin_} prefix, and the other without. Both forms have the
13282 same type (including prototype), the same address (when their address is
13283 taken), and the same meaning as the C library functions even if you specify
13284 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
13285 functions are only optimized in certain cases; if they are not optimized in
13286 a particular case, a call to the library function is emitted.
13290 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
13291 @option{-std=c99} or @option{-std=c11}), the functions
13292 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
13293 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
13294 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
13295 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
13296 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
13297 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
13298 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
13299 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
13300 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
13301 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
13302 @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl},
13303 @code{scalbf}, @code{scalbl}, @code{scalb},
13304 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
13305 @code{signbitd64}, @code{signbitd128}, @code{significandf},
13306 @code{significandl}, @code{significand}, @code{sincosf},
13307 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
13308 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
13309 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
13310 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
13312 may be handled as built-in functions.
13313 All these functions have corresponding versions
13314 prefixed with @code{__builtin_}, which may be used even in strict C90
13317 The ISO C99 functions
13318 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
13319 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
13320 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
13321 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
13322 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
13323 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
13324 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
13325 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
13326 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
13327 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
13328 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
13329 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
13330 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
13331 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
13332 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
13333 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
13334 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
13335 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
13336 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
13337 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
13338 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
13339 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
13340 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
13341 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
13342 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
13343 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
13344 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
13345 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
13346 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
13347 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
13348 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
13349 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
13350 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
13351 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
13352 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
13353 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
13354 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
13355 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
13356 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
13357 are handled as built-in functions
13358 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
13360 There are also built-in versions of the ISO C99 functions
13361 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
13362 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
13363 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
13364 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
13365 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
13366 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
13367 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
13368 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
13369 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
13370 that are recognized in any mode since ISO C90 reserves these names for
13371 the purpose to which ISO C99 puts them. All these functions have
13372 corresponding versions prefixed with @code{__builtin_}.
13374 There are also built-in functions @code{__builtin_fabsf@var{n}},
13375 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
13376 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
13377 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
13378 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
13379 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
13381 There are also GNU extension functions @code{clog10}, @code{clog10f} and
13382 @code{clog10l} which names are reserved by ISO C99 for future use.
13383 All these functions have versions prefixed with @code{__builtin_}.
13385 The ISO C94 functions
13386 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
13387 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
13388 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
13390 are handled as built-in functions
13391 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
13393 The ISO C90 functions
13394 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
13395 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
13396 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
13397 @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf},
13398 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
13399 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
13400 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
13401 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
13402 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
13403 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
13404 @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin},
13405 @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
13406 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
13407 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
13408 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
13409 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
13410 are all recognized as built-in functions unless
13411 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
13412 is specified for an individual function). All of these functions have
13413 corresponding versions prefixed with @code{__builtin_}.
13415 GCC provides built-in versions of the ISO C99 floating-point comparison
13416 macros that avoid raising exceptions for unordered operands. They have
13417 the same names as the standard macros ( @code{isgreater},
13418 @code{isgreaterequal}, @code{isless}, @code{islessequal},
13419 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
13420 prefixed. We intend for a library implementor to be able to simply
13421 @code{#define} each standard macro to its built-in equivalent.
13422 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
13423 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
13424 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
13425 built-in functions appear both with and without the @code{__builtin_} prefix.
13427 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
13428 The @code{__builtin_alloca} function must be called at block scope.
13429 The function allocates an object @var{size} bytes large on the stack
13430 of the calling function. The object is aligned on the default stack
13431 alignment boundary for the target determined by the
13432 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
13433 function returns a pointer to the first byte of the allocated object.
13434 The lifetime of the allocated object ends just before the calling
13435 function returns to its caller. This is so even when
13436 @code{__builtin_alloca} is called within a nested block.
13438 For example, the following function allocates eight objects of @code{n}
13439 bytes each on the stack, storing a pointer to each in consecutive elements
13440 of the array @code{a}. It then passes the array to function @code{g}
13441 which can safely use the storage pointed to by each of the array elements.
13444 void f (unsigned n)
13447 for (int i = 0; i != 8; ++i)
13448 a [i] = __builtin_alloca (n);
13450 g (a, n); // @r{safe}
13454 Since the @code{__builtin_alloca} function doesn't validate its argument
13455 it is the responsibility of its caller to make sure the argument doesn't
13456 cause it to exceed the stack size limit.
13457 The @code{__builtin_alloca} function is provided to make it possible to
13458 allocate on the stack arrays of bytes with an upper bound that may be
13459 computed at run time. Since C99 Variable Length Arrays offer
13460 similar functionality under a portable, more convenient, and safer
13461 interface they are recommended instead, in both C99 and C++ programs
13462 where GCC provides them as an extension.
13463 @xref{Variable Length}, for details.
13467 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
13468 The @code{__builtin_alloca_with_align} function must be called at block
13469 scope. The function allocates an object @var{size} bytes large on
13470 the stack of the calling function. The allocated object is aligned on
13471 the boundary specified by the argument @var{alignment} whose unit is given
13472 in bits (not bytes). The @var{size} argument must be positive and not
13473 exceed the stack size limit. The @var{alignment} argument must be a constant
13474 integer expression that evaluates to a power of 2 greater than or equal to
13475 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
13476 with other values are rejected with an error indicating the valid bounds.
13477 The function returns a pointer to the first byte of the allocated object.
13478 The lifetime of the allocated object ends at the end of the block in which
13479 the function was called. The allocated storage is released no later than
13480 just before the calling function returns to its caller, but may be released
13481 at the end of the block in which the function was called.
13483 For example, in the following function the call to @code{g} is unsafe
13484 because when @code{overalign} is non-zero, the space allocated by
13485 @code{__builtin_alloca_with_align} may have been released at the end
13486 of the @code{if} statement in which it was called.
13489 void f (unsigned n, bool overalign)
13493 p = __builtin_alloca_with_align (n, 64 /* bits */);
13495 p = __builtin_alloc (n);
13497 g (p, n); // @r{unsafe}
13501 Since the @code{__builtin_alloca_with_align} function doesn't validate its
13502 @var{size} argument it is the responsibility of its caller to make sure
13503 the argument doesn't cause it to exceed the stack size limit.
13504 The @code{__builtin_alloca_with_align} function is provided to make
13505 it possible to allocate on the stack overaligned arrays of bytes with
13506 an upper bound that may be computed at run time. Since C99
13507 Variable Length Arrays offer the same functionality under
13508 a portable, more convenient, and safer interface they are recommended
13509 instead, in both C99 and C++ programs where GCC provides them as
13510 an extension. @xref{Variable Length}, for details.
13514 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
13515 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
13516 specifying an upper bound for @var{size} in case its value cannot be computed
13517 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
13518 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
13519 expression, it has no effect on code generation and no attempt is made to
13520 check its compatibility with @var{size}.
13524 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
13525 The @code{__builtin_has_attribute} function evaluates to an integer constant
13526 expression equal to @code{true} if the symbol or type referenced by
13527 the @var{type-or-expression} argument has been declared with
13528 the @var{attribute} referenced by the second argument. For
13529 an @var{type-or-expression} argument that does not reference a symbol,
13530 since attributes do not apply to expressions the built-in consider
13531 the type of the argument. Neither argument is evaluated.
13532 The @var{type-or-expression} argument is subject to the same
13533 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
13534 @var{attribute} argument is an attribute name optionally followed by
13535 a comma-separated list of arguments enclosed in parentheses. Both forms
13536 of attribute names---with and without double leading and trailing
13537 underscores---are recognized. @xref{Attribute Syntax}, for details.
13538 When no attribute arguments are specified for an attribute that expects
13539 one or more arguments the function returns @code{true} if
13540 @var{type-or-expression} has been declared with the attribute regardless
13541 of the attribute argument values. Arguments provided for an attribute
13542 that expects some are validated and matched up to the provided number.
13543 The function returns @code{true} if all provided arguments match. For
13544 example, the first call to the function below evaluates to @code{true}
13545 because @code{x} is declared with the @code{aligned} attribute but
13546 the second call evaluates to @code{false} because @code{x} is declared
13547 @code{aligned (8)} and not @code{aligned (4)}.
13550 __attribute__ ((aligned (8))) int x;
13551 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
13552 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
13555 Due to a limitation the @code{__builtin_has_attribute} function returns
13556 @code{false} for the @code{mode} attribute even if the type or variable
13557 referenced by the @var{type-or-expression} argument was declared with one.
13558 The function is also not supported with labels, and in C with enumerators.
13560 Note that unlike the @code{__has_attribute} preprocessor operator which
13561 is suitable for use in @code{#if} preprocessing directives
13562 @code{__builtin_has_attribute} is an intrinsic function that is not
13563 recognized in such contexts.
13567 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
13569 This built-in function can be used to help mitigate against unsafe
13570 speculative execution. @var{type} may be any integral type or any
13575 If the CPU is not speculatively executing the code, then @var{val}
13578 If the CPU is executing speculatively then either:
13581 The function may cause execution to pause until it is known that the
13582 code is no-longer being executed speculatively (in which case
13583 @var{val} can be returned, as above); or
13585 The function may use target-dependent speculation tracking state to cause
13586 @var{failval} to be returned when it is known that speculative
13587 execution has incorrectly predicted a conditional branch operation.
13591 The second argument, @var{failval}, is optional and defaults to zero
13594 GCC defines the preprocessor macro
13595 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
13596 updated to support this builtin.
13598 The built-in function can be used where a variable appears to be used in a
13599 safe way, but the CPU, due to speculative execution may temporarily ignore
13600 the bounds checks. Consider, for example, the following function:
13604 int f (unsigned untrusted_index)
13606 if (untrusted_index < 500)
13607 return array[untrusted_index];
13612 If the function is called repeatedly with @code{untrusted_index} less
13613 than the limit of 500, then a branch predictor will learn that the
13614 block of code that returns a value stored in @code{array} will be
13615 executed. If the function is subsequently called with an
13616 out-of-range value it will still try to execute that block of code
13617 first until the CPU determines that the prediction was incorrect
13618 (the CPU will unwind any incorrect operations at that point).
13619 However, depending on how the result of the function is used, it might be
13620 possible to leave traces in the cache that can reveal what was stored
13621 at the out-of-bounds location. The built-in function can be used to
13622 provide some protection against leaking data in this way by changing
13627 int f (unsigned untrusted_index)
13629 if (untrusted_index < 500)
13630 return array[__builtin_speculation_safe_value (untrusted_index)];
13635 The built-in function will either cause execution to stall until the
13636 conditional branch has been fully resolved, or it may permit
13637 speculative execution to continue, but using 0 instead of
13638 @code{untrusted_value} if that exceeds the limit.
13640 If accessing any memory location is potentially unsafe when speculative
13641 execution is incorrect, then the code can be rewritten as
13645 int f (unsigned untrusted_index)
13647 if (untrusted_index < 500)
13648 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
13653 which will cause a @code{NULL} pointer to be used for the unsafe case.
13657 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
13659 You can use the built-in function @code{__builtin_types_compatible_p} to
13660 determine whether two types are the same.
13662 This built-in function returns 1 if the unqualified versions of the
13663 types @var{type1} and @var{type2} (which are types, not expressions) are
13664 compatible, 0 otherwise. The result of this built-in function can be
13665 used in integer constant expressions.
13667 This built-in function ignores top level qualifiers (e.g., @code{const},
13668 @code{volatile}). For example, @code{int} is equivalent to @code{const
13671 The type @code{int[]} and @code{int[5]} are compatible. On the other
13672 hand, @code{int} and @code{char *} are not compatible, even if the size
13673 of their types, on the particular architecture are the same. Also, the
13674 amount of pointer indirection is taken into account when determining
13675 similarity. Consequently, @code{short *} is not similar to
13676 @code{short **}. Furthermore, two types that are typedefed are
13677 considered compatible if their underlying types are compatible.
13679 An @code{enum} type is not considered to be compatible with another
13680 @code{enum} type even if both are compatible with the same integer
13681 type; this is what the C standard specifies.
13682 For example, @code{enum @{foo, bar@}} is not similar to
13683 @code{enum @{hot, dog@}}.
13685 You typically use this function in code whose execution varies
13686 depending on the arguments' types. For example:
13691 typeof (x) tmp = (x); \
13692 if (__builtin_types_compatible_p (typeof (x), long double)) \
13693 tmp = foo_long_double (tmp); \
13694 else if (__builtin_types_compatible_p (typeof (x), double)) \
13695 tmp = foo_double (tmp); \
13696 else if (__builtin_types_compatible_p (typeof (x), float)) \
13697 tmp = foo_float (tmp); \
13704 @emph{Note:} This construct is only available for C@.
13708 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
13710 The @var{call_exp} expression must be a function call, and the
13711 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
13712 is passed to the function call in the target's static chain location.
13713 The result of builtin is the result of the function call.
13715 @emph{Note:} This builtin is only available for C@.
13716 This builtin can be used to call Go closures from C.
13720 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
13722 You can use the built-in function @code{__builtin_choose_expr} to
13723 evaluate code depending on the value of a constant expression. This
13724 built-in function returns @var{exp1} if @var{const_exp}, which is an
13725 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
13727 This built-in function is analogous to the @samp{? :} operator in C,
13728 except that the expression returned has its type unaltered by promotion
13729 rules. Also, the built-in function does not evaluate the expression
13730 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
13731 @var{exp2} is not evaluated even if it has side effects.
13733 This built-in function can return an lvalue if the chosen argument is an
13736 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
13737 type. Similarly, if @var{exp2} is returned, its return type is the same
13744 __builtin_choose_expr ( \
13745 __builtin_types_compatible_p (typeof (x), double), \
13747 __builtin_choose_expr ( \
13748 __builtin_types_compatible_p (typeof (x), float), \
13750 /* @r{The void expression results in a compile-time error} \
13751 @r{when assigning the result to something.} */ \
13755 @emph{Note:} This construct is only available for C@. Furthermore, the
13756 unused expression (@var{exp1} or @var{exp2} depending on the value of
13757 @var{const_exp}) may still generate syntax errors. This may change in
13762 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
13764 The built-in function @code{__builtin_tgmath}, available only for C
13765 and Objective-C, calls a function determined according to the rules of
13766 @code{<tgmath.h>} macros. It is intended to be used in
13767 implementations of that header, so that expansions of macros from that
13768 header only expand each of their arguments once, to avoid problems
13769 when calls to such macros are nested inside the arguments of other
13770 calls to such macros; in addition, it results in better diagnostics
13771 for invalid calls to @code{<tgmath.h>} macros than implementations
13772 using other GNU C language features. For example, the @code{pow}
13773 type-generic macro might be defined as:
13776 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
13777 cpowf, cpow, cpowl, a, b)
13780 The arguments to @code{__builtin_tgmath} are at least two pointers to
13781 functions, followed by the arguments to the type-generic macro (which
13782 will be passed as arguments to the selected function). All the
13783 pointers to functions must be pointers to prototyped functions, none
13784 of which may have variable arguments, and all of which must have the
13785 same number of parameters; the number of parameters of the first
13786 function determines how many arguments to @code{__builtin_tgmath} are
13787 interpreted as function pointers, and how many as the arguments to the
13790 The types of the specified functions must all be different, but
13791 related to each other in the same way as a set of functions that may
13792 be selected between by a macro in @code{<tgmath.h>}. This means that
13793 the functions are parameterized by a floating-point type @var{t},
13794 different for each such function. The function return types may all
13795 be the same type, or they may be @var{t} for each function, or they
13796 may be the real type corresponding to @var{t} for each function (if
13797 some of the types @var{t} are complex). Likewise, for each parameter
13798 position, the type of the parameter in that position may always be the
13799 same type, or may be @var{t} for each function (this case must apply
13800 for at least one parameter position), or may be the real type
13801 corresponding to @var{t} for each function.
13803 The standard rules for @code{<tgmath.h>} macros are used to find a
13804 common type @var{u} from the types of the arguments for parameters
13805 whose types vary between the functions; complex integer types (a GNU
13806 extension) are treated like @code{_Complex double} for this purpose
13807 (or @code{_Complex _Float64} if all the function return types are the
13808 same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
13809 If the function return types vary, or are all the same integer type,
13810 the function called is the one for which @var{t} is @var{u}, and it is
13811 an error if there is no such function. If the function return types
13812 are all the same floating-point type, the type-generic macro is taken
13813 to be one of those from TS 18661 that rounds the result to a narrower
13814 type; if there is a function for which @var{t} is @var{u}, it is
13815 called, and otherwise the first function, if any, for which @var{t}
13816 has at least the range and precision of @var{u} is called, and it is
13817 an error if there is no such function.
13821 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
13823 The built-in function @code{__builtin_complex} is provided for use in
13824 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
13825 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
13826 real binary floating-point type, and the result has the corresponding
13827 complex type with real and imaginary parts @var{real} and @var{imag}.
13828 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
13829 infinities, NaNs and negative zeros are involved.
13833 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
13834 You can use the built-in function @code{__builtin_constant_p} to
13835 determine if a value is known to be constant at compile time and hence
13836 that GCC can perform constant-folding on expressions involving that
13837 value. The argument of the function is the value to test. The function
13838 returns the integer 1 if the argument is known to be a compile-time
13839 constant and 0 if it is not known to be a compile-time constant. A
13840 return of 0 does not indicate that the value is @emph{not} a constant,
13841 but merely that GCC cannot prove it is a constant with the specified
13842 value of the @option{-O} option.
13844 You typically use this function in an embedded application where
13845 memory is a critical resource. If you have some complex calculation,
13846 you may want it to be folded if it involves constants, but need to call
13847 a function if it does not. For example:
13850 #define Scale_Value(X) \
13851 (__builtin_constant_p (X) \
13852 ? ((X) * SCALE + OFFSET) : Scale (X))
13855 You may use this built-in function in either a macro or an inline
13856 function. However, if you use it in an inlined function and pass an
13857 argument of the function as the argument to the built-in, GCC
13858 never returns 1 when you call the inline function with a string constant
13859 or compound literal (@pxref{Compound Literals}) and does not return 1
13860 when you pass a constant numeric value to the inline function unless you
13861 specify the @option{-O} option.
13863 You may also use @code{__builtin_constant_p} in initializers for static
13864 data. For instance, you can write
13867 static const int table[] = @{
13868 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
13874 This is an acceptable initializer even if @var{EXPRESSION} is not a
13875 constant expression, including the case where
13876 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
13877 folded to a constant but @var{EXPRESSION} contains operands that are
13878 not otherwise permitted in a static initializer (for example,
13879 @code{0 && foo ()}). GCC must be more conservative about evaluating the
13880 built-in in this case, because it has no opportunity to perform
13884 @deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void)
13885 The @code{__builtin_is_constant_evaluated} function is available only
13886 in C++. The built-in is intended to be used by implementations of
13887 the @code{std::is_constant_evaluated} C++ function. Programs should make
13888 use of the latter function rather than invoking the built-in directly.
13890 The main use case of the built-in is to determine whether a @code{constexpr}
13891 function is being called in a @code{constexpr} context. A call to
13892 the function evaluates to a core constant expression with the value
13893 @code{true} if and only if it occurs within the evaluation of an expression
13894 or conversion that is manifestly constant-evaluated as defined in the C++
13895 standard. Manifestly constant-evaluated contexts include constant-expressions,
13896 the conditions of @code{constexpr if} statements, constraint-expressions, and
13897 initializers of variables usable in constant expressions. For more details
13898 refer to the latest revision of the C++ standard.
13901 @deftypefn {Built-in Function} void __builtin_clear_padding (@var{ptr})
13902 The built-in function @code{__builtin_clear_padding} function clears
13903 padding bits inside of the object representation of object pointed by
13904 @var{ptr}, which has to be a pointer. The value representation of the
13905 object is not affected. The type of the object is assumed to be the type
13906 the pointer points to. Inside of a union, the only cleared bits are
13907 bits that are padding bits for all the union members.
13909 This built-in-function is useful if the padding bits of an object might
13910 have intederminate values and the object representation needs to be
13911 bitwise compared to some other object, for example for atomic operations.
13914 @deftypefn {Built-in Function} @var{type} __builtin_bit_cast (@var{type}, @var{arg})
13915 The @code{__builtin_bit_cast} function is available only
13916 in C++. The built-in is intended to be used by implementations of
13917 the @code{std::bit_cast} C++ template function. Programs should make
13918 use of the latter function rather than invoking the built-in directly.
13920 This built-in function allows reinterpreting the bits of the @var{arg}
13921 argument as if it had type @var{type}. @var{type} and the type of the
13922 @var{arg} argument need to be trivially copyable types with the same size.
13923 When manifestly constant-evaluated, it performs extra diagnostics required
13924 for @code{std::bit_cast} and returns a constant expression if @var{arg}
13925 is a constant expression. For more details
13926 refer to the latest revision of the C++ standard.
13929 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
13930 @opindex fprofile-arcs
13931 You may use @code{__builtin_expect} to provide the compiler with
13932 branch prediction information. In general, you should prefer to
13933 use actual profile feedback for this (@option{-fprofile-arcs}), as
13934 programmers are notoriously bad at predicting how their programs
13935 actually perform. However, there are applications in which this
13936 data is hard to collect.
13938 The return value is the value of @var{exp}, which should be an integral
13939 expression. The semantics of the built-in are that it is expected that
13940 @var{exp} == @var{c}. For example:
13943 if (__builtin_expect (x, 0))
13948 indicates that we do not expect to call @code{foo}, since
13949 we expect @code{x} to be zero. Since you are limited to integral
13950 expressions for @var{exp}, you should use constructions such as
13953 if (__builtin_expect (ptr != NULL, 1))
13958 when testing pointer or floating-point values.
13960 For the purposes of branch prediction optimizations, the probability that
13961 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
13962 @code{builtin-expect-probability} parameter, which defaults to 90%.
13964 You can also use @code{__builtin_expect_with_probability} to explicitly
13965 assign a probability value to individual expressions. If the built-in
13966 is used in a loop construct, the provided probability will influence
13967 the expected number of iterations made by loop optimizations.
13970 @deftypefn {Built-in Function} long __builtin_expect_with_probability
13971 (long @var{exp}, long @var{c}, double @var{probability})
13973 This function has the same semantics as @code{__builtin_expect},
13974 but the caller provides the expected probability that @var{exp} == @var{c}.
13975 The last argument, @var{probability}, is a floating-point value in the
13976 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
13977 constant floating-point expression.
13980 @deftypefn {Built-in Function} void __builtin_trap (void)
13981 This function causes the program to exit abnormally. GCC implements
13982 this function by using a target-dependent mechanism (such as
13983 intentionally executing an illegal instruction) or by calling
13984 @code{abort}. The mechanism used may vary from release to release so
13985 you should not rely on any particular implementation.
13988 @deftypefn {Built-in Function} void __builtin_unreachable (void)
13989 If control flow reaches the point of the @code{__builtin_unreachable},
13990 the program is undefined. It is useful in situations where the
13991 compiler cannot deduce the unreachability of the code.
13993 One such case is immediately following an @code{asm} statement that
13994 either never terminates, or one that transfers control elsewhere
13995 and never returns. In this example, without the
13996 @code{__builtin_unreachable}, GCC issues a warning that control
13997 reaches the end of a non-void function. It also generates code
13998 to return after the @code{asm}.
14001 int f (int c, int v)
14009 asm("jmp error_handler");
14010 __builtin_unreachable ();
14016 Because the @code{asm} statement unconditionally transfers control out
14017 of the function, control never reaches the end of the function
14018 body. The @code{__builtin_unreachable} is in fact unreachable and
14019 communicates this fact to the compiler.
14021 Another use for @code{__builtin_unreachable} is following a call a
14022 function that never returns but that is not declared
14023 @code{__attribute__((noreturn))}, as in this example:
14026 void function_that_never_returns (void);
14036 function_that_never_returns ();
14037 __builtin_unreachable ();
14044 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
14045 This function returns its first argument, and allows the compiler
14046 to assume that the returned pointer is at least @var{align} bytes
14047 aligned. This built-in can have either two or three arguments,
14048 if it has three, the third argument should have integer type, and
14049 if it is nonzero means misalignment offset. For example:
14052 void *x = __builtin_assume_aligned (arg, 16);
14056 means that the compiler can assume @code{x}, set to @code{arg}, is at least
14057 16-byte aligned, while:
14060 void *x = __builtin_assume_aligned (arg, 32, 8);
14064 means that the compiler can assume for @code{x}, set to @code{arg}, that
14065 @code{(char *) x - 8} is 32-byte aligned.
14068 @deftypefn {Built-in Function} int __builtin_LINE ()
14069 This function is the equivalent of the preprocessor @code{__LINE__}
14070 macro and returns a constant integer expression that evaluates to
14071 the line number of the invocation of the built-in. When used as a C++
14072 default argument for a function @var{F}, it returns the line number
14073 of the call to @var{F}.
14076 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
14077 This function is the equivalent of the @code{__FUNCTION__} symbol
14078 and returns an address constant pointing to the name of the function
14079 from which the built-in was invoked, or the empty string if
14080 the invocation is not at function scope. When used as a C++ default
14081 argument for a function @var{F}, it returns the name of @var{F}'s
14082 caller or the empty string if the call was not made at function
14086 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
14087 This function is the equivalent of the preprocessor @code{__FILE__}
14088 macro and returns an address constant pointing to the file name
14089 containing the invocation of the built-in, or the empty string if
14090 the invocation is not at function scope. When used as a C++ default
14091 argument for a function @var{F}, it returns the file name of the call
14092 to @var{F} or the empty string if the call was not made at function
14095 For example, in the following, each call to function @code{foo} will
14096 print a line similar to @code{"file.c:123: foo: message"} with the name
14097 of the file and the line number of the @code{printf} call, the name of
14098 the function @code{foo}, followed by the word @code{message}.
14102 function (const char *func = __builtin_FUNCTION ())
14109 printf ("%s:%i: %s: message\n", file (), line (), function ());
14115 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
14116 This function is used to flush the processor's instruction cache for
14117 the region of memory between @var{begin} inclusive and @var{end}
14118 exclusive. Some targets require that the instruction cache be
14119 flushed, after modifying memory containing code, in order to obtain
14120 deterministic behavior.
14122 If the target does not require instruction cache flushes,
14123 @code{__builtin___clear_cache} has no effect. Otherwise either
14124 instructions are emitted in-line to clear the instruction cache or a
14125 call to the @code{__clear_cache} function in libgcc is made.
14128 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
14129 This function is used to minimize cache-miss latency by moving data into
14130 a cache before it is accessed.
14131 You can insert calls to @code{__builtin_prefetch} into code for which
14132 you know addresses of data in memory that is likely to be accessed soon.
14133 If the target supports them, data prefetch instructions are generated.
14134 If the prefetch is done early enough before the access then the data will
14135 be in the cache by the time it is accessed.
14137 The value of @var{addr} is the address of the memory to prefetch.
14138 There are two optional arguments, @var{rw} and @var{locality}.
14139 The value of @var{rw} is a compile-time constant one or zero; one
14140 means that the prefetch is preparing for a write to the memory address
14141 and zero, the default, means that the prefetch is preparing for a read.
14142 The value @var{locality} must be a compile-time constant integer between
14143 zero and three. A value of zero means that the data has no temporal
14144 locality, so it need not be left in the cache after the access. A value
14145 of three means that the data has a high degree of temporal locality and
14146 should be left in all levels of cache possible. Values of one and two
14147 mean, respectively, a low or moderate degree of temporal locality. The
14151 for (i = 0; i < n; i++)
14153 a[i] = a[i] + b[i];
14154 __builtin_prefetch (&a[i+j], 1, 1);
14155 __builtin_prefetch (&b[i+j], 0, 1);
14160 Data prefetch does not generate faults if @var{addr} is invalid, but
14161 the address expression itself must be valid. For example, a prefetch
14162 of @code{p->next} does not fault if @code{p->next} is not a valid
14163 address, but evaluation faults if @code{p} is not a valid address.
14165 If the target does not support data prefetch, the address expression
14166 is evaluated if it includes side effects but no other code is generated
14167 and GCC does not issue a warning.
14170 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
14171 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size
14172 Checking}, for a detailed description of the function.
14175 @deftypefn {Built-in Function} double __builtin_huge_val (void)
14176 Returns a positive infinity, if supported by the floating-point format,
14177 else @code{DBL_MAX}. This function is suitable for implementing the
14178 ISO C macro @code{HUGE_VAL}.
14181 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
14182 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
14185 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
14186 Similar to @code{__builtin_huge_val}, except the return
14187 type is @code{long double}.
14190 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
14191 Similar to @code{__builtin_huge_val}, except the return type is
14192 @code{_Float@var{n}}.
14195 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
14196 Similar to @code{__builtin_huge_val}, except the return type is
14197 @code{_Float@var{n}x}.
14200 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
14201 This built-in implements the C99 fpclassify functionality. The first
14202 five int arguments should be the target library's notion of the
14203 possible FP classes and are used for return values. They must be
14204 constant values and they must appear in this order: @code{FP_NAN},
14205 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
14206 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
14207 to classify. GCC treats the last argument as type-generic, which
14208 means it does not do default promotion from float to double.
14211 @deftypefn {Built-in Function} double __builtin_inf (void)
14212 Similar to @code{__builtin_huge_val}, except a warning is generated
14213 if the target floating-point format does not support infinities.
14216 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
14217 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
14220 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
14221 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
14224 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
14225 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
14228 @deftypefn {Built-in Function} float __builtin_inff (void)
14229 Similar to @code{__builtin_inf}, except the return type is @code{float}.
14230 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
14233 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
14234 Similar to @code{__builtin_inf}, except the return
14235 type is @code{long double}.
14238 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
14239 Similar to @code{__builtin_inf}, except the return
14240 type is @code{_Float@var{n}}.
14243 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
14244 Similar to @code{__builtin_inf}, except the return
14245 type is @code{_Float@var{n}x}.
14248 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
14249 Similar to @code{isinf}, except the return value is -1 for
14250 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
14251 Note while the parameter list is an
14252 ellipsis, this function only accepts exactly one floating-point
14253 argument. GCC treats this parameter as type-generic, which means it
14254 does not do default promotion from float to double.
14257 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
14258 This is an implementation of the ISO C99 function @code{nan}.
14260 Since ISO C99 defines this function in terms of @code{strtod}, which we
14261 do not implement, a description of the parsing is in order. The string
14262 is parsed as by @code{strtol}; that is, the base is recognized by
14263 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
14264 in the significand such that the least significant bit of the number
14265 is at the least significant bit of the significand. The number is
14266 truncated to fit the significand field provided. The significand is
14267 forced to be a quiet NaN@.
14269 This function, if given a string literal all of which would have been
14270 consumed by @code{strtol}, is evaluated early enough that it is considered a
14271 compile-time constant.
14274 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
14275 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
14278 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
14279 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
14282 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
14283 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
14286 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
14287 Similar to @code{__builtin_nan}, except the return type is @code{float}.
14290 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
14291 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
14294 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
14295 Similar to @code{__builtin_nan}, except the return type is
14296 @code{_Float@var{n}}.
14299 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
14300 Similar to @code{__builtin_nan}, except the return type is
14301 @code{_Float@var{n}x}.
14304 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
14305 Similar to @code{__builtin_nan}, except the significand is forced
14306 to be a signaling NaN@. The @code{nans} function is proposed by
14307 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
14310 @deftypefn {Built-in Function} _Decimal32 __builtin_nansd32 (const char *str)
14311 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}.
14314 @deftypefn {Built-in Function} _Decimal64 __builtin_nansd64 (const char *str)
14315 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}.
14318 @deftypefn {Built-in Function} _Decimal128 __builtin_nansd128 (const char *str)
14319 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}.
14322 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
14323 Similar to @code{__builtin_nans}, except the return type is @code{float}.
14326 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
14327 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
14330 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
14331 Similar to @code{__builtin_nans}, except the return type is
14332 @code{_Float@var{n}}.
14335 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
14336 Similar to @code{__builtin_nans}, except the return type is
14337 @code{_Float@var{n}x}.
14340 @deftypefn {Built-in Function} int __builtin_ffs (int x)
14341 Returns one plus the index of the least significant 1-bit of @var{x}, or
14342 if @var{x} is zero, returns zero.
14345 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
14346 Returns the number of leading 0-bits in @var{x}, starting at the most
14347 significant bit position. If @var{x} is 0, the result is undefined.
14350 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
14351 Returns the number of trailing 0-bits in @var{x}, starting at the least
14352 significant bit position. If @var{x} is 0, the result is undefined.
14355 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
14356 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
14357 number of bits following the most significant bit that are identical
14358 to it. There are no special cases for 0 or other values.
14361 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
14362 Returns the number of 1-bits in @var{x}.
14365 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
14366 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
14370 @deftypefn {Built-in Function} int __builtin_ffsl (long)
14371 Similar to @code{__builtin_ffs}, except the argument type is
14375 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
14376 Similar to @code{__builtin_clz}, except the argument type is
14377 @code{unsigned long}.
14380 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
14381 Similar to @code{__builtin_ctz}, except the argument type is
14382 @code{unsigned long}.
14385 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
14386 Similar to @code{__builtin_clrsb}, except the argument type is
14390 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
14391 Similar to @code{__builtin_popcount}, except the argument type is
14392 @code{unsigned long}.
14395 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
14396 Similar to @code{__builtin_parity}, except the argument type is
14397 @code{unsigned long}.
14400 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
14401 Similar to @code{__builtin_ffs}, except the argument type is
14405 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
14406 Similar to @code{__builtin_clz}, except the argument type is
14407 @code{unsigned long long}.
14410 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
14411 Similar to @code{__builtin_ctz}, except the argument type is
14412 @code{unsigned long long}.
14415 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
14416 Similar to @code{__builtin_clrsb}, except the argument type is
14420 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
14421 Similar to @code{__builtin_popcount}, except the argument type is
14422 @code{unsigned long long}.
14425 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
14426 Similar to @code{__builtin_parity}, except the argument type is
14427 @code{unsigned long long}.
14430 @deftypefn {Built-in Function} double __builtin_powi (double, int)
14431 Returns the first argument raised to the power of the second. Unlike the
14432 @code{pow} function no guarantees about precision and rounding are made.
14435 @deftypefn {Built-in Function} float __builtin_powif (float, int)
14436 Similar to @code{__builtin_powi}, except the argument and return types
14440 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
14441 Similar to @code{__builtin_powi}, except the argument and return types
14442 are @code{long double}.
14445 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
14446 Returns @var{x} with the order of the bytes reversed; for example,
14447 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
14451 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
14452 Similar to @code{__builtin_bswap16}, except the argument and return types
14456 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
14457 Similar to @code{__builtin_bswap32}, except the argument and return types
14461 @deftypefn {Built-in Function} uint128_t __builtin_bswap128 (uint128_t x)
14462 Similar to @code{__builtin_bswap64}, except the argument and return types
14463 are 128-bit. Only supported on targets when 128-bit types are supported.
14467 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
14468 On targets where the user visible pointer size is smaller than the size
14469 of an actual hardware address this function returns the extended user
14470 pointer. Targets where this is true included ILP32 mode on x86_64 or
14471 Aarch64. This function is mainly useful when writing inline assembly
14475 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
14476 Returns the openacc gang, worker or vector id depending on whether @var{x} is
14480 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
14481 Returns the openacc gang, worker or vector size depending on whether @var{x} is
14485 @node Target Builtins
14486 @section Built-in Functions Specific to Particular Target Machines
14488 On some target machines, GCC supports many built-in functions specific
14489 to those machines. Generally these generate calls to specific machine
14490 instructions, but allow the compiler to schedule those calls.
14493 * AArch64 Built-in Functions::
14494 * Alpha Built-in Functions::
14495 * Altera Nios II Built-in Functions::
14496 * ARC Built-in Functions::
14497 * ARC SIMD Built-in Functions::
14498 * ARM iWMMXt Built-in Functions::
14499 * ARM C Language Extensions (ACLE)::
14500 * ARM Floating Point Status and Control Intrinsics::
14501 * ARM ARMv8-M Security Extensions::
14502 * AVR Built-in Functions::
14503 * Blackfin Built-in Functions::
14504 * BPF Built-in Functions::
14505 * FR-V Built-in Functions::
14506 * MIPS DSP Built-in Functions::
14507 * MIPS Paired-Single Support::
14508 * MIPS Loongson Built-in Functions::
14509 * MIPS SIMD Architecture (MSA) Support::
14510 * Other MIPS Built-in Functions::
14511 * MSP430 Built-in Functions::
14512 * NDS32 Built-in Functions::
14513 * picoChip Built-in Functions::
14514 * Basic PowerPC Built-in Functions::
14515 * PowerPC AltiVec/VSX Built-in Functions::
14516 * PowerPC Hardware Transactional Memory Built-in Functions::
14517 * PowerPC Atomic Memory Operation Functions::
14518 * PowerPC Matrix-Multiply Assist Built-in Functions::
14519 * PRU Built-in Functions::
14520 * RISC-V Built-in Functions::
14521 * RX Built-in Functions::
14522 * S/390 System z Built-in Functions::
14523 * SH Built-in Functions::
14524 * SPARC VIS Built-in Functions::
14525 * TI C6X Built-in Functions::
14526 * TILE-Gx Built-in Functions::
14527 * TILEPro Built-in Functions::
14528 * x86 Built-in Functions::
14529 * x86 transactional memory intrinsics::
14530 * x86 control-flow protection intrinsics::
14533 @node AArch64 Built-in Functions
14534 @subsection AArch64 Built-in Functions
14536 These built-in functions are available for the AArch64 family of
14539 unsigned int __builtin_aarch64_get_fpcr ()
14540 void __builtin_aarch64_set_fpcr (unsigned int)
14541 unsigned int __builtin_aarch64_get_fpsr ()
14542 void __builtin_aarch64_set_fpsr (unsigned int)
14544 unsigned long long __builtin_aarch64_get_fpcr64 ()
14545 void __builtin_aarch64_set_fpcr64 (unsigned long long)
14546 unsigned long long __builtin_aarch64_get_fpsr64 ()
14547 void __builtin_aarch64_set_fpsr64 (unsigned long long)
14550 @node Alpha Built-in Functions
14551 @subsection Alpha Built-in Functions
14553 These built-in functions are available for the Alpha family of
14554 processors, depending on the command-line switches used.
14556 The following built-in functions are always available. They
14557 all generate the machine instruction that is part of the name.
14560 long __builtin_alpha_implver (void)
14561 long __builtin_alpha_rpcc (void)
14562 long __builtin_alpha_amask (long)
14563 long __builtin_alpha_cmpbge (long, long)
14564 long __builtin_alpha_extbl (long, long)
14565 long __builtin_alpha_extwl (long, long)
14566 long __builtin_alpha_extll (long, long)
14567 long __builtin_alpha_extql (long, long)
14568 long __builtin_alpha_extwh (long, long)
14569 long __builtin_alpha_extlh (long, long)
14570 long __builtin_alpha_extqh (long, long)
14571 long __builtin_alpha_insbl (long, long)
14572 long __builtin_alpha_inswl (long, long)
14573 long __builtin_alpha_insll (long, long)
14574 long __builtin_alpha_insql (long, long)
14575 long __builtin_alpha_inswh (long, long)
14576 long __builtin_alpha_inslh (long, long)
14577 long __builtin_alpha_insqh (long, long)
14578 long __builtin_alpha_mskbl (long, long)
14579 long __builtin_alpha_mskwl (long, long)
14580 long __builtin_alpha_mskll (long, long)
14581 long __builtin_alpha_mskql (long, long)
14582 long __builtin_alpha_mskwh (long, long)
14583 long __builtin_alpha_msklh (long, long)
14584 long __builtin_alpha_mskqh (long, long)
14585 long __builtin_alpha_umulh (long, long)
14586 long __builtin_alpha_zap (long, long)
14587 long __builtin_alpha_zapnot (long, long)
14590 The following built-in functions are always with @option{-mmax}
14591 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
14592 later. They all generate the machine instruction that is part
14596 long __builtin_alpha_pklb (long)
14597 long __builtin_alpha_pkwb (long)
14598 long __builtin_alpha_unpkbl (long)
14599 long __builtin_alpha_unpkbw (long)
14600 long __builtin_alpha_minub8 (long, long)
14601 long __builtin_alpha_minsb8 (long, long)
14602 long __builtin_alpha_minuw4 (long, long)
14603 long __builtin_alpha_minsw4 (long, long)
14604 long __builtin_alpha_maxub8 (long, long)
14605 long __builtin_alpha_maxsb8 (long, long)
14606 long __builtin_alpha_maxuw4 (long, long)
14607 long __builtin_alpha_maxsw4 (long, long)
14608 long __builtin_alpha_perr (long, long)
14611 The following built-in functions are always with @option{-mcix}
14612 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
14613 later. They all generate the machine instruction that is part
14617 long __builtin_alpha_cttz (long)
14618 long __builtin_alpha_ctlz (long)
14619 long __builtin_alpha_ctpop (long)
14622 The following built-in functions are available on systems that use the OSF/1
14623 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
14624 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
14625 @code{rdval} and @code{wrval}.
14628 void *__builtin_thread_pointer (void)
14629 void __builtin_set_thread_pointer (void *)
14632 @node Altera Nios II Built-in Functions
14633 @subsection Altera Nios II Built-in Functions
14635 These built-in functions are available for the Altera Nios II
14636 family of processors.
14638 The following built-in functions are always available. They
14639 all generate the machine instruction that is part of the name.
14642 int __builtin_ldbio (volatile const void *)
14643 int __builtin_ldbuio (volatile const void *)
14644 int __builtin_ldhio (volatile const void *)
14645 int __builtin_ldhuio (volatile const void *)
14646 int __builtin_ldwio (volatile const void *)
14647 void __builtin_stbio (volatile void *, int)
14648 void __builtin_sthio (volatile void *, int)
14649 void __builtin_stwio (volatile void *, int)
14650 void __builtin_sync (void)
14651 int __builtin_rdctl (int)
14652 int __builtin_rdprs (int, int)
14653 void __builtin_wrctl (int, int)
14654 void __builtin_flushd (volatile void *)
14655 void __builtin_flushda (volatile void *)
14656 int __builtin_wrpie (int);
14657 void __builtin_eni (int);
14658 int __builtin_ldex (volatile const void *)
14659 int __builtin_stex (volatile void *, int)
14660 int __builtin_ldsex (volatile const void *)
14661 int __builtin_stsex (volatile void *, int)
14664 The following built-in functions are always available. They
14665 all generate a Nios II Custom Instruction. The name of the
14666 function represents the types that the function takes and
14667 returns. The letter before the @code{n} is the return type
14668 or void if absent. The @code{n} represents the first parameter
14669 to all the custom instructions, the custom instruction number.
14670 The two letters after the @code{n} represent the up to two
14671 parameters to the function.
14673 The letters represent the following data types:
14676 @code{void} for return type and no parameter for parameter types.
14679 @code{int} for return type and parameter type
14682 @code{float} for return type and parameter type
14685 @code{void *} for return type and parameter type
14689 And the function names are:
14691 void __builtin_custom_n (void)
14692 void __builtin_custom_ni (int)
14693 void __builtin_custom_nf (float)
14694 void __builtin_custom_np (void *)
14695 void __builtin_custom_nii (int, int)
14696 void __builtin_custom_nif (int, float)
14697 void __builtin_custom_nip (int, void *)
14698 void __builtin_custom_nfi (float, int)
14699 void __builtin_custom_nff (float, float)
14700 void __builtin_custom_nfp (float, void *)
14701 void __builtin_custom_npi (void *, int)
14702 void __builtin_custom_npf (void *, float)
14703 void __builtin_custom_npp (void *, void *)
14704 int __builtin_custom_in (void)
14705 int __builtin_custom_ini (int)
14706 int __builtin_custom_inf (float)
14707 int __builtin_custom_inp (void *)
14708 int __builtin_custom_inii (int, int)
14709 int __builtin_custom_inif (int, float)
14710 int __builtin_custom_inip (int, void *)
14711 int __builtin_custom_infi (float, int)
14712 int __builtin_custom_inff (float, float)
14713 int __builtin_custom_infp (float, void *)
14714 int __builtin_custom_inpi (void *, int)
14715 int __builtin_custom_inpf (void *, float)
14716 int __builtin_custom_inpp (void *, void *)
14717 float __builtin_custom_fn (void)
14718 float __builtin_custom_fni (int)
14719 float __builtin_custom_fnf (float)
14720 float __builtin_custom_fnp (void *)
14721 float __builtin_custom_fnii (int, int)
14722 float __builtin_custom_fnif (int, float)
14723 float __builtin_custom_fnip (int, void *)
14724 float __builtin_custom_fnfi (float, int)
14725 float __builtin_custom_fnff (float, float)
14726 float __builtin_custom_fnfp (float, void *)
14727 float __builtin_custom_fnpi (void *, int)
14728 float __builtin_custom_fnpf (void *, float)
14729 float __builtin_custom_fnpp (void *, void *)
14730 void * __builtin_custom_pn (void)
14731 void * __builtin_custom_pni (int)
14732 void * __builtin_custom_pnf (float)
14733 void * __builtin_custom_pnp (void *)
14734 void * __builtin_custom_pnii (int, int)
14735 void * __builtin_custom_pnif (int, float)
14736 void * __builtin_custom_pnip (int, void *)
14737 void * __builtin_custom_pnfi (float, int)
14738 void * __builtin_custom_pnff (float, float)
14739 void * __builtin_custom_pnfp (float, void *)
14740 void * __builtin_custom_pnpi (void *, int)
14741 void * __builtin_custom_pnpf (void *, float)
14742 void * __builtin_custom_pnpp (void *, void *)
14745 @node ARC Built-in Functions
14746 @subsection ARC Built-in Functions
14748 The following built-in functions are provided for ARC targets. The
14749 built-ins generate the corresponding assembly instructions. In the
14750 examples given below, the generated code often requires an operand or
14751 result to be in a register. Where necessary further code will be
14752 generated to ensure this is true, but for brevity this is not
14753 described in each case.
14755 @emph{Note:} Using a built-in to generate an instruction not supported
14756 by a target may cause problems. At present the compiler is not
14757 guaranteed to detect such misuse, and as a result an internal compiler
14758 error may be generated.
14760 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
14761 Return 1 if @var{val} is known to have the byte alignment given
14762 by @var{alignval}, otherwise return 0.
14763 Note that this is different from
14765 __alignof__(*(char *)@var{val}) >= alignval
14767 because __alignof__ sees only the type of the dereference, whereas
14768 __builtin_arc_align uses alignment information from the pointer
14769 as well as from the pointed-to type.
14770 The information available will depend on optimization level.
14773 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
14780 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
14781 The operand is the number of a register to be read. Generates:
14783 mov @var{dest}, r@var{regno}
14785 where the value in @var{dest} will be the result returned from the
14789 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
14790 The first operand is the number of a register to be written, the
14791 second operand is a compile time constant to write into that
14792 register. Generates:
14794 mov r@var{regno}, @var{val}
14798 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
14799 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
14802 divaw @var{dest}, @var{a}, @var{b}
14804 where the value in @var{dest} will be the result returned from the
14808 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
14815 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
14816 The operand, @var{auxv}, is the address of an auxiliary register and
14817 must be a compile time constant. Generates:
14819 lr @var{dest}, [@var{auxr}]
14821 Where the value in @var{dest} will be the result returned from the
14825 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
14826 Only available with @option{-mmul64}. Generates:
14828 mul64 @var{a}, @var{b}
14832 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
14833 Only available with @option{-mmul64}. Generates:
14835 mulu64 @var{a}, @var{b}
14839 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
14846 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
14847 Only valid if the @samp{norm} instruction is available through the
14848 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14851 norm @var{dest}, @var{src}
14853 Where the value in @var{dest} will be the result returned from the
14857 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
14858 Only valid if the @samp{normw} instruction is available through the
14859 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14862 normw @var{dest}, @var{src}
14864 Where the value in @var{dest} will be the result returned from the
14868 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
14875 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
14882 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{val}, unsigned int @var{auxr})
14883 The first argument, @var{val}, is a compile time constant to be
14884 written to the register, the second argument, @var{auxr}, is the
14885 address of an auxiliary register. Generates:
14887 sr @var{val}, [@var{auxr}]
14891 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
14892 Only valid with @option{-mswap}. Generates:
14894 swap @var{dest}, @var{src}
14896 Where the value in @var{dest} will be the result returned from the
14900 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
14907 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
14908 Only available with @option{-mcpu=ARC700}. Generates:
14914 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
14915 Only available with @option{-mcpu=ARC700}. Generates:
14921 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
14922 Only available with @option{-mcpu=ARC700}. Generates:
14928 The instructions generated by the following builtins are not
14929 considered as candidates for scheduling. They are not moved around by
14930 the compiler during scheduling, and thus can be expected to appear
14931 where they are put in the C code:
14933 __builtin_arc_brk()
14934 __builtin_arc_core_read()
14935 __builtin_arc_core_write()
14936 __builtin_arc_flag()
14938 __builtin_arc_sleep()
14940 __builtin_arc_swi()
14943 @node ARC SIMD Built-in Functions
14944 @subsection ARC SIMD Built-in Functions
14946 SIMD builtins provided by the compiler can be used to generate the
14947 vector instructions. This section describes the available builtins
14948 and their usage in programs. With the @option{-msimd} option, the
14949 compiler provides 128-bit vector types, which can be specified using
14950 the @code{vector_size} attribute. The header file @file{arc-simd.h}
14951 can be included to use the following predefined types:
14953 typedef int __v4si __attribute__((vector_size(16)));
14954 typedef short __v8hi __attribute__((vector_size(16)));
14957 These types can be used to define 128-bit variables. The built-in
14958 functions listed in the following section can be used on these
14959 variables to generate the vector operations.
14961 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
14962 @file{arc-simd.h} also provides equivalent macros called
14963 @code{_@var{someinsn}} that can be used for programming ease and
14964 improved readability. The following macros for DMA control are also
14967 #define _setup_dma_in_channel_reg _vdiwr
14968 #define _setup_dma_out_channel_reg _vdowr
14971 The following is a complete list of all the SIMD built-ins provided
14972 for ARC, grouped by calling signature.
14974 The following take two @code{__v8hi} arguments and return a
14975 @code{__v8hi} result:
14977 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi)
14978 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi)
14979 __v8hi __builtin_arc_vand (__v8hi, __v8hi)
14980 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi)
14981 __v8hi __builtin_arc_vavb (__v8hi, __v8hi)
14982 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi)
14983 __v8hi __builtin_arc_vbic (__v8hi, __v8hi)
14984 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi)
14985 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi)
14986 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi)
14987 __v8hi __builtin_arc_veqw (__v8hi, __v8hi)
14988 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi)
14989 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi)
14990 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi)
14991 __v8hi __builtin_arc_vlew (__v8hi, __v8hi)
14992 __v8hi __builtin_arc_vltw (__v8hi, __v8hi)
14993 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi)
14994 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi)
14995 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi)
14996 __v8hi __builtin_arc_vminw (__v8hi, __v8hi)
14997 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi)
14998 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi)
14999 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi)
15000 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi)
15001 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi)
15002 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi)
15003 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi)
15004 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi)
15005 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi)
15006 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi)
15007 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi)
15008 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi)
15009 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi)
15010 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi)
15011 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi)
15012 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi)
15013 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi)
15014 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi)
15015 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi)
15016 __v8hi __builtin_arc_vnew (__v8hi, __v8hi)
15017 __v8hi __builtin_arc_vor (__v8hi, __v8hi)
15018 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi)
15019 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi)
15020 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi)
15021 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi)
15022 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi)
15023 __v8hi __builtin_arc_vxor (__v8hi, __v8hi)
15024 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi)
15027 The following take one @code{__v8hi} and one @code{int} argument and return a
15028 @code{__v8hi} result:
15031 __v8hi __builtin_arc_vbaddw (__v8hi, int)
15032 __v8hi __builtin_arc_vbmaxw (__v8hi, int)
15033 __v8hi __builtin_arc_vbminw (__v8hi, int)
15034 __v8hi __builtin_arc_vbmulaw (__v8hi, int)
15035 __v8hi __builtin_arc_vbmulfw (__v8hi, int)
15036 __v8hi __builtin_arc_vbmulw (__v8hi, int)
15037 __v8hi __builtin_arc_vbrsubw (__v8hi, int)
15038 __v8hi __builtin_arc_vbsubw (__v8hi, int)
15041 The following take one @code{__v8hi} argument and one @code{int} argument which
15042 must be a 3-bit compile time constant indicating a register number
15043 I0-I7. They return a @code{__v8hi} result.
15045 __v8hi __builtin_arc_vasrw (__v8hi, const int)
15046 __v8hi __builtin_arc_vsr8 (__v8hi, const int)
15047 __v8hi __builtin_arc_vsr8aw (__v8hi, const int)
15050 The following take one @code{__v8hi} argument and one @code{int}
15051 argument which must be a 6-bit compile time constant. They return a
15052 @code{__v8hi} result.
15054 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int)
15055 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int)
15056 __v8hi __builtin_arc_vasrrwi (__v8hi, const int)
15057 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int)
15058 __v8hi __builtin_arc_vasrwi (__v8hi, const int)
15059 __v8hi __builtin_arc_vsr8awi (__v8hi, const int)
15060 __v8hi __builtin_arc_vsr8i (__v8hi, const int)
15063 The following take one @code{__v8hi} argument and one @code{int} argument which
15064 must be a 8-bit compile time constant. They return a @code{__v8hi}
15067 __v8hi __builtin_arc_vd6tapf (__v8hi, const int)
15068 __v8hi __builtin_arc_vmvaw (__v8hi, const int)
15069 __v8hi __builtin_arc_vmvw (__v8hi, const int)
15070 __v8hi __builtin_arc_vmvzw (__v8hi, const int)
15073 The following take two @code{int} arguments, the second of which which
15074 must be a 8-bit compile time constant. They return a @code{__v8hi}
15077 __v8hi __builtin_arc_vmovaw (int, const int)
15078 __v8hi __builtin_arc_vmovw (int, const int)
15079 __v8hi __builtin_arc_vmovzw (int, const int)
15082 The following take a single @code{__v8hi} argument and return a
15083 @code{__v8hi} result:
15085 __v8hi __builtin_arc_vabsaw (__v8hi)
15086 __v8hi __builtin_arc_vabsw (__v8hi)
15087 __v8hi __builtin_arc_vaddsuw (__v8hi)
15088 __v8hi __builtin_arc_vexch1 (__v8hi)
15089 __v8hi __builtin_arc_vexch2 (__v8hi)
15090 __v8hi __builtin_arc_vexch4 (__v8hi)
15091 __v8hi __builtin_arc_vsignw (__v8hi)
15092 __v8hi __builtin_arc_vupbaw (__v8hi)
15093 __v8hi __builtin_arc_vupbw (__v8hi)
15094 __v8hi __builtin_arc_vupsbaw (__v8hi)
15095 __v8hi __builtin_arc_vupsbw (__v8hi)
15098 The following take two @code{int} arguments and return no result:
15100 void __builtin_arc_vdirun (int, int)
15101 void __builtin_arc_vdorun (int, int)
15104 The following take two @code{int} arguments and return no result. The
15105 first argument must a 3-bit compile time constant indicating one of
15106 the DR0-DR7 DMA setup channels:
15108 void __builtin_arc_vdiwr (const int, int)
15109 void __builtin_arc_vdowr (const int, int)
15112 The following take an @code{int} argument and return no result:
15114 void __builtin_arc_vendrec (int)
15115 void __builtin_arc_vrec (int)
15116 void __builtin_arc_vrecrun (int)
15117 void __builtin_arc_vrun (int)
15120 The following take a @code{__v8hi} argument and two @code{int}
15121 arguments and return a @code{__v8hi} result. The second argument must
15122 be a 3-bit compile time constants, indicating one the registers I0-I7,
15123 and the third argument must be an 8-bit compile time constant.
15125 @emph{Note:} Although the equivalent hardware instructions do not take
15126 an SIMD register as an operand, these builtins overwrite the relevant
15127 bits of the @code{__v8hi} register provided as the first argument with
15128 the value loaded from the @code{[Ib, u8]} location in the SDM.
15131 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int)
15132 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int)
15133 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int)
15134 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int)
15137 The following take two @code{int} arguments and return a @code{__v8hi}
15138 result. The first argument must be a 3-bit compile time constants,
15139 indicating one the registers I0-I7, and the second argument must be an
15140 8-bit compile time constant.
15143 __v8hi __builtin_arc_vld128 (const int, const int)
15144 __v8hi __builtin_arc_vld64w (const int, const int)
15147 The following take a @code{__v8hi} argument and two @code{int}
15148 arguments and return no result. The second argument must be a 3-bit
15149 compile time constants, indicating one the registers I0-I7, and the
15150 third argument must be an 8-bit compile time constant.
15153 void __builtin_arc_vst128 (__v8hi, const int, const int)
15154 void __builtin_arc_vst64 (__v8hi, const int, const int)
15157 The following take a @code{__v8hi} argument and three @code{int}
15158 arguments and return no result. The second argument must be a 3-bit
15159 compile-time constant, identifying the 16-bit sub-register to be
15160 stored, the third argument must be a 3-bit compile time constants,
15161 indicating one the registers I0-I7, and the fourth argument must be an
15162 8-bit compile time constant.
15165 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int)
15166 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int)
15169 @node ARM iWMMXt Built-in Functions
15170 @subsection ARM iWMMXt Built-in Functions
15172 These built-in functions are available for the ARM family of
15173 processors when the @option{-mcpu=iwmmxt} switch is used:
15176 typedef int v2si __attribute__ ((vector_size (8)));
15177 typedef short v4hi __attribute__ ((vector_size (8)));
15178 typedef char v8qi __attribute__ ((vector_size (8)));
15180 int __builtin_arm_getwcgr0 (void)
15181 void __builtin_arm_setwcgr0 (int)
15182 int __builtin_arm_getwcgr1 (void)
15183 void __builtin_arm_setwcgr1 (int)
15184 int __builtin_arm_getwcgr2 (void)
15185 void __builtin_arm_setwcgr2 (int)
15186 int __builtin_arm_getwcgr3 (void)
15187 void __builtin_arm_setwcgr3 (int)
15188 int __builtin_arm_textrmsb (v8qi, int)
15189 int __builtin_arm_textrmsh (v4hi, int)
15190 int __builtin_arm_textrmsw (v2si, int)
15191 int __builtin_arm_textrmub (v8qi, int)
15192 int __builtin_arm_textrmuh (v4hi, int)
15193 int __builtin_arm_textrmuw (v2si, int)
15194 v8qi __builtin_arm_tinsrb (v8qi, int, int)
15195 v4hi __builtin_arm_tinsrh (v4hi, int, int)
15196 v2si __builtin_arm_tinsrw (v2si, int, int)
15197 long long __builtin_arm_tmia (long long, int, int)
15198 long long __builtin_arm_tmiabb (long long, int, int)
15199 long long __builtin_arm_tmiabt (long long, int, int)
15200 long long __builtin_arm_tmiaph (long long, int, int)
15201 long long __builtin_arm_tmiatb (long long, int, int)
15202 long long __builtin_arm_tmiatt (long long, int, int)
15203 int __builtin_arm_tmovmskb (v8qi)
15204 int __builtin_arm_tmovmskh (v4hi)
15205 int __builtin_arm_tmovmskw (v2si)
15206 long long __builtin_arm_waccb (v8qi)
15207 long long __builtin_arm_wacch (v4hi)
15208 long long __builtin_arm_waccw (v2si)
15209 v8qi __builtin_arm_waddb (v8qi, v8qi)
15210 v8qi __builtin_arm_waddbss (v8qi, v8qi)
15211 v8qi __builtin_arm_waddbus (v8qi, v8qi)
15212 v4hi __builtin_arm_waddh (v4hi, v4hi)
15213 v4hi __builtin_arm_waddhss (v4hi, v4hi)
15214 v4hi __builtin_arm_waddhus (v4hi, v4hi)
15215 v2si __builtin_arm_waddw (v2si, v2si)
15216 v2si __builtin_arm_waddwss (v2si, v2si)
15217 v2si __builtin_arm_waddwus (v2si, v2si)
15218 v8qi __builtin_arm_walign (v8qi, v8qi, int)
15219 long long __builtin_arm_wand(long long, long long)
15220 long long __builtin_arm_wandn (long long, long long)
15221 v8qi __builtin_arm_wavg2b (v8qi, v8qi)
15222 v8qi __builtin_arm_wavg2br (v8qi, v8qi)
15223 v4hi __builtin_arm_wavg2h (v4hi, v4hi)
15224 v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
15225 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
15226 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
15227 v2si __builtin_arm_wcmpeqw (v2si, v2si)
15228 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
15229 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
15230 v2si __builtin_arm_wcmpgtsw (v2si, v2si)
15231 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
15232 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
15233 v2si __builtin_arm_wcmpgtuw (v2si, v2si)
15234 long long __builtin_arm_wmacs (long long, v4hi, v4hi)
15235 long long __builtin_arm_wmacsz (v4hi, v4hi)
15236 long long __builtin_arm_wmacu (long long, v4hi, v4hi)
15237 long long __builtin_arm_wmacuz (v4hi, v4hi)
15238 v4hi __builtin_arm_wmadds (v4hi, v4hi)
15239 v4hi __builtin_arm_wmaddu (v4hi, v4hi)
15240 v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
15241 v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
15242 v2si __builtin_arm_wmaxsw (v2si, v2si)
15243 v8qi __builtin_arm_wmaxub (v8qi, v8qi)
15244 v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
15245 v2si __builtin_arm_wmaxuw (v2si, v2si)
15246 v8qi __builtin_arm_wminsb (v8qi, v8qi)
15247 v4hi __builtin_arm_wminsh (v4hi, v4hi)
15248 v2si __builtin_arm_wminsw (v2si, v2si)
15249 v8qi __builtin_arm_wminub (v8qi, v8qi)
15250 v4hi __builtin_arm_wminuh (v4hi, v4hi)
15251 v2si __builtin_arm_wminuw (v2si, v2si)
15252 v4hi __builtin_arm_wmulsm (v4hi, v4hi)
15253 v4hi __builtin_arm_wmulul (v4hi, v4hi)
15254 v4hi __builtin_arm_wmulum (v4hi, v4hi)
15255 long long __builtin_arm_wor (long long, long long)
15256 v2si __builtin_arm_wpackdss (long long, long long)
15257 v2si __builtin_arm_wpackdus (long long, long long)
15258 v8qi __builtin_arm_wpackhss (v4hi, v4hi)
15259 v8qi __builtin_arm_wpackhus (v4hi, v4hi)
15260 v4hi __builtin_arm_wpackwss (v2si, v2si)
15261 v4hi __builtin_arm_wpackwus (v2si, v2si)
15262 long long __builtin_arm_wrord (long long, long long)
15263 long long __builtin_arm_wrordi (long long, int)
15264 v4hi __builtin_arm_wrorh (v4hi, long long)
15265 v4hi __builtin_arm_wrorhi (v4hi, int)
15266 v2si __builtin_arm_wrorw (v2si, long long)
15267 v2si __builtin_arm_wrorwi (v2si, int)
15268 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi)
15269 v2si __builtin_arm_wsadbz (v8qi, v8qi)
15270 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi)
15271 v2si __builtin_arm_wsadhz (v4hi, v4hi)
15272 v4hi __builtin_arm_wshufh (v4hi, int)
15273 long long __builtin_arm_wslld (long long, long long)
15274 long long __builtin_arm_wslldi (long long, int)
15275 v4hi __builtin_arm_wsllh (v4hi, long long)
15276 v4hi __builtin_arm_wsllhi (v4hi, int)
15277 v2si __builtin_arm_wsllw (v2si, long long)
15278 v2si __builtin_arm_wsllwi (v2si, int)
15279 long long __builtin_arm_wsrad (long long, long long)
15280 long long __builtin_arm_wsradi (long long, int)
15281 v4hi __builtin_arm_wsrah (v4hi, long long)
15282 v4hi __builtin_arm_wsrahi (v4hi, int)
15283 v2si __builtin_arm_wsraw (v2si, long long)
15284 v2si __builtin_arm_wsrawi (v2si, int)
15285 long long __builtin_arm_wsrld (long long, long long)
15286 long long __builtin_arm_wsrldi (long long, int)
15287 v4hi __builtin_arm_wsrlh (v4hi, long long)
15288 v4hi __builtin_arm_wsrlhi (v4hi, int)
15289 v2si __builtin_arm_wsrlw (v2si, long long)
15290 v2si __builtin_arm_wsrlwi (v2si, int)
15291 v8qi __builtin_arm_wsubb (v8qi, v8qi)
15292 v8qi __builtin_arm_wsubbss (v8qi, v8qi)
15293 v8qi __builtin_arm_wsubbus (v8qi, v8qi)
15294 v4hi __builtin_arm_wsubh (v4hi, v4hi)
15295 v4hi __builtin_arm_wsubhss (v4hi, v4hi)
15296 v4hi __builtin_arm_wsubhus (v4hi, v4hi)
15297 v2si __builtin_arm_wsubw (v2si, v2si)
15298 v2si __builtin_arm_wsubwss (v2si, v2si)
15299 v2si __builtin_arm_wsubwus (v2si, v2si)
15300 v4hi __builtin_arm_wunpckehsb (v8qi)
15301 v2si __builtin_arm_wunpckehsh (v4hi)
15302 long long __builtin_arm_wunpckehsw (v2si)
15303 v4hi __builtin_arm_wunpckehub (v8qi)
15304 v2si __builtin_arm_wunpckehuh (v4hi)
15305 long long __builtin_arm_wunpckehuw (v2si)
15306 v4hi __builtin_arm_wunpckelsb (v8qi)
15307 v2si __builtin_arm_wunpckelsh (v4hi)
15308 long long __builtin_arm_wunpckelsw (v2si)
15309 v4hi __builtin_arm_wunpckelub (v8qi)
15310 v2si __builtin_arm_wunpckeluh (v4hi)
15311 long long __builtin_arm_wunpckeluw (v2si)
15312 v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
15313 v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
15314 v2si __builtin_arm_wunpckihw (v2si, v2si)
15315 v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
15316 v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
15317 v2si __builtin_arm_wunpckilw (v2si, v2si)
15318 long long __builtin_arm_wxor (long long, long long)
15319 long long __builtin_arm_wzero ()
15323 @node ARM C Language Extensions (ACLE)
15324 @subsection ARM C Language Extensions (ACLE)
15326 GCC implements extensions for C as described in the ARM C Language
15327 Extensions (ACLE) specification, which can be found at
15328 @uref{https://developer.arm.com/documentation/ihi0053/latest/}.
15330 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
15331 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
15332 intrinsics can be found at
15333 @uref{https://developer.arm.com/documentation/ihi0073/latest/}.
15334 The built-in intrinsics for the Advanced SIMD extension are available when
15337 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
15338 back ends support CRC32 intrinsics and the ARM back end supports the
15339 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
15340 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
15341 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
15344 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
15345 availability of extensions.
15347 @node ARM Floating Point Status and Control Intrinsics
15348 @subsection ARM Floating Point Status and Control Intrinsics
15350 These built-in functions are available for the ARM family of
15351 processors with floating-point unit.
15354 unsigned int __builtin_arm_get_fpscr ()
15355 void __builtin_arm_set_fpscr (unsigned int)
15358 @node ARM ARMv8-M Security Extensions
15359 @subsection ARM ARMv8-M Security Extensions
15361 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
15362 Security Extensions: Requirements on Development Tools Engineering
15363 Specification, which can be found at
15364 @uref{https://developer.arm.com/documentation/ecm0359818/latest/}.
15366 As part of the Security Extensions GCC implements two new function attributes:
15367 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
15369 As part of the Security Extensions GCC implements the intrinsics below. FPTR
15370 is used here to mean any function pointer type.
15373 cmse_address_info_t cmse_TT (void *)
15374 cmse_address_info_t cmse_TT_fptr (FPTR)
15375 cmse_address_info_t cmse_TTT (void *)
15376 cmse_address_info_t cmse_TTT_fptr (FPTR)
15377 cmse_address_info_t cmse_TTA (void *)
15378 cmse_address_info_t cmse_TTA_fptr (FPTR)
15379 cmse_address_info_t cmse_TTAT (void *)
15380 cmse_address_info_t cmse_TTAT_fptr (FPTR)
15381 void * cmse_check_address_range (void *, size_t, int)
15382 typeof(p) cmse_nsfptr_create (FPTR p)
15383 intptr_t cmse_is_nsfptr (FPTR)
15384 int cmse_nonsecure_caller (void)
15387 @node AVR Built-in Functions
15388 @subsection AVR Built-in Functions
15390 For each built-in function for AVR, there is an equally named,
15391 uppercase built-in macro defined. That way users can easily query if
15392 or if not a specific built-in is implemented or not. For example, if
15393 @code{__builtin_avr_nop} is available the macro
15394 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
15398 @item void __builtin_avr_nop (void)
15399 @itemx void __builtin_avr_sei (void)
15400 @itemx void __builtin_avr_cli (void)
15401 @itemx void __builtin_avr_sleep (void)
15402 @itemx void __builtin_avr_wdr (void)
15403 @itemx unsigned char __builtin_avr_swap (unsigned char)
15404 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
15405 @itemx int __builtin_avr_fmuls (char, char)
15406 @itemx int __builtin_avr_fmulsu (char, unsigned char)
15407 These built-in functions map to the respective machine
15408 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
15409 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
15410 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
15411 as library call if no hardware multiplier is available.
15413 @item void __builtin_avr_delay_cycles (unsigned long ticks)
15414 Delay execution for @var{ticks} cycles. Note that this
15415 built-in does not take into account the effect of interrupts that
15416 might increase delay time. @var{ticks} must be a compile-time
15417 integer constant; delays with a variable number of cycles are not supported.
15419 @item char __builtin_avr_flash_segment (const __memx void*)
15420 This built-in takes a byte address to the 24-bit
15421 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
15422 the number of the flash segment (the 64 KiB chunk) where the address
15423 points to. Counting starts at @code{0}.
15424 If the address does not point to flash memory, return @code{-1}.
15426 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
15427 Insert bits from @var{bits} into @var{val} and return the resulting
15428 value. The nibbles of @var{map} determine how the insertion is
15429 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
15431 @item If @var{X} is @code{0xf},
15432 then the @var{n}-th bit of @var{val} is returned unaltered.
15434 @item If X is in the range 0@dots{}7,
15435 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
15437 @item If X is in the range 8@dots{}@code{0xe},
15438 then the @var{n}-th result bit is undefined.
15442 One typical use case for this built-in is adjusting input and
15443 output values to non-contiguous port layouts. Some examples:
15446 // same as val, bits is unused
15447 __builtin_avr_insert_bits (0xffffffff, bits, val)
15451 // same as bits, val is unused
15452 __builtin_avr_insert_bits (0x76543210, bits, val)
15456 // same as rotating bits by 4
15457 __builtin_avr_insert_bits (0x32107654, bits, 0)
15461 // high nibble of result is the high nibble of val
15462 // low nibble of result is the low nibble of bits
15463 __builtin_avr_insert_bits (0xffff3210, bits, val)
15467 // reverse the bit order of bits
15468 __builtin_avr_insert_bits (0x01234567, bits, 0)
15471 @item void __builtin_avr_nops (unsigned count)
15472 Insert @var{count} @code{NOP} instructions.
15473 The number of instructions must be a compile-time integer constant.
15478 There are many more AVR-specific built-in functions that are used to
15479 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
15480 section 7.18a.6. You don't need to use these built-ins directly.
15481 Instead, use the declarations as supplied by the @code{stdfix.h} header
15485 #include <stdfix.h>
15487 // Re-interpret the bit representation of unsigned 16-bit
15488 // integer @var{uval} as Q-format 0.16 value.
15489 unsigned fract get_bits (uint_ur_t uval)
15491 return urbits (uval);
15495 @node Blackfin Built-in Functions
15496 @subsection Blackfin Built-in Functions
15498 Currently, there are two Blackfin-specific built-in functions. These are
15499 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
15500 using inline assembly; by using these built-in functions the compiler can
15501 automatically add workarounds for hardware errata involving these
15502 instructions. These functions are named as follows:
15505 void __builtin_bfin_csync (void)
15506 void __builtin_bfin_ssync (void)
15509 @node BPF Built-in Functions
15510 @subsection BPF Built-in Functions
15512 The following built-in functions are available for eBPF targets.
15514 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset})
15515 Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15518 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset})
15519 Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15522 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset})
15523 Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15526 @deftypefn {Built-in Function} void * __builtin_preserve_access_index (@var{expr})
15527 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).
15530 @node FR-V Built-in Functions
15531 @subsection FR-V Built-in Functions
15533 GCC provides many FR-V-specific built-in functions. In general,
15534 these functions are intended to be compatible with those described
15535 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
15536 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
15537 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
15538 pointer rather than by value.
15540 Most of the functions are named after specific FR-V instructions.
15541 Such functions are said to be ``directly mapped'' and are summarized
15542 here in tabular form.
15546 * Directly-mapped Integer Functions::
15547 * Directly-mapped Media Functions::
15548 * Raw read/write Functions::
15549 * Other Built-in Functions::
15552 @node Argument Types
15553 @subsubsection Argument Types
15555 The arguments to the built-in functions can be divided into three groups:
15556 register numbers, compile-time constants and run-time values. In order
15557 to make this classification clear at a glance, the arguments and return
15558 values are given the following pseudo types:
15560 @multitable @columnfractions .20 .30 .15 .35
15561 @headitem Pseudo type @tab Real C type @tab Constant? @tab Description
15562 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
15563 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
15564 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
15565 @item @code{uw2} @tab @code{unsigned long long} @tab No
15566 @tab an unsigned doubleword
15567 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
15568 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
15569 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
15570 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
15573 These pseudo types are not defined by GCC, they are simply a notational
15574 convenience used in this manual.
15576 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
15577 and @code{sw2} are evaluated at run time. They correspond to
15578 register operands in the underlying FR-V instructions.
15580 @code{const} arguments represent immediate operands in the underlying
15581 FR-V instructions. They must be compile-time constants.
15583 @code{acc} arguments are evaluated at compile time and specify the number
15584 of an accumulator register. For example, an @code{acc} argument of 2
15585 selects the ACC2 register.
15587 @code{iacc} arguments are similar to @code{acc} arguments but specify the
15588 number of an IACC register. See @pxref{Other Built-in Functions}
15591 @node Directly-mapped Integer Functions
15592 @subsubsection Directly-Mapped Integer Functions
15594 The functions listed below map directly to FR-V I-type instructions.
15596 @multitable @columnfractions .45 .32 .23
15597 @headitem Function prototype @tab Example usage @tab Assembly output
15598 @item @code{sw1 __ADDSS (sw1, sw1)}
15599 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
15600 @tab @code{ADDSS @var{a},@var{b},@var{c}}
15601 @item @code{sw1 __SCAN (sw1, sw1)}
15602 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
15603 @tab @code{SCAN @var{a},@var{b},@var{c}}
15604 @item @code{sw1 __SCUTSS (sw1)}
15605 @tab @code{@var{b} = __SCUTSS (@var{a})}
15606 @tab @code{SCUTSS @var{a},@var{b}}
15607 @item @code{sw1 __SLASS (sw1, sw1)}
15608 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
15609 @tab @code{SLASS @var{a},@var{b},@var{c}}
15610 @item @code{void __SMASS (sw1, sw1)}
15611 @tab @code{__SMASS (@var{a}, @var{b})}
15612 @tab @code{SMASS @var{a},@var{b}}
15613 @item @code{void __SMSSS (sw1, sw1)}
15614 @tab @code{__SMSSS (@var{a}, @var{b})}
15615 @tab @code{SMSSS @var{a},@var{b}}
15616 @item @code{void __SMU (sw1, sw1)}
15617 @tab @code{__SMU (@var{a}, @var{b})}
15618 @tab @code{SMU @var{a},@var{b}}
15619 @item @code{sw2 __SMUL (sw1, sw1)}
15620 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
15621 @tab @code{SMUL @var{a},@var{b},@var{c}}
15622 @item @code{sw1 __SUBSS (sw1, sw1)}
15623 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
15624 @tab @code{SUBSS @var{a},@var{b},@var{c}}
15625 @item @code{uw2 __UMUL (uw1, uw1)}
15626 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
15627 @tab @code{UMUL @var{a},@var{b},@var{c}}
15630 @node Directly-mapped Media Functions
15631 @subsubsection Directly-Mapped Media Functions
15633 The functions listed below map directly to FR-V M-type instructions.
15635 @multitable @columnfractions .45 .32 .23
15636 @headitem Function prototype @tab Example usage @tab Assembly output
15637 @item @code{uw1 __MABSHS (sw1)}
15638 @tab @code{@var{b} = __MABSHS (@var{a})}
15639 @tab @code{MABSHS @var{a},@var{b}}
15640 @item @code{void __MADDACCS (acc, acc)}
15641 @tab @code{__MADDACCS (@var{b}, @var{a})}
15642 @tab @code{MADDACCS @var{a},@var{b}}
15643 @item @code{sw1 __MADDHSS (sw1, sw1)}
15644 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
15645 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
15646 @item @code{uw1 __MADDHUS (uw1, uw1)}
15647 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
15648 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
15649 @item @code{uw1 __MAND (uw1, uw1)}
15650 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
15651 @tab @code{MAND @var{a},@var{b},@var{c}}
15652 @item @code{void __MASACCS (acc, acc)}
15653 @tab @code{__MASACCS (@var{b}, @var{a})}
15654 @tab @code{MASACCS @var{a},@var{b}}
15655 @item @code{uw1 __MAVEH (uw1, uw1)}
15656 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
15657 @tab @code{MAVEH @var{a},@var{b},@var{c}}
15658 @item @code{uw2 __MBTOH (uw1)}
15659 @tab @code{@var{b} = __MBTOH (@var{a})}
15660 @tab @code{MBTOH @var{a},@var{b}}
15661 @item @code{void __MBTOHE (uw1 *, uw1)}
15662 @tab @code{__MBTOHE (&@var{b}, @var{a})}
15663 @tab @code{MBTOHE @var{a},@var{b}}
15664 @item @code{void __MCLRACC (acc)}
15665 @tab @code{__MCLRACC (@var{a})}
15666 @tab @code{MCLRACC @var{a}}
15667 @item @code{void __MCLRACCA (void)}
15668 @tab @code{__MCLRACCA ()}
15669 @tab @code{MCLRACCA}
15670 @item @code{uw1 __Mcop1 (uw1, uw1)}
15671 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
15672 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
15673 @item @code{uw1 __Mcop2 (uw1, uw1)}
15674 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
15675 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
15676 @item @code{uw1 __MCPLHI (uw2, const)}
15677 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
15678 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
15679 @item @code{uw1 __MCPLI (uw2, const)}
15680 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
15681 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
15682 @item @code{void __MCPXIS (acc, sw1, sw1)}
15683 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
15684 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
15685 @item @code{void __MCPXIU (acc, uw1, uw1)}
15686 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
15687 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
15688 @item @code{void __MCPXRS (acc, sw1, sw1)}
15689 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
15690 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
15691 @item @code{void __MCPXRU (acc, uw1, uw1)}
15692 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
15693 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
15694 @item @code{uw1 __MCUT (acc, uw1)}
15695 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
15696 @tab @code{MCUT @var{a},@var{b},@var{c}}
15697 @item @code{uw1 __MCUTSS (acc, sw1)}
15698 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
15699 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
15700 @item @code{void __MDADDACCS (acc, acc)}
15701 @tab @code{__MDADDACCS (@var{b}, @var{a})}
15702 @tab @code{MDADDACCS @var{a},@var{b}}
15703 @item @code{void __MDASACCS (acc, acc)}
15704 @tab @code{__MDASACCS (@var{b}, @var{a})}
15705 @tab @code{MDASACCS @var{a},@var{b}}
15706 @item @code{uw2 __MDCUTSSI (acc, const)}
15707 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
15708 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
15709 @item @code{uw2 __MDPACKH (uw2, uw2)}
15710 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
15711 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
15712 @item @code{uw2 __MDROTLI (uw2, const)}
15713 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
15714 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
15715 @item @code{void __MDSUBACCS (acc, acc)}
15716 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
15717 @tab @code{MDSUBACCS @var{a},@var{b}}
15718 @item @code{void __MDUNPACKH (uw1 *, uw2)}
15719 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
15720 @tab @code{MDUNPACKH @var{a},@var{b}}
15721 @item @code{uw2 __MEXPDHD (uw1, const)}
15722 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
15723 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
15724 @item @code{uw1 __MEXPDHW (uw1, const)}
15725 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
15726 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
15727 @item @code{uw1 __MHDSETH (uw1, const)}
15728 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
15729 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
15730 @item @code{sw1 __MHDSETS (const)}
15731 @tab @code{@var{b} = __MHDSETS (@var{a})}
15732 @tab @code{MHDSETS #@var{a},@var{b}}
15733 @item @code{uw1 __MHSETHIH (uw1, const)}
15734 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
15735 @tab @code{MHSETHIH #@var{a},@var{b}}
15736 @item @code{sw1 __MHSETHIS (sw1, const)}
15737 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
15738 @tab @code{MHSETHIS #@var{a},@var{b}}
15739 @item @code{uw1 __MHSETLOH (uw1, const)}
15740 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
15741 @tab @code{MHSETLOH #@var{a},@var{b}}
15742 @item @code{sw1 __MHSETLOS (sw1, const)}
15743 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
15744 @tab @code{MHSETLOS #@var{a},@var{b}}
15745 @item @code{uw1 __MHTOB (uw2)}
15746 @tab @code{@var{b} = __MHTOB (@var{a})}
15747 @tab @code{MHTOB @var{a},@var{b}}
15748 @item @code{void __MMACHS (acc, sw1, sw1)}
15749 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
15750 @tab @code{MMACHS @var{a},@var{b},@var{c}}
15751 @item @code{void __MMACHU (acc, uw1, uw1)}
15752 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
15753 @tab @code{MMACHU @var{a},@var{b},@var{c}}
15754 @item @code{void __MMRDHS (acc, sw1, sw1)}
15755 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
15756 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
15757 @item @code{void __MMRDHU (acc, uw1, uw1)}
15758 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
15759 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
15760 @item @code{void __MMULHS (acc, sw1, sw1)}
15761 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
15762 @tab @code{MMULHS @var{a},@var{b},@var{c}}
15763 @item @code{void __MMULHU (acc, uw1, uw1)}
15764 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
15765 @tab @code{MMULHU @var{a},@var{b},@var{c}}
15766 @item @code{void __MMULXHS (acc, sw1, sw1)}
15767 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
15768 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
15769 @item @code{void __MMULXHU (acc, uw1, uw1)}
15770 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
15771 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
15772 @item @code{uw1 __MNOT (uw1)}
15773 @tab @code{@var{b} = __MNOT (@var{a})}
15774 @tab @code{MNOT @var{a},@var{b}}
15775 @item @code{uw1 __MOR (uw1, uw1)}
15776 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
15777 @tab @code{MOR @var{a},@var{b},@var{c}}
15778 @item @code{uw1 __MPACKH (uh, uh)}
15779 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
15780 @tab @code{MPACKH @var{a},@var{b},@var{c}}
15781 @item @code{sw2 __MQADDHSS (sw2, sw2)}
15782 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
15783 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
15784 @item @code{uw2 __MQADDHUS (uw2, uw2)}
15785 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
15786 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
15787 @item @code{void __MQCPXIS (acc, sw2, sw2)}
15788 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
15789 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
15790 @item @code{void __MQCPXIU (acc, uw2, uw2)}
15791 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
15792 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
15793 @item @code{void __MQCPXRS (acc, sw2, sw2)}
15794 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
15795 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
15796 @item @code{void __MQCPXRU (acc, uw2, uw2)}
15797 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
15798 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
15799 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
15800 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
15801 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
15802 @item @code{sw2 __MQLMTHS (sw2, sw2)}
15803 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
15804 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
15805 @item @code{void __MQMACHS (acc, sw2, sw2)}
15806 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
15807 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
15808 @item @code{void __MQMACHU (acc, uw2, uw2)}
15809 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
15810 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
15811 @item @code{void __MQMACXHS (acc, sw2, sw2)}
15812 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
15813 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
15814 @item @code{void __MQMULHS (acc, sw2, sw2)}
15815 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
15816 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
15817 @item @code{void __MQMULHU (acc, uw2, uw2)}
15818 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
15819 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
15820 @item @code{void __MQMULXHS (acc, sw2, sw2)}
15821 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
15822 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
15823 @item @code{void __MQMULXHU (acc, uw2, uw2)}
15824 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
15825 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
15826 @item @code{sw2 __MQSATHS (sw2, sw2)}
15827 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
15828 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
15829 @item @code{uw2 __MQSLLHI (uw2, int)}
15830 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
15831 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
15832 @item @code{sw2 __MQSRAHI (sw2, int)}
15833 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
15834 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
15835 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
15836 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
15837 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
15838 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
15839 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
15840 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
15841 @item @code{void __MQXMACHS (acc, sw2, sw2)}
15842 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
15843 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
15844 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
15845 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
15846 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
15847 @item @code{uw1 __MRDACC (acc)}
15848 @tab @code{@var{b} = __MRDACC (@var{a})}
15849 @tab @code{MRDACC @var{a},@var{b}}
15850 @item @code{uw1 __MRDACCG (acc)}
15851 @tab @code{@var{b} = __MRDACCG (@var{a})}
15852 @tab @code{MRDACCG @var{a},@var{b}}
15853 @item @code{uw1 __MROTLI (uw1, const)}
15854 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
15855 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
15856 @item @code{uw1 __MROTRI (uw1, const)}
15857 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
15858 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
15859 @item @code{sw1 __MSATHS (sw1, sw1)}
15860 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
15861 @tab @code{MSATHS @var{a},@var{b},@var{c}}
15862 @item @code{uw1 __MSATHU (uw1, uw1)}
15863 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
15864 @tab @code{MSATHU @var{a},@var{b},@var{c}}
15865 @item @code{uw1 __MSLLHI (uw1, const)}
15866 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
15867 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
15868 @item @code{sw1 __MSRAHI (sw1, const)}
15869 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
15870 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
15871 @item @code{uw1 __MSRLHI (uw1, const)}
15872 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
15873 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
15874 @item @code{void __MSUBACCS (acc, acc)}
15875 @tab @code{__MSUBACCS (@var{b}, @var{a})}
15876 @tab @code{MSUBACCS @var{a},@var{b}}
15877 @item @code{sw1 __MSUBHSS (sw1, sw1)}
15878 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
15879 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
15880 @item @code{uw1 __MSUBHUS (uw1, uw1)}
15881 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
15882 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
15883 @item @code{void __MTRAP (void)}
15884 @tab @code{__MTRAP ()}
15886 @item @code{uw2 __MUNPACKH (uw1)}
15887 @tab @code{@var{b} = __MUNPACKH (@var{a})}
15888 @tab @code{MUNPACKH @var{a},@var{b}}
15889 @item @code{uw1 __MWCUT (uw2, uw1)}
15890 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
15891 @tab @code{MWCUT @var{a},@var{b},@var{c}}
15892 @item @code{void __MWTACC (acc, uw1)}
15893 @tab @code{__MWTACC (@var{b}, @var{a})}
15894 @tab @code{MWTACC @var{a},@var{b}}
15895 @item @code{void __MWTACCG (acc, uw1)}
15896 @tab @code{__MWTACCG (@var{b}, @var{a})}
15897 @tab @code{MWTACCG @var{a},@var{b}}
15898 @item @code{uw1 __MXOR (uw1, uw1)}
15899 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
15900 @tab @code{MXOR @var{a},@var{b},@var{c}}
15903 @node Raw read/write Functions
15904 @subsubsection Raw Read/Write Functions
15906 This sections describes built-in functions related to read and write
15907 instructions to access memory. These functions generate
15908 @code{membar} instructions to flush the I/O load and stores where
15909 appropriate, as described in Fujitsu's manual described above.
15913 @item unsigned char __builtin_read8 (void *@var{data})
15914 @item unsigned short __builtin_read16 (void *@var{data})
15915 @item unsigned long __builtin_read32 (void *@var{data})
15916 @item unsigned long long __builtin_read64 (void *@var{data})
15918 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
15919 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
15920 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
15921 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
15924 @node Other Built-in Functions
15925 @subsubsection Other Built-in Functions
15927 This section describes built-in functions that are not named after
15928 a specific FR-V instruction.
15931 @item sw2 __IACCreadll (iacc @var{reg})
15932 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
15933 for future expansion and must be 0.
15935 @item sw1 __IACCreadl (iacc @var{reg})
15936 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
15937 Other values of @var{reg} are rejected as invalid.
15939 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
15940 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
15941 is reserved for future expansion and must be 0.
15943 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
15944 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
15945 is 1. Other values of @var{reg} are rejected as invalid.
15947 @item void __data_prefetch0 (const void *@var{x})
15948 Use the @code{dcpl} instruction to load the contents of address @var{x}
15949 into the data cache.
15951 @item void __data_prefetch (const void *@var{x})
15952 Use the @code{nldub} instruction to load the contents of address @var{x}
15953 into the data cache. The instruction is issued in slot I1@.
15956 @node MIPS DSP Built-in Functions
15957 @subsection MIPS DSP Built-in Functions
15959 The MIPS DSP Application-Specific Extension (ASE) includes new
15960 instructions that are designed to improve the performance of DSP and
15961 media applications. It provides instructions that operate on packed
15962 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
15964 GCC supports MIPS DSP operations using both the generic
15965 vector extensions (@pxref{Vector Extensions}) and a collection of
15966 MIPS-specific built-in functions. Both kinds of support are
15967 enabled by the @option{-mdsp} command-line option.
15969 Revision 2 of the ASE was introduced in the second half of 2006.
15970 This revision adds extra instructions to the original ASE, but is
15971 otherwise backwards-compatible with it. You can select revision 2
15972 using the command-line option @option{-mdspr2}; this option implies
15975 The SCOUNT and POS bits of the DSP control register are global. The
15976 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
15977 POS bits. During optimization, the compiler does not delete these
15978 instructions and it does not delete calls to functions containing
15979 these instructions.
15981 At present, GCC only provides support for operations on 32-bit
15982 vectors. The vector type associated with 8-bit integer data is
15983 usually called @code{v4i8}, the vector type associated with Q7
15984 is usually called @code{v4q7}, the vector type associated with 16-bit
15985 integer data is usually called @code{v2i16}, and the vector type
15986 associated with Q15 is usually called @code{v2q15}. They can be
15987 defined in C as follows:
15990 typedef signed char v4i8 __attribute__ ((vector_size(4)));
15991 typedef signed char v4q7 __attribute__ ((vector_size(4)));
15992 typedef short v2i16 __attribute__ ((vector_size(4)));
15993 typedef short v2q15 __attribute__ ((vector_size(4)));
15996 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
15997 initialized in the same way as aggregates. For example:
16000 v4i8 a = @{1, 2, 3, 4@};
16002 b = (v4i8) @{5, 6, 7, 8@};
16004 v2q15 c = @{0x0fcb, 0x3a75@};
16006 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
16009 @emph{Note:} The CPU's endianness determines the order in which values
16010 are packed. On little-endian targets, the first value is the least
16011 significant and the last value is the most significant. The opposite
16012 order applies to big-endian targets. For example, the code above
16013 sets the lowest byte of @code{a} to @code{1} on little-endian targets
16014 and @code{4} on big-endian targets.
16016 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
16017 representation. As shown in this example, the integer representation
16018 of a Q7 value can be obtained by multiplying the fractional value by
16019 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
16020 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
16023 The table below lists the @code{v4i8} and @code{v2q15} operations for which
16024 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
16025 and @code{c} and @code{d} are @code{v2q15} values.
16027 @multitable @columnfractions .50 .50
16028 @headitem C code @tab MIPS instruction
16029 @item @code{a + b} @tab @code{addu.qb}
16030 @item @code{c + d} @tab @code{addq.ph}
16031 @item @code{a - b} @tab @code{subu.qb}
16032 @item @code{c - d} @tab @code{subq.ph}
16035 The table below lists the @code{v2i16} operation for which
16036 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
16037 @code{v2i16} values.
16039 @multitable @columnfractions .50 .50
16040 @headitem C code @tab MIPS instruction
16041 @item @code{e * f} @tab @code{mul.ph}
16044 It is easier to describe the DSP built-in functions if we first define
16045 the following types:
16050 typedef unsigned int ui32;
16051 typedef long long a64;
16054 @code{q31} and @code{i32} are actually the same as @code{int}, but we
16055 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
16056 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
16057 @code{long long}, but we use @code{a64} to indicate values that are
16058 placed in one of the four DSP accumulators (@code{$ac0},
16059 @code{$ac1}, @code{$ac2} or @code{$ac3}).
16061 Also, some built-in functions prefer or require immediate numbers as
16062 parameters, because the corresponding DSP instructions accept both immediate
16063 numbers and register operands, or accept immediate numbers only. The
16064 immediate parameters are listed as follows.
16072 imm0_255: 0 to 255.
16073 imm_n32_31: -32 to 31.
16074 imm_n512_511: -512 to 511.
16077 The following built-in functions map directly to a particular MIPS DSP
16078 instruction. Please refer to the architecture specification
16079 for details on what each instruction does.
16082 v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
16083 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
16084 q31 __builtin_mips_addq_s_w (q31, q31)
16085 v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
16086 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
16087 v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
16088 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
16089 q31 __builtin_mips_subq_s_w (q31, q31)
16090 v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
16091 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
16092 i32 __builtin_mips_addsc (i32, i32)
16093 i32 __builtin_mips_addwc (i32, i32)
16094 i32 __builtin_mips_modsub (i32, i32)
16095 i32 __builtin_mips_raddu_w_qb (v4i8)
16096 v2q15 __builtin_mips_absq_s_ph (v2q15)
16097 q31 __builtin_mips_absq_s_w (q31)
16098 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
16099 v2q15 __builtin_mips_precrq_ph_w (q31, q31)
16100 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
16101 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
16102 q31 __builtin_mips_preceq_w_phl (v2q15)
16103 q31 __builtin_mips_preceq_w_phr (v2q15)
16104 v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
16105 v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
16106 v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
16107 v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
16108 v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
16109 v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
16110 v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
16111 v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
16112 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
16113 v4i8 __builtin_mips_shll_qb (v4i8, i32)
16114 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
16115 v2q15 __builtin_mips_shll_ph (v2q15, i32)
16116 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
16117 v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
16118 q31 __builtin_mips_shll_s_w (q31, imm0_31)
16119 q31 __builtin_mips_shll_s_w (q31, i32)
16120 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
16121 v4i8 __builtin_mips_shrl_qb (v4i8, i32)
16122 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
16123 v2q15 __builtin_mips_shra_ph (v2q15, i32)
16124 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
16125 v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
16126 q31 __builtin_mips_shra_r_w (q31, imm0_31)
16127 q31 __builtin_mips_shra_r_w (q31, i32)
16128 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
16129 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
16130 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
16131 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
16132 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
16133 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
16134 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
16135 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
16136 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
16137 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
16138 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
16139 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
16140 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
16141 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
16142 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
16143 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
16144 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
16145 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
16146 i32 __builtin_mips_bitrev (i32)
16147 i32 __builtin_mips_insv (i32, i32)
16148 v4i8 __builtin_mips_repl_qb (imm0_255)
16149 v4i8 __builtin_mips_repl_qb (i32)
16150 v2q15 __builtin_mips_repl_ph (imm_n512_511)
16151 v2q15 __builtin_mips_repl_ph (i32)
16152 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
16153 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
16154 void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
16155 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
16156 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
16157 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
16158 void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
16159 void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
16160 void __builtin_mips_cmp_le_ph (v2q15, v2q15)
16161 v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
16162 v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
16163 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
16164 i32 __builtin_mips_extr_w (a64, imm0_31)
16165 i32 __builtin_mips_extr_w (a64, i32)
16166 i32 __builtin_mips_extr_r_w (a64, imm0_31)
16167 i32 __builtin_mips_extr_s_h (a64, i32)
16168 i32 __builtin_mips_extr_rs_w (a64, imm0_31)
16169 i32 __builtin_mips_extr_rs_w (a64, i32)
16170 i32 __builtin_mips_extr_s_h (a64, imm0_31)
16171 i32 __builtin_mips_extr_r_w (a64, i32)
16172 i32 __builtin_mips_extp (a64, imm0_31)
16173 i32 __builtin_mips_extp (a64, i32)
16174 i32 __builtin_mips_extpdp (a64, imm0_31)
16175 i32 __builtin_mips_extpdp (a64, i32)
16176 a64 __builtin_mips_shilo (a64, imm_n32_31)
16177 a64 __builtin_mips_shilo (a64, i32)
16178 a64 __builtin_mips_mthlip (a64, i32)
16179 void __builtin_mips_wrdsp (i32, imm0_63)
16180 i32 __builtin_mips_rddsp (imm0_63)
16181 i32 __builtin_mips_lbux (void *, i32)
16182 i32 __builtin_mips_lhx (void *, i32)
16183 i32 __builtin_mips_lwx (void *, i32)
16184 a64 __builtin_mips_ldx (void *, i32) [MIPS64 only]
16185 i32 __builtin_mips_bposge32 (void)
16186 a64 __builtin_mips_madd (a64, i32, i32);
16187 a64 __builtin_mips_maddu (a64, ui32, ui32);
16188 a64 __builtin_mips_msub (a64, i32, i32);
16189 a64 __builtin_mips_msubu (a64, ui32, ui32);
16190 a64 __builtin_mips_mult (i32, i32);
16191 a64 __builtin_mips_multu (ui32, ui32);
16194 The following built-in functions map directly to a particular MIPS DSP REV 2
16195 instruction. Please refer to the architecture specification
16196 for details on what each instruction does.
16199 v4q7 __builtin_mips_absq_s_qb (v4q7);
16200 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
16201 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
16202 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
16203 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
16204 i32 __builtin_mips_append (i32, i32, imm0_31);
16205 i32 __builtin_mips_balign (i32, i32, imm0_3);
16206 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
16207 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
16208 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
16209 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
16210 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
16211 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
16212 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
16213 q31 __builtin_mips_mulq_rs_w (q31, q31);
16214 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
16215 q31 __builtin_mips_mulq_s_w (q31, q31);
16216 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
16217 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
16218 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
16219 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
16220 i32 __builtin_mips_prepend (i32, i32, imm0_31);
16221 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
16222 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
16223 v4i8 __builtin_mips_shra_qb (v4i8, i32);
16224 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
16225 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
16226 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
16227 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
16228 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
16229 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
16230 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
16231 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
16232 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
16233 q31 __builtin_mips_addqh_w (q31, q31);
16234 q31 __builtin_mips_addqh_r_w (q31, q31);
16235 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
16236 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
16237 q31 __builtin_mips_subqh_w (q31, q31);
16238 q31 __builtin_mips_subqh_r_w (q31, q31);
16239 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
16240 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
16241 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
16242 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
16243 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
16244 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
16248 @node MIPS Paired-Single Support
16249 @subsection MIPS Paired-Single Support
16251 The MIPS64 architecture includes a number of instructions that
16252 operate on pairs of single-precision floating-point values.
16253 Each pair is packed into a 64-bit floating-point register,
16254 with one element being designated the ``upper half'' and
16255 the other being designated the ``lower half''.
16257 GCC supports paired-single operations using both the generic
16258 vector extensions (@pxref{Vector Extensions}) and a collection of
16259 MIPS-specific built-in functions. Both kinds of support are
16260 enabled by the @option{-mpaired-single} command-line option.
16262 The vector type associated with paired-single values is usually
16263 called @code{v2sf}. It can be defined in C as follows:
16266 typedef float v2sf __attribute__ ((vector_size (8)));
16269 @code{v2sf} values are initialized in the same way as aggregates.
16273 v2sf a = @{1.5, 9.1@};
16276 b = (v2sf) @{e, f@};
16279 @emph{Note:} The CPU's endianness determines which value is stored in
16280 the upper half of a register and which value is stored in the lower half.
16281 On little-endian targets, the first value is the lower one and the second
16282 value is the upper one. The opposite order applies to big-endian targets.
16283 For example, the code above sets the lower half of @code{a} to
16284 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
16286 @node MIPS Loongson Built-in Functions
16287 @subsection MIPS Loongson Built-in Functions
16289 GCC provides intrinsics to access the SIMD instructions provided by the
16290 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
16291 available after inclusion of the @code{loongson.h} header file,
16292 operate on the following 64-bit vector types:
16295 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
16296 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
16297 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
16298 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
16299 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
16300 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
16303 The intrinsics provided are listed below; each is named after the
16304 machine instruction to which it corresponds, with suffixes added as
16305 appropriate to distinguish intrinsics that expand to the same machine
16306 instruction yet have different argument types. Refer to the architecture
16307 documentation for a description of the functionality of each
16311 int16x4_t packsswh (int32x2_t s, int32x2_t t);
16312 int8x8_t packsshb (int16x4_t s, int16x4_t t);
16313 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
16314 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
16315 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
16316 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
16317 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
16318 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
16319 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
16320 uint64_t paddd_u (uint64_t s, uint64_t t);
16321 int64_t paddd_s (int64_t s, int64_t t);
16322 int16x4_t paddsh (int16x4_t s, int16x4_t t);
16323 int8x8_t paddsb (int8x8_t s, int8x8_t t);
16324 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
16325 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
16326 uint64_t pandn_ud (uint64_t s, uint64_t t);
16327 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
16328 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
16329 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
16330 int64_t pandn_sd (int64_t s, int64_t t);
16331 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
16332 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
16333 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
16334 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
16335 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
16336 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
16337 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
16338 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
16339 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
16340 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
16341 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
16342 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
16343 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
16344 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
16345 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
16346 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
16347 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
16348 uint16x4_t pextrh_u (uint16x4_t s, int field);
16349 int16x4_t pextrh_s (int16x4_t s, int field);
16350 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
16351 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
16352 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
16353 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
16354 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
16355 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
16356 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
16357 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
16358 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
16359 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
16360 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
16361 int16x4_t pminsh (int16x4_t s, int16x4_t t);
16362 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
16363 uint8x8_t pmovmskb_u (uint8x8_t s);
16364 int8x8_t pmovmskb_s (int8x8_t s);
16365 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
16366 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
16367 int16x4_t pmullh (int16x4_t s, int16x4_t t);
16368 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
16369 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
16370 uint16x4_t biadd (uint8x8_t s);
16371 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
16372 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
16373 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
16374 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
16375 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
16376 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
16377 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
16378 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
16379 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
16380 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
16381 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
16382 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
16383 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
16384 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
16385 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
16386 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
16387 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
16388 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
16389 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
16390 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
16391 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
16392 uint64_t psubd_u (uint64_t s, uint64_t t);
16393 int64_t psubd_s (int64_t s, int64_t t);
16394 int16x4_t psubsh (int16x4_t s, int16x4_t t);
16395 int8x8_t psubsb (int8x8_t s, int8x8_t t);
16396 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
16397 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
16398 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
16399 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
16400 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
16401 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
16402 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
16403 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
16404 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
16405 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
16406 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
16407 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
16408 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
16409 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
16413 * Paired-Single Arithmetic::
16414 * Paired-Single Built-in Functions::
16415 * MIPS-3D Built-in Functions::
16418 @node Paired-Single Arithmetic
16419 @subsubsection Paired-Single Arithmetic
16421 The table below lists the @code{v2sf} operations for which hardware
16422 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
16423 values and @code{x} is an integral value.
16425 @multitable @columnfractions .50 .50
16426 @headitem C code @tab MIPS instruction
16427 @item @code{a + b} @tab @code{add.ps}
16428 @item @code{a - b} @tab @code{sub.ps}
16429 @item @code{-a} @tab @code{neg.ps}
16430 @item @code{a * b} @tab @code{mul.ps}
16431 @item @code{a * b + c} @tab @code{madd.ps}
16432 @item @code{a * b - c} @tab @code{msub.ps}
16433 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
16434 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
16435 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
16438 Note that the multiply-accumulate instructions can be disabled
16439 using the command-line option @code{-mno-fused-madd}.
16441 @node Paired-Single Built-in Functions
16442 @subsubsection Paired-Single Built-in Functions
16444 The following paired-single functions map directly to a particular
16445 MIPS instruction. Please refer to the architecture specification
16446 for details on what each instruction does.
16449 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
16450 Pair lower lower (@code{pll.ps}).
16452 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
16453 Pair upper lower (@code{pul.ps}).
16455 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
16456 Pair lower upper (@code{plu.ps}).
16458 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
16459 Pair upper upper (@code{puu.ps}).
16461 @item v2sf __builtin_mips_cvt_ps_s (float, float)
16462 Convert pair to paired single (@code{cvt.ps.s}).
16464 @item float __builtin_mips_cvt_s_pl (v2sf)
16465 Convert pair lower to single (@code{cvt.s.pl}).
16467 @item float __builtin_mips_cvt_s_pu (v2sf)
16468 Convert pair upper to single (@code{cvt.s.pu}).
16470 @item v2sf __builtin_mips_abs_ps (v2sf)
16471 Absolute value (@code{abs.ps}).
16473 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
16474 Align variable (@code{alnv.ps}).
16476 @emph{Note:} The value of the third parameter must be 0 or 4
16477 modulo 8, otherwise the result is unpredictable. Please read the
16478 instruction description for details.
16481 The following multi-instruction functions are also available.
16482 In each case, @var{cond} can be any of the 16 floating-point conditions:
16483 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16484 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
16485 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16488 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16489 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16490 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
16491 @code{movt.ps}/@code{movf.ps}).
16493 The @code{movt} functions return the value @var{x} computed by:
16496 c.@var{cond}.ps @var{cc},@var{a},@var{b}
16497 mov.ps @var{x},@var{c}
16498 movt.ps @var{x},@var{d},@var{cc}
16501 The @code{movf} functions are similar but use @code{movf.ps} instead
16504 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16505 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16506 Comparison of two paired-single values (@code{c.@var{cond}.ps},
16507 @code{bc1t}/@code{bc1f}).
16509 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16510 and return either the upper or lower half of the result. For example:
16514 if (__builtin_mips_upper_c_eq_ps (a, b))
16515 upper_halves_are_equal ();
16517 upper_halves_are_unequal ();
16519 if (__builtin_mips_lower_c_eq_ps (a, b))
16520 lower_halves_are_equal ();
16522 lower_halves_are_unequal ();
16526 @node MIPS-3D Built-in Functions
16527 @subsubsection MIPS-3D Built-in Functions
16529 The MIPS-3D Application-Specific Extension (ASE) includes additional
16530 paired-single instructions that are designed to improve the performance
16531 of 3D graphics operations. Support for these instructions is controlled
16532 by the @option{-mips3d} command-line option.
16534 The functions listed below map directly to a particular MIPS-3D
16535 instruction. Please refer to the architecture specification for
16536 more details on what each instruction does.
16539 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
16540 Reduction add (@code{addr.ps}).
16542 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
16543 Reduction multiply (@code{mulr.ps}).
16545 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
16546 Convert paired single to paired word (@code{cvt.pw.ps}).
16548 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
16549 Convert paired word to paired single (@code{cvt.ps.pw}).
16551 @item float __builtin_mips_recip1_s (float)
16552 @itemx double __builtin_mips_recip1_d (double)
16553 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
16554 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
16556 @item float __builtin_mips_recip2_s (float, float)
16557 @itemx double __builtin_mips_recip2_d (double, double)
16558 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
16559 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
16561 @item float __builtin_mips_rsqrt1_s (float)
16562 @itemx double __builtin_mips_rsqrt1_d (double)
16563 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
16564 Reduced-precision reciprocal square root (sequence step 1)
16565 (@code{rsqrt1.@var{fmt}}).
16567 @item float __builtin_mips_rsqrt2_s (float, float)
16568 @itemx double __builtin_mips_rsqrt2_d (double, double)
16569 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
16570 Reduced-precision reciprocal square root (sequence step 2)
16571 (@code{rsqrt2.@var{fmt}}).
16574 The following multi-instruction functions are also available.
16575 In each case, @var{cond} can be any of the 16 floating-point conditions:
16576 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16577 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
16578 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16581 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
16582 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
16583 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
16584 @code{bc1t}/@code{bc1f}).
16586 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
16587 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
16592 if (__builtin_mips_cabs_eq_s (a, b))
16598 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16599 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16600 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
16601 @code{bc1t}/@code{bc1f}).
16603 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
16604 and return either the upper or lower half of the result. For example:
16608 if (__builtin_mips_upper_cabs_eq_ps (a, b))
16609 upper_halves_are_equal ();
16611 upper_halves_are_unequal ();
16613 if (__builtin_mips_lower_cabs_eq_ps (a, b))
16614 lower_halves_are_equal ();
16616 lower_halves_are_unequal ();
16619 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16620 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16621 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
16622 @code{movt.ps}/@code{movf.ps}).
16624 The @code{movt} functions return the value @var{x} computed by:
16627 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
16628 mov.ps @var{x},@var{c}
16629 movt.ps @var{x},@var{d},@var{cc}
16632 The @code{movf} functions are similar but use @code{movf.ps} instead
16635 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16636 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16637 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16638 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16639 Comparison of two paired-single values
16640 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16641 @code{bc1any2t}/@code{bc1any2f}).
16643 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16644 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
16645 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
16650 if (__builtin_mips_any_c_eq_ps (a, b))
16655 if (__builtin_mips_all_c_eq_ps (a, b))
16661 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16662 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16663 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16664 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16665 Comparison of four paired-single values
16666 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16667 @code{bc1any4t}/@code{bc1any4f}).
16669 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
16670 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
16671 The @code{any} forms return @code{true} if any of the four results are @code{true}
16672 and the @code{all} forms return @code{true} if all four results are @code{true}.
16677 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
16682 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
16689 @node MIPS SIMD Architecture (MSA) Support
16690 @subsection MIPS SIMD Architecture (MSA) Support
16693 * MIPS SIMD Architecture Built-in Functions::
16696 GCC provides intrinsics to access the SIMD instructions provided by the
16697 MSA MIPS SIMD Architecture. The interface is made available by including
16698 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
16699 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
16702 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
16703 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
16704 data elements. The following vectors typedefs are included in @code{msa.h}:
16706 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
16707 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
16708 @item @code{v8i16}, a vector of eight signed 16-bit integers;
16709 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
16710 @item @code{v4i32}, a vector of four signed 32-bit integers;
16711 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
16712 @item @code{v2i64}, a vector of two signed 64-bit integers;
16713 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
16714 @item @code{v4f32}, a vector of four 32-bit floats;
16715 @item @code{v2f64}, a vector of two 64-bit doubles.
16718 Instructions and corresponding built-ins may have additional restrictions and/or
16719 input/output values manipulated:
16721 @item @code{imm0_1}, an integer literal in range 0 to 1;
16722 @item @code{imm0_3}, an integer literal in range 0 to 3;
16723 @item @code{imm0_7}, an integer literal in range 0 to 7;
16724 @item @code{imm0_15}, an integer literal in range 0 to 15;
16725 @item @code{imm0_31}, an integer literal in range 0 to 31;
16726 @item @code{imm0_63}, an integer literal in range 0 to 63;
16727 @item @code{imm0_255}, an integer literal in range 0 to 255;
16728 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
16729 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
16730 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
16731 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
16732 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
16733 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
16734 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
16735 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
16736 @item @code{imm1_4}, an integer literal in range 1 to 4;
16737 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
16743 #if __LONG_MAX__ == __LONG_LONG_MAX__
16746 typedef long long i64;
16749 typedef unsigned int u32;
16750 #if __LONG_MAX__ == __LONG_LONG_MAX__
16751 typedef unsigned long u64;
16753 typedef unsigned long long u64;
16756 typedef double f64;
16761 @node MIPS SIMD Architecture Built-in Functions
16762 @subsubsection MIPS SIMD Architecture Built-in Functions
16764 The intrinsics provided are listed below; each is named after the
16765 machine instruction.
16768 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
16769 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
16770 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
16771 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
16773 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
16774 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
16775 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
16776 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
16778 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
16779 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
16780 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
16781 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
16783 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
16784 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
16785 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
16786 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
16788 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
16789 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
16790 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
16791 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
16793 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
16794 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
16795 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
16796 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
16798 v16u8 __builtin_msa_and_v (v16u8, v16u8);
16800 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
16802 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
16803 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
16804 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
16805 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
16807 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
16808 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
16809 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
16810 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
16812 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
16813 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
16814 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
16815 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
16817 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
16818 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
16819 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
16820 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
16822 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
16823 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
16824 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
16825 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
16827 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
16828 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
16829 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
16830 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
16832 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
16833 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
16834 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
16835 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
16837 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
16838 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
16839 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
16840 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
16842 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
16843 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
16844 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
16845 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
16847 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
16848 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
16849 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
16850 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
16852 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
16853 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
16854 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
16855 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
16857 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
16858 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
16859 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
16860 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
16862 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
16864 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
16866 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
16868 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
16870 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
16871 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
16872 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
16873 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
16875 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
16876 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
16877 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
16878 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
16880 i32 __builtin_msa_bnz_b (v16u8);
16881 i32 __builtin_msa_bnz_h (v8u16);
16882 i32 __builtin_msa_bnz_w (v4u32);
16883 i32 __builtin_msa_bnz_d (v2u64);
16885 i32 __builtin_msa_bnz_v (v16u8);
16887 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
16889 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
16891 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
16892 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
16893 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
16894 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
16896 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
16897 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
16898 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
16899 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
16901 i32 __builtin_msa_bz_b (v16u8);
16902 i32 __builtin_msa_bz_h (v8u16);
16903 i32 __builtin_msa_bz_w (v4u32);
16904 i32 __builtin_msa_bz_d (v2u64);
16906 i32 __builtin_msa_bz_v (v16u8);
16908 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
16909 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
16910 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
16911 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
16913 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
16914 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
16915 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
16916 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
16918 i32 __builtin_msa_cfcmsa (imm0_31);
16920 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
16921 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
16922 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
16923 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
16925 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
16926 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
16927 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
16928 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
16930 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
16931 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
16932 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
16933 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
16935 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
16936 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
16937 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
16938 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
16940 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
16941 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
16942 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
16943 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
16945 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
16946 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
16947 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
16948 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
16950 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
16951 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
16952 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
16953 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
16955 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
16956 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
16957 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
16958 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
16960 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
16961 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
16962 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
16963 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
16965 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
16966 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
16967 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
16968 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
16970 void __builtin_msa_ctcmsa (imm0_31, i32);
16972 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
16973 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
16974 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
16975 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
16977 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
16978 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
16979 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
16980 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
16982 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
16983 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
16984 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
16986 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
16987 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
16988 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
16990 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
16991 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
16992 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
16994 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
16995 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
16996 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
16998 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
16999 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
17000 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
17002 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
17003 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
17004 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
17006 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
17007 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
17009 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
17010 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
17012 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
17013 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
17015 v4i32 __builtin_msa_fclass_w (v4f32);
17016 v2i64 __builtin_msa_fclass_d (v2f64);
17018 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
17019 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
17021 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
17022 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
17024 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
17025 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
17027 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
17028 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
17030 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
17031 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
17033 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
17034 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
17036 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
17037 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
17039 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
17040 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
17042 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
17043 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
17045 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
17046 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
17048 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
17049 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
17051 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
17052 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
17054 v4f32 __builtin_msa_fexupl_w (v8i16);
17055 v2f64 __builtin_msa_fexupl_d (v4f32);
17057 v4f32 __builtin_msa_fexupr_w (v8i16);
17058 v2f64 __builtin_msa_fexupr_d (v4f32);
17060 v4f32 __builtin_msa_ffint_s_w (v4i32);
17061 v2f64 __builtin_msa_ffint_s_d (v2i64);
17063 v4f32 __builtin_msa_ffint_u_w (v4u32);
17064 v2f64 __builtin_msa_ffint_u_d (v2u64);
17066 v4f32 __builtin_msa_ffql_w (v8i16);
17067 v2f64 __builtin_msa_ffql_d (v4i32);
17069 v4f32 __builtin_msa_ffqr_w (v8i16);
17070 v2f64 __builtin_msa_ffqr_d (v4i32);
17072 v16i8 __builtin_msa_fill_b (i32);
17073 v8i16 __builtin_msa_fill_h (i32);
17074 v4i32 __builtin_msa_fill_w (i32);
17075 v2i64 __builtin_msa_fill_d (i64);
17077 v4f32 __builtin_msa_flog2_w (v4f32);
17078 v2f64 __builtin_msa_flog2_d (v2f64);
17080 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
17081 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
17083 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
17084 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
17086 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
17087 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
17089 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
17090 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
17092 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
17093 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
17095 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
17096 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
17098 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
17099 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
17101 v4f32 __builtin_msa_frint_w (v4f32);
17102 v2f64 __builtin_msa_frint_d (v2f64);
17104 v4f32 __builtin_msa_frcp_w (v4f32);
17105 v2f64 __builtin_msa_frcp_d (v2f64);
17107 v4f32 __builtin_msa_frsqrt_w (v4f32);
17108 v2f64 __builtin_msa_frsqrt_d (v2f64);
17110 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
17111 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
17113 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
17114 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
17116 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
17117 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
17119 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
17120 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
17122 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
17123 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
17125 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
17126 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
17128 v4f32 __builtin_msa_fsqrt_w (v4f32);
17129 v2f64 __builtin_msa_fsqrt_d (v2f64);
17131 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
17132 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
17134 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
17135 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
17137 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
17138 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
17140 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
17141 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
17143 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
17144 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
17146 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
17147 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
17149 v4i32 __builtin_msa_ftint_s_w (v4f32);
17150 v2i64 __builtin_msa_ftint_s_d (v2f64);
17152 v4u32 __builtin_msa_ftint_u_w (v4f32);
17153 v2u64 __builtin_msa_ftint_u_d (v2f64);
17155 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
17156 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
17158 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
17159 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
17161 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
17162 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
17164 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
17165 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
17166 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
17168 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
17169 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
17170 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
17172 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
17173 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
17174 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
17176 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
17177 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
17178 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
17180 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
17181 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
17182 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
17183 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
17185 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
17186 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
17187 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
17188 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
17190 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
17191 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
17192 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
17193 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
17195 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
17196 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
17197 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
17198 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
17200 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
17201 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
17202 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
17203 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
17205 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
17206 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
17207 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
17208 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
17210 v16i8 __builtin_msa_ld_b (const void *, imm_n512_511);
17211 v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022);
17212 v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044);
17213 v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088);
17215 v16i8 __builtin_msa_ldi_b (imm_n512_511);
17216 v8i16 __builtin_msa_ldi_h (imm_n512_511);
17217 v4i32 __builtin_msa_ldi_w (imm_n512_511);
17218 v2i64 __builtin_msa_ldi_d (imm_n512_511);
17220 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
17221 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
17223 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
17224 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
17226 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
17227 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
17228 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
17229 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
17231 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
17232 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
17233 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
17234 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
17236 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
17237 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
17238 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
17239 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
17241 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
17242 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
17243 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
17244 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
17246 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
17247 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
17248 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
17249 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
17251 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
17252 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
17253 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
17254 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
17256 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
17257 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
17258 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
17259 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
17261 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
17262 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
17263 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
17264 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
17266 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
17267 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
17268 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
17269 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
17271 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
17272 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
17273 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
17274 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
17276 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
17277 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
17278 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
17279 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
17281 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
17282 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
17283 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
17284 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
17286 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
17287 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
17288 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
17289 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
17291 v16i8 __builtin_msa_move_v (v16i8);
17293 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
17294 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
17296 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
17297 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
17299 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
17300 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
17301 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
17302 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
17304 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
17305 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
17307 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
17308 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
17310 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
17311 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
17312 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
17313 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
17315 v16i8 __builtin_msa_nloc_b (v16i8);
17316 v8i16 __builtin_msa_nloc_h (v8i16);
17317 v4i32 __builtin_msa_nloc_w (v4i32);
17318 v2i64 __builtin_msa_nloc_d (v2i64);
17320 v16i8 __builtin_msa_nlzc_b (v16i8);
17321 v8i16 __builtin_msa_nlzc_h (v8i16);
17322 v4i32 __builtin_msa_nlzc_w (v4i32);
17323 v2i64 __builtin_msa_nlzc_d (v2i64);
17325 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
17327 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
17329 v16u8 __builtin_msa_or_v (v16u8, v16u8);
17331 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
17333 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
17334 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
17335 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
17336 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
17338 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
17339 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
17340 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
17341 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
17343 v16i8 __builtin_msa_pcnt_b (v16i8);
17344 v8i16 __builtin_msa_pcnt_h (v8i16);
17345 v4i32 __builtin_msa_pcnt_w (v4i32);
17346 v2i64 __builtin_msa_pcnt_d (v2i64);
17348 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
17349 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
17350 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
17351 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
17353 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
17354 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
17355 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
17356 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
17358 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
17359 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
17360 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
17362 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
17363 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
17364 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
17365 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
17367 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
17368 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
17369 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
17370 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
17372 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
17373 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
17374 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
17375 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
17377 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
17378 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
17379 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
17380 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
17382 v16i8 __builtin_msa_splat_b (v16i8, i32);
17383 v8i16 __builtin_msa_splat_h (v8i16, i32);
17384 v4i32 __builtin_msa_splat_w (v4i32, i32);
17385 v2i64 __builtin_msa_splat_d (v2i64, i32);
17387 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
17388 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
17389 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
17390 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
17392 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
17393 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
17394 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
17395 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
17397 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
17398 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
17399 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
17400 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
17402 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
17403 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
17404 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
17405 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
17407 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
17408 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
17409 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
17410 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
17412 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
17413 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
17414 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
17415 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
17417 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
17418 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
17419 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
17420 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
17422 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
17423 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
17424 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
17425 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
17427 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
17428 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
17429 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
17430 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
17432 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
17433 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
17434 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
17435 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
17437 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
17438 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
17439 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
17440 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
17442 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
17443 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
17444 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
17445 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
17447 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
17448 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
17449 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
17450 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
17452 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
17453 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
17454 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
17455 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
17457 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
17458 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
17459 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
17460 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
17462 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
17463 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
17464 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
17465 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
17467 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
17468 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
17469 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
17470 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
17472 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
17474 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
17477 @node Other MIPS Built-in Functions
17478 @subsection Other MIPS Built-in Functions
17480 GCC provides other MIPS-specific built-in functions:
17483 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
17484 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
17485 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
17486 when this function is available.
17488 @item unsigned int __builtin_mips_get_fcsr (void)
17489 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
17490 Get and set the contents of the floating-point control and status register
17491 (FPU control register 31). These functions are only available in hard-float
17492 code but can be called in both MIPS16 and non-MIPS16 contexts.
17494 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
17495 register except the condition codes, which GCC assumes are preserved.
17498 @node MSP430 Built-in Functions
17499 @subsection MSP430 Built-in Functions
17501 GCC provides a couple of special builtin functions to aid in the
17502 writing of interrupt handlers in C.
17505 @item __bic_SR_register_on_exit (int @var{mask})
17506 This clears the indicated bits in the saved copy of the status register
17507 currently residing on the stack. This only works inside interrupt
17508 handlers and the changes to the status register will only take affect
17509 once the handler returns.
17511 @item __bis_SR_register_on_exit (int @var{mask})
17512 This sets the indicated bits in the saved copy of the status register
17513 currently residing on the stack. This only works inside interrupt
17514 handlers and the changes to the status register will only take affect
17515 once the handler returns.
17517 @item __delay_cycles (long long @var{cycles})
17518 This inserts an instruction sequence that takes exactly @var{cycles}
17519 cycles (between 0 and about 17E9) to complete. The inserted sequence
17520 may use jumps, loops, or no-ops, and does not interfere with any other
17521 instructions. Note that @var{cycles} must be a compile-time constant
17522 integer - that is, you must pass a number, not a variable that may be
17523 optimized to a constant later. The number of cycles delayed by this
17527 @node NDS32 Built-in Functions
17528 @subsection NDS32 Built-in Functions
17530 These built-in functions are available for the NDS32 target:
17532 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
17533 Insert an ISYNC instruction into the instruction stream where
17534 @var{addr} is an instruction address for serialization.
17537 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
17538 Insert an ISB instruction into the instruction stream.
17541 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
17542 Return the content of a system register which is mapped by @var{sr}.
17545 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
17546 Return the content of a user space register which is mapped by @var{usr}.
17549 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
17550 Move the @var{value} to a system register which is mapped by @var{sr}.
17553 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
17554 Move the @var{value} to a user space register which is mapped by @var{usr}.
17557 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
17558 Enable global interrupt.
17561 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
17562 Disable global interrupt.
17565 @node picoChip Built-in Functions
17566 @subsection picoChip Built-in Functions
17568 GCC provides an interface to selected machine instructions from the
17569 picoChip instruction set.
17572 @item int __builtin_sbc (int @var{value})
17573 Sign bit count. Return the number of consecutive bits in @var{value}
17574 that have the same value as the sign bit. The result is the number of
17575 leading sign bits minus one, giving the number of redundant sign bits in
17578 @item int __builtin_byteswap (int @var{value})
17579 Byte swap. Return the result of swapping the upper and lower bytes of
17582 @item int __builtin_brev (int @var{value})
17583 Bit reversal. Return the result of reversing the bits in
17584 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
17587 @item int __builtin_adds (int @var{x}, int @var{y})
17588 Saturating addition. Return the result of adding @var{x} and @var{y},
17589 storing the value 32767 if the result overflows.
17591 @item int __builtin_subs (int @var{x}, int @var{y})
17592 Saturating subtraction. Return the result of subtracting @var{y} from
17593 @var{x}, storing the value @minus{}32768 if the result overflows.
17595 @item void __builtin_halt (void)
17596 Halt. The processor stops execution. This built-in is useful for
17597 implementing assertions.
17601 @node Basic PowerPC Built-in Functions
17602 @subsection Basic PowerPC Built-in Functions
17605 * Basic PowerPC Built-in Functions Available on all Configurations::
17606 * Basic PowerPC Built-in Functions Available on ISA 2.05::
17607 * Basic PowerPC Built-in Functions Available on ISA 2.06::
17608 * Basic PowerPC Built-in Functions Available on ISA 2.07::
17609 * Basic PowerPC Built-in Functions Available on ISA 3.0::
17610 * Basic PowerPC Built-in Functions Available on ISA 3.1::
17613 This section describes PowerPC built-in functions that do not require
17614 the inclusion of any special header files to declare prototypes or
17615 provide macro definitions. The sections that follow describe
17616 additional PowerPC built-in functions.
17618 @node Basic PowerPC Built-in Functions Available on all Configurations
17619 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
17621 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
17622 This function is a @code{nop} on the PowerPC platform and is included solely
17623 to maintain API compatibility with the x86 builtins.
17626 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
17627 This function returns a value of @code{1} if the run-time CPU is of type
17628 @var{cpuname} and returns @code{0} otherwise
17630 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
17631 which exports the hardware capability bits. GCC defines the macro
17632 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
17633 built-in function is fully supported.
17635 If GCC was configured to use a GLIBC before 2.23, the built-in
17636 function @code{__builtin_cpu_is} always returns a 0 and the compiler
17639 The following CPU names can be detected:
17643 IBM POWER10 Server CPU.
17645 IBM POWER9 Server CPU.
17647 IBM POWER8 Server CPU.
17649 IBM POWER7 Server CPU.
17651 IBM POWER6 Server CPU (RAW mode).
17653 IBM POWER6 Server CPU (Architected mode).
17655 IBM POWER5+ Server CPU.
17657 IBM POWER5 Server CPU.
17659 IBM 970 Server CPU (ie, Apple G5).
17661 IBM POWER4 Server CPU.
17663 IBM A2 64-bit Embedded CPU
17665 IBM PowerPC 476FP 32-bit Embedded CPU.
17667 IBM PowerPC 464 32-bit Embedded CPU.
17669 PowerPC 440 32-bit Embedded CPU.
17671 PowerPC 405 32-bit Embedded CPU.
17673 IBM PowerPC Cell Broadband Engine Architecture CPU.
17676 Here is an example:
17678 #ifdef __BUILTIN_CPU_SUPPORTS__
17679 if (__builtin_cpu_is ("power8"))
17681 do_power8 (); // POWER8 specific implementation.
17686 do_generic (); // Generic implementation.
17691 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
17692 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
17693 feature @var{feature} and returns @code{0} otherwise.
17695 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
17696 newer which exports the hardware capability bits. GCC defines the
17697 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
17698 @code{__builtin_cpu_supports} built-in function is fully supported.
17700 If GCC was configured to use a GLIBC before 2.23, the built-in
17701 function @code{__builtin_cpu_supports} always returns a 0 and the
17702 compiler issues a warning.
17704 The following features can be
17709 4xx CPU has a Multiply Accumulator.
17711 CPU has a SIMD/Vector Unit.
17713 CPU supports ISA 2.05 (eg, POWER6)
17715 CPU supports ISA 2.06 (eg, POWER7)
17717 CPU supports ISA 2.07 (eg, POWER8)
17719 CPU supports ISA 3.0 (eg, POWER9)
17721 CPU supports ISA 3.1 (eg, POWER10)
17723 CPU supports the set of compatible performance monitoring events.
17725 CPU supports the Embedded ISA category.
17727 CPU has a CELL broadband engine.
17729 CPU supports the @code{darn} (deliver a random number) instruction.
17731 CPU has a decimal floating point unit.
17733 CPU supports the data stream control register.
17735 CPU supports event base branching.
17737 CPU has a SPE double precision floating point unit.
17739 CPU has a SPE single precision floating point unit.
17741 CPU has a floating point unit.
17743 CPU has hardware transaction memory instructions.
17745 Kernel aborts hardware transactions when a syscall is made.
17746 @item htm-no-suspend
17747 CPU supports hardware transaction memory but does not support the
17748 @code{tsuspend.} instruction.
17750 CPU supports icache snooping capabilities.
17752 CPU supports 128-bit IEEE binary floating point instructions.
17754 CPU supports the integer select instruction.
17756 CPU supports the matrix-multiply assist instructions.
17758 CPU has a memory management unit.
17760 CPU does not have a timebase (eg, 601 and 403gx).
17762 CPU supports the PA Semi 6T CORE ISA.
17764 CPU supports ISA 2.00 (eg, POWER4)
17766 CPU supports ISA 2.02 (eg, POWER5)
17768 CPU supports ISA 2.03 (eg, POWER5+)
17770 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
17772 CPU supports 32-bit mode execution.
17774 CPU supports the old POWER ISA (eg, 601)
17776 CPU supports 64-bit mode execution.
17778 CPU supports a little-endian mode that uses address swizzling.
17780 Kernel supports system call vectored.
17782 CPU support simultaneous multi-threading.
17784 CPU has a signal processing extension unit.
17786 CPU supports the target address register.
17788 CPU supports true little-endian mode.
17790 CPU has unified I/D cache.
17792 CPU supports the vector cryptography instructions.
17794 CPU supports the vector-scalar extension.
17797 Here is an example:
17799 #ifdef __BUILTIN_CPU_SUPPORTS__
17800 if (__builtin_cpu_supports ("fpu"))
17802 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
17807 dst = __fadd (src1, src2); // Software FP addition function.
17812 The following built-in functions are also available on all PowerPC
17815 uint64_t __builtin_ppc_get_timebase ();
17816 unsigned long __builtin_ppc_mftb ();
17817 double __builtin_unpack_ibm128 (__ibm128, int);
17818 __ibm128 __builtin_pack_ibm128 (double, double);
17819 double __builtin_mffs (void);
17820 void __builtin_mtfsf (const int, double);
17821 void __builtin_mtfsb0 (const int);
17822 void __builtin_mtfsb1 (const int);
17823 void __builtin_set_fpscr_rn (int);
17826 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
17827 functions generate instructions to read the Time Base Register. The
17828 @code{__builtin_ppc_get_timebase} function may generate multiple
17829 instructions and always returns the 64 bits of the Time Base Register.
17830 The @code{__builtin_ppc_mftb} function always generates one instruction and
17831 returns the Time Base Register value as an unsigned long, throwing away
17832 the most significant word on 32-bit environments. The @code{__builtin_mffs}
17833 return the value of the FPSCR register. Note, ISA 3.0 supports the
17834 @code{__builtin_mffsl()} which permits software to read the control and
17835 non-sticky status bits in the FSPCR without the higher latency associated with
17836 accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant
17837 8-bit integer field mask and a double precision floating point argument
17838 and generates the @code{mtfsf} (extended mnemonic) instruction to write new
17839 values to selected fields of the FPSCR. The
17840 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
17841 as an argument. The valid bit range is between 0 and 31. The builtins map to
17842 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
17843 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
17844 changing the specified bit to a zero or one respectively. The
17845 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
17846 point rounding mode bits. The argument is a 2-bit value. The argument can
17847 either be a @code{const int} or stored in a variable. The builtin uses
17849 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
17850 the current rounding mode bits out and OR's in the new value.
17852 @node Basic PowerPC Built-in Functions Available on ISA 2.05
17853 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
17855 The basic built-in functions described in this section are
17856 available on the PowerPC family of processors starting with ISA 2.05
17857 or later. Unless specific options are explicitly disabled on the
17858 command line, specifying option @option{-mcpu=power6} has the effect of
17859 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
17860 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
17861 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
17862 @option{-mrecip-precision} options. Specify the
17863 @option{-maltivec} option explicitly in
17864 combination with the above options if desired.
17866 The following functions require option @option{-mcmpb}.
17868 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
17869 unsigned int __builtin_cmpb (unsigned int, unsigned int);
17872 The @code{__builtin_cmpb} function
17873 performs a byte-wise compare on the contents of its two arguments,
17874 returning the result of the byte-wise comparison as the returned
17875 value. For each byte comparison, the corresponding byte of the return
17876 value holds 0xff if the input bytes are equal and 0 if the input bytes
17877 are not equal. If either of the arguments to this built-in function
17878 is wider than 32 bits, the function call expands into the form that
17879 expects @code{unsigned long long int} arguments
17880 which is only available on 64-bit targets.
17882 The following built-in functions are available
17883 when hardware decimal floating point
17884 (@option{-mhard-dfp}) is available:
17886 void __builtin_set_fpscr_drn(int);
17887 _Decimal64 __builtin_ddedpd (int, _Decimal64);
17888 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
17889 _Decimal64 __builtin_denbcd (int, _Decimal64);
17890 _Decimal128 __builtin_denbcdq (int, _Decimal128);
17891 _Decimal64 __builtin_diex (long long, _Decimal64);
17892 _Decimal128 _builtin_diexq (long long, _Decimal128);
17893 _Decimal64 __builtin_dscli (_Decimal64, int);
17894 _Decimal128 __builtin_dscliq (_Decimal128, int);
17895 _Decimal64 __builtin_dscri (_Decimal64, int);
17896 _Decimal128 __builtin_dscriq (_Decimal128, int);
17897 long long __builtin_dxex (_Decimal64);
17898 long long __builtin_dxexq (_Decimal128);
17899 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
17900 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
17902 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
17903 floating point rounding mode bits. The argument is a 3-bit value. The
17904 argument can either be a @code{const int} or the value can be stored in
17906 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
17907 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
17908 mode bits out and OR's in the new value.
17912 The following functions require @option{-mhard-float},
17913 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
17916 double __builtin_recipdiv (double, double);
17917 float __builtin_recipdivf (float, float);
17918 double __builtin_rsqrt (double);
17919 float __builtin_rsqrtf (float);
17922 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
17923 @code{__builtin_rsqrtf} functions generate multiple instructions to
17924 implement the reciprocal sqrt functionality using reciprocal sqrt
17925 estimate instructions.
17927 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
17928 functions generate multiple instructions to implement division using
17929 the reciprocal estimate instructions.
17931 The following functions require @option{-mhard-float} and
17932 @option{-mmultiple} options.
17934 The @code{__builtin_unpack_longdouble} function takes a
17935 @code{long double} argument and a compile time constant of 0 or 1. If
17936 the constant is 0, the first @code{double} within the
17937 @code{long double} is returned, otherwise the second @code{double}
17938 is returned. The @code{__builtin_unpack_longdouble} function is only
17939 available if @code{long double} uses the IBM extended double
17942 The @code{__builtin_pack_longdouble} function takes two @code{double}
17943 arguments and returns a @code{long double} value that combines the two
17944 arguments. The @code{__builtin_pack_longdouble} function is only
17945 available if @code{long double} uses the IBM extended double
17948 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
17949 argument and a compile time constant of 0 or 1. If the constant is 0,
17950 the first @code{double} within the @code{__ibm128} is returned,
17951 otherwise the second @code{double} is returned.
17953 The @code{__builtin_pack_ibm128} function takes two @code{double}
17954 arguments and returns a @code{__ibm128} value that combines the two
17957 Additional built-in functions are available for the 64-bit PowerPC
17958 family of processors, for efficient use of 128-bit floating point
17959 (@code{__float128}) values.
17961 @node Basic PowerPC Built-in Functions Available on ISA 2.06
17962 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
17964 The basic built-in functions described in this section are
17965 available on the PowerPC family of processors starting with ISA 2.05
17966 or later. Unless specific options are explicitly disabled on the
17967 command line, specifying option @option{-mcpu=power7} has the effect of
17968 enabling all the same options as for @option{-mcpu=power6} in
17969 addition to the @option{-maltivec}, @option{-mpopcntd}, and
17970 @option{-mvsx} options.
17972 The following basic built-in functions require @option{-mpopcntd}:
17974 unsigned int __builtin_addg6s (unsigned int, unsigned int);
17975 long long __builtin_bpermd (long long, long long);
17976 unsigned int __builtin_cbcdtd (unsigned int);
17977 unsigned int __builtin_cdtbcd (unsigned int);
17978 long long __builtin_divde (long long, long long);
17979 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
17980 int __builtin_divwe (int, int);
17981 unsigned int __builtin_divweu (unsigned int, unsigned int);
17982 vector __int128 __builtin_pack_vector_int128 (long long, long long);
17983 void __builtin_rs6000_speculation_barrier (void);
17984 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
17987 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
17988 require a 64-bit environment.
17990 The following basic built-in functions, which are also supported on
17991 x86 targets, require @option{-mfloat128}.
17993 __float128 __builtin_fabsq (__float128);
17994 __float128 __builtin_copysignq (__float128, __float128);
17995 __float128 __builtin_infq (void);
17996 __float128 __builtin_huge_valq (void);
17997 __float128 __builtin_nanq (void);
17998 __float128 __builtin_nansq (void);
18000 __float128 __builtin_sqrtf128 (__float128);
18001 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
18004 @node Basic PowerPC Built-in Functions Available on ISA 2.07
18005 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
18007 The basic built-in functions described in this section are
18008 available on the PowerPC family of processors starting with ISA 2.07
18009 or later. Unless specific options are explicitly disabled on the
18010 command line, specifying option @option{-mcpu=power8} has the effect of
18011 enabling all the same options as for @option{-mcpu=power7} in
18012 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
18013 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
18014 @option{-mquad-memory-atomic} options.
18016 This section intentionally empty.
18018 @node Basic PowerPC Built-in Functions Available on ISA 3.0
18019 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
18021 The basic built-in functions described in this section are
18022 available on the PowerPC family of processors starting with ISA 3.0
18023 or later. Unless specific options are explicitly disabled on the
18024 command line, specifying option @option{-mcpu=power9} has the effect of
18025 enabling all the same options as for @option{-mcpu=power8} in
18026 addition to the @option{-misel} option.
18028 The following built-in functions are available on Linux 64-bit systems
18029 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
18032 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
18033 Perform a 128-bit IEEE floating point add using round to odd as the
18035 @findex __builtin_addf128_round_to_odd
18037 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
18038 Perform a 128-bit IEEE floating point subtract using round to odd as
18040 @findex __builtin_subf128_round_to_odd
18042 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
18043 Perform a 128-bit IEEE floating point multiply using round to odd as
18045 @findex __builtin_mulf128_round_to_odd
18047 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
18048 Perform a 128-bit IEEE floating point divide using round to odd as
18050 @findex __builtin_divf128_round_to_odd
18052 @item __float128 __builtin_sqrtf128_round_to_odd (__float128)
18053 Perform a 128-bit IEEE floating point square root using round to odd
18054 as the rounding mode.
18055 @findex __builtin_sqrtf128_round_to_odd
18057 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
18058 Perform a 128-bit IEEE floating point fused multiply and add operation
18059 using round to odd as the rounding mode.
18060 @findex __builtin_fmaf128_round_to_odd
18062 @item double __builtin_truncf128_round_to_odd (__float128)
18063 Convert a 128-bit IEEE floating point value to @code{double} using
18064 round to odd as the rounding mode.
18065 @findex __builtin_truncf128_round_to_odd
18068 The following additional built-in functions are also available for the
18069 PowerPC family of processors, starting with ISA 3.0 or later:
18071 long long __builtin_darn (void);
18072 long long __builtin_darn_raw (void);
18073 int __builtin_darn_32 (void);
18076 The @code{__builtin_darn} and @code{__builtin_darn_raw}
18077 functions require a
18078 64-bit environment supporting ISA 3.0 or later.
18079 The @code{__builtin_darn} function provides a 64-bit conditioned
18080 random number. The @code{__builtin_darn_raw} function provides a
18081 64-bit raw random number. The @code{__builtin_darn_32} function
18082 provides a 32-bit conditioned random number.
18084 The following additional built-in functions are also available for the
18085 PowerPC family of processors, starting with ISA 3.0 or later:
18088 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
18089 int __builtin_byte_in_range (unsigned char u, unsigned int range);
18090 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
18092 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
18093 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
18094 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
18095 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
18097 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
18098 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
18099 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
18100 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
18102 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
18103 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
18104 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
18105 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
18107 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
18108 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
18109 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
18110 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
18112 double __builtin_mffsl(void);
18115 The @code{__builtin_byte_in_set} function requires a
18116 64-bit environment supporting ISA 3.0 or later. This function returns
18117 a non-zero value if and only if its @code{u} argument exactly equals one of
18118 the eight bytes contained within its 64-bit @code{set} argument.
18120 The @code{__builtin_byte_in_range} and
18121 @code{__builtin_byte_in_either_range} require an environment
18122 supporting ISA 3.0 or later. For these two functions, the
18123 @code{range} argument is encoded as 4 bytes, organized as
18124 @code{hi_1:lo_1:hi_2:lo_2}.
18125 The @code{__builtin_byte_in_range} function returns a
18126 non-zero value if and only if its @code{u} argument is within the
18127 range bounded between @code{lo_2} and @code{hi_2} inclusive.
18128 The @code{__builtin_byte_in_either_range} function returns non-zero if
18129 and only if its @code{u} argument is within either the range bounded
18130 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
18131 between @code{lo_2} and @code{hi_2} inclusive.
18133 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
18134 if and only if the number of signficant digits of its @code{value} argument
18135 is less than its @code{comparison} argument. The
18136 @code{__builtin_dfp_dtstsfi_lt_dd} and
18137 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
18138 require that the type of the @code{value} argument be
18139 @code{__Decimal64} and @code{__Decimal128} respectively.
18141 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
18142 if and only if the number of signficant digits of its @code{value} argument
18143 is greater than its @code{comparison} argument. The
18144 @code{__builtin_dfp_dtstsfi_gt_dd} and
18145 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
18146 require that the type of the @code{value} argument be
18147 @code{__Decimal64} and @code{__Decimal128} respectively.
18149 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
18150 if and only if the number of signficant digits of its @code{value} argument
18151 equals its @code{comparison} argument. The
18152 @code{__builtin_dfp_dtstsfi_eq_dd} and
18153 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
18154 require that the type of the @code{value} argument be
18155 @code{__Decimal64} and @code{__Decimal128} respectively.
18157 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
18158 if and only if its @code{value} argument has an undefined number of
18159 significant digits, such as when @code{value} is an encoding of @code{NaN}.
18160 The @code{__builtin_dfp_dtstsfi_ov_dd} and
18161 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
18162 require that the type of the @code{value} argument be
18163 @code{__Decimal64} and @code{__Decimal128} respectively.
18165 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
18166 the FPSCR. The instruction is a lower latency version of the @code{mffs}
18167 instruction. If the @code{mffsl} instruction is not available, then the
18168 builtin uses the older @code{mffs} instruction to read the FPSCR.
18170 @node Basic PowerPC Built-in Functions Available on ISA 3.1
18171 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1
18173 The basic built-in functions described in this section are
18174 available on the PowerPC family of processors starting with ISA 3.1.
18175 Unless specific options are explicitly disabled on the
18176 command line, specifying option @option{-mcpu=power10} has the effect of
18177 enabling all the same options as for @option{-mcpu=power9}.
18179 The following built-in functions are available on Linux 64-bit systems
18180 that use a future architecture instruction set (@option{-mcpu=power10}):
18183 @exdent unsigned long long int
18184 @exdent __builtin_cfuged (unsigned long long int, unsigned long long int)
18186 Perform a 64-bit centrifuge operation, as if implemented by the
18187 @code{cfuged} instruction.
18188 @findex __builtin_cfuged
18191 @exdent unsigned long long int
18192 @exdent __builtin_cntlzdm (unsigned long long int, unsigned long long int)
18194 Perform a 64-bit count leading zeros operation under mask, as if
18195 implemented by the @code{cntlzdm} instruction.
18196 @findex __builtin_cntlzdm
18199 @exdent unsigned long long int
18200 @exdent __builtin_cnttzdm (unsigned long long int, unsigned long long int)
18202 Perform a 64-bit count trailing zeros operation under mask, as if
18203 implemented by the @code{cnttzdm} instruction.
18204 @findex __builtin_cnttzdm
18207 @exdent unsigned long long int
18208 @exdent __builtin_pdepd (unsigned long long int, unsigned long long int)
18210 Perform a 64-bit parallel bits deposit operation, as if implemented by the
18211 @code{pdepd} instruction.
18212 @findex __builtin_pdepd
18215 @exdent unsigned long long int
18216 @exdent __builtin_pextd (unsigned long long int, unsigned long long int)
18218 Perform a 64-bit parallel bits extract operation, as if implemented by the
18219 @code{pextd} instruction.
18220 @findex __builtin_pextd
18223 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed char *);
18224 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed short *);
18225 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed int *);
18226 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed long long *);
18227 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned char *);
18228 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned short *);
18229 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned int *);
18230 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned long long *);
18233 Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1
18234 @code{lxvrbx} @code{lxvrhx} @code{lxvrwx} @code{lxvrdx} instructions.
18235 @findex vsx_xl_sext
18236 @findex vsx_xl_zext
18239 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed char *);
18240 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed short *);
18241 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed int *);
18242 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed long long *);
18243 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *);
18244 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *);
18245 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *);
18246 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *);
18249 Truncate and store the rightmost element of a vector, as if implemented by the
18250 ISA 3.1 @code{stxvrbx} @code{stxvrhx} @code{stxvrwx} @code{stxvrdx} instructions.
18251 @findex vec_xst_trunc
18253 @node PowerPC AltiVec/VSX Built-in Functions
18254 @subsection PowerPC AltiVec/VSX Built-in Functions
18256 GCC provides an interface for the PowerPC family of processors to access
18257 the AltiVec operations described in Motorola's AltiVec Programming
18258 Interface Manual. The interface is made available by including
18259 @code{<altivec.h>} and using @option{-maltivec} and
18260 @option{-mabi=altivec}. The interface supports the following vector
18264 vector unsigned char
18268 vector unsigned short
18269 vector signed short
18273 vector unsigned int
18279 GCC's implementation of the high-level language interface available from
18280 C and C++ code differs from Motorola's documentation in several ways.
18285 A vector constant is a list of constant expressions within curly braces.
18288 A vector initializer requires no cast if the vector constant is of the
18289 same type as the variable it is initializing.
18292 If @code{signed} or @code{unsigned} is omitted, the signedness of the
18293 vector type is the default signedness of the base type. The default
18294 varies depending on the operating system, so a portable program should
18295 always specify the signedness.
18298 Compiling with @option{-maltivec} adds keywords @code{__vector},
18299 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
18300 @code{bool}. When compiling ISO C, the context-sensitive substitution
18301 of the keywords @code{vector}, @code{pixel} and @code{bool} is
18302 disabled. To use them, you must include @code{<altivec.h>} instead.
18305 GCC allows using a @code{typedef} name as the type specifier for a
18306 vector type, but only under the following circumstances:
18311 When using @code{__vector} instead of @code{vector}; for example,
18314 typedef signed short int16;
18315 __vector int16 data;
18319 When using @code{vector} in keyword-and-predefine mode; for example,
18322 typedef signed short int16;
18326 Note that keyword-and-predefine mode is enabled by disabling GNU
18327 extensions (e.g., by using @code{-std=c11}) and including
18328 @code{<altivec.h>}.
18332 For C, overloaded functions are implemented with macros so the following
18336 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
18340 Since @code{vec_add} is a macro, the vector constant in the example
18341 is treated as four separate arguments. Wrap the entire argument in
18342 parentheses for this to work.
18345 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
18346 Internally, GCC uses built-in functions to achieve the functionality in
18347 the aforementioned header file, but they are not supported and are
18348 subject to change without notice.
18350 GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR),
18351 which may be found at
18352 @uref{https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference}.
18353 Chapter 4 of this document fully documents the vector API interfaces
18355 provided by compliant compilers. Programmers should preferentially use
18356 the interfaces described therein. However, historically GCC has provided
18357 additional interfaces for access to vector instructions. These are
18358 briefly described below. Where the PVIPR provides a portable interface,
18359 other functions in GCC that provide the same capabilities should be
18360 considered deprecated.
18362 The PVIPR documents the following overloaded functions:
18364 @multitable @columnfractions 0.33 0.33 0.33
18366 @item @code{vec_abs}
18367 @tab @code{vec_absd}
18368 @tab @code{vec_abss}
18369 @item @code{vec_add}
18370 @tab @code{vec_addc}
18371 @tab @code{vec_adde}
18372 @item @code{vec_addec}
18373 @tab @code{vec_adds}
18374 @tab @code{vec_all_eq}
18375 @item @code{vec_all_ge}
18376 @tab @code{vec_all_gt}
18377 @tab @code{vec_all_in}
18378 @item @code{vec_all_le}
18379 @tab @code{vec_all_lt}
18380 @tab @code{vec_all_nan}
18381 @item @code{vec_all_ne}
18382 @tab @code{vec_all_nge}
18383 @tab @code{vec_all_ngt}
18384 @item @code{vec_all_nle}
18385 @tab @code{vec_all_nlt}
18386 @tab @code{vec_all_numeric}
18387 @item @code{vec_and}
18388 @tab @code{vec_andc}
18389 @tab @code{vec_any_eq}
18390 @item @code{vec_any_ge}
18391 @tab @code{vec_any_gt}
18392 @tab @code{vec_any_le}
18393 @item @code{vec_any_lt}
18394 @tab @code{vec_any_nan}
18395 @tab @code{vec_any_ne}
18396 @item @code{vec_any_nge}
18397 @tab @code{vec_any_ngt}
18398 @tab @code{vec_any_nle}
18399 @item @code{vec_any_nlt}
18400 @tab @code{vec_any_numeric}
18401 @tab @code{vec_any_out}
18402 @item @code{vec_avg}
18403 @tab @code{vec_bperm}
18404 @tab @code{vec_ceil}
18405 @item @code{vec_cipher_be}
18406 @tab @code{vec_cipherlast_be}
18407 @tab @code{vec_cmpb}
18408 @item @code{vec_cmpeq}
18409 @tab @code{vec_cmpge}
18410 @tab @code{vec_cmpgt}
18411 @item @code{vec_cmple}
18412 @tab @code{vec_cmplt}
18413 @tab @code{vec_cmpne}
18414 @item @code{vec_cmpnez}
18415 @tab @code{vec_cntlz}
18416 @tab @code{vec_cntlz_lsbb}
18417 @item @code{vec_cnttz}
18418 @tab @code{vec_cnttz_lsbb}
18419 @tab @code{vec_cpsgn}
18420 @item @code{vec_ctf}
18421 @tab @code{vec_cts}
18422 @tab @code{vec_ctu}
18423 @item @code{vec_div}
18424 @tab @code{vec_double}
18425 @tab @code{vec_doublee}
18426 @item @code{vec_doubleh}
18427 @tab @code{vec_doublel}
18428 @tab @code{vec_doubleo}
18429 @item @code{vec_eqv}
18430 @tab @code{vec_expte}
18431 @tab @code{vec_extract}
18432 @item @code{vec_extract_exp}
18433 @tab @code{vec_extract_fp32_from_shorth}
18434 @tab @code{vec_extract_fp32_from_shortl}
18435 @item @code{vec_extract_sig}
18436 @tab @code{vec_extract_4b}
18437 @tab @code{vec_first_match_index}
18438 @item @code{vec_first_match_or_eos_index}
18439 @tab @code{vec_first_mismatch_index}
18440 @tab @code{vec_first_mismatch_or_eos_index}
18441 @item @code{vec_float}
18442 @tab @code{vec_float2}
18443 @tab @code{vec_floate}
18444 @item @code{vec_floato}
18445 @tab @code{vec_floor}
18447 @item @code{vec_insert}
18448 @tab @code{vec_insert_exp}
18449 @tab @code{vec_insert4b}
18450 @item @code{vec_ld}
18451 @tab @code{vec_lde}
18452 @tab @code{vec_ldl}
18453 @item @code{vec_loge}
18454 @tab @code{vec_madd}
18455 @tab @code{vec_madds}
18456 @item @code{vec_max}
18457 @tab @code{vec_mergee}
18458 @tab @code{vec_mergeh}
18459 @item @code{vec_mergel}
18460 @tab @code{vec_mergeo}
18461 @tab @code{vec_mfvscr}
18462 @item @code{vec_min}
18463 @tab @code{vec_mradds}
18464 @tab @code{vec_msub}
18465 @item @code{vec_msum}
18466 @tab @code{vec_msums}
18467 @tab @code{vec_mtvscr}
18468 @item @code{vec_mul}
18469 @tab @code{vec_mule}
18470 @tab @code{vec_mulo}
18471 @item @code{vec_nabs}
18472 @tab @code{vec_nand}
18473 @tab @code{vec_ncipher_be}
18474 @item @code{vec_ncipherlast_be}
18475 @tab @code{vec_nearbyint}
18476 @tab @code{vec_neg}
18477 @item @code{vec_nmadd}
18478 @tab @code{vec_nmsub}
18479 @tab @code{vec_nor}
18480 @item @code{vec_or}
18481 @tab @code{vec_orc}
18482 @tab @code{vec_pack}
18483 @item @code{vec_pack_to_short_fp32}
18484 @tab @code{vec_packpx}
18485 @tab @code{vec_packs}
18486 @item @code{vec_packsu}
18487 @tab @code{vec_parity_lsbb}
18488 @tab @code{vec_perm}
18489 @item @code{vec_permxor}
18490 @tab @code{vec_pmsum_be}
18491 @tab @code{vec_popcnt}
18492 @item @code{vec_re}
18493 @tab @code{vec_recipdiv}
18494 @tab @code{vec_revb}
18495 @item @code{vec_reve}
18496 @tab @code{vec_rint}
18498 @item @code{vec_rlmi}
18499 @tab @code{vec_rlnm}
18500 @tab @code{vec_round}
18501 @item @code{vec_rsqrt}
18502 @tab @code{vec_rsqrte}
18503 @tab @code{vec_sbox_be}
18504 @item @code{vec_sel}
18505 @tab @code{vec_shasigma_be}
18506 @tab @code{vec_signed}
18507 @item @code{vec_signed2}
18508 @tab @code{vec_signede}
18509 @tab @code{vec_signedo}
18510 @item @code{vec_sl}
18511 @tab @code{vec_sld}
18512 @tab @code{vec_sldw}
18513 @item @code{vec_sll}
18514 @tab @code{vec_slo}
18515 @tab @code{vec_slv}
18516 @item @code{vec_splat}
18517 @tab @code{vec_splat_s8}
18518 @tab @code{vec_splat_s16}
18519 @item @code{vec_splat_s32}
18520 @tab @code{vec_splat_u8}
18521 @tab @code{vec_splat_u16}
18522 @item @code{vec_splat_u32}
18523 @tab @code{vec_splats}
18524 @tab @code{vec_sqrt}
18525 @item @code{vec_sr}
18526 @tab @code{vec_sra}
18527 @tab @code{vec_srl}
18528 @item @code{vec_sro}
18529 @tab @code{vec_srv}
18531 @item @code{vec_ste}
18532 @tab @code{vec_stl}
18533 @tab @code{vec_sub}
18534 @item @code{vec_subc}
18535 @tab @code{vec_sube}
18536 @tab @code{vec_subec}
18537 @item @code{vec_subs}
18538 @tab @code{vec_sum2s}
18539 @tab @code{vec_sum4s}
18540 @item @code{vec_sums}
18541 @tab @code{vec_test_data_class}
18542 @tab @code{vec_trunc}
18543 @item @code{vec_unpackh}
18544 @tab @code{vec_unpackl}
18545 @tab @code{vec_unsigned}
18546 @item @code{vec_unsigned2}
18547 @tab @code{vec_unsignede}
18548 @tab @code{vec_unsignedo}
18549 @item @code{vec_xl}
18550 @tab @code{vec_xl_be}
18551 @tab @code{vec_xl_len}
18552 @item @code{vec_xl_len_r}
18553 @tab @code{vec_xor}
18554 @tab @code{vec_xst}
18555 @item @code{vec_xst_be}
18556 @tab @code{vec_xst_len}
18557 @tab @code{vec_xst_len_r}
18562 * PowerPC AltiVec Built-in Functions on ISA 2.05::
18563 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
18564 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
18565 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
18566 * PowerPC AltiVec Built-in Functions Available on ISA 3.1::
18569 @node PowerPC AltiVec Built-in Functions on ISA 2.05
18570 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
18572 The following interfaces are supported for the generic and specific
18573 AltiVec operations and the AltiVec predicates. In cases where there
18574 is a direct mapping between generic and specific operations, only the
18575 generic names are shown here, although the specific operations can also
18578 Arguments that are documented as @code{const int} require literal
18579 integral values within the range required for that operation.
18581 Only functions excluded from the PVIPR are listed here.
18584 void vec_dss (const int);
18586 void vec_dssall (void);
18588 void vec_dst (const vector unsigned char *, int, const int);
18589 void vec_dst (const vector signed char *, int, const int);
18590 void vec_dst (const vector bool char *, int, const int);
18591 void vec_dst (const vector unsigned short *, int, const int);
18592 void vec_dst (const vector signed short *, int, const int);
18593 void vec_dst (const vector bool short *, int, const int);
18594 void vec_dst (const vector pixel *, int, const int);
18595 void vec_dst (const vector unsigned int *, int, const int);
18596 void vec_dst (const vector signed int *, int, const int);
18597 void vec_dst (const vector bool int *, int, const int);
18598 void vec_dst (const vector float *, int, const int);
18599 void vec_dst (const unsigned char *, int, const int);
18600 void vec_dst (const signed char *, int, const int);
18601 void vec_dst (const unsigned short *, int, const int);
18602 void vec_dst (const short *, int, const int);
18603 void vec_dst (const unsigned int *, int, const int);
18604 void vec_dst (const int *, int, const int);
18605 void vec_dst (const float *, int, const int);
18607 void vec_dstst (const vector unsigned char *, int, const int);
18608 void vec_dstst (const vector signed char *, int, const int);
18609 void vec_dstst (const vector bool char *, int, const int);
18610 void vec_dstst (const vector unsigned short *, int, const int);
18611 void vec_dstst (const vector signed short *, int, const int);
18612 void vec_dstst (const vector bool short *, int, const int);
18613 void vec_dstst (const vector pixel *, int, const int);
18614 void vec_dstst (const vector unsigned int *, int, const int);
18615 void vec_dstst (const vector signed int *, int, const int);
18616 void vec_dstst (const vector bool int *, int, const int);
18617 void vec_dstst (const vector float *, int, const int);
18618 void vec_dstst (const unsigned char *, int, const int);
18619 void vec_dstst (const signed char *, int, const int);
18620 void vec_dstst (const unsigned short *, int, const int);
18621 void vec_dstst (const short *, int, const int);
18622 void vec_dstst (const unsigned int *, int, const int);
18623 void vec_dstst (const int *, int, const int);
18624 void vec_dstst (const unsigned long *, int, const int);
18625 void vec_dstst (const long *, int, const int);
18626 void vec_dstst (const float *, int, const int);
18628 void vec_dststt (const vector unsigned char *, int, const int);
18629 void vec_dststt (const vector signed char *, int, const int);
18630 void vec_dststt (const vector bool char *, int, const int);
18631 void vec_dststt (const vector unsigned short *, int, const int);
18632 void vec_dststt (const vector signed short *, int, const int);
18633 void vec_dststt (const vector bool short *, int, const int);
18634 void vec_dststt (const vector pixel *, int, const int);
18635 void vec_dststt (const vector unsigned int *, int, const int);
18636 void vec_dststt (const vector signed int *, int, const int);
18637 void vec_dststt (const vector bool int *, int, const int);
18638 void vec_dststt (const vector float *, int, const int);
18639 void vec_dststt (const unsigned char *, int, const int);
18640 void vec_dststt (const signed char *, int, const int);
18641 void vec_dststt (const unsigned short *, int, const int);
18642 void vec_dststt (const short *, int, const int);
18643 void vec_dststt (const unsigned int *, int, const int);
18644 void vec_dststt (const int *, int, const int);
18645 void vec_dststt (const float *, int, const int);
18647 void vec_dstt (const vector unsigned char *, int, const int);
18648 void vec_dstt (const vector signed char *, int, const int);
18649 void vec_dstt (const vector bool char *, int, const int);
18650 void vec_dstt (const vector unsigned short *, int, const int);
18651 void vec_dstt (const vector signed short *, int, const int);
18652 void vec_dstt (const vector bool short *, int, const int);
18653 void vec_dstt (const vector pixel *, int, const int);
18654 void vec_dstt (const vector unsigned int *, int, const int);
18655 void vec_dstt (const vector signed int *, int, const int);
18656 void vec_dstt (const vector bool int *, int, const int);
18657 void vec_dstt (const vector float *, int, const int);
18658 void vec_dstt (const unsigned char *, int, const int);
18659 void vec_dstt (const signed char *, int, const int);
18660 void vec_dstt (const unsigned short *, int, const int);
18661 void vec_dstt (const short *, int, const int);
18662 void vec_dstt (const unsigned int *, int, const int);
18663 void vec_dstt (const int *, int, const int);
18664 void vec_dstt (const float *, int, const int);
18666 vector signed char vec_lvebx (int, char *);
18667 vector unsigned char vec_lvebx (int, unsigned char *);
18669 vector signed short vec_lvehx (int, short *);
18670 vector unsigned short vec_lvehx (int, unsigned short *);
18672 vector float vec_lvewx (int, float *);
18673 vector signed int vec_lvewx (int, int *);
18674 vector unsigned int vec_lvewx (int, unsigned int *);
18676 vector unsigned char vec_lvsl (int, const unsigned char *);
18677 vector unsigned char vec_lvsl (int, const signed char *);
18678 vector unsigned char vec_lvsl (int, const unsigned short *);
18679 vector unsigned char vec_lvsl (int, const short *);
18680 vector unsigned char vec_lvsl (int, const unsigned int *);
18681 vector unsigned char vec_lvsl (int, const int *);
18682 vector unsigned char vec_lvsl (int, const float *);
18684 vector unsigned char vec_lvsr (int, const unsigned char *);
18685 vector unsigned char vec_lvsr (int, const signed char *);
18686 vector unsigned char vec_lvsr (int, const unsigned short *);
18687 vector unsigned char vec_lvsr (int, const short *);
18688 vector unsigned char vec_lvsr (int, const unsigned int *);
18689 vector unsigned char vec_lvsr (int, const int *);
18690 vector unsigned char vec_lvsr (int, const float *);
18692 void vec_stvebx (vector signed char, int, signed char *);
18693 void vec_stvebx (vector unsigned char, int, unsigned char *);
18694 void vec_stvebx (vector bool char, int, signed char *);
18695 void vec_stvebx (vector bool char, int, unsigned char *);
18697 void vec_stvehx (vector signed short, int, short *);
18698 void vec_stvehx (vector unsigned short, int, unsigned short *);
18699 void vec_stvehx (vector bool short, int, short *);
18700 void vec_stvehx (vector bool short, int, unsigned short *);
18702 void vec_stvewx (vector float, int, float *);
18703 void vec_stvewx (vector signed int, int, int *);
18704 void vec_stvewx (vector unsigned int, int, unsigned int *);
18705 void vec_stvewx (vector bool int, int, int *);
18706 void vec_stvewx (vector bool int, int, unsigned int *);
18708 vector float vec_vaddfp (vector float, vector float);
18710 vector signed char vec_vaddsbs (vector bool char, vector signed char);
18711 vector signed char vec_vaddsbs (vector signed char, vector bool char);
18712 vector signed char vec_vaddsbs (vector signed char, vector signed char);
18714 vector signed short vec_vaddshs (vector bool short, vector signed short);
18715 vector signed short vec_vaddshs (vector signed short, vector bool short);
18716 vector signed short vec_vaddshs (vector signed short, vector signed short);
18718 vector signed int vec_vaddsws (vector bool int, vector signed int);
18719 vector signed int vec_vaddsws (vector signed int, vector bool int);
18720 vector signed int vec_vaddsws (vector signed int, vector signed int);
18722 vector signed char vec_vaddubm (vector bool char, vector signed char);
18723 vector signed char vec_vaddubm (vector signed char, vector bool char);
18724 vector signed char vec_vaddubm (vector signed char, vector signed char);
18725 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
18726 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
18727 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
18729 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
18730 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
18731 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
18733 vector signed short vec_vadduhm (vector bool short, vector signed short);
18734 vector signed short vec_vadduhm (vector signed short, vector bool short);
18735 vector signed short vec_vadduhm (vector signed short, vector signed short);
18736 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
18737 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
18738 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
18740 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
18741 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
18742 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
18744 vector signed int vec_vadduwm (vector bool int, vector signed int);
18745 vector signed int vec_vadduwm (vector signed int, vector bool int);
18746 vector signed int vec_vadduwm (vector signed int, vector signed int);
18747 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
18748 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
18749 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
18751 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
18752 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
18753 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
18755 vector signed char vec_vavgsb (vector signed char, vector signed char);
18757 vector signed short vec_vavgsh (vector signed short, vector signed short);
18759 vector signed int vec_vavgsw (vector signed int, vector signed int);
18761 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
18763 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
18765 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
18767 vector float vec_vcfsx (vector signed int, const int);
18769 vector float vec_vcfux (vector unsigned int, const int);
18771 vector bool int vec_vcmpeqfp (vector float, vector float);
18773 vector bool char vec_vcmpequb (vector signed char, vector signed char);
18774 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
18776 vector bool short vec_vcmpequh (vector signed short, vector signed short);
18777 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
18779 vector bool int vec_vcmpequw (vector signed int, vector signed int);
18780 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
18782 vector bool int vec_vcmpgtfp (vector float, vector float);
18784 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
18786 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
18788 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
18790 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
18792 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
18794 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
18796 vector float vec_vmaxfp (vector float, vector float);
18798 vector signed char vec_vmaxsb (vector bool char, vector signed char);
18799 vector signed char vec_vmaxsb (vector signed char, vector bool char);
18800 vector signed char vec_vmaxsb (vector signed char, vector signed char);
18802 vector signed short vec_vmaxsh (vector bool short, vector signed short);
18803 vector signed short vec_vmaxsh (vector signed short, vector bool short);
18804 vector signed short vec_vmaxsh (vector signed short, vector signed short);
18806 vector signed int vec_vmaxsw (vector bool int, vector signed int);
18807 vector signed int vec_vmaxsw (vector signed int, vector bool int);
18808 vector signed int vec_vmaxsw (vector signed int, vector signed int);
18810 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
18811 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
18812 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
18814 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
18815 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
18816 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
18818 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
18819 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
18820 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
18822 vector float vec_vminfp (vector float, vector float);
18824 vector signed char vec_vminsb (vector bool char, vector signed char);
18825 vector signed char vec_vminsb (vector signed char, vector bool char);
18826 vector signed char vec_vminsb (vector signed char, vector signed char);
18828 vector signed short vec_vminsh (vector bool short, vector signed short);
18829 vector signed short vec_vminsh (vector signed short, vector bool short);
18830 vector signed short vec_vminsh (vector signed short, vector signed short);
18832 vector signed int vec_vminsw (vector bool int, vector signed int);
18833 vector signed int vec_vminsw (vector signed int, vector bool int);
18834 vector signed int vec_vminsw (vector signed int, vector signed int);
18836 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
18837 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
18838 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
18840 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
18841 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
18842 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
18844 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
18845 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
18846 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
18848 vector bool char vec_vmrghb (vector bool char, vector bool char);
18849 vector signed char vec_vmrghb (vector signed char, vector signed char);
18850 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
18852 vector bool short vec_vmrghh (vector bool short, vector bool short);
18853 vector signed short vec_vmrghh (vector signed short, vector signed short);
18854 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
18855 vector pixel vec_vmrghh (vector pixel, vector pixel);
18857 vector float vec_vmrghw (vector float, vector float);
18858 vector bool int vec_vmrghw (vector bool int, vector bool int);
18859 vector signed int vec_vmrghw (vector signed int, vector signed int);
18860 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
18862 vector bool char vec_vmrglb (vector bool char, vector bool char);
18863 vector signed char vec_vmrglb (vector signed char, vector signed char);
18864 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
18866 vector bool short vec_vmrglh (vector bool short, vector bool short);
18867 vector signed short vec_vmrglh (vector signed short, vector signed short);
18868 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
18869 vector pixel vec_vmrglh (vector pixel, vector pixel);
18871 vector float vec_vmrglw (vector float, vector float);
18872 vector signed int vec_vmrglw (vector signed int, vector signed int);
18873 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
18874 vector bool int vec_vmrglw (vector bool int, vector bool int);
18876 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
18877 vector signed int);
18879 vector signed int vec_vmsumshm (vector signed short, vector signed short,
18880 vector signed int);
18882 vector signed int vec_vmsumshs (vector signed short, vector signed short,
18883 vector signed int);
18885 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
18886 vector unsigned int);
18888 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
18889 vector unsigned int);
18891 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
18892 vector unsigned int);
18894 vector signed short vec_vmulesb (vector signed char, vector signed char);
18896 vector signed int vec_vmulesh (vector signed short, vector signed short);
18898 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
18900 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
18902 vector signed short vec_vmulosb (vector signed char, vector signed char);
18904 vector signed int vec_vmulosh (vector signed short, vector signed short);
18906 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
18908 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
18910 vector signed char vec_vpkshss (vector signed short, vector signed short);
18912 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
18914 vector signed short vec_vpkswss (vector signed int, vector signed int);
18916 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
18918 vector bool char vec_vpkuhum (vector bool short, vector bool short);
18919 vector signed char vec_vpkuhum (vector signed short, vector signed short);
18920 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
18922 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
18924 vector bool short vec_vpkuwum (vector bool int, vector bool int);
18925 vector signed short vec_vpkuwum (vector signed int, vector signed int);
18926 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
18928 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
18930 vector signed char vec_vrlb (vector signed char, vector unsigned char);
18931 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
18933 vector signed short vec_vrlh (vector signed short, vector unsigned short);
18934 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
18936 vector signed int vec_vrlw (vector signed int, vector unsigned int);
18937 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
18939 vector signed char vec_vslb (vector signed char, vector unsigned char);
18940 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
18942 vector signed short vec_vslh (vector signed short, vector unsigned short);
18943 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
18945 vector signed int vec_vslw (vector signed int, vector unsigned int);
18946 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
18948 vector signed char vec_vspltb (vector signed char, const int);
18949 vector unsigned char vec_vspltb (vector unsigned char, const int);
18950 vector bool char vec_vspltb (vector bool char, const int);
18952 vector bool short vec_vsplth (vector bool short, const int);
18953 vector signed short vec_vsplth (vector signed short, const int);
18954 vector unsigned short vec_vsplth (vector unsigned short, const int);
18955 vector pixel vec_vsplth (vector pixel, const int);
18957 vector float vec_vspltw (vector float, const int);
18958 vector signed int vec_vspltw (vector signed int, const int);
18959 vector unsigned int vec_vspltw (vector unsigned int, const int);
18960 vector bool int vec_vspltw (vector bool int, const int);
18962 vector signed char vec_vsrab (vector signed char, vector unsigned char);
18963 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
18965 vector signed short vec_vsrah (vector signed short, vector unsigned short);
18966 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
18968 vector signed int vec_vsraw (vector signed int, vector unsigned int);
18969 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
18971 vector signed char vec_vsrb (vector signed char, vector unsigned char);
18972 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
18974 vector signed short vec_vsrh (vector signed short, vector unsigned short);
18975 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
18977 vector signed int vec_vsrw (vector signed int, vector unsigned int);
18978 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
18980 vector float vec_vsubfp (vector float, vector float);
18982 vector signed char vec_vsubsbs (vector bool char, vector signed char);
18983 vector signed char vec_vsubsbs (vector signed char, vector bool char);
18984 vector signed char vec_vsubsbs (vector signed char, vector signed char);
18986 vector signed short vec_vsubshs (vector bool short, vector signed short);
18987 vector signed short vec_vsubshs (vector signed short, vector bool short);
18988 vector signed short vec_vsubshs (vector signed short, vector signed short);
18990 vector signed int vec_vsubsws (vector bool int, vector signed int);
18991 vector signed int vec_vsubsws (vector signed int, vector bool int);
18992 vector signed int vec_vsubsws (vector signed int, vector signed int);
18994 vector signed char vec_vsububm (vector bool char, vector signed char);
18995 vector signed char vec_vsububm (vector signed char, vector bool char);
18996 vector signed char vec_vsububm (vector signed char, vector signed char);
18997 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
18998 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
18999 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
19001 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
19002 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
19003 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
19005 vector signed short vec_vsubuhm (vector bool short, vector signed short);
19006 vector signed short vec_vsubuhm (vector signed short, vector bool short);
19007 vector signed short vec_vsubuhm (vector signed short, vector signed short);
19008 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
19009 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
19010 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
19012 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
19013 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
19014 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
19016 vector signed int vec_vsubuwm (vector bool int, vector signed int);
19017 vector signed int vec_vsubuwm (vector signed int, vector bool int);
19018 vector signed int vec_vsubuwm (vector signed int, vector signed int);
19019 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
19020 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
19021 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
19023 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
19024 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
19025 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
19027 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
19029 vector signed int vec_vsum4shs (vector signed short, vector signed int);
19031 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
19033 vector unsigned int vec_vupkhpx (vector pixel);
19035 vector bool short vec_vupkhsb (vector bool char);
19036 vector signed short vec_vupkhsb (vector signed char);
19038 vector bool int vec_vupkhsh (vector bool short);
19039 vector signed int vec_vupkhsh (vector signed short);
19041 vector unsigned int vec_vupklpx (vector pixel);
19043 vector bool short vec_vupklsb (vector bool char);
19044 vector signed short vec_vupklsb (vector signed char);
19046 vector bool int vec_vupklsh (vector bool short);
19047 vector signed int vec_vupklsh (vector signed short);
19050 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
19051 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
19053 The AltiVec built-in functions described in this section are
19054 available on the PowerPC family of processors starting with ISA 2.06
19055 or later. These are normally enabled by adding @option{-mvsx} to the
19058 When @option{-mvsx} is used, the following additional vector types are
19062 vector unsigned __int128
19063 vector signed __int128
19064 vector unsigned long long int
19065 vector signed long long int
19069 The long long types are only implemented for 64-bit code generation.
19071 Only functions excluded from the PVIPR are listed here.
19074 void vec_dst (const unsigned long *, int, const int);
19075 void vec_dst (const long *, int, const int);
19077 void vec_dststt (const unsigned long *, int, const int);
19078 void vec_dststt (const long *, int, const int);
19080 void vec_dstt (const unsigned long *, int, const int);
19081 void vec_dstt (const long *, int, const int);
19083 vector unsigned char vec_lvsl (int, const unsigned long *);
19084 vector unsigned char vec_lvsl (int, const long *);
19086 vector unsigned char vec_lvsr (int, const unsigned long *);
19087 vector unsigned char vec_lvsr (int, const long *);
19089 vector unsigned char vec_lvsl (int, const double *);
19090 vector unsigned char vec_lvsr (int, const double *);
19092 vector double vec_vsx_ld (int, const vector double *);
19093 vector double vec_vsx_ld (int, const double *);
19094 vector float vec_vsx_ld (int, const vector float *);
19095 vector float vec_vsx_ld (int, const float *);
19096 vector bool int vec_vsx_ld (int, const vector bool int *);
19097 vector signed int vec_vsx_ld (int, const vector signed int *);
19098 vector signed int vec_vsx_ld (int, const int *);
19099 vector signed int vec_vsx_ld (int, const long *);
19100 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
19101 vector unsigned int vec_vsx_ld (int, const unsigned int *);
19102 vector unsigned int vec_vsx_ld (int, const unsigned long *);
19103 vector bool short vec_vsx_ld (int, const vector bool short *);
19104 vector pixel vec_vsx_ld (int, const vector pixel *);
19105 vector signed short vec_vsx_ld (int, const vector signed short *);
19106 vector signed short vec_vsx_ld (int, const short *);
19107 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
19108 vector unsigned short vec_vsx_ld (int, const unsigned short *);
19109 vector bool char vec_vsx_ld (int, const vector bool char *);
19110 vector signed char vec_vsx_ld (int, const vector signed char *);
19111 vector signed char vec_vsx_ld (int, const signed char *);
19112 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
19113 vector unsigned char vec_vsx_ld (int, const unsigned char *);
19115 void vec_vsx_st (vector double, int, vector double *);
19116 void vec_vsx_st (vector double, int, double *);
19117 void vec_vsx_st (vector float, int, vector float *);
19118 void vec_vsx_st (vector float, int, float *);
19119 void vec_vsx_st (vector signed int, int, vector signed int *);
19120 void vec_vsx_st (vector signed int, int, int *);
19121 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
19122 void vec_vsx_st (vector unsigned int, int, unsigned int *);
19123 void vec_vsx_st (vector bool int, int, vector bool int *);
19124 void vec_vsx_st (vector bool int, int, unsigned int *);
19125 void vec_vsx_st (vector bool int, int, int *);
19126 void vec_vsx_st (vector signed short, int, vector signed short *);
19127 void vec_vsx_st (vector signed short, int, short *);
19128 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
19129 void vec_vsx_st (vector unsigned short, int, unsigned short *);
19130 void vec_vsx_st (vector bool short, int, vector bool short *);
19131 void vec_vsx_st (vector bool short, int, unsigned short *);
19132 void vec_vsx_st (vector pixel, int, vector pixel *);
19133 void vec_vsx_st (vector pixel, int, unsigned short *);
19134 void vec_vsx_st (vector pixel, int, short *);
19135 void vec_vsx_st (vector bool short, int, short *);
19136 void vec_vsx_st (vector signed char, int, vector signed char *);
19137 void vec_vsx_st (vector signed char, int, signed char *);
19138 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
19139 void vec_vsx_st (vector unsigned char, int, unsigned char *);
19140 void vec_vsx_st (vector bool char, int, vector bool char *);
19141 void vec_vsx_st (vector bool char, int, unsigned char *);
19142 void vec_vsx_st (vector bool char, int, signed char *);
19144 vector double vec_xxpermdi (vector double, vector double, const int);
19145 vector float vec_xxpermdi (vector float, vector float, const int);
19146 vector long long vec_xxpermdi (vector long long, vector long long, const int);
19147 vector unsigned long long vec_xxpermdi (vector unsigned long long,
19148 vector unsigned long long, const int);
19149 vector int vec_xxpermdi (vector int, vector int, const int);
19150 vector unsigned int vec_xxpermdi (vector unsigned int,
19151 vector unsigned int, const int);
19152 vector short vec_xxpermdi (vector short, vector short, const int);
19153 vector unsigned short vec_xxpermdi (vector unsigned short,
19154 vector unsigned short, const int);
19155 vector signed char vec_xxpermdi (vector signed char, vector signed char,
19157 vector unsigned char vec_xxpermdi (vector unsigned char,
19158 vector unsigned char, const int);
19160 vector double vec_xxsldi (vector double, vector double, int);
19161 vector float vec_xxsldi (vector float, vector float, int);
19162 vector long long vec_xxsldi (vector long long, vector long long, int);
19163 vector unsigned long long vec_xxsldi (vector unsigned long long,
19164 vector unsigned long long, int);
19165 vector int vec_xxsldi (vector int, vector int, int);
19166 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
19167 vector short vec_xxsldi (vector short, vector short, int);
19168 vector unsigned short vec_xxsldi (vector unsigned short,
19169 vector unsigned short, int);
19170 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
19171 vector unsigned char vec_xxsldi (vector unsigned char,
19172 vector unsigned char, int);
19175 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
19176 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
19177 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
19178 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
19179 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
19181 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
19182 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
19184 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19185 instruction set are available, the following additional functions are
19186 available for both 32-bit and 64-bit targets. For 64-bit targets, you
19187 can use @var{vector long} instead of @var{vector long long},
19188 @var{vector bool long} instead of @var{vector bool long long}, and
19189 @var{vector unsigned long} instead of @var{vector unsigned long long}.
19191 Only functions excluded from the PVIPR are listed here.
19194 vector long long vec_vaddudm (vector long long, vector long long);
19195 vector long long vec_vaddudm (vector bool long long, vector long long);
19196 vector long long vec_vaddudm (vector long long, vector bool long long);
19197 vector unsigned long long vec_vaddudm (vector unsigned long long,
19198 vector unsigned long long);
19199 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
19200 vector unsigned long long);
19201 vector unsigned long long vec_vaddudm (vector unsigned long long,
19202 vector bool unsigned long long);
19204 vector long long vec_vclz (vector long long);
19205 vector unsigned long long vec_vclz (vector unsigned long long);
19206 vector int vec_vclz (vector int);
19207 vector unsigned int vec_vclz (vector int);
19208 vector short vec_vclz (vector short);
19209 vector unsigned short vec_vclz (vector unsigned short);
19210 vector signed char vec_vclz (vector signed char);
19211 vector unsigned char vec_vclz (vector unsigned char);
19213 vector signed char vec_vclzb (vector signed char);
19214 vector unsigned char vec_vclzb (vector unsigned char);
19216 vector long long vec_vclzd (vector long long);
19217 vector unsigned long long vec_vclzd (vector unsigned long long);
19219 vector short vec_vclzh (vector short);
19220 vector unsigned short vec_vclzh (vector unsigned short);
19222 vector int vec_vclzw (vector int);
19223 vector unsigned int vec_vclzw (vector int);
19225 vector signed char vec_vgbbd (vector signed char);
19226 vector unsigned char vec_vgbbd (vector unsigned char);
19228 vector long long vec_vmaxsd (vector long long, vector long long);
19230 vector unsigned long long vec_vmaxud (vector unsigned long long,
19231 unsigned vector long long);
19233 vector long long vec_vminsd (vector long long, vector long long);
19235 vector unsigned long long vec_vminud (vector long long, vector long long);
19237 vector int vec_vpksdss (vector long long, vector long long);
19238 vector unsigned int vec_vpksdss (vector long long, vector long long);
19240 vector unsigned int vec_vpkudus (vector unsigned long long,
19241 vector unsigned long long);
19243 vector int vec_vpkudum (vector long long, vector long long);
19244 vector unsigned int vec_vpkudum (vector unsigned long long,
19245 vector unsigned long long);
19246 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
19248 vector long long vec_vpopcnt (vector long long);
19249 vector unsigned long long vec_vpopcnt (vector unsigned long long);
19250 vector int vec_vpopcnt (vector int);
19251 vector unsigned int vec_vpopcnt (vector int);
19252 vector short vec_vpopcnt (vector short);
19253 vector unsigned short vec_vpopcnt (vector unsigned short);
19254 vector signed char vec_vpopcnt (vector signed char);
19255 vector unsigned char vec_vpopcnt (vector unsigned char);
19257 vector signed char vec_vpopcntb (vector signed char);
19258 vector unsigned char vec_vpopcntb (vector unsigned char);
19260 vector long long vec_vpopcntd (vector long long);
19261 vector unsigned long long vec_vpopcntd (vector unsigned long long);
19263 vector short vec_vpopcnth (vector short);
19264 vector unsigned short vec_vpopcnth (vector unsigned short);
19266 vector int vec_vpopcntw (vector int);
19267 vector unsigned int vec_vpopcntw (vector int);
19269 vector long long vec_vrld (vector long long, vector unsigned long long);
19270 vector unsigned long long vec_vrld (vector unsigned long long,
19271 vector unsigned long long);
19273 vector long long vec_vsld (vector long long, vector unsigned long long);
19274 vector long long vec_vsld (vector unsigned long long,
19275 vector unsigned long long);
19277 vector long long vec_vsrad (vector long long, vector unsigned long long);
19278 vector unsigned long long vec_vsrad (vector unsigned long long,
19279 vector unsigned long long);
19281 vector long long vec_vsrd (vector long long, vector unsigned long long);
19282 vector unsigned long long char vec_vsrd (vector unsigned long long,
19283 vector unsigned long long);
19285 vector long long vec_vsubudm (vector long long, vector long long);
19286 vector long long vec_vsubudm (vector bool long long, vector long long);
19287 vector long long vec_vsubudm (vector long long, vector bool long long);
19288 vector unsigned long long vec_vsubudm (vector unsigned long long,
19289 vector unsigned long long);
19290 vector unsigned long long vec_vsubudm (vector bool long long,
19291 vector unsigned long long);
19292 vector unsigned long long vec_vsubudm (vector unsigned long long,
19293 vector bool long long);
19295 vector long long vec_vupkhsw (vector int);
19296 vector unsigned long long vec_vupkhsw (vector unsigned int);
19298 vector long long vec_vupklsw (vector int);
19299 vector unsigned long long vec_vupklsw (vector int);
19302 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19303 instruction set are available, the following additional functions are
19304 available for 64-bit targets. New vector types
19305 (@var{vector __int128} and @var{vector __uint128}) are available
19306 to hold the @var{__int128} and @var{__uint128} types to use these
19309 The normal vector extract, and set operations work on
19310 @var{vector __int128} and @var{vector __uint128} types,
19311 but the index value must be 0.
19313 Only functions excluded from the PVIPR are listed here.
19316 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
19317 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
19319 vector __int128 vec_vadduqm (vector __int128, vector __int128);
19320 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
19322 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
19324 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
19327 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
19329 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
19332 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
19334 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
19337 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
19339 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
19342 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
19343 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
19345 __int128 vec_vsubuqm (__int128, __int128);
19346 __uint128 vec_vsubuqm (__uint128, __uint128);
19348 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
19349 vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char,
19351 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
19352 int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int);
19353 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
19354 int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int);
19355 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
19356 int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int);
19357 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
19358 int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int);
19360 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
19361 vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char,
19363 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
19364 int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int);
19365 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
19366 int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int);
19367 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
19368 int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int);
19369 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
19370 int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int);
19373 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
19374 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
19376 The following additional built-in functions are also available for the
19377 PowerPC family of processors, starting with ISA 3.0
19378 (@option{-mcpu=power9}) or later.
19380 Only instructions excluded from the PVIPR are listed here.
19383 unsigned int scalar_extract_exp (double source);
19384 unsigned long long int scalar_extract_exp (__ieee128 source);
19386 unsigned long long int scalar_extract_sig (double source);
19387 unsigned __int128 scalar_extract_sig (__ieee128 source);
19389 double scalar_insert_exp (unsigned long long int significand,
19390 unsigned long long int exponent);
19391 double scalar_insert_exp (double significand, unsigned long long int exponent);
19393 ieee_128 scalar_insert_exp (unsigned __int128 significand,
19394 unsigned long long int exponent);
19395 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
19397 int scalar_cmp_exp_gt (double arg1, double arg2);
19398 int scalar_cmp_exp_lt (double arg1, double arg2);
19399 int scalar_cmp_exp_eq (double arg1, double arg2);
19400 int scalar_cmp_exp_unordered (double arg1, double arg2);
19402 bool scalar_test_data_class (float source, const int condition);
19403 bool scalar_test_data_class (double source, const int condition);
19404 bool scalar_test_data_class (__ieee128 source, const int condition);
19406 bool scalar_test_neg (float source);
19407 bool scalar_test_neg (double source);
19408 bool scalar_test_neg (__ieee128 source);
19411 The @code{scalar_extract_exp} and @code{scalar_extract_sig}
19412 functions require a 64-bit environment supporting ISA 3.0 or later.
19413 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
19414 functions return the significand and the biased exponent value
19415 respectively of their @code{source} arguments.
19416 When supplied with a 64-bit @code{source} argument, the
19417 result returned by @code{scalar_extract_sig} has
19418 the @code{0x0010000000000000} bit set if the
19419 function's @code{source} argument is in normalized form.
19420 Otherwise, this bit is set to 0.
19421 When supplied with a 128-bit @code{source} argument, the
19422 @code{0x00010000000000000000000000000000} bit of the result is
19424 Note that the sign of the significand is not represented in the result
19425 returned from the @code{scalar_extract_sig} function. Use the
19426 @code{scalar_test_neg} function to test the sign of its @code{double}
19429 The @code{scalar_insert_exp}
19430 functions require a 64-bit environment supporting ISA 3.0 or later.
19431 When supplied with a 64-bit first argument, the
19432 @code{scalar_insert_exp} built-in function returns a double-precision
19433 floating point value that is constructed by assembling the values of its
19434 @code{significand} and @code{exponent} arguments. The sign of the
19435 result is copied from the most significant bit of the
19436 @code{significand} argument. The significand and exponent components
19437 of the result are composed of the least significant 11 bits of the
19438 @code{exponent} argument and the least significant 52 bits of the
19439 @code{significand} argument respectively.
19441 When supplied with a 128-bit first argument, the
19442 @code{scalar_insert_exp} built-in function returns a quad-precision
19443 ieee floating point value. The sign bit of the result is copied from
19444 the most significant bit of the @code{significand} argument.
19445 The significand and exponent components of the result are composed of
19446 the least significant 15 bits of the @code{exponent} argument and the
19447 least significant 112 bits of the @code{significand} argument respectively.
19449 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
19450 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
19451 functions return a non-zero value if @code{arg1} is greater than, less
19452 than, equal to, or not comparable to @code{arg2} respectively. The
19453 arguments are not comparable if one or the other equals NaN (not a
19456 The @code{scalar_test_data_class} built-in function returns 1
19457 if any of the condition tests enabled by the value of the
19458 @code{condition} variable are true, and 0 otherwise. The
19459 @code{condition} argument must be a compile-time constant integer with
19460 value not exceeding 127. The
19461 @code{condition} argument is encoded as a bitmask with each bit
19462 enabling the testing of a different condition, as characterized by the
19466 0x20 Test for +Infinity
19467 0x10 Test for -Infinity
19468 0x08 Test for +Zero
19469 0x04 Test for -Zero
19470 0x02 Test for +Denormal
19471 0x01 Test for -Denormal
19474 The @code{scalar_test_neg} built-in function returns 1 if its
19475 @code{source} argument holds a negative value, 0 otherwise.
19477 The following built-in functions are also available for the PowerPC family
19478 of processors, starting with ISA 3.0 or later
19479 (@option{-mcpu=power9}). These string functions are described
19480 separately in order to group the descriptions closer to the function
19483 Only functions excluded from the PVIPR are listed here.
19486 int vec_all_nez (vector signed char, vector signed char);
19487 int vec_all_nez (vector unsigned char, vector unsigned char);
19488 int vec_all_nez (vector signed short, vector signed short);
19489 int vec_all_nez (vector unsigned short, vector unsigned short);
19490 int vec_all_nez (vector signed int, vector signed int);
19491 int vec_all_nez (vector unsigned int, vector unsigned int);
19493 int vec_any_eqz (vector signed char, vector signed char);
19494 int vec_any_eqz (vector unsigned char, vector unsigned char);
19495 int vec_any_eqz (vector signed short, vector signed short);
19496 int vec_any_eqz (vector unsigned short, vector unsigned short);
19497 int vec_any_eqz (vector signed int, vector signed int);
19498 int vec_any_eqz (vector unsigned int, vector unsigned int);
19500 signed char vec_xlx (unsigned int index, vector signed char data);
19501 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
19502 signed short vec_xlx (unsigned int index, vector signed short data);
19503 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
19504 signed int vec_xlx (unsigned int index, vector signed int data);
19505 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
19506 float vec_xlx (unsigned int index, vector float data);
19508 signed char vec_xrx (unsigned int index, vector signed char data);
19509 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
19510 signed short vec_xrx (unsigned int index, vector signed short data);
19511 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
19512 signed int vec_xrx (unsigned int index, vector signed int data);
19513 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
19514 float vec_xrx (unsigned int index, vector float data);
19517 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
19518 perform pairwise comparisons between the elements at the same
19519 positions within their two vector arguments.
19520 The @code{vec_all_nez} function returns a
19521 non-zero value if and only if all pairwise comparisons are not
19522 equal and no element of either vector argument contains a zero.
19523 The @code{vec_any_eqz} function returns a
19524 non-zero value if and only if at least one pairwise comparison is equal
19525 or if at least one element of either vector argument contains a zero.
19526 The @code{vec_cmpnez} function returns a vector of the same type as
19527 its two arguments, within which each element consists of all ones to
19528 denote that either the corresponding elements of the incoming arguments are
19529 not equal or that at least one of the corresponding elements contains
19530 zero. Otherwise, the element of the returned vector contains all zeros.
19532 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
19533 element selected by the @code{index} argument from the vector
19534 represented by the @code{data} argument. The @code{index} argument
19535 always specifies a byte offset, regardless of the size of the vector
19536 element. With @code{vec_xlx}, @code{index} is the offset of the first
19537 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
19538 represents the last byte of the element to be extracted, measured
19539 from the right end of the vector. In other words, the last byte of
19540 the element to be extracted is found at position @code{(15 - index)}.
19541 There is no requirement that @code{index} be a multiple of the vector
19542 element size. However, if the size of the vector element added to
19543 @code{index} is greater than 15, the content of the returned value is
19546 The following functions are also available if the ISA 3.0 instruction
19547 set additions (@option{-mcpu=power9}) are available.
19549 Only functions excluded from the PVIPR are listed here.
19552 vector long long vec_vctz (vector long long);
19553 vector unsigned long long vec_vctz (vector unsigned long long);
19554 vector int vec_vctz (vector int);
19555 vector unsigned int vec_vctz (vector int);
19556 vector short vec_vctz (vector short);
19557 vector unsigned short vec_vctz (vector unsigned short);
19558 vector signed char vec_vctz (vector signed char);
19559 vector unsigned char vec_vctz (vector unsigned char);
19561 vector signed char vec_vctzb (vector signed char);
19562 vector unsigned char vec_vctzb (vector unsigned char);
19564 vector long long vec_vctzd (vector long long);
19565 vector unsigned long long vec_vctzd (vector unsigned long long);
19567 vector short vec_vctzh (vector short);
19568 vector unsigned short vec_vctzh (vector unsigned short);
19570 vector int vec_vctzw (vector int);
19571 vector unsigned int vec_vctzw (vector int);
19573 vector int vec_vprtyb (vector int);
19574 vector unsigned int vec_vprtyb (vector unsigned int);
19575 vector long long vec_vprtyb (vector long long);
19576 vector unsigned long long vec_vprtyb (vector unsigned long long);
19578 vector int vec_vprtybw (vector int);
19579 vector unsigned int vec_vprtybw (vector unsigned int);
19581 vector long long vec_vprtybd (vector long long);
19582 vector unsigned long long vec_vprtybd (vector unsigned long long);
19585 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
19589 vector long vec_vprtyb (vector long);
19590 vector unsigned long vec_vprtyb (vector unsigned long);
19591 vector __int128 vec_vprtyb (vector __int128);
19592 vector __uint128 vec_vprtyb (vector __uint128);
19594 vector long vec_vprtybd (vector long);
19595 vector unsigned long vec_vprtybd (vector unsigned long);
19597 vector __int128 vec_vprtybq (vector __int128);
19598 vector __uint128 vec_vprtybd (vector __uint128);
19601 The following built-in functions are available for the PowerPC family
19602 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}).
19604 Only functions excluded from the PVIPR are listed here.
19607 __vector unsigned char
19608 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
19609 __vector unsigned short
19610 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
19611 __vector unsigned int
19612 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
19615 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
19616 @code{vec_absdw} built-in functions each computes the absolute
19617 differences of the pairs of vector elements supplied in its two vector
19618 arguments, placing the absolute differences into the corresponding
19619 elements of the vector result.
19621 The following built-in functions are available for the PowerPC family
19622 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
19624 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
19625 vector unsigned long long vec_vrlnm (vector unsigned long long,
19626 vector unsigned long long);
19629 The result of @code{vec_vrlnm} is obtained by rotating each element
19630 of the first argument vector left and ANDing it with a mask. The
19631 second argument vector contains the mask beginning in bits 11:15,
19632 the mask end in bits 19:23, and the shift count in bits 27:31,
19635 If the cryptographic instructions are enabled (@option{-mcrypto} or
19636 @option{-mcpu=power8}), the following builtins are enabled.
19638 Only functions excluded from the PVIPR are listed here.
19641 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
19643 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
19644 vector unsigned long long);
19646 vector unsigned long long __builtin_crypto_vcipherlast
19647 (vector unsigned long long,
19648 vector unsigned long long);
19650 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
19651 vector unsigned long long);
19653 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
19654 vector unsigned long long);
19656 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
19657 vector unsigned char,
19658 vector unsigned char);
19660 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
19661 vector unsigned short,
19662 vector unsigned short);
19664 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
19665 vector unsigned int,
19666 vector unsigned int);
19668 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
19669 vector unsigned long long,
19670 vector unsigned long long);
19672 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
19673 vector unsigned char);
19675 vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short,
19676 vector unsigned short);
19678 vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int,
19679 vector unsigned int);
19681 vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long,
19682 vector unsigned long long);
19684 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
19687 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
19690 The second argument to @var{__builtin_crypto_vshasigmad} and
19691 @var{__builtin_crypto_vshasigmaw} must be a constant
19692 integer that is 0 or 1. The third argument to these built-in functions
19693 must be a constant integer in the range of 0 to 15.
19695 The following sign extension builtins are provided:
19698 vector signed int vec_signexti (vector signed char a)
19699 vector signed long long vec_signextll (vector signed char a)
19700 vector signed int vec_signexti (vector signed short a)
19701 vector signed long long vec_signextll (vector signed short a)
19702 vector signed long long vec_signextll (vector signed int a)
19703 vector signed long long vec_signextq (vector signed long long a)
19706 Each element of the result is produced by sign-extending the element of the
19707 input vector that would fall in the least significant portion of the result
19708 element. For example, a sign-extension of a vector signed char to a vector
19709 signed long long will sign extend the rightmost byte of each doubleword.
19711 @node PowerPC AltiVec Built-in Functions Available on ISA 3.1
19712 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1
19714 The following additional built-in functions are also available for the
19715 PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}):
19719 @exdent vector unsigned long long int
19720 @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int)
19722 Perform a vector centrifuge operation, as if implemented by the
19723 @code{vcfuged} instruction.
19727 @exdent vector unsigned long long int
19728 @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int)
19730 Perform a vector count leading zeros under bit mask operation, as if
19731 implemented by the @code{vclzdm} instruction.
19735 @exdent vector unsigned long long int
19736 @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int)
19738 Perform a vector count trailing zeros under bit mask operation, as if
19739 implemented by the @code{vctzdm} instruction.
19743 @exdent vector signed char
19744 @exdent vec_clrl (vector signed char a, unsigned int n)
19745 @exdent vector unsigned char
19746 @exdent vec_clrl (vector unsigned char a, unsigned int n)
19748 Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if
19749 implemented by the @code{vclrlb} instruction on a big-endian target
19750 and by the @code{vclrrb} instruction on a little-endian target. A
19751 value of @code{n} that is greater than 16 is treated as if it equaled 16.
19755 @exdent vector signed char
19756 @exdent vec_clrr (vector signed char a, unsigned int n)
19757 @exdent vector unsigned char
19758 @exdent vec_clrr (vector unsigned char a, unsigned int n)
19760 Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if
19761 implemented by the @code{vclrrb} instruction on a big-endian target
19762 and by the @code{vclrlb} instruction on a little-endian target. A
19763 value of @code{n} that is greater than 16 is treated as if it equaled 16.
19767 @exdent vector unsigned long long int
19768 @exdent vec_gnb (vector unsigned __int128, const unsigned char)
19770 Perform a 128-bit vector gather operation, as if implemented by the
19771 @code{vgnb} instruction. The second argument must be a literal
19772 integer value between 2 and 7 inclusive.
19779 @exdent vector unsigned long long int
19780 @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int)
19781 @exdent vector unsigned long long int
19782 @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int)
19783 @exdent vector unsigned long long int
19784 @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int)
19785 @exdent vector unsigned long long int
19786 @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int)
19788 Extract an element from two concatenated vectors starting at the given byte index
19789 in natural-endian order, and place it zero-extended in doubleword 1 of the result
19790 according to natural element order. If the byte index is out of range for the
19791 data type, the intrinsic will be rejected.
19792 For little-endian, this output will match the placement by the hardware
19793 instruction, i.e., dword[0] in RTL notation. For big-endian, an additional
19794 instruction is needed to move it from the "left" doubleword to the "right" one.
19795 For little-endian, semantics matching the @code{vextdubvrx},
19796 @code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for
19797 big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx},
19798 @code{vextduwvlx} instructions
19799 will be generated. Note that some fairly anomalous results can be generated if
19800 the byte index is not aligned on an element boundary for the element being
19801 extracted. This is a limitation of the bi-endian vector programming model is
19802 consistent with the limitation on @code{vec_perm}.
19803 @findex vec_extractl
19806 @exdent vector unsigned long long int
19807 @exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int)
19808 @exdent vector unsigned long long int
19809 @exdent vec_extracth (vector unsigned short, vector unsigned short,
19811 @exdent vector unsigned long long int
19812 @exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int)
19813 @exdent vector unsigned long long int
19814 @exdent vec_extracth (vector unsigned long long, vector unsigned long long,
19817 Extract an element from two concatenated vectors starting at the given byte
19818 index. The index is based on big endian order for a little endian system.
19819 Similarly, the index is based on little endian order for a big endian system.
19820 The extraced elements are zero-extended and put in doubleword 1
19821 according to natural element order. If the byte index is out of range for the
19822 data type, the intrinsic will be rejected. For little-endian, this output
19823 will match the placement by the hardware instruction (vextdubvrx, vextduhvrx,
19824 vextduwvrx, vextddvrx) i.e., dword[0] in RTL
19825 notation. For big-endian, an additional instruction is needed to move it
19826 from the "left" doubleword to the "right" one. For little-endian, semantics
19827 matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx}
19828 instructions will be generated, while for big-endian, semantics matching the
19829 @code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will
19830 be generated. Note that some fairly anomalous
19831 results can be generated if the byte index is not aligned on the
19832 element boundary for the element being extracted. This is a
19833 limitation of the bi-endian vector programming model consistent with the
19834 limitation on @code{vec_perm}.
19835 @findex vec_extracth
19837 @exdent vector unsigned long long int
19838 @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int)
19840 Perform a vector parallel bits deposit operation, as if implemented by
19841 the @code{vpdepd} instruction.
19847 @exdent vector unsigned char
19848 @exdent vec_insertl (unsigned char, vector unsigned char, unsigned int);
19849 @exdent vector unsigned short
19850 @exdent vec_insertl (unsigned short, vector unsigned short, unsigned int);
19851 @exdent vector unsigned int
19852 @exdent vec_insertl (unsigned int, vector unsigned int, unsigned int);
19853 @exdent vector unsigned long long
19854 @exdent vec_insertl (unsigned long long, vector unsigned long long,
19856 @exdent vector unsigned char
19857 @exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int;
19858 @exdent vector unsigned short
19859 @exdent vec_insertl (vector unsigned short, vector unsigned short,
19861 @exdent vector unsigned int
19862 @exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int);
19865 Let src be the first argument, when the first argument is a scalar, or the
19866 rightmost element of the left doubleword of the first argument, when the first
19867 argument is a vector. Insert the source into the destination at the position
19868 given by the third argument, using natural element order in the second
19869 argument. The rest of the second argument is unchanged. If the byte
19870 index is greater than 14 for halfwords, greater than 12 for words, or
19871 greater than 8 for doublewords the result is undefined. For little-endian,
19872 the generated code will be semantically equivalent to @code{vins[bhwd]rx}
19873 instructions. Similarly for big-endian it will be semantically equivalent
19874 to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be
19875 generated if the byte index is not aligned on an element boundary for the
19876 type of element being inserted.
19877 @findex vec_insertl
19880 @exdent vector unsigned char
19881 @exdent vec_inserth (unsigned char, vector unsigned char, unsigned int);
19882 @exdent vector unsigned short
19883 @exdent vec_inserth (unsigned short, vector unsigned short, unsigned int);
19884 @exdent vector unsigned int
19885 @exdent vec_inserth (unsigned int, vector unsigned int, unsigned int);
19886 @exdent vector unsigned long long
19887 @exdent vec_inserth (unsigned long long, vector unsigned long long,
19889 @exdent vector unsigned char
19890 @exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int);
19891 @exdent vector unsigned short
19892 @exdent vec_inserth (vector unsigned short, vector unsigned short,
19894 @exdent vector unsigned int
19895 @exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int);
19898 Let src be the first argument, when the first argument is a scalar, or the
19899 rightmost element of the first argument, when the first argument is a vector.
19900 Insert src into the second argument at the position identified by the third
19901 argument, using opposite element order in the second argument, and leaving the
19902 rest of the second argument unchanged. If the byte index is greater than 14
19903 for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be
19904 rejected. Note that the underlying hardware instruction uses the same register
19905 for the second argument and the result.
19906 For little-endian, the code generation will be semantically equivalent to
19907 @code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to
19908 @code{vins[bhwd]rx}.
19909 Note that some fairly anomalous results can be generated if the byte index is
19910 not aligned on an element boundary for the sort of element being inserted.
19911 @findex vec_inserth
19913 Vector Replace Element
19915 @exdent vector signed int vec_replace_elt (vector signed int, signed int,
19917 @exdent vector unsigned int vec_replace_elt (vector unsigned int,
19918 unsigned int, const int);
19919 @exdent vector float vec_replace_elt (vector float, float, const int);
19920 @exdent vector signed long long vec_replace_elt (vector signed long long,
19921 signed long long, const int);
19922 @exdent vector unsigned long long vec_replace_elt (vector unsigned long long,
19923 unsigned long long, const int);
19924 @exdent vector double rec_replace_elt (vector double, double, const int);
19926 The third argument (constrained to [0,3]) identifies the natural-endian
19927 element number of the first argument that will be replaced by the second
19928 argument to produce the result. The other elements of the first argument will
19929 remain unchanged in the result.
19931 If it's desirable to insert a word at an unaligned position, use
19932 vec_replace_unaligned instead.
19934 @findex vec_replace_element
19936 Vector Replace Unaligned
19938 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19939 signed int, const int);
19940 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19941 unsigned int, const int);
19942 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19944 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19945 signed long long, const int);
19946 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19947 unsigned long long, const int);
19948 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19949 double, const int);
19952 The second argument replaces a portion of the first argument to produce the
19953 result, with the rest of the first argument unchanged in the result. The
19954 third argument identifies the byte index (using left-to-right, or big-endian
19955 order) where the high-order byte of the second argument will be placed, with
19956 the remaining bytes of the second argument placed naturally "to the right"
19957 of the high-order byte.
19959 The programmer is responsible for understanding the endianness issues involved
19960 with the first argument and the result.
19961 @findex vec_replace_unaligned
19963 Vector Shift Left Double Bit Immediate
19965 @exdent vector signed char vec_sldb (vector signed char, vector signed char,
19966 const unsigned int);
19967 @exdent vector unsigned char vec_sldb (vector unsigned char,
19968 vector unsigned char, const unsigned int);
19969 @exdent vector signed short vec_sldb (vector signed short, vector signed short,
19970 const unsigned int);
19971 @exdent vector unsigned short vec_sldb (vector unsigned short,
19972 vector unsigned short, const unsigned int);
19973 @exdent vector signed int vec_sldb (vector signed int, vector signed int,
19974 const unsigned int);
19975 @exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int,
19976 const unsigned int);
19977 @exdent vector signed long long vec_sldb (vector signed long long,
19978 vector signed long long, const unsigned int);
19979 @exdent vector unsigned long long vec_sldb (vector unsigned long long,
19980 vector unsigned long long, const unsigned int);
19983 Shift the combined input vectors left by the amount specified by the low-order
19984 three bits of the third argument, and return the leftmost remaining 128 bits.
19985 Code using this instruction must be endian-aware.
19989 Vector Shift Right Double Bit Immediate
19992 @exdent vector signed char vec_srdb (vector signed char, vector signed char,
19993 const unsigned int);
19994 @exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char,
19995 const unsigned int);
19996 @exdent vector signed short vec_srdb (vector signed short, vector signed short,
19997 const unsigned int);
19998 @exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short,
19999 const unsigned int);
20000 @exdent vector signed int vec_srdb (vector signed int, vector signed int,
20001 const unsigned int);
20002 @exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int,
20003 const unsigned int);
20004 @exdent vector signed long long vec_srdb (vector signed long long,
20005 vector signed long long, const unsigned int);
20006 @exdent vector unsigned long long vec_srdb (vector unsigned long long,
20007 vector unsigned long long, const unsigned int);
20010 Shift the combined input vectors right by the amount specified by the low-order
20011 three bits of the third argument, and return the remaining 128 bits. Code
20012 using this built-in must be endian-aware.
20019 @exdent vector signed int vec_splati (const signed int);
20020 @exdent vector float vec_splati (const float);
20023 Splat a 32-bit immediate into a vector of words.
20028 @exdent vector double vec_splatid (const float);
20031 Convert a single precision floating-point value to double-precision and splat
20032 the result to a vector of double-precision floats.
20034 @findex vec_splatid
20037 @exdent vector signed int vec_splati_ins (vector signed int,
20038 const unsigned int, const signed int);
20039 @exdent vector unsigned int vec_splati_ins (vector unsigned int,
20040 const unsigned int, const unsigned int);
20041 @exdent vector float vec_splati_ins (vector float, const unsigned int,
20045 Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word
20046 identified by argument 2 of each doubleword of argument 1 and return the
20047 result. The other words of argument 1 are unchanged.
20049 @findex vec_splati_ins
20051 Vector Blend Variable
20054 @exdent vector signed char vec_blendv (vector signed char, vector signed char,
20055 vector unsigned char);
20056 @exdent vector unsigned char vec_blendv (vector unsigned char,
20057 vector unsigned char, vector unsigned char);
20058 @exdent vector signed short vec_blendv (vector signed short,
20059 vector signed short, vector unsigned short);
20060 @exdent vector unsigned short vec_blendv (vector unsigned short,
20061 vector unsigned short, vector unsigned short);
20062 @exdent vector signed int vec_blendv (vector signed int, vector signed int,
20063 vector unsigned int);
20064 @exdent vector unsigned int vec_blendv (vector unsigned int,
20065 vector unsigned int, vector unsigned int);
20066 @exdent vector signed long long vec_blendv (vector signed long long,
20067 vector signed long long, vector unsigned long long);
20068 @exdent vector unsigned long long vec_blendv (vector unsigned long long,
20069 vector unsigned long long, vector unsigned long long);
20070 @exdent vector float vec_blendv (vector float, vector float,
20071 vector unsigned int);
20072 @exdent vector double vec_blendv (vector double, vector double,
20073 vector unsigned long long);
20076 Blend the first and second argument vectors according to the sign bits of the
20077 corresponding elements of the third argument vector. This is similar to the
20078 @code{vsel} and @code{xxsel} instructions but for bigger elements.
20082 Vector Permute Extended
20085 @exdent vector signed char vec_permx (vector signed char, vector signed char,
20086 vector unsigned char, const int);
20087 @exdent vector unsigned char vec_permx (vector unsigned char,
20088 vector unsigned char, vector unsigned char, const int);
20089 @exdent vector signed short vec_permx (vector signed short,
20090 vector signed short, vector unsigned char, const int);
20091 @exdent vector unsigned short vec_permx (vector unsigned short,
20092 vector unsigned short, vector unsigned char, const int);
20093 @exdent vector signed int vec_permx (vector signed int, vector signed int,
20094 vector unsigned char, const int);
20095 @exdent vector unsigned int vec_permx (vector unsigned int,
20096 vector unsigned int, vector unsigned char, const int);
20097 @exdent vector signed long long vec_permx (vector signed long long,
20098 vector signed long long, vector unsigned char, const int);
20099 @exdent vector unsigned long long vec_permx (vector unsigned long long,
20100 vector unsigned long long, vector unsigned char, const int);
20101 @exdent vector float (vector float, vector float, vector unsigned char,
20103 @exdent vector double (vector double, vector double, vector unsigned char,
20107 Perform a partial permute of the first two arguments, which form a 32-byte
20108 section of an emulated vector up to 256 bytes wide, using the partial permute
20109 control vector in the third argument. The fourth argument (constrained to
20110 values of 0-7) identifies which 32-byte section of the emulated vector is
20111 contained in the first two arguments.
20115 @exdent vector unsigned long long int
20116 @exdent vec_pext (vector unsigned long long int, vector unsigned long long int)
20118 Perform a vector parallel bit extract operation, as if implemented by
20119 the @code{vpextd} instruction.
20123 @exdent vector unsigned char vec_stril (vector unsigned char)
20124 @exdent vector signed char vec_stril (vector signed char)
20125 @exdent vector unsigned short vec_stril (vector unsigned short)
20126 @exdent vector signed short vec_stril (vector signed short)
20128 Isolate the left-most non-zero elements of the incoming vector argument,
20129 replacing all elements to the right of the left-most zero element
20130 found within the argument with zero. The typical implementation uses
20131 the @code{vstribl} or @code{vstrihl} instruction on big-endian targets
20132 and uses the @code{vstribr} or @code{vstrihr} instruction on
20133 little-endian targets.
20137 @exdent int vec_stril_p (vector unsigned char)
20138 @exdent int vec_stril_p (vector signed char)
20139 @exdent int short vec_stril_p (vector unsigned short)
20140 @exdent int vec_stril_p (vector signed short)
20142 Return a non-zero value if and only if the argument contains a zero
20143 element. The typical implementation uses
20144 the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets
20145 and uses the @code{vstribr.} or @code{vstrihr.} instruction on
20146 little-endian targets. Choose this built-in to check for presence of
20147 zero element if the same argument is also passed to @code{vec_stril}.
20148 @findex vec_stril_p
20151 @exdent vector unsigned char vec_strir (vector unsigned char)
20152 @exdent vector signed char vec_strir (vector signed char)
20153 @exdent vector unsigned short vec_strir (vector unsigned short)
20154 @exdent vector signed short vec_strir (vector signed short)
20156 Isolate the right-most non-zero elements of the incoming vector argument,
20157 replacing all elements to the left of the right-most zero element
20158 found within the argument with zero. The typical implementation uses
20159 the @code{vstribr} or @code{vstrihr} instruction on big-endian targets
20160 and uses the @code{vstribl} or @code{vstrihl} instruction on
20161 little-endian targets.
20165 @exdent int vec_strir_p (vector unsigned char)
20166 @exdent int vec_strir_p (vector signed char)
20167 @exdent int short vec_strir_p (vector unsigned short)
20168 @exdent int vec_strir_p (vector signed short)
20170 Return a non-zero value if and only if the argument contains a zero
20171 element. The typical implementation uses
20172 the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets
20173 and uses the @code{vstribl.} or @code{vstrihl.} instruction on
20174 little-endian targets. Choose this built-in to check for presence of
20175 zero element if the same argument is also passed to @code{vec_strir}.
20176 @findex vec_strir_p
20179 @exdent vector unsigned char
20180 @exdent vec_ternarylogic (vector unsigned char, vector unsigned char,
20181 vector unsigned char, const unsigned int)
20182 @exdent vector unsigned short
20183 @exdent vec_ternarylogic (vector unsigned short, vector unsigned short,
20184 vector unsigned short, const unsigned int)
20185 @exdent vector unsigned int
20186 @exdent vec_ternarylogic (vector unsigned int, vector unsigned int,
20187 vector unsigned int, const unsigned int)
20188 @exdent vector unsigned long long int
20189 @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int,
20190 vector unsigned long long int, const unsigned int)
20191 @exdent vector unsigned __int128
20192 @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128,
20193 vector unsigned __int128, const unsigned int)
20195 Perform a 128-bit vector evaluate operation, as if implemented by the
20196 @code{xxeval} instruction. The fourth argument must be a literal
20197 integer value between 0 and 255 inclusive.
20198 @findex vec_ternarylogic
20201 @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int)
20202 @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int)
20203 @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int)
20204 @exdent vector unsigned int vec_genpcvm (vector unsigned long long int,
20208 Vector Integer Multiply/Divide/Modulo
20211 @exdent vector signed int
20212 @exdent vec_mulh (vector signed int a, vector signed int b)
20213 @exdent vector unsigned int
20214 @exdent vec_mulh (vector unsigned int a, vector unsigned int b)
20217 For each integer value @code{i} from 0 to 3, do the following. The integer
20218 value in word element @code{i} of a is multiplied by the integer value in word
20219 element @code{i} of b. The high-order 32 bits of the 64-bit product are placed
20220 into word element @code{i} of the vector returned.
20223 @exdent vector signed long long
20224 @exdent vec_mulh (vector signed long long a, vector signed long long b)
20225 @exdent vector unsigned long long
20226 @exdent vec_mulh (vector unsigned long long a, vector unsigned long long b)
20229 For each integer value @code{i} from 0 to 1, do the following. The integer
20230 value in doubleword element @code{i} of a is multiplied by the integer value in
20231 doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product
20232 are placed into doubleword element @code{i} of the vector returned.
20235 @exdent vector unsigned long long
20236 @exdent vec_mul (vector unsigned long long a, vector unsigned long long b)
20237 @exdent vector signed long long
20238 @exdent vec_mul (vector signed long long a, vector signed long long b)
20241 For each integer value @code{i} from 0 to 1, do the following. The integer
20242 value in doubleword element @code{i} of a is multiplied by the integer value in
20243 doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product
20244 are placed into doubleword element @code{i} of the vector returned.
20247 @exdent vector signed int
20248 @exdent vec_div (vector signed int a, vector signed int b)
20249 @exdent vector unsigned int
20250 @exdent vec_div (vector unsigned int a, vector unsigned int b)
20253 For each integer value @code{i} from 0 to 3, do the following. The integer in
20254 word element @code{i} of a is divided by the integer in word element @code{i}
20255 of b. The unique integer quotient is placed into the word element @code{i} of
20256 the vector returned. If an attempt is made to perform any of the divisions
20257 <anything> ÷ 0 then the quotient is undefined.
20260 @exdent vector signed long long
20261 @exdent vec_div (vector signed long long a, vector signed long long b)
20262 @exdent vector unsigned long long
20263 @exdent vec_div (vector unsigned long long a, vector unsigned long long b)
20266 For each integer value @code{i} from 0 to 1, do the following. The integer in
20267 doubleword element @code{i} of a is divided by the integer in doubleword
20268 element @code{i} of b. The unique integer quotient is placed into the
20269 doubleword element @code{i} of the vector returned. If an attempt is made to
20270 perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then
20271 the quotient is undefined.
20274 @exdent vector signed int
20275 @exdent vec_dive (vector signed int a, vector signed int b)
20276 @exdent vector unsigned int
20277 @exdent vec_dive (vector unsigned int a, vector unsigned int b)
20280 For each integer value @code{i} from 0 to 3, do the following. The integer in
20281 word element @code{i} of a is shifted left by 32 bits, then divided by the
20282 integer in word element @code{i} of b. The unique integer quotient is placed
20283 into the word element @code{i} of the vector returned. If the quotient cannot
20284 be represented in 32 bits, or if an attempt is made to perform any of the
20285 divisions <anything> ÷ 0 then the quotient is undefined.
20288 @exdent vector signed long long
20289 @exdent vec_dive (vector signed long long a, vector signed long long b)
20290 @exdent vector unsigned long long
20291 @exdent vec_dive (vector unsigned long long a, vector unsigned long long b)
20294 For each integer value @code{i} from 0 to 1, do the following. The integer in
20295 doubleword element @code{i} of a is shifted left by 64 bits, then divided by
20296 the integer in doubleword element @code{i} of b. The unique integer quotient is
20297 placed into the doubleword element @code{i} of the vector returned. If the
20298 quotient cannot be represented in 64 bits, or if an attempt is made to perform
20299 <anything> ÷ 0 then the quotient is undefined.
20302 @exdent vector signed int
20303 @exdent vec_mod (vector signed int a, vector signed int b)
20304 @exdent vector unsigned int
20305 @exdent vec_mod (vector unsigned int a, vector unsigned int b)
20308 For each integer value @code{i} from 0 to 3, do the following. The integer in
20309 word element @code{i} of a is divided by the integer in word element @code{i}
20310 of b. The unique integer remainder is placed into the word element @code{i} of
20311 the vector returned. If an attempt is made to perform any of the divisions
20312 0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined.
20315 @exdent vector signed long long
20316 @exdent vec_mod (vector signed long long a, vector signed long long b)
20317 @exdent vector unsigned long long
20318 @exdent vec_mod (vector unsigned long long a, vector unsigned long long b)
20321 For each integer value @code{i} from 0 to 1, do the following. The integer in
20322 doubleword element @code{i} of a is divided by the integer in doubleword
20323 element @code{i} of b. The unique integer remainder is placed into the
20324 doubleword element @code{i} of the vector returned. If an attempt is made to
20325 perform <anything> ÷ 0 then the remainder is undefined.
20327 Generate PCV from specified Mask size, as if implemented by the
20328 @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where
20329 immediate value is either 0, 1, 2 or 3.
20330 @findex vec_genpcvm
20333 @exdent vector unsigned __int128 vec_rl (vector unsigned __int128 A,
20334 vector unsigned __int128 B);
20335 @exdent vector signed __int128 vec_rl (vector signed __int128 A,
20336 vector unsigned __int128 B);
20339 Result value: Each element of R is obtained by rotating the corresponding element
20340 of A left by the number of bits specified by the corresponding element of B.
20344 @exdent vector unsigned __int128 vec_rlmi (vector unsigned __int128,
20345 vector unsigned __int128,
20346 vector unsigned __int128);
20347 @exdent vector signed __int128 vec_rlmi (vector signed __int128,
20348 vector signed __int128,
20349 vector unsigned __int128);
20352 Returns the result of rotating the first input and inserting it under mask
20353 into the second input. The first bit in the mask, the last bit in the mask are
20354 obtained from the two 7-bit fields bits [108:115] and bits [117:123]
20355 respectively of the second input. The shift is obtained from the third input
20356 in the 7-bit field [125:131] where all bits counted from zero at the left.
20359 @exdent vector unsigned __int128 vec_rlnm (vector unsigned __int128,
20360 vector unsigned __int128,
20361 vector unsigned __int128);
20362 @exdent vector signed __int128 vec_rlnm (vector signed __int128,
20363 vector unsigned __int128,
20364 vector unsigned __int128);
20367 Returns the result of rotating the first input and ANDing it with a mask. The
20368 first bit in the mask and the last bit in the mask are obtained from the two
20369 7-bit fields bits [117:123] and bits [125:131] respectively of the second
20370 input. The shift is obtained from the third input in the 7-bit field bits
20371 [125:131] where all bits counted from zero at the left.
20374 @exdent vector unsigned __int128 vec_sl(vector unsigned __int128 A, vector unsigned __int128 B);
20375 @exdent vector signed __int128 vec_sl(vector signed __int128 A, vector unsigned __int128 B);
20378 Result value: Each element of R is obtained by shifting the corresponding element of
20379 A left by the number of bits specified by the corresponding element of B.
20382 @exdent vector unsigned __int128 vec_sr(vector unsigned __int128 A, vector unsigned __int128 B);
20383 @exdent vector signed __int128 vec_sr(vector signed __int128 A, vector unsigned __int128 B);
20386 Result value: Each element of R is obtained by shifting the corresponding element of
20387 A right by the number of bits specified by the corresponding element of B.
20390 @exdent vector unsigned __int128 vec_sra(vector unsigned __int128 A, vector unsigned __int128 B);
20391 @exdent vector signed __int128 vec_sra(vector signed __int128 A, vector unsigned __int128 B);
20394 Result value: Each element of R is obtained by arithmetic shifting the corresponding
20395 element of A right by the number of bits specified by the corresponding element of B.
20398 @exdent vector unsigned __int128 vec_mule (vector unsigned long long,
20399 vector unsigned long long);
20400 @exdent vector signed __int128 vec_mule (vector signed long long,
20401 vector signed long long);
20404 Returns a vector containing a 128-bit integer result of multiplying the even
20405 doubleword elements of the two inputs.
20408 @exdent vector unsigned __int128 vec_mulo (vector unsigned long long,
20409 vector unsigned long long);
20410 @exdent vector signed __int128 vec_mulo (vector signed long long,
20411 vector signed long long);
20414 Returns a vector containing a 128-bit integer result of multiplying the odd
20415 doubleword elements of the two inputs.
20418 @exdent vector unsigned __int128 vec_div (vector unsigned __int128,
20419 vector unsigned __int128);
20420 @exdent vector signed __int128 vec_div (vector signed __int128,
20421 vector signed __int128);
20424 Returns the result of dividing the first operand by the second operand. An
20425 attempt to divide any value by zero or to divide the most negative signed
20426 128-bit integer by negative one results in an undefined value.
20429 @exdent vector unsigned __int128 vec_dive (vector unsigned __int128,
20430 vector unsigned __int128);
20431 @exdent vector signed __int128 vec_dive (vector signed __int128,
20432 vector signed __int128);
20435 The result is produced by shifting the first input left by 128 bits and
20436 dividing by the second. If an attempt is made to divide by zero or the result
20437 is larger than 128 bits, the result is undefined.
20440 @exdent vector unsigned __int128 vec_mod (vector unsigned __int128,
20441 vector unsigned __int128);
20442 @exdent vector signed __int128 vec_mod (vector signed __int128,
20443 vector signed __int128);
20446 The result is the modulo result of dividing the first input by the second
20449 The following builtins perform 128-bit vector comparisons. The
20450 @code{vec_all_xx}, @code{vec_any_xx}, and @code{vec_cmpxx}, where @code{xx} is
20451 one of the operations @code{eq, ne, gt, lt, ge, le} perform pairwise
20452 comparisons between the elements at the same positions within their two vector
20453 arguments. The @code{vec_all_xx}function returns a non-zero value if and only
20454 if all pairwise comparisons are true. The @code{vec_any_xx} function returns
20455 a non-zero value if and only if at least one pairwise comparison is true. The
20456 @code{vec_cmpxx}function returns a vector of the same type as its two
20457 arguments, within which each element consists of all ones to denote that
20458 specified logical comparison of the corresponding elements was true.
20459 Otherwise, the element of the returned vector contains all zeros.
20462 vector bool __int128 vec_cmpeq (vector signed __int128, vector signed __int128);
20463 vector bool __int128 vec_cmpeq (vector unsigned __int128, vector unsigned __int128);
20464 vector bool __int128 vec_cmpne (vector signed __int128, vector signed __int128);
20465 vector bool __int128 vec_cmpne (vector unsigned __int128, vector unsigned __int128);
20466 vector bool __int128 vec_cmpgt (vector signed __int128, vector signed __int128);
20467 vector bool __int128 vec_cmpgt (vector unsigned __int128, vector unsigned __int128);
20468 vector bool __int128 vec_cmplt (vector signed __int128, vector signed __int128);
20469 vector bool __int128 vec_cmplt (vector unsigned __int128, vector unsigned __int128);
20470 vector bool __int128 vec_cmpge (vector signed __int128, vector signed __int128);
20471 vector bool __int128 vec_cmpge (vector unsigned __int128, vector unsigned __int128);
20472 vector bool __int128 vec_cmple (vector signed __int128, vector signed __int128);
20473 vector bool __int128 vec_cmple (vector unsigned __int128, vector unsigned __int128);
20475 int vec_all_eq (vector signed __int128, vector signed __int128);
20476 int vec_all_eq (vector unsigned __int128, vector unsigned __int128);
20477 int vec_all_ne (vector signed __int128, vector signed __int128);
20478 int vec_all_ne (vector unsigned __int128, vector unsigned __int128);
20479 int vec_all_gt (vector signed __int128, vector signed __int128);
20480 int vec_all_gt (vector unsigned __int128, vector unsigned __int128);
20481 int vec_all_lt (vector signed __int128, vector signed __int128);
20482 int vec_all_lt (vector unsigned __int128, vector unsigned __int128);
20483 int vec_all_ge (vector signed __int128, vector signed __int128);
20484 int vec_all_ge (vector unsigned __int128, vector unsigned __int128);
20485 int vec_all_le (vector signed __int128, vector signed __int128);
20486 int vec_all_le (vector unsigned __int128, vector unsigned __int128);
20488 int vec_any_eq (vector signed __int128, vector signed __int128);
20489 int vec_any_eq (vector unsigned __int128, vector unsigned __int128);
20490 int vec_any_ne (vector signed __int128, vector signed __int128);
20491 int vec_any_ne (vector unsigned __int128, vector unsigned __int128);
20492 int vec_any_gt (vector signed __int128, vector signed __int128);
20493 int vec_any_gt (vector unsigned __int128, vector unsigned __int128);
20494 int vec_any_lt (vector signed __int128, vector signed __int128);
20495 int vec_any_lt (vector unsigned __int128, vector unsigned __int128);
20496 int vec_any_ge (vector signed __int128, vector signed __int128);
20497 int vec_any_ge (vector unsigned __int128, vector unsigned __int128);
20498 int vec_any_le (vector signed __int128, vector signed __int128);
20499 int vec_any_le (vector unsigned __int128, vector unsigned __int128);
20503 @node PowerPC Hardware Transactional Memory Built-in Functions
20504 @subsection PowerPC Hardware Transactional Memory Built-in Functions
20505 GCC provides two interfaces for accessing the Hardware Transactional
20506 Memory (HTM) instructions available on some of the PowerPC family
20507 of processors (eg, POWER8). The two interfaces come in a low level
20508 interface, consisting of built-in functions specific to PowerPC and a
20509 higher level interface consisting of inline functions that are common
20510 between PowerPC and S/390.
20512 @subsubsection PowerPC HTM Low Level Built-in Functions
20514 The following low level built-in functions are available with
20515 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
20516 They all generate the machine instruction that is part of the name.
20518 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
20519 the full 4-bit condition register value set by their associated hardware
20520 instruction. The header file @code{htmintrin.h} defines some macros that can
20521 be used to decipher the return value. The @code{__builtin_tbegin} builtin
20522 returns a simple @code{true} or @code{false} value depending on whether a transaction was
20523 successfully started or not. The arguments of the builtins match exactly the
20524 type and order of the associated hardware instruction's operands, except for
20525 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
20526 Refer to the ISA manual for a description of each instruction's operands.
20529 unsigned int __builtin_tbegin (unsigned int)
20530 unsigned int __builtin_tend (unsigned int)
20532 unsigned int __builtin_tabort (unsigned int)
20533 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int)
20534 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int)
20535 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int)
20536 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int)
20538 unsigned int __builtin_tcheck (void)
20539 unsigned int __builtin_treclaim (unsigned int)
20540 unsigned int __builtin_trechkpt (void)
20541 unsigned int __builtin_tsr (unsigned int)
20544 In addition to the above HTM built-ins, we have added built-ins for
20545 some common extended mnemonics of the HTM instructions:
20548 unsigned int __builtin_tendall (void)
20549 unsigned int __builtin_tresume (void)
20550 unsigned int __builtin_tsuspend (void)
20553 Note that the semantics of the above HTM builtins are required to mimic
20554 the locking semantics used for critical sections. Builtins that are used
20555 to create a new transaction or restart a suspended transaction must have
20556 lock acquisition like semantics while those builtins that end or suspend a
20557 transaction must have lock release like semantics. Specifically, this must
20558 mimic lock semantics as specified by C++11, for example: Lock acquisition is
20559 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
20560 that returns 0, and lock release is as-if an execution of
20561 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
20562 implicit implementation-defined lock used for all transactions. The HTM
20563 instructions associated with with the builtins inherently provide the
20564 correct acquisition and release hardware barriers required. However,
20565 the compiler must also be prohibited from moving loads and stores across
20566 the builtins in a way that would violate their semantics. This has been
20567 accomplished by adding memory barriers to the associated HTM instructions
20568 (which is a conservative approach to provide acquire and release semantics).
20569 Earlier versions of the compiler did not treat the HTM instructions as
20570 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
20571 be used to determine whether the current compiler treats HTM instructions
20572 as memory barriers or not. This allows the user to explicitly add memory
20573 barriers to their code when using an older version of the compiler.
20575 The following set of built-in functions are available to gain access
20576 to the HTM specific special purpose registers.
20579 unsigned long __builtin_get_texasr (void)
20580 unsigned long __builtin_get_texasru (void)
20581 unsigned long __builtin_get_tfhar (void)
20582 unsigned long __builtin_get_tfiar (void)
20584 void __builtin_set_texasr (unsigned long);
20585 void __builtin_set_texasru (unsigned long);
20586 void __builtin_set_tfhar (unsigned long);
20587 void __builtin_set_tfiar (unsigned long);
20590 Example usage of these low level built-in functions may look like:
20593 #include <htmintrin.h>
20595 int num_retries = 10;
20599 if (__builtin_tbegin (0))
20601 /* Transaction State Initiated. */
20602 if (is_locked (lock))
20603 __builtin_tabort (0);
20604 ... transaction code...
20605 __builtin_tend (0);
20610 /* Transaction State Failed. Use locks if the transaction
20611 failure is "persistent" or we've tried too many times. */
20612 if (num_retries-- <= 0
20613 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
20615 acquire_lock (lock);
20616 ... non transactional fallback path...
20617 release_lock (lock);
20624 One final built-in function has been added that returns the value of
20625 the 2-bit Transaction State field of the Machine Status Register (MSR)
20626 as stored in @code{CR0}.
20629 unsigned long __builtin_ttest (void)
20632 This built-in can be used to determine the current transaction state
20633 using the following code example:
20636 #include <htmintrin.h>
20638 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
20640 if (tx_state == _HTM_TRANSACTIONAL)
20642 /* Code to use in transactional state. */
20644 else if (tx_state == _HTM_NONTRANSACTIONAL)
20646 /* Code to use in non-transactional state. */
20648 else if (tx_state == _HTM_SUSPENDED)
20650 /* Code to use in transaction suspended state. */
20654 @subsubsection PowerPC HTM High Level Inline Functions
20656 The following high level HTM interface is made available by including
20657 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
20658 where CPU is `power8' or later. This interface is common between PowerPC
20659 and S/390, allowing users to write one HTM source implementation that
20660 can be compiled and executed on either system.
20663 long __TM_simple_begin (void)
20664 long __TM_begin (void* const TM_buff)
20665 long __TM_end (void)
20666 void __TM_abort (void)
20667 void __TM_named_abort (unsigned char const code)
20668 void __TM_resume (void)
20669 void __TM_suspend (void)
20671 long __TM_is_user_abort (void* const TM_buff)
20672 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code)
20673 long __TM_is_illegal (void* const TM_buff)
20674 long __TM_is_footprint_exceeded (void* const TM_buff)
20675 long __TM_nesting_depth (void* const TM_buff)
20676 long __TM_is_nested_too_deep(void* const TM_buff)
20677 long __TM_is_conflict(void* const TM_buff)
20678 long __TM_is_failure_persistent(void* const TM_buff)
20679 long __TM_failure_address(void* const TM_buff)
20680 long long __TM_failure_code(void* const TM_buff)
20683 Using these common set of HTM inline functions, we can create
20684 a more portable version of the HTM example in the previous
20685 section that will work on either PowerPC or S/390:
20688 #include <htmxlintrin.h>
20690 int num_retries = 10;
20691 TM_buff_type TM_buff;
20695 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
20697 /* Transaction State Initiated. */
20698 if (is_locked (lock))
20700 ... transaction code...
20706 /* Transaction State Failed. Use locks if the transaction
20707 failure is "persistent" or we've tried too many times. */
20708 if (num_retries-- <= 0
20709 || __TM_is_failure_persistent (TM_buff))
20711 acquire_lock (lock);
20712 ... non transactional fallback path...
20713 release_lock (lock);
20720 @node PowerPC Atomic Memory Operation Functions
20721 @subsection PowerPC Atomic Memory Operation Functions
20722 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
20723 instructions. GCC provides support for these instructions in 64-bit
20724 environments. All of the functions are declared in the include file
20727 The functions supported are:
20732 uint32_t amo_lwat_add (uint32_t *, uint32_t);
20733 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
20734 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
20735 uint32_t amo_lwat_and (uint32_t *, uint32_t);
20736 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
20737 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
20738 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
20740 int32_t amo_lwat_sadd (int32_t *, int32_t);
20741 int32_t amo_lwat_smax (int32_t *, int32_t);
20742 int32_t amo_lwat_smin (int32_t *, int32_t);
20743 int32_t amo_lwat_sswap (int32_t *, int32_t);
20745 uint64_t amo_ldat_add (uint64_t *, uint64_t);
20746 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
20747 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
20748 uint64_t amo_ldat_and (uint64_t *, uint64_t);
20749 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
20750 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
20751 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
20753 int64_t amo_ldat_sadd (int64_t *, int64_t);
20754 int64_t amo_ldat_smax (int64_t *, int64_t);
20755 int64_t amo_ldat_smin (int64_t *, int64_t);
20756 int64_t amo_ldat_sswap (int64_t *, int64_t);
20758 void amo_stwat_add (uint32_t *, uint32_t);
20759 void amo_stwat_xor (uint32_t *, uint32_t);
20760 void amo_stwat_ior (uint32_t *, uint32_t);
20761 void amo_stwat_and (uint32_t *, uint32_t);
20762 void amo_stwat_umax (uint32_t *, uint32_t);
20763 void amo_stwat_umin (uint32_t *, uint32_t);
20765 void amo_stwat_sadd (int32_t *, int32_t);
20766 void amo_stwat_smax (int32_t *, int32_t);
20767 void amo_stwat_smin (int32_t *, int32_t);
20769 void amo_stdat_add (uint64_t *, uint64_t);
20770 void amo_stdat_xor (uint64_t *, uint64_t);
20771 void amo_stdat_ior (uint64_t *, uint64_t);
20772 void amo_stdat_and (uint64_t *, uint64_t);
20773 void amo_stdat_umax (uint64_t *, uint64_t);
20774 void amo_stdat_umin (uint64_t *, uint64_t);
20776 void amo_stdat_sadd (int64_t *, int64_t);
20777 void amo_stdat_smax (int64_t *, int64_t);
20778 void amo_stdat_smin (int64_t *, int64_t);
20781 @node PowerPC Matrix-Multiply Assist Built-in Functions
20782 @subsection PowerPC Matrix-Multiply Assist Built-in Functions
20783 ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions.
20784 GCC provides support for these instructions through the following built-in
20785 functions which are enabled with the @code{-mmma} option. The vec_t type
20786 below is defined to be a normal vector unsigned char type. The uint2, uint4
20787 and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants
20788 respectively. The compiler will verify that they are constants and that
20789 their values are within range.
20791 The built-in functions supported are:
20794 void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t);
20795 void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t);
20796 void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t);
20797 void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t);
20798 void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t);
20799 void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t);
20800 void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t);
20802 void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t);
20803 void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t);
20804 void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t);
20805 void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t);
20806 void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t);
20807 void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t);
20808 void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t);
20809 void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t);
20810 void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t);
20811 void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t);
20812 void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t);
20813 void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t);
20814 void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t);
20815 void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t);
20816 void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t);
20817 void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t);
20818 void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t);
20820 void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
20821 void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
20823 void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20824 void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20825 void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20827 void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20828 void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20829 void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20830 void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20832 void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20833 void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20834 void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20835 void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20836 void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20837 void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20838 void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20839 void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20840 void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20841 void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20843 void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4);
20844 void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4);
20845 void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4);
20846 void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4);
20847 void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4);
20849 void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t);
20850 void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t);
20851 void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t);
20852 void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t);
20853 void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t);
20855 void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20856 void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20857 void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20858 void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20859 void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20861 void __builtin_mma_xxmtacc (__vector_quad *);
20862 void __builtin_mma_xxmfacc (__vector_quad *);
20863 void __builtin_mma_xxsetaccz (__vector_quad *);
20865 void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t);
20866 void __builtin_mma_disassemble_acc (void *, __vector_quad *);
20868 void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t);
20869 void __builtin_vsx_disassemble_pair (void *, __vector_pair *);
20871 vec_t __builtin_vsx_xvcvspbf16 (vec_t);
20872 vec_t __builtin_vsx_xvcvbf16spn (vec_t);
20874 __vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *);
20875 void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *);
20878 @node PRU Built-in Functions
20879 @subsection PRU Built-in Functions
20881 GCC provides a couple of special builtin functions to aid in utilizing
20882 special PRU instructions.
20884 The built-in functions supported are:
20887 @item __delay_cycles (long long @var{cycles})
20888 This inserts an instruction sequence that takes exactly @var{cycles}
20889 cycles (between 0 and 0xffffffff) to complete. The inserted sequence
20890 may use jumps, loops, or no-ops, and does not interfere with any other
20891 instructions. Note that @var{cycles} must be a compile-time constant
20892 integer - that is, you must pass a number, not a variable that may be
20893 optimized to a constant later. The number of cycles delayed by this
20896 @item __halt (void)
20897 This inserts a HALT instruction to stop processor execution.
20899 @item unsigned int __lmbd (unsigned int @var{wordval}, unsigned int @var{bitval})
20900 This inserts LMBD instruction to calculate the left-most bit with value
20901 @var{bitval} in value @var{wordval}. Only the least significant bit
20902 of @var{bitval} is taken into account.
20905 @node RISC-V Built-in Functions
20906 @subsection RISC-V Built-in Functions
20908 These built-in functions are available for the RISC-V family of
20911 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
20912 Returns the value that is currently set in the @samp{tp} register.
20915 @node RX Built-in Functions
20916 @subsection RX Built-in Functions
20917 GCC supports some of the RX instructions which cannot be expressed in
20918 the C programming language via the use of built-in functions. The
20919 following functions are supported:
20921 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
20922 Generates the @code{brk} machine instruction.
20925 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
20926 Generates the @code{clrpsw} machine instruction to clear the specified
20927 bit in the processor status word.
20930 @deftypefn {Built-in Function} void __builtin_rx_int (int)
20931 Generates the @code{int} machine instruction to generate an interrupt
20932 with the specified value.
20935 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
20936 Generates the @code{machi} machine instruction to add the result of
20937 multiplying the top 16 bits of the two arguments into the
20941 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
20942 Generates the @code{maclo} machine instruction to add the result of
20943 multiplying the bottom 16 bits of the two arguments into the
20947 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
20948 Generates the @code{mulhi} machine instruction to place the result of
20949 multiplying the top 16 bits of the two arguments into the
20953 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
20954 Generates the @code{mullo} machine instruction to place the result of
20955 multiplying the bottom 16 bits of the two arguments into the
20959 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
20960 Generates the @code{mvfachi} machine instruction to read the top
20961 32 bits of the accumulator.
20964 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
20965 Generates the @code{mvfacmi} machine instruction to read the middle
20966 32 bits of the accumulator.
20969 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
20970 Generates the @code{mvfc} machine instruction which reads the control
20971 register specified in its argument and returns its value.
20974 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
20975 Generates the @code{mvtachi} machine instruction to set the top
20976 32 bits of the accumulator.
20979 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
20980 Generates the @code{mvtaclo} machine instruction to set the bottom
20981 32 bits of the accumulator.
20984 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
20985 Generates the @code{mvtc} machine instruction which sets control
20986 register number @code{reg} to @code{val}.
20989 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
20990 Generates the @code{mvtipl} machine instruction set the interrupt
20994 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
20995 Generates the @code{racw} machine instruction to round the accumulator
20996 according to the specified mode.
20999 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
21000 Generates the @code{revw} machine instruction which swaps the bytes in
21001 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
21002 and also bits 16--23 occupy bits 24--31 and vice versa.
21005 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
21006 Generates the @code{rmpa} machine instruction which initiates a
21007 repeated multiply and accumulate sequence.
21010 @deftypefn {Built-in Function} void __builtin_rx_round (float)
21011 Generates the @code{round} machine instruction which returns the
21012 floating-point argument rounded according to the current rounding mode
21013 set in the floating-point status word register.
21016 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
21017 Generates the @code{sat} machine instruction which returns the
21018 saturated value of the argument.
21021 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
21022 Generates the @code{setpsw} machine instruction to set the specified
21023 bit in the processor status word.
21026 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
21027 Generates the @code{wait} machine instruction.
21030 @node S/390 System z Built-in Functions
21031 @subsection S/390 System z Built-in Functions
21032 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
21033 Generates the @code{tbegin} machine instruction starting a
21034 non-constrained hardware transaction. If the parameter is non-NULL the
21035 memory area is used to store the transaction diagnostic buffer and
21036 will be passed as first operand to @code{tbegin}. This buffer can be
21037 defined using the @code{struct __htm_tdb} C struct defined in
21038 @code{htmintrin.h} and must reside on a double-word boundary. The
21039 second tbegin operand is set to @code{0xff0c}. This enables
21040 save/restore of all GPRs and disables aborts for FPR and AR
21041 manipulations inside the transaction body. The condition code set by
21042 the tbegin instruction is returned as integer value. The tbegin
21043 instruction by definition overwrites the content of all FPRs. The
21044 compiler will generate code which saves and restores the FPRs. For
21045 soft-float code it is recommended to used the @code{*_nofloat}
21046 variant. In order to prevent a TDB from being written it is required
21047 to pass a constant zero value as parameter. Passing a zero value
21048 through a variable is not sufficient. Although modifications of
21049 access registers inside the transaction will not trigger an
21050 transaction abort it is not supported to actually modify them. Access
21051 registers do not get saved when entering a transaction. They will have
21052 undefined state when reaching the abort code.
21055 Macros for the possible return codes of tbegin are defined in the
21056 @code{htmintrin.h} header file:
21059 @item _HTM_TBEGIN_STARTED
21060 @code{tbegin} has been executed as part of normal processing. The
21061 transaction body is supposed to be executed.
21062 @item _HTM_TBEGIN_INDETERMINATE
21063 The transaction was aborted due to an indeterminate condition which
21064 might be persistent.
21065 @item _HTM_TBEGIN_TRANSIENT
21066 The transaction aborted due to a transient failure. The transaction
21067 should be re-executed in that case.
21068 @item _HTM_TBEGIN_PERSISTENT
21069 The transaction aborted due to a persistent failure. Re-execution
21070 under same circumstances will not be productive.
21073 @defmac _HTM_FIRST_USER_ABORT_CODE
21074 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
21075 specifies the first abort code which can be used for
21076 @code{__builtin_tabort}. Values below this threshold are reserved for
21080 @deftp {Data type} {struct __htm_tdb}
21081 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
21082 the structure of the transaction diagnostic block as specified in the
21083 Principles of Operation manual chapter 5-91.
21086 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
21087 Same as @code{__builtin_tbegin} but without FPR saves and restores.
21088 Using this variant in code making use of FPRs will leave the FPRs in
21089 undefined state when entering the transaction abort handler code.
21092 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
21093 In addition to @code{__builtin_tbegin} a loop for transient failures
21094 is generated. If tbegin returns a condition code of 2 the transaction
21095 will be retried as often as specified in the second argument. The
21096 perform processor assist instruction is used to tell the CPU about the
21097 number of fails so far.
21100 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
21101 Same as @code{__builtin_tbegin_retry} but without FPR saves and
21102 restores. Using this variant in code making use of FPRs will leave
21103 the FPRs in undefined state when entering the transaction abort
21107 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
21108 Generates the @code{tbeginc} machine instruction starting a constrained
21109 hardware transaction. The second operand is set to @code{0xff08}.
21112 @deftypefn {Built-in Function} int __builtin_tend (void)
21113 Generates the @code{tend} machine instruction finishing a transaction
21114 and making the changes visible to other threads. The condition code
21115 generated by tend is returned as integer value.
21118 @deftypefn {Built-in Function} void __builtin_tabort (int)
21119 Generates the @code{tabort} machine instruction with the specified
21120 abort code. Abort codes from 0 through 255 are reserved and will
21121 result in an error message.
21124 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
21125 Generates the @code{ppa rX,rY,1} machine instruction. Where the
21126 integer parameter is loaded into rX and a value of zero is loaded into
21127 rY. The integer parameter specifies the number of times the
21128 transaction repeatedly aborted.
21131 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
21132 Generates the @code{etnd} machine instruction. The current nesting
21133 depth is returned as integer value. For a nesting depth of 0 the code
21134 is not executed as part of an transaction.
21137 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
21139 Generates the @code{ntstg} machine instruction. The second argument
21140 is written to the first arguments location. The store operation will
21141 not be rolled-back in case of an transaction abort.
21144 @node SH Built-in Functions
21145 @subsection SH Built-in Functions
21146 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
21147 families of processors:
21149 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
21150 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
21151 used by system code that manages threads and execution contexts. The compiler
21152 normally does not generate code that modifies the contents of @samp{GBR} and
21153 thus the value is preserved across function calls. Changing the @samp{GBR}
21154 value in user code must be done with caution, since the compiler might use
21155 @samp{GBR} in order to access thread local variables.
21159 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
21160 Returns the value that is currently set in the @samp{GBR} register.
21161 Memory loads and stores that use the thread pointer as a base address are
21162 turned into @samp{GBR} based displacement loads and stores, if possible.
21170 int get_tcb_value (void)
21172 // Generate @samp{mov.l @@(8,gbr),r0} instruction
21173 return ((my_tcb*)__builtin_thread_pointer ())->c;
21179 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
21180 Returns the value that is currently set in the @samp{FPSCR} register.
21183 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
21184 Sets the @samp{FPSCR} register to the specified value @var{val}, while
21185 preserving the current values of the FR, SZ and PR bits.
21188 @node SPARC VIS Built-in Functions
21189 @subsection SPARC VIS Built-in Functions
21191 GCC supports SIMD operations on the SPARC using both the generic vector
21192 extensions (@pxref{Vector Extensions}) as well as built-in functions for
21193 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
21194 switch, the VIS extension is exposed as the following built-in functions:
21197 typedef int v1si __attribute__ ((vector_size (4)));
21198 typedef int v2si __attribute__ ((vector_size (8)));
21199 typedef short v4hi __attribute__ ((vector_size (8)));
21200 typedef short v2hi __attribute__ ((vector_size (4)));
21201 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
21202 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
21204 void __builtin_vis_write_gsr (int64_t);
21205 int64_t __builtin_vis_read_gsr (void);
21207 void * __builtin_vis_alignaddr (void *, long);
21208 void * __builtin_vis_alignaddrl (void *, long);
21209 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
21210 v2si __builtin_vis_faligndatav2si (v2si, v2si);
21211 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
21212 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
21214 v4hi __builtin_vis_fexpand (v4qi);
21216 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
21217 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
21218 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
21219 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
21220 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
21221 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
21222 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
21224 v4qi __builtin_vis_fpack16 (v4hi);
21225 v8qi __builtin_vis_fpack32 (v2si, v8qi);
21226 v2hi __builtin_vis_fpackfix (v2si);
21227 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
21229 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
21231 long __builtin_vis_edge8 (void *, void *);
21232 long __builtin_vis_edge8l (void *, void *);
21233 long __builtin_vis_edge16 (void *, void *);
21234 long __builtin_vis_edge16l (void *, void *);
21235 long __builtin_vis_edge32 (void *, void *);
21236 long __builtin_vis_edge32l (void *, void *);
21238 long __builtin_vis_fcmple16 (v4hi, v4hi);
21239 long __builtin_vis_fcmple32 (v2si, v2si);
21240 long __builtin_vis_fcmpne16 (v4hi, v4hi);
21241 long __builtin_vis_fcmpne32 (v2si, v2si);
21242 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
21243 long __builtin_vis_fcmpgt32 (v2si, v2si);
21244 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
21245 long __builtin_vis_fcmpeq32 (v2si, v2si);
21247 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
21248 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
21249 v2si __builtin_vis_fpadd32 (v2si, v2si);
21250 v1si __builtin_vis_fpadd32s (v1si, v1si);
21251 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
21252 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
21253 v2si __builtin_vis_fpsub32 (v2si, v2si);
21254 v1si __builtin_vis_fpsub32s (v1si, v1si);
21256 long __builtin_vis_array8 (long, long);
21257 long __builtin_vis_array16 (long, long);
21258 long __builtin_vis_array32 (long, long);
21261 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
21262 functions also become available:
21265 long __builtin_vis_bmask (long, long);
21266 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
21267 v2si __builtin_vis_bshufflev2si (v2si, v2si);
21268 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
21269 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
21271 long __builtin_vis_edge8n (void *, void *);
21272 long __builtin_vis_edge8ln (void *, void *);
21273 long __builtin_vis_edge16n (void *, void *);
21274 long __builtin_vis_edge16ln (void *, void *);
21275 long __builtin_vis_edge32n (void *, void *);
21276 long __builtin_vis_edge32ln (void *, void *);
21279 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
21280 functions also become available:
21283 void __builtin_vis_cmask8 (long);
21284 void __builtin_vis_cmask16 (long);
21285 void __builtin_vis_cmask32 (long);
21287 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
21289 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
21290 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
21291 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
21292 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
21293 v2si __builtin_vis_fsll16 (v2si, v2si);
21294 v2si __builtin_vis_fslas16 (v2si, v2si);
21295 v2si __builtin_vis_fsrl16 (v2si, v2si);
21296 v2si __builtin_vis_fsra16 (v2si, v2si);
21298 long __builtin_vis_pdistn (v8qi, v8qi);
21300 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
21302 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
21303 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
21305 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
21306 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
21307 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
21308 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
21309 v2si __builtin_vis_fpadds32 (v2si, v2si);
21310 v1si __builtin_vis_fpadds32s (v1si, v1si);
21311 v2si __builtin_vis_fpsubs32 (v2si, v2si);
21312 v1si __builtin_vis_fpsubs32s (v1si, v1si);
21314 long __builtin_vis_fucmple8 (v8qi, v8qi);
21315 long __builtin_vis_fucmpne8 (v8qi, v8qi);
21316 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
21317 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
21319 float __builtin_vis_fhadds (float, float);
21320 double __builtin_vis_fhaddd (double, double);
21321 float __builtin_vis_fhsubs (float, float);
21322 double __builtin_vis_fhsubd (double, double);
21323 float __builtin_vis_fnhadds (float, float);
21324 double __builtin_vis_fnhaddd (double, double);
21326 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
21327 int64_t __builtin_vis_xmulx (int64_t, int64_t);
21328 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
21331 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
21332 functions also become available:
21335 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
21336 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
21337 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
21338 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
21340 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
21341 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
21342 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
21343 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
21345 long __builtin_vis_fpcmple8 (v8qi, v8qi);
21346 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
21347 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
21348 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
21349 long __builtin_vis_fpcmpule32 (v2si, v2si);
21350 long __builtin_vis_fpcmpugt32 (v2si, v2si);
21352 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
21353 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
21354 v2si __builtin_vis_fpmax32 (v2si, v2si);
21356 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
21357 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
21358 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
21360 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
21361 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
21362 v2si __builtin_vis_fpmin32 (v2si, v2si);
21364 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
21365 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
21366 v2si __builtin_vis_fpminu32 (v2si, v2si);
21369 When you use the @option{-mvis4b} switch, the VIS version 4.0B
21370 built-in functions also become available:
21373 v8qi __builtin_vis_dictunpack8 (double, int);
21374 v4hi __builtin_vis_dictunpack16 (double, int);
21375 v2si __builtin_vis_dictunpack32 (double, int);
21377 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
21378 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
21379 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
21380 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
21382 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
21383 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
21384 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
21385 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
21387 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
21388 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
21389 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
21390 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
21392 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
21393 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
21394 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
21395 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
21396 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
21397 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
21399 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
21400 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
21401 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
21403 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
21404 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
21405 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
21408 @node TI C6X Built-in Functions
21409 @subsection TI C6X Built-in Functions
21411 GCC provides intrinsics to access certain instructions of the TI C6X
21412 processors. These intrinsics, listed below, are available after
21413 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
21414 to C6X instructions.
21418 int _sadd (int, int)
21419 int _ssub (int, int)
21420 int _sadd2 (int, int)
21421 int _ssub2 (int, int)
21422 long long _mpy2 (int, int)
21423 long long _smpy2 (int, int)
21424 int _add4 (int, int)
21425 int _sub4 (int, int)
21426 int _saddu4 (int, int)
21428 int _smpy (int, int)
21429 int _smpyh (int, int)
21430 int _smpyhl (int, int)
21431 int _smpylh (int, int)
21433 int _sshl (int, int)
21434 int _subc (int, int)
21436 int _avg2 (int, int)
21437 int _avgu4 (int, int)
21439 int _clrr (int, int)
21440 int _extr (int, int)
21441 int _extru (int, int)
21447 @node TILE-Gx Built-in Functions
21448 @subsection TILE-Gx Built-in Functions
21450 GCC provides intrinsics to access every instruction of the TILE-Gx
21451 processor. The intrinsics are of the form:
21455 unsigned long long __insn_@var{op} (...)
21459 Where @var{op} is the name of the instruction. Refer to the ISA manual
21460 for the complete list of instructions.
21462 GCC also provides intrinsics to directly access the network registers.
21463 The intrinsics are:
21467 unsigned long long __tile_idn0_receive (void)
21468 unsigned long long __tile_idn1_receive (void)
21469 unsigned long long __tile_udn0_receive (void)
21470 unsigned long long __tile_udn1_receive (void)
21471 unsigned long long __tile_udn2_receive (void)
21472 unsigned long long __tile_udn3_receive (void)
21473 void __tile_idn_send (unsigned long long)
21474 void __tile_udn_send (unsigned long long)
21478 The intrinsic @code{void __tile_network_barrier (void)} is used to
21479 guarantee that no network operations before it are reordered with
21482 @node TILEPro Built-in Functions
21483 @subsection TILEPro Built-in Functions
21485 GCC provides intrinsics to access every instruction of the TILEPro
21486 processor. The intrinsics are of the form:
21490 unsigned __insn_@var{op} (...)
21495 where @var{op} is the name of the instruction. Refer to the ISA manual
21496 for the complete list of instructions.
21498 GCC also provides intrinsics to directly access the network registers.
21499 The intrinsics are:
21503 unsigned __tile_idn0_receive (void)
21504 unsigned __tile_idn1_receive (void)
21505 unsigned __tile_sn_receive (void)
21506 unsigned __tile_udn0_receive (void)
21507 unsigned __tile_udn1_receive (void)
21508 unsigned __tile_udn2_receive (void)
21509 unsigned __tile_udn3_receive (void)
21510 void __tile_idn_send (unsigned)
21511 void __tile_sn_send (unsigned)
21512 void __tile_udn_send (unsigned)
21516 The intrinsic @code{void __tile_network_barrier (void)} is used to
21517 guarantee that no network operations before it are reordered with
21520 @node x86 Built-in Functions
21521 @subsection x86 Built-in Functions
21523 These built-in functions are available for the x86-32 and x86-64 family
21524 of computers, depending on the command-line switches used.
21526 If you specify command-line switches such as @option{-msse},
21527 the compiler could use the extended instruction sets even if the built-ins
21528 are not used explicitly in the program. For this reason, applications
21529 that perform run-time CPU detection must compile separate files for each
21530 supported architecture, using the appropriate flags. In particular,
21531 the file containing the CPU detection code should be compiled without
21534 The following machine modes are available for use with MMX built-in functions
21535 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
21536 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
21537 vector of eight 8-bit integers. Some of the built-in functions operate on
21538 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
21540 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
21541 of two 32-bit floating-point values.
21543 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
21544 floating-point values. Some instructions use a vector of four 32-bit
21545 integers, these use @code{V4SI}. Finally, some instructions operate on an
21546 entire vector register, interpreting it as a 128-bit integer, these use mode
21549 The x86-32 and x86-64 family of processors use additional built-in
21550 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
21551 floating point and @code{TC} 128-bit complex floating-point values.
21553 The following floating-point built-in functions are always available. All
21554 of them implement the function that is part of the name.
21557 __float128 __builtin_fabsq (__float128)
21558 __float128 __builtin_copysignq (__float128, __float128)
21561 The following built-in functions are always available.
21564 @item __float128 __builtin_infq (void)
21565 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
21566 @findex __builtin_infq
21568 @item __float128 __builtin_huge_valq (void)
21569 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
21570 @findex __builtin_huge_valq
21572 @item __float128 __builtin_nanq (void)
21573 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
21574 @findex __builtin_nanq
21576 @item __float128 __builtin_nansq (void)
21577 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
21578 @findex __builtin_nansq
21581 The following built-in function is always available.
21584 @item void __builtin_ia32_pause (void)
21585 Generates the @code{pause} machine instruction with a compiler memory
21589 The following built-in functions are always available and can be used to
21590 check the target platform type.
21592 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
21593 This function runs the CPU detection code to check the type of CPU and the
21594 features supported. This built-in function needs to be invoked along with the built-in functions
21595 to check CPU type and features, @code{__builtin_cpu_is} and
21596 @code{__builtin_cpu_supports}, only when used in a function that is
21597 executed before any constructors are called. The CPU detection code is
21598 automatically executed in a very high priority constructor.
21600 For example, this function has to be used in @code{ifunc} resolvers that
21601 check for CPU type using the built-in functions @code{__builtin_cpu_is}
21602 and @code{__builtin_cpu_supports}, or in constructors on targets that
21603 don't support constructor priority.
21606 static void (*resolve_memcpy (void)) (void)
21608 // ifunc resolvers fire before constructors, explicitly call the init
21610 __builtin_cpu_init ();
21611 if (__builtin_cpu_supports ("ssse3"))
21612 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
21614 return default_memcpy;
21617 void *memcpy (void *, const void *, size_t)
21618 __attribute__ ((ifunc ("resolve_memcpy")));
21623 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
21624 This function returns a positive integer if the run-time CPU
21625 is of type @var{cpuname}
21626 and returns @code{0} otherwise. The following CPU names can be detected:
21639 Intel Silvermont CPU.
21648 Intel Core i7 Nehalem CPU.
21651 Intel Core i7 Westmere CPU.
21654 Intel Core i7 Sandy Bridge CPU.
21657 Intel Core i7 Ivy Bridge CPU.
21660 Intel Core i7 Haswell CPU.
21663 Intel Core i7 Broadwell CPU.
21666 Intel Core i7 Skylake CPU.
21668 @item skylake-avx512
21669 Intel Core i7 Skylake AVX512 CPU.
21672 Intel Core i7 Cannon Lake CPU.
21674 @item icelake-client
21675 Intel Core i7 Ice Lake Client CPU.
21677 @item icelake-server
21678 Intel Core i7 Ice Lake Server CPU.
21681 Intel Core i7 Cascadelake CPU.
21684 Intel Core i7 Tigerlake CPU.
21687 Intel Core i7 Cooperlake CPU.
21689 @item sapphirerapids
21690 Intel Core i7 sapphirerapids CPU.
21693 Intel Core i7 Alderlake CPU.
21696 Intel Core i7 Rocketlake CPU.
21699 Intel Atom Bonnell CPU.
21702 Intel Atom Silvermont CPU.
21705 Intel Atom Goldmont CPU.
21707 @item goldmont-plus
21708 Intel Atom Goldmont Plus CPU.
21711 Intel Atom Tremont CPU.
21714 Intel Knights Landing CPU.
21717 Intel Knights Mill CPU.
21720 AMD Family 10h CPU.
21723 AMD Family 10h Barcelona CPU.
21726 AMD Family 10h Shanghai CPU.
21729 AMD Family 10h Istanbul CPU.
21732 AMD Family 14h CPU.
21735 AMD Family 15h CPU.
21738 AMD Family 15h Bulldozer version 1.
21741 AMD Family 15h Bulldozer version 2.
21744 AMD Family 15h Bulldozer version 3.
21747 AMD Family 15h Bulldozer version 4.
21750 AMD Family 16h CPU.
21753 AMD Family 17h CPU.
21756 AMD Family 17h Zen version 1.
21759 AMD Family 17h Zen version 2.
21762 AMD Family 19h CPU.
21765 AMD Family 19h Zen version 3.
21768 Baseline x86-64 microarchitecture level (as defined in x86-64 psABI).
21771 x86-64-v2 microarchitecture level.
21774 x86-64-v3 microarchitecture level.
21777 x86-64-v4 microarchitecture level.
21780 Here is an example:
21782 if (__builtin_cpu_is ("corei7"))
21784 do_corei7 (); // Core i7 specific implementation.
21788 do_generic (); // Generic implementation.
21793 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
21794 This function returns a positive integer if the run-time CPU
21795 supports @var{feature}
21796 and returns @code{0} otherwise. The following features can be detected:
21804 POPCNT instruction.
21812 SSSE3 instructions.
21814 SSE4.1 instructions.
21816 SSE4.2 instructions.
21822 SSE4A instructions.
21830 AVX512F instructions.
21838 PCLMUL instructions.
21840 AVX512VL instructions.
21842 AVX512BW instructions.
21844 AVX512DQ instructions.
21846 AVX512CD instructions.
21848 AVX512ER instructions.
21850 AVX512PF instructions.
21852 AVX512VBMI instructions.
21854 AVX512IFMA instructions.
21856 AVX5124VNNIW instructions.
21858 AVX5124FMAPS instructions.
21859 @item avx512vpopcntdq
21860 AVX512VPOPCNTDQ instructions.
21862 AVX512VBMI2 instructions.
21866 VPCLMULQDQ instructions.
21868 AVX512VNNI instructions.
21870 AVX512BITALG instructions.
21873 Here is an example:
21875 if (__builtin_cpu_supports ("popcnt"))
21877 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
21881 count = generic_countbits (n); //generic implementation.
21886 The following built-in functions are made available by @option{-mmmx}.
21887 All of them generate the machine instruction that is part of the name.
21890 v8qi __builtin_ia32_paddb (v8qi, v8qi)
21891 v4hi __builtin_ia32_paddw (v4hi, v4hi)
21892 v2si __builtin_ia32_paddd (v2si, v2si)
21893 v8qi __builtin_ia32_psubb (v8qi, v8qi)
21894 v4hi __builtin_ia32_psubw (v4hi, v4hi)
21895 v2si __builtin_ia32_psubd (v2si, v2si)
21896 v8qi __builtin_ia32_paddsb (v8qi, v8qi)
21897 v4hi __builtin_ia32_paddsw (v4hi, v4hi)
21898 v8qi __builtin_ia32_psubsb (v8qi, v8qi)
21899 v4hi __builtin_ia32_psubsw (v4hi, v4hi)
21900 v8qi __builtin_ia32_paddusb (v8qi, v8qi)
21901 v4hi __builtin_ia32_paddusw (v4hi, v4hi)
21902 v8qi __builtin_ia32_psubusb (v8qi, v8qi)
21903 v4hi __builtin_ia32_psubusw (v4hi, v4hi)
21904 v4hi __builtin_ia32_pmullw (v4hi, v4hi)
21905 v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
21906 di __builtin_ia32_pand (di, di)
21907 di __builtin_ia32_pandn (di,di)
21908 di __builtin_ia32_por (di, di)
21909 di __builtin_ia32_pxor (di, di)
21910 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
21911 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
21912 v2si __builtin_ia32_pcmpeqd (v2si, v2si)
21913 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
21914 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
21915 v2si __builtin_ia32_pcmpgtd (v2si, v2si)
21916 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
21917 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
21918 v2si __builtin_ia32_punpckhdq (v2si, v2si)
21919 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
21920 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
21921 v2si __builtin_ia32_punpckldq (v2si, v2si)
21922 v8qi __builtin_ia32_packsswb (v4hi, v4hi)
21923 v4hi __builtin_ia32_packssdw (v2si, v2si)
21924 v8qi __builtin_ia32_packuswb (v4hi, v4hi)
21926 v4hi __builtin_ia32_psllw (v4hi, v4hi)
21927 v2si __builtin_ia32_pslld (v2si, v2si)
21928 v1di __builtin_ia32_psllq (v1di, v1di)
21929 v4hi __builtin_ia32_psrlw (v4hi, v4hi)
21930 v2si __builtin_ia32_psrld (v2si, v2si)
21931 v1di __builtin_ia32_psrlq (v1di, v1di)
21932 v4hi __builtin_ia32_psraw (v4hi, v4hi)
21933 v2si __builtin_ia32_psrad (v2si, v2si)
21934 v4hi __builtin_ia32_psllwi (v4hi, int)
21935 v2si __builtin_ia32_pslldi (v2si, int)
21936 v1di __builtin_ia32_psllqi (v1di, int)
21937 v4hi __builtin_ia32_psrlwi (v4hi, int)
21938 v2si __builtin_ia32_psrldi (v2si, int)
21939 v1di __builtin_ia32_psrlqi (v1di, int)
21940 v4hi __builtin_ia32_psrawi (v4hi, int)
21941 v2si __builtin_ia32_psradi (v2si, int)
21945 The following built-in functions are made available either with
21946 @option{-msse}, or with @option{-m3dnowa}. All of them generate
21947 the machine instruction that is part of the name.
21950 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
21951 v8qi __builtin_ia32_pavgb (v8qi, v8qi)
21952 v4hi __builtin_ia32_pavgw (v4hi, v4hi)
21953 v1di __builtin_ia32_psadbw (v8qi, v8qi)
21954 v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
21955 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
21956 v8qi __builtin_ia32_pminub (v8qi, v8qi)
21957 v4hi __builtin_ia32_pminsw (v4hi, v4hi)
21958 int __builtin_ia32_pmovmskb (v8qi)
21959 void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
21960 void __builtin_ia32_movntq (di *, di)
21961 void __builtin_ia32_sfence (void)
21964 The following built-in functions are available when @option{-msse} is used.
21965 All of them generate the machine instruction that is part of the name.
21968 int __builtin_ia32_comieq (v4sf, v4sf)
21969 int __builtin_ia32_comineq (v4sf, v4sf)
21970 int __builtin_ia32_comilt (v4sf, v4sf)
21971 int __builtin_ia32_comile (v4sf, v4sf)
21972 int __builtin_ia32_comigt (v4sf, v4sf)
21973 int __builtin_ia32_comige (v4sf, v4sf)
21974 int __builtin_ia32_ucomieq (v4sf, v4sf)
21975 int __builtin_ia32_ucomineq (v4sf, v4sf)
21976 int __builtin_ia32_ucomilt (v4sf, v4sf)
21977 int __builtin_ia32_ucomile (v4sf, v4sf)
21978 int __builtin_ia32_ucomigt (v4sf, v4sf)
21979 int __builtin_ia32_ucomige (v4sf, v4sf)
21980 v4sf __builtin_ia32_addps (v4sf, v4sf)
21981 v4sf __builtin_ia32_subps (v4sf, v4sf)
21982 v4sf __builtin_ia32_mulps (v4sf, v4sf)
21983 v4sf __builtin_ia32_divps (v4sf, v4sf)
21984 v4sf __builtin_ia32_addss (v4sf, v4sf)
21985 v4sf __builtin_ia32_subss (v4sf, v4sf)
21986 v4sf __builtin_ia32_mulss (v4sf, v4sf)
21987 v4sf __builtin_ia32_divss (v4sf, v4sf)
21988 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf)
21989 v4sf __builtin_ia32_cmpltps (v4sf, v4sf)
21990 v4sf __builtin_ia32_cmpleps (v4sf, v4sf)
21991 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf)
21992 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf)
21993 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf)
21994 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf)
21995 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf)
21996 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf)
21997 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf)
21998 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf)
21999 v4sf __builtin_ia32_cmpordps (v4sf, v4sf)
22000 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf)
22001 v4sf __builtin_ia32_cmpltss (v4sf, v4sf)
22002 v4sf __builtin_ia32_cmpless (v4sf, v4sf)
22003 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf)
22004 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf)
22005 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf)
22006 v4sf __builtin_ia32_cmpnless (v4sf, v4sf)
22007 v4sf __builtin_ia32_cmpordss (v4sf, v4sf)
22008 v4sf __builtin_ia32_maxps (v4sf, v4sf)
22009 v4sf __builtin_ia32_maxss (v4sf, v4sf)
22010 v4sf __builtin_ia32_minps (v4sf, v4sf)
22011 v4sf __builtin_ia32_minss (v4sf, v4sf)
22012 v4sf __builtin_ia32_andps (v4sf, v4sf)
22013 v4sf __builtin_ia32_andnps (v4sf, v4sf)
22014 v4sf __builtin_ia32_orps (v4sf, v4sf)
22015 v4sf __builtin_ia32_xorps (v4sf, v4sf)
22016 v4sf __builtin_ia32_movss (v4sf, v4sf)
22017 v4sf __builtin_ia32_movhlps (v4sf, v4sf)
22018 v4sf __builtin_ia32_movlhps (v4sf, v4sf)
22019 v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
22020 v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
22021 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
22022 v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
22023 v2si __builtin_ia32_cvtps2pi (v4sf)
22024 int __builtin_ia32_cvtss2si (v4sf)
22025 v2si __builtin_ia32_cvttps2pi (v4sf)
22026 int __builtin_ia32_cvttss2si (v4sf)
22027 v4sf __builtin_ia32_rcpps (v4sf)
22028 v4sf __builtin_ia32_rsqrtps (v4sf)
22029 v4sf __builtin_ia32_sqrtps (v4sf)
22030 v4sf __builtin_ia32_rcpss (v4sf)
22031 v4sf __builtin_ia32_rsqrtss (v4sf)
22032 v4sf __builtin_ia32_sqrtss (v4sf)
22033 v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
22034 void __builtin_ia32_movntps (float *, v4sf)
22035 int __builtin_ia32_movmskps (v4sf)
22038 The following built-in functions are available when @option{-msse} is used.
22041 @item v4sf __builtin_ia32_loadups (float *)
22042 Generates the @code{movups} machine instruction as a load from memory.
22043 @item void __builtin_ia32_storeups (float *, v4sf)
22044 Generates the @code{movups} machine instruction as a store to memory.
22045 @item v4sf __builtin_ia32_loadss (float *)
22046 Generates the @code{movss} machine instruction as a load from memory.
22047 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
22048 Generates the @code{movhps} machine instruction as a load from memory.
22049 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
22050 Generates the @code{movlps} machine instruction as a load from memory
22051 @item void __builtin_ia32_storehps (v2sf *, v4sf)
22052 Generates the @code{movhps} machine instruction as a store to memory.
22053 @item void __builtin_ia32_storelps (v2sf *, v4sf)
22054 Generates the @code{movlps} machine instruction as a store to memory.
22057 The following built-in functions are available when @option{-msse2} is used.
22058 All of them generate the machine instruction that is part of the name.
22061 int __builtin_ia32_comisdeq (v2df, v2df)
22062 int __builtin_ia32_comisdlt (v2df, v2df)
22063 int __builtin_ia32_comisdle (v2df, v2df)
22064 int __builtin_ia32_comisdgt (v2df, v2df)
22065 int __builtin_ia32_comisdge (v2df, v2df)
22066 int __builtin_ia32_comisdneq (v2df, v2df)
22067 int __builtin_ia32_ucomisdeq (v2df, v2df)
22068 int __builtin_ia32_ucomisdlt (v2df, v2df)
22069 int __builtin_ia32_ucomisdle (v2df, v2df)
22070 int __builtin_ia32_ucomisdgt (v2df, v2df)
22071 int __builtin_ia32_ucomisdge (v2df, v2df)
22072 int __builtin_ia32_ucomisdneq (v2df, v2df)
22073 v2df __builtin_ia32_cmpeqpd (v2df, v2df)
22074 v2df __builtin_ia32_cmpltpd (v2df, v2df)
22075 v2df __builtin_ia32_cmplepd (v2df, v2df)
22076 v2df __builtin_ia32_cmpgtpd (v2df, v2df)
22077 v2df __builtin_ia32_cmpgepd (v2df, v2df)
22078 v2df __builtin_ia32_cmpunordpd (v2df, v2df)
22079 v2df __builtin_ia32_cmpneqpd (v2df, v2df)
22080 v2df __builtin_ia32_cmpnltpd (v2df, v2df)
22081 v2df __builtin_ia32_cmpnlepd (v2df, v2df)
22082 v2df __builtin_ia32_cmpngtpd (v2df, v2df)
22083 v2df __builtin_ia32_cmpngepd (v2df, v2df)
22084 v2df __builtin_ia32_cmpordpd (v2df, v2df)
22085 v2df __builtin_ia32_cmpeqsd (v2df, v2df)
22086 v2df __builtin_ia32_cmpltsd (v2df, v2df)
22087 v2df __builtin_ia32_cmplesd (v2df, v2df)
22088 v2df __builtin_ia32_cmpunordsd (v2df, v2df)
22089 v2df __builtin_ia32_cmpneqsd (v2df, v2df)
22090 v2df __builtin_ia32_cmpnltsd (v2df, v2df)
22091 v2df __builtin_ia32_cmpnlesd (v2df, v2df)
22092 v2df __builtin_ia32_cmpordsd (v2df, v2df)
22093 v2di __builtin_ia32_paddq (v2di, v2di)
22094 v2di __builtin_ia32_psubq (v2di, v2di)
22095 v2df __builtin_ia32_addpd (v2df, v2df)
22096 v2df __builtin_ia32_subpd (v2df, v2df)
22097 v2df __builtin_ia32_mulpd (v2df, v2df)
22098 v2df __builtin_ia32_divpd (v2df, v2df)
22099 v2df __builtin_ia32_addsd (v2df, v2df)
22100 v2df __builtin_ia32_subsd (v2df, v2df)
22101 v2df __builtin_ia32_mulsd (v2df, v2df)
22102 v2df __builtin_ia32_divsd (v2df, v2df)
22103 v2df __builtin_ia32_minpd (v2df, v2df)
22104 v2df __builtin_ia32_maxpd (v2df, v2df)
22105 v2df __builtin_ia32_minsd (v2df, v2df)
22106 v2df __builtin_ia32_maxsd (v2df, v2df)
22107 v2df __builtin_ia32_andpd (v2df, v2df)
22108 v2df __builtin_ia32_andnpd (v2df, v2df)
22109 v2df __builtin_ia32_orpd (v2df, v2df)
22110 v2df __builtin_ia32_xorpd (v2df, v2df)
22111 v2df __builtin_ia32_movsd (v2df, v2df)
22112 v2df __builtin_ia32_unpckhpd (v2df, v2df)
22113 v2df __builtin_ia32_unpcklpd (v2df, v2df)
22114 v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
22115 v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
22116 v4si __builtin_ia32_paddd128 (v4si, v4si)
22117 v2di __builtin_ia32_paddq128 (v2di, v2di)
22118 v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
22119 v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
22120 v4si __builtin_ia32_psubd128 (v4si, v4si)
22121 v2di __builtin_ia32_psubq128 (v2di, v2di)
22122 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
22123 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
22124 v2di __builtin_ia32_pand128 (v2di, v2di)
22125 v2di __builtin_ia32_pandn128 (v2di, v2di)
22126 v2di __builtin_ia32_por128 (v2di, v2di)
22127 v2di __builtin_ia32_pxor128 (v2di, v2di)
22128 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
22129 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
22130 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
22131 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
22132 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
22133 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
22134 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
22135 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
22136 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
22137 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
22138 v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
22139 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
22140 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
22141 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
22142 v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
22143 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
22144 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
22145 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
22146 v4si __builtin_ia32_punpckldq128 (v4si, v4si)
22147 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
22148 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
22149 v8hi __builtin_ia32_packssdw128 (v4si, v4si)
22150 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
22151 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
22152 void __builtin_ia32_maskmovdqu (v16qi, v16qi)
22153 v2df __builtin_ia32_loadupd (double *)
22154 void __builtin_ia32_storeupd (double *, v2df)
22155 v2df __builtin_ia32_loadhpd (v2df, double const *)
22156 v2df __builtin_ia32_loadlpd (v2df, double const *)
22157 int __builtin_ia32_movmskpd (v2df)
22158 int __builtin_ia32_pmovmskb128 (v16qi)
22159 void __builtin_ia32_movnti (int *, int)
22160 void __builtin_ia32_movnti64 (long long int *, long long int)
22161 void __builtin_ia32_movntpd (double *, v2df)
22162 void __builtin_ia32_movntdq (v2df *, v2df)
22163 v4si __builtin_ia32_pshufd (v4si, int)
22164 v8hi __builtin_ia32_pshuflw (v8hi, int)
22165 v8hi __builtin_ia32_pshufhw (v8hi, int)
22166 v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
22167 v2df __builtin_ia32_sqrtpd (v2df)
22168 v2df __builtin_ia32_sqrtsd (v2df)
22169 v2df __builtin_ia32_shufpd (v2df, v2df, int)
22170 v2df __builtin_ia32_cvtdq2pd (v4si)
22171 v4sf __builtin_ia32_cvtdq2ps (v4si)
22172 v4si __builtin_ia32_cvtpd2dq (v2df)
22173 v2si __builtin_ia32_cvtpd2pi (v2df)
22174 v4sf __builtin_ia32_cvtpd2ps (v2df)
22175 v4si __builtin_ia32_cvttpd2dq (v2df)
22176 v2si __builtin_ia32_cvttpd2pi (v2df)
22177 v2df __builtin_ia32_cvtpi2pd (v2si)
22178 int __builtin_ia32_cvtsd2si (v2df)
22179 int __builtin_ia32_cvttsd2si (v2df)
22180 long long __builtin_ia32_cvtsd2si64 (v2df)
22181 long long __builtin_ia32_cvttsd2si64 (v2df)
22182 v4si __builtin_ia32_cvtps2dq (v4sf)
22183 v2df __builtin_ia32_cvtps2pd (v4sf)
22184 v4si __builtin_ia32_cvttps2dq (v4sf)
22185 v2df __builtin_ia32_cvtsi2sd (v2df, int)
22186 v2df __builtin_ia32_cvtsi642sd (v2df, long long)
22187 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
22188 v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
22189 void __builtin_ia32_clflush (const void *)
22190 void __builtin_ia32_lfence (void)
22191 void __builtin_ia32_mfence (void)
22192 v16qi __builtin_ia32_loaddqu (const char *)
22193 void __builtin_ia32_storedqu (char *, v16qi)
22194 v1di __builtin_ia32_pmuludq (v2si, v2si)
22195 v2di __builtin_ia32_pmuludq128 (v4si, v4si)
22196 v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
22197 v4si __builtin_ia32_pslld128 (v4si, v4si)
22198 v2di __builtin_ia32_psllq128 (v2di, v2di)
22199 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
22200 v4si __builtin_ia32_psrld128 (v4si, v4si)
22201 v2di __builtin_ia32_psrlq128 (v2di, v2di)
22202 v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
22203 v4si __builtin_ia32_psrad128 (v4si, v4si)
22204 v2di __builtin_ia32_pslldqi128 (v2di, int)
22205 v8hi __builtin_ia32_psllwi128 (v8hi, int)
22206 v4si __builtin_ia32_pslldi128 (v4si, int)
22207 v2di __builtin_ia32_psllqi128 (v2di, int)
22208 v2di __builtin_ia32_psrldqi128 (v2di, int)
22209 v8hi __builtin_ia32_psrlwi128 (v8hi, int)
22210 v4si __builtin_ia32_psrldi128 (v4si, int)
22211 v2di __builtin_ia32_psrlqi128 (v2di, int)
22212 v8hi __builtin_ia32_psrawi128 (v8hi, int)
22213 v4si __builtin_ia32_psradi128 (v4si, int)
22214 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
22215 v2di __builtin_ia32_movq128 (v2di)
22218 The following built-in functions are available when @option{-msse3} is used.
22219 All of them generate the machine instruction that is part of the name.
22222 v2df __builtin_ia32_addsubpd (v2df, v2df)
22223 v4sf __builtin_ia32_addsubps (v4sf, v4sf)
22224 v2df __builtin_ia32_haddpd (v2df, v2df)
22225 v4sf __builtin_ia32_haddps (v4sf, v4sf)
22226 v2df __builtin_ia32_hsubpd (v2df, v2df)
22227 v4sf __builtin_ia32_hsubps (v4sf, v4sf)
22228 v16qi __builtin_ia32_lddqu (char const *)
22229 void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
22230 v4sf __builtin_ia32_movshdup (v4sf)
22231 v4sf __builtin_ia32_movsldup (v4sf)
22232 void __builtin_ia32_mwait (unsigned int, unsigned int)
22235 The following built-in functions are available when @option{-mssse3} is used.
22236 All of them generate the machine instruction that is part of the name.
22239 v2si __builtin_ia32_phaddd (v2si, v2si)
22240 v4hi __builtin_ia32_phaddw (v4hi, v4hi)
22241 v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
22242 v2si __builtin_ia32_phsubd (v2si, v2si)
22243 v4hi __builtin_ia32_phsubw (v4hi, v4hi)
22244 v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
22245 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
22246 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
22247 v8qi __builtin_ia32_pshufb (v8qi, v8qi)
22248 v8qi __builtin_ia32_psignb (v8qi, v8qi)
22249 v2si __builtin_ia32_psignd (v2si, v2si)
22250 v4hi __builtin_ia32_psignw (v4hi, v4hi)
22251 v1di __builtin_ia32_palignr (v1di, v1di, int)
22252 v8qi __builtin_ia32_pabsb (v8qi)
22253 v2si __builtin_ia32_pabsd (v2si)
22254 v4hi __builtin_ia32_pabsw (v4hi)
22257 The following built-in functions are available when @option{-mssse3} is used.
22258 All of them generate the machine instruction that is part of the name.
22261 v4si __builtin_ia32_phaddd128 (v4si, v4si)
22262 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
22263 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
22264 v4si __builtin_ia32_phsubd128 (v4si, v4si)
22265 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
22266 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
22267 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
22268 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
22269 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
22270 v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
22271 v4si __builtin_ia32_psignd128 (v4si, v4si)
22272 v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
22273 v2di __builtin_ia32_palignr128 (v2di, v2di, int)
22274 v16qi __builtin_ia32_pabsb128 (v16qi)
22275 v4si __builtin_ia32_pabsd128 (v4si)
22276 v8hi __builtin_ia32_pabsw128 (v8hi)
22279 The following built-in functions are available when @option{-msse4.1} is
22280 used. All of them generate the machine instruction that is part of the
22284 v2df __builtin_ia32_blendpd (v2df, v2df, const int)
22285 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
22286 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
22287 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
22288 v2df __builtin_ia32_dppd (v2df, v2df, const int)
22289 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
22290 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
22291 v2di __builtin_ia32_movntdqa (v2di *);
22292 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
22293 v8hi __builtin_ia32_packusdw128 (v4si, v4si)
22294 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
22295 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
22296 v2di __builtin_ia32_pcmpeqq (v2di, v2di)
22297 v8hi __builtin_ia32_phminposuw128 (v8hi)
22298 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
22299 v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
22300 v4si __builtin_ia32_pmaxud128 (v4si, v4si)
22301 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
22302 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
22303 v4si __builtin_ia32_pminsd128 (v4si, v4si)
22304 v4si __builtin_ia32_pminud128 (v4si, v4si)
22305 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
22306 v4si __builtin_ia32_pmovsxbd128 (v16qi)
22307 v2di __builtin_ia32_pmovsxbq128 (v16qi)
22308 v8hi __builtin_ia32_pmovsxbw128 (v16qi)
22309 v2di __builtin_ia32_pmovsxdq128 (v4si)
22310 v4si __builtin_ia32_pmovsxwd128 (v8hi)
22311 v2di __builtin_ia32_pmovsxwq128 (v8hi)
22312 v4si __builtin_ia32_pmovzxbd128 (v16qi)
22313 v2di __builtin_ia32_pmovzxbq128 (v16qi)
22314 v8hi __builtin_ia32_pmovzxbw128 (v16qi)
22315 v2di __builtin_ia32_pmovzxdq128 (v4si)
22316 v4si __builtin_ia32_pmovzxwd128 (v8hi)
22317 v2di __builtin_ia32_pmovzxwq128 (v8hi)
22318 v2di __builtin_ia32_pmuldq128 (v4si, v4si)
22319 v4si __builtin_ia32_pmulld128 (v4si, v4si)
22320 int __builtin_ia32_ptestc128 (v2di, v2di)
22321 int __builtin_ia32_ptestnzc128 (v2di, v2di)
22322 int __builtin_ia32_ptestz128 (v2di, v2di)
22323 v2df __builtin_ia32_roundpd (v2df, const int)
22324 v4sf __builtin_ia32_roundps (v4sf, const int)
22325 v2df __builtin_ia32_roundsd (v2df, v2df, const int)
22326 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
22329 The following built-in functions are available when @option{-msse4.1} is
22333 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
22334 Generates the @code{insertps} machine instruction.
22335 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
22336 Generates the @code{pextrb} machine instruction.
22337 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
22338 Generates the @code{pinsrb} machine instruction.
22339 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
22340 Generates the @code{pinsrd} machine instruction.
22341 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
22342 Generates the @code{pinsrq} machine instruction in 64bit mode.
22345 The following built-in functions are changed to generate new SSE4.1
22346 instructions when @option{-msse4.1} is used.
22349 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
22350 Generates the @code{extractps} machine instruction.
22351 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
22352 Generates the @code{pextrd} machine instruction.
22353 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
22354 Generates the @code{pextrq} machine instruction in 64bit mode.
22357 The following built-in functions are available when @option{-msse4.2} is
22358 used. All of them generate the machine instruction that is part of the
22362 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
22363 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
22364 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
22365 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
22366 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
22367 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
22368 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
22369 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
22370 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
22371 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
22372 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
22373 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
22374 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
22375 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
22376 v2di __builtin_ia32_pcmpgtq (v2di, v2di)
22379 The following built-in functions are available when @option{-msse4.2} is
22383 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
22384 Generates the @code{crc32b} machine instruction.
22385 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
22386 Generates the @code{crc32w} machine instruction.
22387 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
22388 Generates the @code{crc32l} machine instruction.
22389 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
22390 Generates the @code{crc32q} machine instruction.
22393 The following built-in functions are changed to generate new SSE4.2
22394 instructions when @option{-msse4.2} is used.
22397 @item int __builtin_popcount (unsigned int)
22398 Generates the @code{popcntl} machine instruction.
22399 @item int __builtin_popcountl (unsigned long)
22400 Generates the @code{popcntl} or @code{popcntq} machine instruction,
22401 depending on the size of @code{unsigned long}.
22402 @item int __builtin_popcountll (unsigned long long)
22403 Generates the @code{popcntq} machine instruction.
22406 The following built-in functions are available when @option{-mavx} is
22407 used. All of them generate the machine instruction that is part of the
22411 v4df __builtin_ia32_addpd256 (v4df,v4df)
22412 v8sf __builtin_ia32_addps256 (v8sf,v8sf)
22413 v4df __builtin_ia32_addsubpd256 (v4df,v4df)
22414 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
22415 v4df __builtin_ia32_andnpd256 (v4df,v4df)
22416 v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
22417 v4df __builtin_ia32_andpd256 (v4df,v4df)
22418 v8sf __builtin_ia32_andps256 (v8sf,v8sf)
22419 v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
22420 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
22421 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
22422 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
22423 v2df __builtin_ia32_cmppd (v2df,v2df,int)
22424 v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
22425 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
22426 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
22427 v2df __builtin_ia32_cmpsd (v2df,v2df,int)
22428 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
22429 v4df __builtin_ia32_cvtdq2pd256 (v4si)
22430 v8sf __builtin_ia32_cvtdq2ps256 (v8si)
22431 v4si __builtin_ia32_cvtpd2dq256 (v4df)
22432 v4sf __builtin_ia32_cvtpd2ps256 (v4df)
22433 v8si __builtin_ia32_cvtps2dq256 (v8sf)
22434 v4df __builtin_ia32_cvtps2pd256 (v4sf)
22435 v4si __builtin_ia32_cvttpd2dq256 (v4df)
22436 v8si __builtin_ia32_cvttps2dq256 (v8sf)
22437 v4df __builtin_ia32_divpd256 (v4df,v4df)
22438 v8sf __builtin_ia32_divps256 (v8sf,v8sf)
22439 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
22440 v4df __builtin_ia32_haddpd256 (v4df,v4df)
22441 v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
22442 v4df __builtin_ia32_hsubpd256 (v4df,v4df)
22443 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
22444 v32qi __builtin_ia32_lddqu256 (pcchar)
22445 v32qi __builtin_ia32_loaddqu256 (pcchar)
22446 v4df __builtin_ia32_loadupd256 (pcdouble)
22447 v8sf __builtin_ia32_loadups256 (pcfloat)
22448 v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
22449 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
22450 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
22451 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
22452 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
22453 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
22454 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
22455 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
22456 v4df __builtin_ia32_maxpd256 (v4df,v4df)
22457 v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
22458 v4df __builtin_ia32_minpd256 (v4df,v4df)
22459 v8sf __builtin_ia32_minps256 (v8sf,v8sf)
22460 v4df __builtin_ia32_movddup256 (v4df)
22461 int __builtin_ia32_movmskpd256 (v4df)
22462 int __builtin_ia32_movmskps256 (v8sf)
22463 v8sf __builtin_ia32_movshdup256 (v8sf)
22464 v8sf __builtin_ia32_movsldup256 (v8sf)
22465 v4df __builtin_ia32_mulpd256 (v4df,v4df)
22466 v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
22467 v4df __builtin_ia32_orpd256 (v4df,v4df)
22468 v8sf __builtin_ia32_orps256 (v8sf,v8sf)
22469 v2df __builtin_ia32_pd_pd256 (v4df)
22470 v4df __builtin_ia32_pd256_pd (v2df)
22471 v4sf __builtin_ia32_ps_ps256 (v8sf)
22472 v8sf __builtin_ia32_ps256_ps (v4sf)
22473 int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
22474 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
22475 int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
22476 v8sf __builtin_ia32_rcpps256 (v8sf)
22477 v4df __builtin_ia32_roundpd256 (v4df,int)
22478 v8sf __builtin_ia32_roundps256 (v8sf,int)
22479 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
22480 v8sf __builtin_ia32_rsqrtps256 (v8sf)
22481 v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
22482 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
22483 v4si __builtin_ia32_si_si256 (v8si)
22484 v8si __builtin_ia32_si256_si (v4si)
22485 v4df __builtin_ia32_sqrtpd256 (v4df)
22486 v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
22487 v8sf __builtin_ia32_sqrtps256 (v8sf)
22488 void __builtin_ia32_storedqu256 (pchar,v32qi)
22489 void __builtin_ia32_storeupd256 (pdouble,v4df)
22490 void __builtin_ia32_storeups256 (pfloat,v8sf)
22491 v4df __builtin_ia32_subpd256 (v4df,v4df)
22492 v8sf __builtin_ia32_subps256 (v8sf,v8sf)
22493 v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
22494 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
22495 v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
22496 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
22497 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
22498 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
22499 v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
22500 v4sf __builtin_ia32_vbroadcastss (pcfloat)
22501 v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
22502 v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
22503 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
22504 v4si __builtin_ia32_vextractf128_si256 (v8si,int)
22505 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
22506 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
22507 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
22508 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
22509 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
22510 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
22511 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
22512 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
22513 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
22514 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
22515 v2df __builtin_ia32_vpermilpd (v2df,int)
22516 v4df __builtin_ia32_vpermilpd256 (v4df,int)
22517 v4sf __builtin_ia32_vpermilps (v4sf,int)
22518 v8sf __builtin_ia32_vpermilps256 (v8sf,int)
22519 v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
22520 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
22521 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
22522 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
22523 int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
22524 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
22525 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
22526 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
22527 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
22528 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
22529 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
22530 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
22531 int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
22532 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
22533 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
22534 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
22535 void __builtin_ia32_vzeroall (void)
22536 void __builtin_ia32_vzeroupper (void)
22537 v4df __builtin_ia32_xorpd256 (v4df,v4df)
22538 v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
22541 The following built-in functions are available when @option{-mavx2} is
22542 used. All of them generate the machine instruction that is part of the
22546 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
22547 v32qi __builtin_ia32_pabsb256 (v32qi)
22548 v16hi __builtin_ia32_pabsw256 (v16hi)
22549 v8si __builtin_ia32_pabsd256 (v8si)
22550 v16hi __builtin_ia32_packssdw256 (v8si,v8si)
22551 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi)
22552 v16hi __builtin_ia32_packusdw256 (v8si,v8si)
22553 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi)
22554 v32qi __builtin_ia32_paddb256 (v32qi,v32qi)
22555 v16hi __builtin_ia32_paddw256 (v16hi,v16hi)
22556 v8si __builtin_ia32_paddd256 (v8si,v8si)
22557 v4di __builtin_ia32_paddq256 (v4di,v4di)
22558 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi)
22559 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi)
22560 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi)
22561 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi)
22562 v4di __builtin_ia32_palignr256 (v4di,v4di,int)
22563 v4di __builtin_ia32_andsi256 (v4di,v4di)
22564 v4di __builtin_ia32_andnotsi256 (v4di,v4di)
22565 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi)
22566 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi)
22567 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi)
22568 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int)
22569 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi)
22570 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi)
22571 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si)
22572 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di)
22573 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi)
22574 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi)
22575 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si)
22576 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di)
22577 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi)
22578 v8si __builtin_ia32_phaddd256 (v8si,v8si)
22579 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi)
22580 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi)
22581 v8si __builtin_ia32_phsubd256 (v8si,v8si)
22582 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi)
22583 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi)
22584 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi)
22585 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi)
22586 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi)
22587 v8si __builtin_ia32_pmaxsd256 (v8si,v8si)
22588 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi)
22589 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi)
22590 v8si __builtin_ia32_pmaxud256 (v8si,v8si)
22591 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi)
22592 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi)
22593 v8si __builtin_ia32_pminsd256 (v8si,v8si)
22594 v32qi __builtin_ia32_pminub256 (v32qi,v32qi)
22595 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi)
22596 v8si __builtin_ia32_pminud256 (v8si,v8si)
22597 int __builtin_ia32_pmovmskb256 (v32qi)
22598 v16hi __builtin_ia32_pmovsxbw256 (v16qi)
22599 v8si __builtin_ia32_pmovsxbd256 (v16qi)
22600 v4di __builtin_ia32_pmovsxbq256 (v16qi)
22601 v8si __builtin_ia32_pmovsxwd256 (v8hi)
22602 v4di __builtin_ia32_pmovsxwq256 (v8hi)
22603 v4di __builtin_ia32_pmovsxdq256 (v4si)
22604 v16hi __builtin_ia32_pmovzxbw256 (v16qi)
22605 v8si __builtin_ia32_pmovzxbd256 (v16qi)
22606 v4di __builtin_ia32_pmovzxbq256 (v16qi)
22607 v8si __builtin_ia32_pmovzxwd256 (v8hi)
22608 v4di __builtin_ia32_pmovzxwq256 (v8hi)
22609 v4di __builtin_ia32_pmovzxdq256 (v4si)
22610 v4di __builtin_ia32_pmuldq256 (v8si,v8si)
22611 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi)
22612 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi)
22613 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi)
22614 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi)
22615 v8si __builtin_ia32_pmulld256 (v8si,v8si)
22616 v4di __builtin_ia32_pmuludq256 (v8si,v8si)
22617 v4di __builtin_ia32_por256 (v4di,v4di)
22618 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi)
22619 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi)
22620 v8si __builtin_ia32_pshufd256 (v8si,int)
22621 v16hi __builtin_ia32_pshufhw256 (v16hi,int)
22622 v16hi __builtin_ia32_pshuflw256 (v16hi,int)
22623 v32qi __builtin_ia32_psignb256 (v32qi,v32qi)
22624 v16hi __builtin_ia32_psignw256 (v16hi,v16hi)
22625 v8si __builtin_ia32_psignd256 (v8si,v8si)
22626 v4di __builtin_ia32_pslldqi256 (v4di,int)
22627 v16hi __builtin_ia32_psllwi256 (16hi,int)
22628 v16hi __builtin_ia32_psllw256(v16hi,v8hi)
22629 v8si __builtin_ia32_pslldi256 (v8si,int)
22630 v8si __builtin_ia32_pslld256(v8si,v4si)
22631 v4di __builtin_ia32_psllqi256 (v4di,int)
22632 v4di __builtin_ia32_psllq256(v4di,v2di)
22633 v16hi __builtin_ia32_psrawi256 (v16hi,int)
22634 v16hi __builtin_ia32_psraw256 (v16hi,v8hi)
22635 v8si __builtin_ia32_psradi256 (v8si,int)
22636 v8si __builtin_ia32_psrad256 (v8si,v4si)
22637 v4di __builtin_ia32_psrldqi256 (v4di, int)
22638 v16hi __builtin_ia32_psrlwi256 (v16hi,int)
22639 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi)
22640 v8si __builtin_ia32_psrldi256 (v8si,int)
22641 v8si __builtin_ia32_psrld256 (v8si,v4si)
22642 v4di __builtin_ia32_psrlqi256 (v4di,int)
22643 v4di __builtin_ia32_psrlq256(v4di,v2di)
22644 v32qi __builtin_ia32_psubb256 (v32qi,v32qi)
22645 v32hi __builtin_ia32_psubw256 (v16hi,v16hi)
22646 v8si __builtin_ia32_psubd256 (v8si,v8si)
22647 v4di __builtin_ia32_psubq256 (v4di,v4di)
22648 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi)
22649 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi)
22650 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi)
22651 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi)
22652 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi)
22653 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi)
22654 v8si __builtin_ia32_punpckhdq256 (v8si,v8si)
22655 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di)
22656 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi)
22657 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi)
22658 v8si __builtin_ia32_punpckldq256 (v8si,v8si)
22659 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di)
22660 v4di __builtin_ia32_pxor256 (v4di,v4di)
22661 v4di __builtin_ia32_movntdqa256 (pv4di)
22662 v4sf __builtin_ia32_vbroadcastss_ps (v4sf)
22663 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf)
22664 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df)
22665 v4di __builtin_ia32_vbroadcastsi256 (v2di)
22666 v4si __builtin_ia32_pblendd128 (v4si,v4si)
22667 v8si __builtin_ia32_pblendd256 (v8si,v8si)
22668 v32qi __builtin_ia32_pbroadcastb256 (v16qi)
22669 v16hi __builtin_ia32_pbroadcastw256 (v8hi)
22670 v8si __builtin_ia32_pbroadcastd256 (v4si)
22671 v4di __builtin_ia32_pbroadcastq256 (v2di)
22672 v16qi __builtin_ia32_pbroadcastb128 (v16qi)
22673 v8hi __builtin_ia32_pbroadcastw128 (v8hi)
22674 v4si __builtin_ia32_pbroadcastd128 (v4si)
22675 v2di __builtin_ia32_pbroadcastq128 (v2di)
22676 v8si __builtin_ia32_permvarsi256 (v8si,v8si)
22677 v4df __builtin_ia32_permdf256 (v4df,int)
22678 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf)
22679 v4di __builtin_ia32_permdi256 (v4di,int)
22680 v4di __builtin_ia32_permti256 (v4di,v4di,int)
22681 v4di __builtin_ia32_extract128i256 (v4di,int)
22682 v4di __builtin_ia32_insert128i256 (v4di,v2di,int)
22683 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si)
22684 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di)
22685 v4si __builtin_ia32_maskloadd (pcv4si,v4si)
22686 v2di __builtin_ia32_maskloadq (pcv2di,v2di)
22687 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si)
22688 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di)
22689 void __builtin_ia32_maskstored (pv4si,v4si,v4si)
22690 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di)
22691 v8si __builtin_ia32_psllv8si (v8si,v8si)
22692 v4si __builtin_ia32_psllv4si (v4si,v4si)
22693 v4di __builtin_ia32_psllv4di (v4di,v4di)
22694 v2di __builtin_ia32_psllv2di (v2di,v2di)
22695 v8si __builtin_ia32_psrav8si (v8si,v8si)
22696 v4si __builtin_ia32_psrav4si (v4si,v4si)
22697 v8si __builtin_ia32_psrlv8si (v8si,v8si)
22698 v4si __builtin_ia32_psrlv4si (v4si,v4si)
22699 v4di __builtin_ia32_psrlv4di (v4di,v4di)
22700 v2di __builtin_ia32_psrlv2di (v2di,v2di)
22701 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int)
22702 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int)
22703 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int)
22704 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int)
22705 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int)
22706 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int)
22707 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int)
22708 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int)
22709 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int)
22710 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int)
22711 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int)
22712 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int)
22713 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int)
22714 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int)
22715 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int)
22716 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int)
22719 The following built-in functions are available when @option{-maes} is
22720 used. All of them generate the machine instruction that is part of the
22724 v2di __builtin_ia32_aesenc128 (v2di, v2di)
22725 v2di __builtin_ia32_aesenclast128 (v2di, v2di)
22726 v2di __builtin_ia32_aesdec128 (v2di, v2di)
22727 v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
22728 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
22729 v2di __builtin_ia32_aesimc128 (v2di)
22732 The following built-in function is available when @option{-mpclmul} is
22736 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
22737 Generates the @code{pclmulqdq} machine instruction.
22740 The following built-in function is available when @option{-mfsgsbase} is
22741 used. All of them generate the machine instruction that is part of the
22745 unsigned int __builtin_ia32_rdfsbase32 (void)
22746 unsigned long long __builtin_ia32_rdfsbase64 (void)
22747 unsigned int __builtin_ia32_rdgsbase32 (void)
22748 unsigned long long __builtin_ia32_rdgsbase64 (void)
22749 void _writefsbase_u32 (unsigned int)
22750 void _writefsbase_u64 (unsigned long long)
22751 void _writegsbase_u32 (unsigned int)
22752 void _writegsbase_u64 (unsigned long long)
22755 The following built-in function is available when @option{-mrdrnd} is
22756 used. All of them generate the machine instruction that is part of the
22760 unsigned int __builtin_ia32_rdrand16_step (unsigned short *)
22761 unsigned int __builtin_ia32_rdrand32_step (unsigned int *)
22762 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *)
22765 The following built-in function is available when @option{-mptwrite} is
22766 used. All of them generate the machine instruction that is part of the
22770 void __builtin_ia32_ptwrite32 (unsigned)
22771 void __builtin_ia32_ptwrite64 (unsigned long long)
22774 The following built-in functions are available when @option{-msse4a} is used.
22775 All of them generate the machine instruction that is part of the name.
22778 void __builtin_ia32_movntsd (double *, v2df)
22779 void __builtin_ia32_movntss (float *, v4sf)
22780 v2di __builtin_ia32_extrq (v2di, v16qi)
22781 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
22782 v2di __builtin_ia32_insertq (v2di, v2di)
22783 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
22786 The following built-in functions are available when @option{-mxop} is used.
22788 v2df __builtin_ia32_vfrczpd (v2df)
22789 v4sf __builtin_ia32_vfrczps (v4sf)
22790 v2df __builtin_ia32_vfrczsd (v2df)
22791 v4sf __builtin_ia32_vfrczss (v4sf)
22792 v4df __builtin_ia32_vfrczpd256 (v4df)
22793 v8sf __builtin_ia32_vfrczps256 (v8sf)
22794 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
22795 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
22796 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
22797 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
22798 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
22799 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
22800 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
22801 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
22802 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
22803 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
22804 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
22805 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
22806 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
22807 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
22808 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
22809 v4si __builtin_ia32_vpcomeqd (v4si, v4si)
22810 v2di __builtin_ia32_vpcomeqq (v2di, v2di)
22811 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
22812 v4si __builtin_ia32_vpcomequd (v4si, v4si)
22813 v2di __builtin_ia32_vpcomequq (v2di, v2di)
22814 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
22815 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
22816 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
22817 v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
22818 v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
22819 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
22820 v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
22821 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
22822 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
22823 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
22824 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
22825 v4si __builtin_ia32_vpcomged (v4si, v4si)
22826 v2di __builtin_ia32_vpcomgeq (v2di, v2di)
22827 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
22828 v4si __builtin_ia32_vpcomgeud (v4si, v4si)
22829 v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
22830 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
22831 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
22832 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
22833 v4si __builtin_ia32_vpcomgtd (v4si, v4si)
22834 v2di __builtin_ia32_vpcomgtq (v2di, v2di)
22835 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
22836 v4si __builtin_ia32_vpcomgtud (v4si, v4si)
22837 v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
22838 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
22839 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
22840 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
22841 v4si __builtin_ia32_vpcomled (v4si, v4si)
22842 v2di __builtin_ia32_vpcomleq (v2di, v2di)
22843 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
22844 v4si __builtin_ia32_vpcomleud (v4si, v4si)
22845 v2di __builtin_ia32_vpcomleuq (v2di, v2di)
22846 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
22847 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
22848 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
22849 v4si __builtin_ia32_vpcomltd (v4si, v4si)
22850 v2di __builtin_ia32_vpcomltq (v2di, v2di)
22851 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
22852 v4si __builtin_ia32_vpcomltud (v4si, v4si)
22853 v2di __builtin_ia32_vpcomltuq (v2di, v2di)
22854 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
22855 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
22856 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
22857 v4si __builtin_ia32_vpcomned (v4si, v4si)
22858 v2di __builtin_ia32_vpcomneq (v2di, v2di)
22859 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
22860 v4si __builtin_ia32_vpcomneud (v4si, v4si)
22861 v2di __builtin_ia32_vpcomneuq (v2di, v2di)
22862 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
22863 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
22864 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
22865 v4si __builtin_ia32_vpcomtrued (v4si, v4si)
22866 v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
22867 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
22868 v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
22869 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
22870 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
22871 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
22872 v4si __builtin_ia32_vphaddbd (v16qi)
22873 v2di __builtin_ia32_vphaddbq (v16qi)
22874 v8hi __builtin_ia32_vphaddbw (v16qi)
22875 v2di __builtin_ia32_vphadddq (v4si)
22876 v4si __builtin_ia32_vphaddubd (v16qi)
22877 v2di __builtin_ia32_vphaddubq (v16qi)
22878 v8hi __builtin_ia32_vphaddubw (v16qi)
22879 v2di __builtin_ia32_vphaddudq (v4si)
22880 v4si __builtin_ia32_vphadduwd (v8hi)
22881 v2di __builtin_ia32_vphadduwq (v8hi)
22882 v4si __builtin_ia32_vphaddwd (v8hi)
22883 v2di __builtin_ia32_vphaddwq (v8hi)
22884 v8hi __builtin_ia32_vphsubbw (v16qi)
22885 v2di __builtin_ia32_vphsubdq (v4si)
22886 v4si __builtin_ia32_vphsubwd (v8hi)
22887 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
22888 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
22889 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
22890 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
22891 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
22892 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
22893 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
22894 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
22895 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
22896 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
22897 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
22898 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
22899 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
22900 v16qi __builtin_ia32_vprotb (v16qi, v16qi)
22901 v4si __builtin_ia32_vprotd (v4si, v4si)
22902 v2di __builtin_ia32_vprotq (v2di, v2di)
22903 v8hi __builtin_ia32_vprotw (v8hi, v8hi)
22904 v16qi __builtin_ia32_vpshab (v16qi, v16qi)
22905 v4si __builtin_ia32_vpshad (v4si, v4si)
22906 v2di __builtin_ia32_vpshaq (v2di, v2di)
22907 v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
22908 v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
22909 v4si __builtin_ia32_vpshld (v4si, v4si)
22910 v2di __builtin_ia32_vpshlq (v2di, v2di)
22911 v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
22914 The following built-in functions are available when @option{-mfma4} is used.
22915 All of them generate the machine instruction that is part of the name.
22918 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df)
22919 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf)
22920 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df)
22921 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf)
22922 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df)
22923 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf)
22924 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df)
22925 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf)
22926 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df)
22927 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf)
22928 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df)
22929 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf)
22930 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df)
22931 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf)
22932 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df)
22933 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf)
22934 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df)
22935 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf)
22936 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df)
22937 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf)
22938 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df)
22939 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf)
22940 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df)
22941 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf)
22942 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df)
22943 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf)
22944 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df)
22945 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf)
22946 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df)
22947 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf)
22948 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df)
22949 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf)
22953 The following built-in functions are available when @option{-mlwp} is used.
22956 void __builtin_ia32_llwpcb16 (void *);
22957 void __builtin_ia32_llwpcb32 (void *);
22958 void __builtin_ia32_llwpcb64 (void *);
22959 void * __builtin_ia32_llwpcb16 (void);
22960 void * __builtin_ia32_llwpcb32 (void);
22961 void * __builtin_ia32_llwpcb64 (void);
22962 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
22963 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
22964 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
22965 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
22966 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
22967 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
22970 The following built-in functions are available when @option{-mbmi} is used.
22971 All of them generate the machine instruction that is part of the name.
22973 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
22974 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
22977 The following built-in functions are available when @option{-mbmi2} is used.
22978 All of them generate the machine instruction that is part of the name.
22980 unsigned int _bzhi_u32 (unsigned int, unsigned int)
22981 unsigned int _pdep_u32 (unsigned int, unsigned int)
22982 unsigned int _pext_u32 (unsigned int, unsigned int)
22983 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long)
22984 unsigned long long _pdep_u64 (unsigned long long, unsigned long long)
22985 unsigned long long _pext_u64 (unsigned long long, unsigned long long)
22988 The following built-in functions are available when @option{-mlzcnt} is used.
22989 All of them generate the machine instruction that is part of the name.
22991 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
22992 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
22993 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
22996 The following built-in functions are available when @option{-mfxsr} is used.
22997 All of them generate the machine instruction that is part of the name.
22999 void __builtin_ia32_fxsave (void *)
23000 void __builtin_ia32_fxrstor (void *)
23001 void __builtin_ia32_fxsave64 (void *)
23002 void __builtin_ia32_fxrstor64 (void *)
23005 The following built-in functions are available when @option{-mxsave} is used.
23006 All of them generate the machine instruction that is part of the name.
23008 void __builtin_ia32_xsave (void *, long long)
23009 void __builtin_ia32_xrstor (void *, long long)
23010 void __builtin_ia32_xsave64 (void *, long long)
23011 void __builtin_ia32_xrstor64 (void *, long long)
23014 The following built-in functions are available when @option{-mxsaveopt} is used.
23015 All of them generate the machine instruction that is part of the name.
23017 void __builtin_ia32_xsaveopt (void *, long long)
23018 void __builtin_ia32_xsaveopt64 (void *, long long)
23021 The following built-in functions are available when @option{-mtbm} is used.
23022 Both of them generate the immediate form of the bextr machine instruction.
23024 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
23025 const unsigned int);
23026 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
23027 const unsigned long long);
23031 The following built-in functions are available when @option{-m3dnow} is used.
23032 All of them generate the machine instruction that is part of the name.
23035 void __builtin_ia32_femms (void)
23036 v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
23037 v2si __builtin_ia32_pf2id (v2sf)
23038 v2sf __builtin_ia32_pfacc (v2sf, v2sf)
23039 v2sf __builtin_ia32_pfadd (v2sf, v2sf)
23040 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
23041 v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
23042 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
23043 v2sf __builtin_ia32_pfmax (v2sf, v2sf)
23044 v2sf __builtin_ia32_pfmin (v2sf, v2sf)
23045 v2sf __builtin_ia32_pfmul (v2sf, v2sf)
23046 v2sf __builtin_ia32_pfrcp (v2sf)
23047 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
23048 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
23049 v2sf __builtin_ia32_pfrsqrt (v2sf)
23050 v2sf __builtin_ia32_pfsub (v2sf, v2sf)
23051 v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
23052 v2sf __builtin_ia32_pi2fd (v2si)
23053 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
23056 The following built-in functions are available when @option{-m3dnowa} is used.
23057 All of them generate the machine instruction that is part of the name.
23060 v2si __builtin_ia32_pf2iw (v2sf)
23061 v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
23062 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
23063 v2sf __builtin_ia32_pi2fw (v2si)
23064 v2sf __builtin_ia32_pswapdsf (v2sf)
23065 v2si __builtin_ia32_pswapdsi (v2si)
23068 The following built-in functions are available when @option{-mrtm} is used
23069 They are used for restricted transactional memory. These are the internal
23070 low level functions. Normally the functions in
23071 @ref{x86 transactional memory intrinsics} should be used instead.
23074 int __builtin_ia32_xbegin ()
23075 void __builtin_ia32_xend ()
23076 void __builtin_ia32_xabort (status)
23077 int __builtin_ia32_xtest ()
23080 The following built-in functions are available when @option{-mmwaitx} is used.
23081 All of them generate the machine instruction that is part of the name.
23083 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int)
23084 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int)
23087 The following built-in functions are available when @option{-mclzero} is used.
23088 All of them generate the machine instruction that is part of the name.
23090 void __builtin_i32_clzero (void *)
23093 The following built-in functions are available when @option{-mpku} is used.
23094 They generate reads and writes to PKRU.
23096 void __builtin_ia32_wrpkru (unsigned int)
23097 unsigned int __builtin_ia32_rdpkru ()
23100 The following built-in functions are available when
23101 @option{-mshstk} option is used. They support shadow stack
23102 machine instructions from Intel Control-flow Enforcement Technology (CET).
23103 Each built-in function generates the machine instruction that is part
23104 of the function's name. These are the internal low-level functions.
23105 Normally the functions in @ref{x86 control-flow protection intrinsics}
23106 should be used instead.
23109 unsigned int __builtin_ia32_rdsspd (void)
23110 unsigned long long __builtin_ia32_rdsspq (void)
23111 void __builtin_ia32_incsspd (unsigned int)
23112 void __builtin_ia32_incsspq (unsigned long long)
23113 void __builtin_ia32_saveprevssp(void);
23114 void __builtin_ia32_rstorssp(void *);
23115 void __builtin_ia32_wrssd(unsigned int, void *);
23116 void __builtin_ia32_wrssq(unsigned long long, void *);
23117 void __builtin_ia32_wrussd(unsigned int, void *);
23118 void __builtin_ia32_wrussq(unsigned long long, void *);
23119 void __builtin_ia32_setssbsy(void);
23120 void __builtin_ia32_clrssbsy(void *);
23123 @node x86 transactional memory intrinsics
23124 @subsection x86 Transactional Memory Intrinsics
23126 These hardware transactional memory intrinsics for x86 allow you to use
23127 memory transactions with RTM (Restricted Transactional Memory).
23128 This support is enabled with the @option{-mrtm} option.
23129 For using HLE (Hardware Lock Elision) see
23130 @ref{x86 specific memory model extensions for transactional memory} instead.
23132 A memory transaction commits all changes to memory in an atomic way,
23133 as visible to other threads. If the transaction fails it is rolled back
23134 and all side effects discarded.
23136 Generally there is no guarantee that a memory transaction ever succeeds
23137 and suitable fallback code always needs to be supplied.
23139 @deftypefn {RTM Function} {unsigned} _xbegin ()
23140 Start a RTM (Restricted Transactional Memory) transaction.
23141 Returns @code{_XBEGIN_STARTED} when the transaction
23142 started successfully (note this is not 0, so the constant has to be
23143 explicitly tested).
23145 If the transaction aborts, all side effects
23146 are undone and an abort code encoded as a bit mask is returned.
23147 The following macros are defined:
23150 @item _XABORT_EXPLICIT
23151 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
23152 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
23153 @item _XABORT_RETRY
23154 Transaction retry is possible.
23155 @item _XABORT_CONFLICT
23156 Transaction abort due to a memory conflict with another thread.
23157 @item _XABORT_CAPACITY
23158 Transaction abort due to the transaction using too much memory.
23159 @item _XABORT_DEBUG
23160 Transaction abort due to a debug trap.
23161 @item _XABORT_NESTED
23162 Transaction abort in an inner nested transaction.
23165 There is no guarantee
23166 any transaction ever succeeds, so there always needs to be a valid
23170 @deftypefn {RTM Function} {void} _xend ()
23171 Commit the current transaction. When no transaction is active this faults.
23172 All memory side effects of the transaction become visible
23173 to other threads in an atomic manner.
23176 @deftypefn {RTM Function} {int} _xtest ()
23177 Return a nonzero value if a transaction is currently active, otherwise 0.
23180 @deftypefn {RTM Function} {void} _xabort (status)
23181 Abort the current transaction. When no transaction is active this is a no-op.
23182 The @var{status} is an 8-bit constant; its value is encoded in the return
23183 value from @code{_xbegin}.
23186 Here is an example showing handling for @code{_XABORT_RETRY}
23187 and a fallback path for other failures:
23190 #include <immintrin.h>
23192 int n_tries, max_tries;
23193 unsigned status = _XABORT_EXPLICIT;
23196 for (n_tries = 0; n_tries < max_tries; n_tries++)
23198 status = _xbegin ();
23199 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
23202 if (status == _XBEGIN_STARTED)
23204 ... transaction code...
23209 ... non-transactional fallback path...
23214 Note that, in most cases, the transactional and non-transactional code
23215 must synchronize together to ensure consistency.
23217 @node x86 control-flow protection intrinsics
23218 @subsection x86 Control-Flow Protection Intrinsics
23220 @deftypefn {CET Function} {ret_type} _get_ssp (void)
23221 Get the current value of shadow stack pointer if shadow stack support
23222 from Intel CET is enabled in the hardware or @code{0} otherwise.
23223 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
23224 and @code{unsigned int} for 32-bit targets.
23227 @deftypefn {CET Function} void _inc_ssp (unsigned int)
23228 Increment the current shadow stack pointer by the size specified by the
23229 function argument. The argument is masked to a byte value for security
23230 reasons, so to increment by more than 255 bytes you must call the function
23234 The shadow stack unwind code looks like:
23237 #include <immintrin.h>
23239 /* Unwind the shadow stack for EH. */
23240 #define _Unwind_Frames_Extra(x) \
23243 _Unwind_Word ssp = _get_ssp (); \
23246 _Unwind_Word tmp = (x); \
23247 while (tmp > 255) \
23259 This code runs unconditionally on all 64-bit processors. For 32-bit
23260 processors the code runs on those that support multi-byte NOP instructions.
23262 @node Target Format Checks
23263 @section Format Checks Specific to Particular Target Machines
23265 For some target machines, GCC supports additional options to the
23267 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
23270 * Solaris Format Checks::
23271 * Darwin Format Checks::
23274 @node Solaris Format Checks
23275 @subsection Solaris Format Checks
23277 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
23278 check. @code{cmn_err} accepts a subset of the standard @code{printf}
23279 conversions, and the two-argument @code{%b} conversion for displaying
23280 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
23282 @node Darwin Format Checks
23283 @subsection Darwin Format Checks
23285 In addition to the full set of format archetypes (attribute format style
23286 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
23287 @code{strfmon}), Darwin targets also support the @code{CFString} (or
23288 @code{__CFString__}) archetype in the @code{format} attribute.
23289 Declarations with this archetype are parsed for correct syntax
23290 and argument types. However, parsing of the format string itself and
23291 validating arguments against it in calls to such functions is currently
23294 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
23295 also be used as format arguments. Note that the relevant headers are only likely to be
23296 available on Darwin (OSX) installations. On such installations, the XCode and system
23297 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
23298 associated functions.
23301 @section Pragmas Accepted by GCC
23303 @cindex @code{#pragma}
23305 GCC supports several types of pragmas, primarily in order to compile
23306 code originally written for other compilers. Note that in general
23307 we do not recommend the use of pragmas; @xref{Function Attributes},
23308 for further explanation.
23310 The GNU C preprocessor recognizes several pragmas in addition to the
23311 compiler pragmas documented here. Refer to the CPP manual for more
23315 * AArch64 Pragmas::
23320 * RS/6000 and PowerPC Pragmas::
23323 * Solaris Pragmas::
23324 * Symbol-Renaming Pragmas::
23325 * Structure-Layout Pragmas::
23327 * Diagnostic Pragmas::
23328 * Visibility Pragmas::
23329 * Push/Pop Macro Pragmas::
23330 * Function Specific Option Pragmas::
23331 * Loop-Specific Pragmas::
23334 @node AArch64 Pragmas
23335 @subsection AArch64 Pragmas
23337 The pragmas defined by the AArch64 target correspond to the AArch64
23338 target function attributes. They can be specified as below:
23340 #pragma GCC target("string")
23343 where @code{@var{string}} can be any string accepted as an AArch64 target
23344 attribute. @xref{AArch64 Function Attributes}, for more details
23345 on the permissible values of @code{string}.
23348 @subsection ARM Pragmas
23350 The ARM target defines pragmas for controlling the default addition of
23351 @code{long_call} and @code{short_call} attributes to functions.
23352 @xref{Function Attributes}, for information about the effects of these
23357 @cindex pragma, long_calls
23358 Set all subsequent functions to have the @code{long_call} attribute.
23360 @item no_long_calls
23361 @cindex pragma, no_long_calls
23362 Set all subsequent functions to have the @code{short_call} attribute.
23364 @item long_calls_off
23365 @cindex pragma, long_calls_off
23366 Do not affect the @code{long_call} or @code{short_call} attributes of
23367 subsequent functions.
23371 @subsection M32C Pragmas
23374 @item GCC memregs @var{number}
23375 @cindex pragma, memregs
23376 Overrides the command-line option @code{-memregs=} for the current
23377 file. Use with care! This pragma must be before any function in the
23378 file, and mixing different memregs values in different objects may
23379 make them incompatible. This pragma is useful when a
23380 performance-critical function uses a memreg for temporary values,
23381 as it may allow you to reduce the number of memregs used.
23383 @item ADDRESS @var{name} @var{address}
23384 @cindex pragma, address
23385 For any declared symbols matching @var{name}, this does three things
23386 to that symbol: it forces the symbol to be located at the given
23387 address (a number), it forces the symbol to be volatile, and it
23388 changes the symbol's scope to be static. This pragma exists for
23389 compatibility with other compilers, but note that the common
23390 @code{1234H} numeric syntax is not supported (use @code{0x1234}
23394 #pragma ADDRESS port3 0x103
23401 @subsection MeP Pragmas
23405 @item custom io_volatile (on|off)
23406 @cindex pragma, custom io_volatile
23407 Overrides the command-line option @code{-mio-volatile} for the current
23408 file. Note that for compatibility with future GCC releases, this
23409 option should only be used once before any @code{io} variables in each
23412 @item GCC coprocessor available @var{registers}
23413 @cindex pragma, coprocessor available
23414 Specifies which coprocessor registers are available to the register
23415 allocator. @var{registers} may be a single register, register range
23416 separated by ellipses, or comma-separated list of those. Example:
23419 #pragma GCC coprocessor available $c0...$c10, $c28
23422 @item GCC coprocessor call_saved @var{registers}
23423 @cindex pragma, coprocessor call_saved
23424 Specifies which coprocessor registers are to be saved and restored by
23425 any function using them. @var{registers} may be a single register,
23426 register range separated by ellipses, or comma-separated list of
23430 #pragma GCC coprocessor call_saved $c4...$c6, $c31
23433 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
23434 @cindex pragma, coprocessor subclass
23435 Creates and defines a register class. These register classes can be
23436 used by inline @code{asm} constructs. @var{registers} may be a single
23437 register, register range separated by ellipses, or comma-separated
23438 list of those. Example:
23441 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
23443 asm ("cpfoo %0" : "=B" (x));
23446 @item GCC disinterrupt @var{name} , @var{name} @dots{}
23447 @cindex pragma, disinterrupt
23448 For the named functions, the compiler adds code to disable interrupts
23449 for the duration of those functions. If any functions so named
23450 are not encountered in the source, a warning is emitted that the pragma is
23451 not used. Examples:
23454 #pragma disinterrupt foo
23455 #pragma disinterrupt bar, grill
23456 int foo () @{ @dots{} @}
23459 @item GCC call @var{name} , @var{name} @dots{}
23460 @cindex pragma, call
23461 For the named functions, the compiler always uses a register-indirect
23462 call model when calling the named functions. Examples:
23472 @subsection PRU Pragmas
23476 @item ctable_entry @var{index} @var{constant_address}
23477 @cindex pragma, ctable_entry
23478 Specifies that the PRU CTABLE entry given by @var{index} has the value
23479 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
23480 when the load/store address is known and can be addressed with some CTABLE
23481 entry. For example:
23484 /* will compile to "sbco Rx, 2, 0x10, 4" */
23485 #pragma ctable_entry 2 0x4802a000
23486 *(unsigned int *)0x4802a010 = val;
23491 @node RS/6000 and PowerPC Pragmas
23492 @subsection RS/6000 and PowerPC Pragmas
23494 The RS/6000 and PowerPC targets define one pragma for controlling
23495 whether or not the @code{longcall} attribute is added to function
23496 declarations by default. This pragma overrides the @option{-mlongcall}
23497 option, but not the @code{longcall} and @code{shortcall} attributes.
23498 @xref{RS/6000 and PowerPC Options}, for more information about when long
23499 calls are and are not necessary.
23503 @cindex pragma, longcall
23504 Apply the @code{longcall} attribute to all subsequent function
23508 Do not apply the @code{longcall} attribute to subsequent function
23512 @c Describe h8300 pragmas here.
23513 @c Describe sh pragmas here.
23514 @c Describe v850 pragmas here.
23516 @node S/390 Pragmas
23517 @subsection S/390 Pragmas
23519 The pragmas defined by the S/390 target correspond to the S/390
23520 target function attributes and some the additional options:
23527 Note that options of the pragma, unlike options of the target
23528 attribute, do change the value of preprocessor macros like
23529 @code{__VEC__}. They can be specified as below:
23532 #pragma GCC target("string[,string]...")
23533 #pragma GCC target("string"[,"string"]...)
23536 @node Darwin Pragmas
23537 @subsection Darwin Pragmas
23539 The following pragmas are available for all architectures running the
23540 Darwin operating system. These are useful for compatibility with other
23544 @item mark @var{tokens}@dots{}
23545 @cindex pragma, mark
23546 This pragma is accepted, but has no effect.
23548 @item options align=@var{alignment}
23549 @cindex pragma, options align
23550 This pragma sets the alignment of fields in structures. The values of
23551 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
23552 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
23553 properly; to restore the previous setting, use @code{reset} for the
23556 @item segment @var{tokens}@dots{}
23557 @cindex pragma, segment
23558 This pragma is accepted, but has no effect.
23560 @item unused (@var{var} [, @var{var}]@dots{})
23561 @cindex pragma, unused
23562 This pragma declares variables to be possibly unused. GCC does not
23563 produce warnings for the listed variables. The effect is similar to
23564 that of the @code{unused} attribute, except that this pragma may appear
23565 anywhere within the variables' scopes.
23568 @node Solaris Pragmas
23569 @subsection Solaris Pragmas
23571 The Solaris target supports @code{#pragma redefine_extname}
23572 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
23573 @code{#pragma} directives for compatibility with the system compiler.
23576 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
23577 @cindex pragma, align
23579 Increase the minimum alignment of each @var{variable} to @var{alignment}.
23580 This is the same as GCC's @code{aligned} attribute @pxref{Variable
23581 Attributes}). Macro expansion occurs on the arguments to this pragma
23582 when compiling C and Objective-C@. It does not currently occur when
23583 compiling C++, but this is a bug which may be fixed in a future
23586 @item fini (@var{function} [, @var{function}]...)
23587 @cindex pragma, fini
23589 This pragma causes each listed @var{function} to be called after
23590 main, or during shared module unloading, by adding a call to the
23591 @code{.fini} section.
23593 @item init (@var{function} [, @var{function}]...)
23594 @cindex pragma, init
23596 This pragma causes each listed @var{function} to be called during
23597 initialization (before @code{main}) or during shared module loading, by
23598 adding a call to the @code{.init} section.
23602 @node Symbol-Renaming Pragmas
23603 @subsection Symbol-Renaming Pragmas
23605 GCC supports a @code{#pragma} directive that changes the name used in
23606 assembly for a given declaration. While this pragma is supported on all
23607 platforms, it is intended primarily to provide compatibility with the
23608 Solaris system headers. This effect can also be achieved using the asm
23609 labels extension (@pxref{Asm Labels}).
23612 @item redefine_extname @var{oldname} @var{newname}
23613 @cindex pragma, redefine_extname
23615 This pragma gives the C function @var{oldname} the assembly symbol
23616 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
23617 is defined if this pragma is available (currently on all platforms).
23620 This pragma and the @code{asm} labels extension interact in a complicated
23621 manner. Here are some corner cases you may want to be aware of:
23624 @item This pragma silently applies only to declarations with external
23625 linkage. The @code{asm} label feature does not have this restriction.
23627 @item In C++, this pragma silently applies only to declarations with
23628 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
23630 @item If either of the ways of changing the assembly name of a
23631 declaration are applied to a declaration whose assembly name has
23632 already been determined (either by a previous use of one of these
23633 features, or because the compiler needed the assembly name in order to
23634 generate code), and the new name is different, a warning issues and
23635 the name does not change.
23637 @item The @var{oldname} used by @code{#pragma redefine_extname} is
23638 always the C-language name.
23641 @node Structure-Layout Pragmas
23642 @subsection Structure-Layout Pragmas
23644 For compatibility with Microsoft Windows compilers, GCC supports a
23645 set of @code{#pragma} directives that change the maximum alignment of
23646 members of structures (other than zero-width bit-fields), unions, and
23647 classes subsequently defined. The @var{n} value below always is required
23648 to be a small power of two and specifies the new alignment in bytes.
23651 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
23652 @item @code{#pragma pack()} sets the alignment to the one that was in
23653 effect when compilation started (see also command-line option
23654 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
23655 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
23656 setting on an internal stack and then optionally sets the new alignment.
23657 @item @code{#pragma pack(pop)} restores the alignment setting to the one
23658 saved at the top of the internal stack (and removes that stack entry).
23659 Note that @code{#pragma pack([@var{n}])} does not influence this internal
23660 stack; thus it is possible to have @code{#pragma pack(push)} followed by
23661 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
23662 @code{#pragma pack(pop)}.
23665 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
23666 directive which lays out structures and unions subsequently defined as the
23667 documented @code{__attribute__ ((ms_struct))}.
23670 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
23671 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
23672 @item @code{#pragma ms_struct reset} goes back to the default layout.
23675 Most targets also support the @code{#pragma scalar_storage_order} directive
23676 which lays out structures and unions subsequently defined as the documented
23677 @code{__attribute__ ((scalar_storage_order))}.
23680 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
23681 of the scalar fields to big-endian.
23682 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
23683 of the scalar fields to little-endian.
23684 @item @code{#pragma scalar_storage_order default} goes back to the endianness
23685 that was in effect when compilation started (see also command-line option
23686 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
23690 @subsection Weak Pragmas
23692 For compatibility with SVR4, GCC supports a set of @code{#pragma}
23693 directives for declaring symbols to be weak, and defining weak
23697 @item #pragma weak @var{symbol}
23698 @cindex pragma, weak
23699 This pragma declares @var{symbol} to be weak, as if the declaration
23700 had the attribute of the same name. The pragma may appear before
23701 or after the declaration of @var{symbol}. It is not an error for
23702 @var{symbol} to never be defined at all.
23704 @item #pragma weak @var{symbol1} = @var{symbol2}
23705 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
23706 It is an error if @var{symbol2} is not defined in the current
23710 @node Diagnostic Pragmas
23711 @subsection Diagnostic Pragmas
23713 GCC allows the user to selectively enable or disable certain types of
23714 diagnostics, and change the kind of the diagnostic. For example, a
23715 project's policy might require that all sources compile with
23716 @option{-Werror} but certain files might have exceptions allowing
23717 specific types of warnings. Or, a project might selectively enable
23718 diagnostics and treat them as errors depending on which preprocessor
23719 macros are defined.
23722 @item #pragma GCC diagnostic @var{kind} @var{option}
23723 @cindex pragma, diagnostic
23725 Modifies the disposition of a diagnostic. Note that not all
23726 diagnostics are modifiable; at the moment only warnings (normally
23727 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
23728 Use @option{-fdiagnostics-show-option} to determine which diagnostics
23729 are controllable and which option controls them.
23731 @var{kind} is @samp{error} to treat this diagnostic as an error,
23732 @samp{warning} to treat it like a warning (even if @option{-Werror} is
23733 in effect), or @samp{ignored} if the diagnostic is to be ignored.
23734 @var{option} is a double quoted string that matches the command-line
23738 #pragma GCC diagnostic warning "-Wformat"
23739 #pragma GCC diagnostic error "-Wformat"
23740 #pragma GCC diagnostic ignored "-Wformat"
23743 Note that these pragmas override any command-line options. GCC keeps
23744 track of the location of each pragma, and issues diagnostics according
23745 to the state as of that point in the source file. Thus, pragmas occurring
23746 after a line do not affect diagnostics caused by that line.
23748 @item #pragma GCC diagnostic push
23749 @itemx #pragma GCC diagnostic pop
23751 Causes GCC to remember the state of the diagnostics as of each
23752 @code{push}, and restore to that point at each @code{pop}. If a
23753 @code{pop} has no matching @code{push}, the command-line options are
23757 #pragma GCC diagnostic error "-Wuninitialized"
23758 foo(a); /* error is given for this one */
23759 #pragma GCC diagnostic push
23760 #pragma GCC diagnostic ignored "-Wuninitialized"
23761 foo(b); /* no diagnostic for this one */
23762 #pragma GCC diagnostic pop
23763 foo(c); /* error is given for this one */
23764 #pragma GCC diagnostic pop
23765 foo(d); /* depends on command-line options */
23770 GCC also offers a simple mechanism for printing messages during
23774 @item #pragma message @var{string}
23775 @cindex pragma, diagnostic
23777 Prints @var{string} as a compiler message on compilation. The message
23778 is informational only, and is neither a compilation warning nor an
23779 error. Newlines can be included in the string by using the @samp{\n}
23783 #pragma message "Compiling " __FILE__ "..."
23786 @var{string} may be parenthesized, and is printed with location
23787 information. For example,
23790 #define DO_PRAGMA(x) _Pragma (#x)
23791 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
23793 TODO(Remember to fix this)
23797 prints @samp{/tmp/file.c:4: note: #pragma message:
23798 TODO - Remember to fix this}.
23800 @item #pragma GCC error @var{message}
23801 @cindex pragma, diagnostic
23802 Generates an error message. This pragma @emph{is} considered to
23803 indicate an error in the compilation, and it will be treated as such.
23805 Newlines can be included in the string by using the @samp{\n}
23806 escape sequence. They will be displayed as newlines even if the
23807 @option{-fmessage-length} option is set to zero.
23809 The error is only generated if the pragma is present in the code after
23810 pre-processing has been completed. It does not matter however if the
23811 code containing the pragma is unreachable:
23815 #pragma GCC error "this error is not seen"
23820 #pragma GCC error "this error is seen"
23824 @item #pragma GCC warning @var{message}
23825 @cindex pragma, diagnostic
23826 This is just like @samp{pragma GCC error} except that a warning
23827 message is issued instead of an error message. Unless
23828 @option{-Werror} is in effect, in which case this pragma will generate
23833 @node Visibility Pragmas
23834 @subsection Visibility Pragmas
23837 @item #pragma GCC visibility push(@var{visibility})
23838 @itemx #pragma GCC visibility pop
23839 @cindex pragma, visibility
23841 This pragma allows the user to set the visibility for multiple
23842 declarations without having to give each a visibility attribute
23843 (@pxref{Function Attributes}).
23845 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
23846 declarations. Class members and template specializations are not
23847 affected; if you want to override the visibility for a particular
23848 member or instantiation, you must use an attribute.
23853 @node Push/Pop Macro Pragmas
23854 @subsection Push/Pop Macro Pragmas
23856 For compatibility with Microsoft Windows compilers, GCC supports
23857 @samp{#pragma push_macro(@var{"macro_name"})}
23858 and @samp{#pragma pop_macro(@var{"macro_name"})}.
23861 @item #pragma push_macro(@var{"macro_name"})
23862 @cindex pragma, push_macro
23863 This pragma saves the value of the macro named as @var{macro_name} to
23864 the top of the stack for this macro.
23866 @item #pragma pop_macro(@var{"macro_name"})
23867 @cindex pragma, pop_macro
23868 This pragma sets the value of the macro named as @var{macro_name} to
23869 the value on top of the stack for this macro. If the stack for
23870 @var{macro_name} is empty, the value of the macro remains unchanged.
23877 #pragma push_macro("X")
23880 #pragma pop_macro("X")
23885 In this example, the definition of X as 1 is saved by @code{#pragma
23886 push_macro} and restored by @code{#pragma pop_macro}.
23888 @node Function Specific Option Pragmas
23889 @subsection Function Specific Option Pragmas
23892 @item #pragma GCC target (@var{string}, @dots{})
23893 @cindex pragma GCC target
23895 This pragma allows you to set target-specific options for functions
23896 defined later in the source file. One or more strings can be
23897 specified. Each function that is defined after this point is treated
23898 as if it had been declared with one @code{target(}@var{string}@code{)}
23899 attribute for each @var{string} argument. The parentheses around
23900 the strings in the pragma are optional. @xref{Function Attributes},
23901 for more information about the @code{target} attribute and the attribute
23904 The @code{#pragma GCC target} pragma is presently implemented for
23905 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
23907 @item #pragma GCC optimize (@var{string}, @dots{})
23908 @cindex pragma GCC optimize
23910 This pragma allows you to set global optimization options for functions
23911 defined later in the source file. One or more strings can be
23912 specified. Each function that is defined after this point is treated
23913 as if it had been declared with one @code{optimize(}@var{string}@code{)}
23914 attribute for each @var{string} argument. The parentheses around
23915 the strings in the pragma are optional. @xref{Function Attributes},
23916 for more information about the @code{optimize} attribute and the attribute
23919 @item #pragma GCC push_options
23920 @itemx #pragma GCC pop_options
23921 @cindex pragma GCC push_options
23922 @cindex pragma GCC pop_options
23924 These pragmas maintain a stack of the current target and optimization
23925 options. It is intended for include files where you temporarily want
23926 to switch to using a different @samp{#pragma GCC target} or
23927 @samp{#pragma GCC optimize} and then to pop back to the previous
23930 @item #pragma GCC reset_options
23931 @cindex pragma GCC reset_options
23933 This pragma clears the current @code{#pragma GCC target} and
23934 @code{#pragma GCC optimize} to use the default switches as specified
23935 on the command line.
23939 @node Loop-Specific Pragmas
23940 @subsection Loop-Specific Pragmas
23943 @item #pragma GCC ivdep
23944 @cindex pragma GCC ivdep
23946 With this pragma, the programmer asserts that there are no loop-carried
23947 dependencies which would prevent consecutive iterations of
23948 the following loop from executing concurrently with SIMD
23949 (single instruction multiple data) instructions.
23951 For example, the compiler can only unconditionally vectorize the following
23952 loop with the pragma:
23955 void foo (int n, int *a, int *b, int *c)
23959 for (i = 0; i < n; ++i)
23960 a[i] = b[i] + c[i];
23965 In this example, using the @code{restrict} qualifier had the same
23966 effect. In the following example, that would not be possible. Assume
23967 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
23968 that it can unconditionally vectorize the following loop:
23971 void ignore_vec_dep (int *a, int k, int c, int m)
23974 for (int i = 0; i < m; i++)
23975 a[i] = a[i + k] * c;
23979 @item #pragma GCC unroll @var{n}
23980 @cindex pragma GCC unroll @var{n}
23982 You can use this pragma to control how many times a loop should be unrolled.
23983 It must be placed immediately before a @code{for}, @code{while} or @code{do}
23984 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
23985 @var{n} is an integer constant expression specifying the unrolling factor.
23986 The values of @math{0} and @math{1} block any unrolling of the loop.
23990 @node Unnamed Fields
23991 @section Unnamed Structure and Union Fields
23992 @cindex @code{struct}
23993 @cindex @code{union}
23995 As permitted by ISO C11 and for compatibility with other compilers,
23996 GCC allows you to define
23997 a structure or union that contains, as fields, structures and unions
23998 without names. For example:
24012 In this example, you are able to access members of the unnamed
24013 union with code like @samp{foo.b}. Note that only unnamed structs and
24014 unions are allowed, you may not have, for example, an unnamed
24017 You must never create such structures that cause ambiguous field definitions.
24018 For example, in this structure:
24030 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
24031 The compiler gives errors for such constructs.
24033 @opindex fms-extensions
24034 Unless @option{-fms-extensions} is used, the unnamed field must be a
24035 structure or union definition without a tag (for example, @samp{struct
24036 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
24037 also be a definition with a tag such as @samp{struct foo @{ int a;
24038 @};}, a reference to a previously defined structure or union such as
24039 @samp{struct foo;}, or a reference to a @code{typedef} name for a
24040 previously defined structure or union type.
24042 @opindex fplan9-extensions
24043 The option @option{-fplan9-extensions} enables
24044 @option{-fms-extensions} as well as two other extensions. First, a
24045 pointer to a structure is automatically converted to a pointer to an
24046 anonymous field for assignments and function calls. For example:
24049 struct s1 @{ int a; @};
24050 struct s2 @{ struct s1; @};
24051 extern void f1 (struct s1 *);
24052 void f2 (struct s2 *p) @{ f1 (p); @}
24056 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
24057 converted into a pointer to the anonymous field.
24059 Second, when the type of an anonymous field is a @code{typedef} for a
24060 @code{struct} or @code{union}, code may refer to the field using the
24061 name of the @code{typedef}.
24064 typedef struct @{ int a; @} s1;
24065 struct s2 @{ s1; @};
24066 s1 f1 (struct s2 *p) @{ return p->s1; @}
24069 These usages are only permitted when they are not ambiguous.
24072 @section Thread-Local Storage
24073 @cindex Thread-Local Storage
24074 @cindex @acronym{TLS}
24075 @cindex @code{__thread}
24077 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
24078 are allocated such that there is one instance of the variable per extant
24079 thread. The runtime model GCC uses to implement this originates
24080 in the IA-64 processor-specific ABI, but has since been migrated
24081 to other processors as well. It requires significant support from
24082 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
24083 system libraries (@file{libc.so} and @file{libpthread.so}), so it
24084 is not available everywhere.
24086 At the user level, the extension is visible with a new storage
24087 class keyword: @code{__thread}. For example:
24091 extern __thread struct state s;
24092 static __thread char *p;
24095 The @code{__thread} specifier may be used alone, with the @code{extern}
24096 or @code{static} specifiers, but with no other storage class specifier.
24097 When used with @code{extern} or @code{static}, @code{__thread} must appear
24098 immediately after the other storage class specifier.
24100 The @code{__thread} specifier may be applied to any global, file-scoped
24101 static, function-scoped static, or static data member of a class. It may
24102 not be applied to block-scoped automatic or non-static data member.
24104 When the address-of operator is applied to a thread-local variable, it is
24105 evaluated at run time and returns the address of the current thread's
24106 instance of that variable. An address so obtained may be used by any
24107 thread. When a thread terminates, any pointers to thread-local variables
24108 in that thread become invalid.
24110 No static initialization may refer to the address of a thread-local variable.
24112 In C++, if an initializer is present for a thread-local variable, it must
24113 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
24116 See @uref{https://www.akkadia.org/drepper/tls.pdf,
24117 ELF Handling For Thread-Local Storage} for a detailed explanation of
24118 the four thread-local storage addressing models, and how the runtime
24119 is expected to function.
24122 * C99 Thread-Local Edits::
24123 * C++98 Thread-Local Edits::
24126 @node C99 Thread-Local Edits
24127 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
24129 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
24130 that document the exact semantics of the language extension.
24134 @cite{5.1.2 Execution environments}
24136 Add new text after paragraph 1
24139 Within either execution environment, a @dfn{thread} is a flow of
24140 control within a program. It is implementation defined whether
24141 or not there may be more than one thread associated with a program.
24142 It is implementation defined how threads beyond the first are
24143 created, the name and type of the function called at thread
24144 startup, and how threads may be terminated. However, objects
24145 with thread storage duration shall be initialized before thread
24150 @cite{6.2.4 Storage durations of objects}
24152 Add new text before paragraph 3
24155 An object whose identifier is declared with the storage-class
24156 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
24157 Its lifetime is the entire execution of the thread, and its
24158 stored value is initialized only once, prior to thread startup.
24162 @cite{6.4.1 Keywords}
24164 Add @code{__thread}.
24167 @cite{6.7.1 Storage-class specifiers}
24169 Add @code{__thread} to the list of storage class specifiers in
24172 Change paragraph 2 to
24175 With the exception of @code{__thread}, at most one storage-class
24176 specifier may be given [@dots{}]. The @code{__thread} specifier may
24177 be used alone, or immediately following @code{extern} or
24181 Add new text after paragraph 6
24184 The declaration of an identifier for a variable that has
24185 block scope that specifies @code{__thread} shall also
24186 specify either @code{extern} or @code{static}.
24188 The @code{__thread} specifier shall be used only with
24193 @node C++98 Thread-Local Edits
24194 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
24196 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
24197 that document the exact semantics of the language extension.
24201 @b{[intro.execution]}
24203 New text after paragraph 4
24206 A @dfn{thread} is a flow of control within the abstract machine.
24207 It is implementation defined whether or not there may be more than
24211 New text after paragraph 7
24214 It is unspecified whether additional action must be taken to
24215 ensure when and whether side effects are visible to other threads.
24221 Add @code{__thread}.
24224 @b{[basic.start.main]}
24226 Add after paragraph 5
24229 The thread that begins execution at the @code{main} function is called
24230 the @dfn{main thread}. It is implementation defined how functions
24231 beginning threads other than the main thread are designated or typed.
24232 A function so designated, as well as the @code{main} function, is called
24233 a @dfn{thread startup function}. It is implementation defined what
24234 happens if a thread startup function returns. It is implementation
24235 defined what happens to other threads when any thread calls @code{exit}.
24239 @b{[basic.start.init]}
24241 Add after paragraph 4
24244 The storage for an object of thread storage duration shall be
24245 statically initialized before the first statement of the thread startup
24246 function. An object of thread storage duration shall not require
24247 dynamic initialization.
24251 @b{[basic.start.term]}
24253 Add after paragraph 3
24256 The type of an object with thread storage duration shall not have a
24257 non-trivial destructor, nor shall it be an array type whose elements
24258 (directly or indirectly) have non-trivial destructors.
24264 Add ``thread storage duration'' to the list in paragraph 1.
24269 Thread, static, and automatic storage durations are associated with
24270 objects introduced by declarations [@dots{}].
24273 Add @code{__thread} to the list of specifiers in paragraph 3.
24276 @b{[basic.stc.thread]}
24278 New section before @b{[basic.stc.static]}
24281 The keyword @code{__thread} applied to a non-local object gives the
24282 object thread storage duration.
24284 A local variable or class data member declared both @code{static}
24285 and @code{__thread} gives the variable or member thread storage
24290 @b{[basic.stc.static]}
24295 All objects that have neither thread storage duration, dynamic
24296 storage duration nor are local [@dots{}].
24302 Add @code{__thread} to the list in paragraph 1.
24307 With the exception of @code{__thread}, at most one
24308 @var{storage-class-specifier} shall appear in a given
24309 @var{decl-specifier-seq}. The @code{__thread} specifier may
24310 be used alone, or immediately following the @code{extern} or
24311 @code{static} specifiers. [@dots{}]
24314 Add after paragraph 5
24317 The @code{__thread} specifier can be applied only to the names of objects
24318 and to anonymous unions.
24324 Add after paragraph 6
24327 Non-@code{static} members shall not be @code{__thread}.
24331 @node Binary constants
24332 @section Binary Constants using the @samp{0b} Prefix
24333 @cindex Binary constants using the @samp{0b} prefix
24335 Integer constants can be written as binary constants, consisting of a
24336 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
24337 @samp{0B}. This is particularly useful in environments that operate a
24338 lot on the bit level (like microcontrollers).
24340 The following statements are identical:
24349 The type of these constants follows the same rules as for octal or
24350 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
24353 @node C++ Extensions
24354 @chapter Extensions to the C++ Language
24355 @cindex extensions, C++ language
24356 @cindex C++ language extensions
24358 The GNU compiler provides these extensions to the C++ language (and you
24359 can also use most of the C language extensions in your C++ programs). If you
24360 want to write code that checks whether these features are available, you can
24361 test for the GNU compiler the same way as for C programs: check for a
24362 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
24363 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
24364 Predefined Macros,cpp,The GNU C Preprocessor}).
24367 * C++ Volatiles:: What constitutes an access to a volatile object.
24368 * Restricted Pointers:: C99 restricted pointers and references.
24369 * Vague Linkage:: Where G++ puts inlines, vtables and such.
24370 * C++ Interface:: You can use a single C++ header file for both
24371 declarations and definitions.
24372 * Template Instantiation:: Methods for ensuring that exactly one copy of
24373 each needed template instantiation is emitted.
24374 * Bound member functions:: You can extract a function pointer to the
24375 method denoted by a @samp{->*} or @samp{.*} expression.
24376 * C++ Attributes:: Variable, function, and type attributes for C++ only.
24377 * Function Multiversioning:: Declaring multiple function versions.
24378 * Type Traits:: Compiler support for type traits.
24379 * C++ Concepts:: Improved support for generic programming.
24380 * Deprecated Features:: Things will disappear from G++.
24381 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
24384 @node C++ Volatiles
24385 @section When is a Volatile C++ Object Accessed?
24386 @cindex accessing volatiles
24387 @cindex volatile read
24388 @cindex volatile write
24389 @cindex volatile access
24391 The C++ standard differs from the C standard in its treatment of
24392 volatile objects. It fails to specify what constitutes a volatile
24393 access, except to say that C++ should behave in a similar manner to C
24394 with respect to volatiles, where possible. However, the different
24395 lvalueness of expressions between C and C++ complicate the behavior.
24396 G++ behaves the same as GCC for volatile access, @xref{C
24397 Extensions,,Volatiles}, for a description of GCC's behavior.
24399 The C and C++ language specifications differ when an object is
24400 accessed in a void context:
24403 volatile int *src = @var{somevalue};
24407 The C++ standard specifies that such expressions do not undergo lvalue
24408 to rvalue conversion, and that the type of the dereferenced object may
24409 be incomplete. The C++ standard does not specify explicitly that it
24410 is lvalue to rvalue conversion that is responsible for causing an
24411 access. There is reason to believe that it is, because otherwise
24412 certain simple expressions become undefined. However, because it
24413 would surprise most programmers, G++ treats dereferencing a pointer to
24414 volatile object of complete type as GCC would do for an equivalent
24415 type in C@. When the object has incomplete type, G++ issues a
24416 warning; if you wish to force an error, you must force a conversion to
24417 rvalue with, for instance, a static cast.
24419 When using a reference to volatile, G++ does not treat equivalent
24420 expressions as accesses to volatiles, but instead issues a warning that
24421 no volatile is accessed. The rationale for this is that otherwise it
24422 becomes difficult to determine where volatile access occur, and not
24423 possible to ignore the return value from functions returning volatile
24424 references. Again, if you wish to force a read, cast the reference to
24427 G++ implements the same behavior as GCC does when assigning to a
24428 volatile object---there is no reread of the assigned-to object, the
24429 assigned rvalue is reused. Note that in C++ assignment expressions
24430 are lvalues, and if used as an lvalue, the volatile object is
24431 referred to. For instance, @var{vref} refers to @var{vobj}, as
24432 expected, in the following example:
24436 volatile int &vref = vobj = @var{something};
24439 @node Restricted Pointers
24440 @section Restricting Pointer Aliasing
24441 @cindex restricted pointers
24442 @cindex restricted references
24443 @cindex restricted this pointer
24445 As with the C front end, G++ understands the C99 feature of restricted pointers,
24446 specified with the @code{__restrict__}, or @code{__restrict} type
24447 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
24448 language flag, @code{restrict} is not a keyword in C++.
24450 In addition to allowing restricted pointers, you can specify restricted
24451 references, which indicate that the reference is not aliased in the local
24455 void fn (int *__restrict__ rptr, int &__restrict__ rref)
24462 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
24463 @var{rref} refers to a (different) unaliased integer.
24465 You may also specify whether a member function's @var{this} pointer is
24466 unaliased by using @code{__restrict__} as a member function qualifier.
24469 void T::fn () __restrict__
24476 Within the body of @code{T::fn}, @var{this} has the effective
24477 definition @code{T *__restrict__ const this}. Notice that the
24478 interpretation of a @code{__restrict__} member function qualifier is
24479 different to that of @code{const} or @code{volatile} qualifier, in that it
24480 is applied to the pointer rather than the object. This is consistent with
24481 other compilers that implement restricted pointers.
24483 As with all outermost parameter qualifiers, @code{__restrict__} is
24484 ignored in function definition matching. This means you only need to
24485 specify @code{__restrict__} in a function definition, rather than
24486 in a function prototype as well.
24488 @node Vague Linkage
24489 @section Vague Linkage
24490 @cindex vague linkage
24492 There are several constructs in C++ that require space in the object
24493 file but are not clearly tied to a single translation unit. We say that
24494 these constructs have ``vague linkage''. Typically such constructs are
24495 emitted wherever they are needed, though sometimes we can be more
24499 @item Inline Functions
24500 Inline functions are typically defined in a header file which can be
24501 included in many different compilations. Hopefully they can usually be
24502 inlined, but sometimes an out-of-line copy is necessary, if the address
24503 of the function is taken or if inlining fails. In general, we emit an
24504 out-of-line copy in all translation units where one is needed. As an
24505 exception, we only emit inline virtual functions with the vtable, since
24506 it always requires a copy.
24508 Local static variables and string constants used in an inline function
24509 are also considered to have vague linkage, since they must be shared
24510 between all inlined and out-of-line instances of the function.
24514 C++ virtual functions are implemented in most compilers using a lookup
24515 table, known as a vtable. The vtable contains pointers to the virtual
24516 functions provided by a class, and each object of the class contains a
24517 pointer to its vtable (or vtables, in some multiple-inheritance
24518 situations). If the class declares any non-inline, non-pure virtual
24519 functions, the first one is chosen as the ``key method'' for the class,
24520 and the vtable is only emitted in the translation unit where the key
24523 @emph{Note:} If the chosen key method is later defined as inline, the
24524 vtable is still emitted in every translation unit that defines it.
24525 Make sure that any inline virtuals are declared inline in the class
24526 body, even if they are not defined there.
24528 @item @code{type_info} objects
24529 @cindex @code{type_info}
24531 C++ requires information about types to be written out in order to
24532 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
24533 For polymorphic classes (classes with virtual functions), the @samp{type_info}
24534 object is written out along with the vtable so that @samp{dynamic_cast}
24535 can determine the dynamic type of a class object at run time. For all
24536 other types, we write out the @samp{type_info} object when it is used: when
24537 applying @samp{typeid} to an expression, throwing an object, or
24538 referring to a type in a catch clause or exception specification.
24540 @item Template Instantiations
24541 Most everything in this section also applies to template instantiations,
24542 but there are other options as well.
24543 @xref{Template Instantiation,,Where's the Template?}.
24547 When used with GNU ld version 2.8 or later on an ELF system such as
24548 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
24549 these constructs will be discarded at link time. This is known as
24552 On targets that don't support COMDAT, but do support weak symbols, GCC
24553 uses them. This way one copy overrides all the others, but
24554 the unused copies still take up space in the executable.
24556 For targets that do not support either COMDAT or weak symbols,
24557 most entities with vague linkage are emitted as local symbols to
24558 avoid duplicate definition errors from the linker. This does not happen
24559 for local statics in inlines, however, as having multiple copies
24560 almost certainly breaks things.
24562 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
24563 another way to control placement of these constructs.
24565 @node C++ Interface
24566 @section C++ Interface and Implementation Pragmas
24568 @cindex interface and implementation headers, C++
24569 @cindex C++ interface and implementation headers
24570 @cindex pragmas, interface and implementation
24572 @code{#pragma interface} and @code{#pragma implementation} provide the
24573 user with a way of explicitly directing the compiler to emit entities
24574 with vague linkage (and debugging information) in a particular
24577 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
24578 by COMDAT support and the ``key method'' heuristic
24579 mentioned in @ref{Vague Linkage}. Using them can actually cause your
24580 program to grow due to unnecessary out-of-line copies of inline
24584 @item #pragma interface
24585 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
24586 @kindex #pragma interface
24587 Use this directive in @emph{header files} that define object classes, to save
24588 space in most of the object files that use those classes. Normally,
24589 local copies of certain information (backup copies of inline member
24590 functions, debugging information, and the internal tables that implement
24591 virtual functions) must be kept in each object file that includes class
24592 definitions. You can use this pragma to avoid such duplication. When a
24593 header file containing @samp{#pragma interface} is included in a
24594 compilation, this auxiliary information is not generated (unless
24595 the main input source file itself uses @samp{#pragma implementation}).
24596 Instead, the object files contain references to be resolved at link
24599 The second form of this directive is useful for the case where you have
24600 multiple headers with the same name in different directories. If you
24601 use this form, you must specify the same string to @samp{#pragma
24604 @item #pragma implementation
24605 @itemx #pragma implementation "@var{objects}.h"
24606 @kindex #pragma implementation
24607 Use this pragma in a @emph{main input file}, when you want full output from
24608 included header files to be generated (and made globally visible). The
24609 included header file, in turn, should use @samp{#pragma interface}.
24610 Backup copies of inline member functions, debugging information, and the
24611 internal tables used to implement virtual functions are all generated in
24612 implementation files.
24614 @cindex implied @code{#pragma implementation}
24615 @cindex @code{#pragma implementation}, implied
24616 @cindex naming convention, implementation headers
24617 If you use @samp{#pragma implementation} with no argument, it applies to
24618 an include file with the same basename@footnote{A file's @dfn{basename}
24619 is the name stripped of all leading path information and of trailing
24620 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
24621 file. For example, in @file{allclass.cc}, giving just
24622 @samp{#pragma implementation}
24623 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
24625 Use the string argument if you want a single implementation file to
24626 include code from multiple header files. (You must also use
24627 @samp{#include} to include the header file; @samp{#pragma
24628 implementation} only specifies how to use the file---it doesn't actually
24631 There is no way to split up the contents of a single header file into
24632 multiple implementation files.
24635 @cindex inlining and C++ pragmas
24636 @cindex C++ pragmas, effect on inlining
24637 @cindex pragmas in C++, effect on inlining
24638 @samp{#pragma implementation} and @samp{#pragma interface} also have an
24639 effect on function inlining.
24641 If you define a class in a header file marked with @samp{#pragma
24642 interface}, the effect on an inline function defined in that class is
24643 similar to an explicit @code{extern} declaration---the compiler emits
24644 no code at all to define an independent version of the function. Its
24645 definition is used only for inlining with its callers.
24647 @opindex fno-implement-inlines
24648 Conversely, when you include the same header file in a main source file
24649 that declares it as @samp{#pragma implementation}, the compiler emits
24650 code for the function itself; this defines a version of the function
24651 that can be found via pointers (or by callers compiled without
24652 inlining). If all calls to the function can be inlined, you can avoid
24653 emitting the function by compiling with @option{-fno-implement-inlines}.
24654 If any calls are not inlined, you will get linker errors.
24656 @node Template Instantiation
24657 @section Where's the Template?
24658 @cindex template instantiation
24660 C++ templates were the first language feature to require more
24661 intelligence from the environment than was traditionally found on a UNIX
24662 system. Somehow the compiler and linker have to make sure that each
24663 template instance occurs exactly once in the executable if it is needed,
24664 and not at all otherwise. There are two basic approaches to this
24665 problem, which are referred to as the Borland model and the Cfront model.
24668 @item Borland model
24669 Borland C++ solved the template instantiation problem by adding the code
24670 equivalent of common blocks to their linker; the compiler emits template
24671 instances in each translation unit that uses them, and the linker
24672 collapses them together. The advantage of this model is that the linker
24673 only has to consider the object files themselves; there is no external
24674 complexity to worry about. The disadvantage is that compilation time
24675 is increased because the template code is being compiled repeatedly.
24676 Code written for this model tends to include definitions of all
24677 templates in the header file, since they must be seen to be
24681 The AT&T C++ translator, Cfront, solved the template instantiation
24682 problem by creating the notion of a template repository, an
24683 automatically maintained place where template instances are stored. A
24684 more modern version of the repository works as follows: As individual
24685 object files are built, the compiler places any template definitions and
24686 instantiations encountered in the repository. At link time, the link
24687 wrapper adds in the objects in the repository and compiles any needed
24688 instances that were not previously emitted. The advantages of this
24689 model are more optimal compilation speed and the ability to use the
24690 system linker; to implement the Borland model a compiler vendor also
24691 needs to replace the linker. The disadvantages are vastly increased
24692 complexity, and thus potential for error; for some code this can be
24693 just as transparent, but in practice it can been very difficult to build
24694 multiple programs in one directory and one program in multiple
24695 directories. Code written for this model tends to separate definitions
24696 of non-inline member templates into a separate file, which should be
24697 compiled separately.
24700 G++ implements the Borland model on targets where the linker supports it,
24701 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
24702 Otherwise G++ implements neither automatic model.
24704 You have the following options for dealing with template instantiations:
24708 Do nothing. Code written for the Borland model works fine, but
24709 each translation unit contains instances of each of the templates it
24710 uses. The duplicate instances will be discarded by the linker, but in
24711 a large program, this can lead to an unacceptable amount of code
24712 duplication in object files or shared libraries.
24714 Duplicate instances of a template can be avoided by defining an explicit
24715 instantiation in one object file, and preventing the compiler from doing
24716 implicit instantiations in any other object files by using an explicit
24717 instantiation declaration, using the @code{extern template} syntax:
24720 extern template int max (int, int);
24723 This syntax is defined in the C++ 2011 standard, but has been supported by
24724 G++ and other compilers since well before 2011.
24726 Explicit instantiations can be used for the largest or most frequently
24727 duplicated instances, without having to know exactly which other instances
24728 are used in the rest of the program. You can scatter the explicit
24729 instantiations throughout your program, perhaps putting them in the
24730 translation units where the instances are used or the translation units
24731 that define the templates themselves; you can put all of the explicit
24732 instantiations you need into one big file; or you can create small files
24739 template class Foo<int>;
24740 template ostream& operator <<
24741 (ostream&, const Foo<int>&);
24745 for each of the instances you need, and create a template instantiation
24746 library from those.
24748 This is the simplest option, but also offers flexibility and
24749 fine-grained control when necessary. It is also the most portable
24750 alternative and programs using this approach will work with most modern
24754 @opindex fno-implicit-templates
24755 Compile your code with @option{-fno-implicit-templates} to disable the
24756 implicit generation of template instances, and explicitly instantiate
24757 all the ones you use. This approach requires more knowledge of exactly
24758 which instances you need than do the others, but it's less
24759 mysterious and allows greater control if you want to ensure that only
24760 the intended instances are used.
24762 If you are using Cfront-model code, you can probably get away with not
24763 using @option{-fno-implicit-templates} when compiling files that don't
24764 @samp{#include} the member template definitions.
24766 If you use one big file to do the instantiations, you may want to
24767 compile it without @option{-fno-implicit-templates} so you get all of the
24768 instances required by your explicit instantiations (but not by any
24769 other files) without having to specify them as well.
24771 In addition to forward declaration of explicit instantiations
24772 (with @code{extern}), G++ has extended the template instantiation
24773 syntax to support instantiation of the compiler support data for a
24774 template class (i.e.@: the vtable) without instantiating any of its
24775 members (with @code{inline}), and instantiation of only the static data
24776 members of a template class, without the support data or member
24777 functions (with @code{static}):
24780 inline template class Foo<int>;
24781 static template class Foo<int>;
24785 @node Bound member functions
24786 @section Extracting the Function Pointer from a Bound Pointer to Member Function
24788 @cindex pointer to member function
24789 @cindex bound pointer to member function
24791 In C++, pointer to member functions (PMFs) are implemented using a wide
24792 pointer of sorts to handle all the possible call mechanisms; the PMF
24793 needs to store information about how to adjust the @samp{this} pointer,
24794 and if the function pointed to is virtual, where to find the vtable, and
24795 where in the vtable to look for the member function. If you are using
24796 PMFs in an inner loop, you should really reconsider that decision. If
24797 that is not an option, you can extract the pointer to the function that
24798 would be called for a given object/PMF pair and call it directly inside
24799 the inner loop, to save a bit of time.
24801 Note that you still pay the penalty for the call through a
24802 function pointer; on most modern architectures, such a call defeats the
24803 branch prediction features of the CPU@. This is also true of normal
24804 virtual function calls.
24806 The syntax for this extension is
24810 extern int (A::*fp)();
24811 typedef int (*fptr)(A *);
24813 fptr p = (fptr)(a.*fp);
24816 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
24817 no object is needed to obtain the address of the function. They can be
24818 converted to function pointers directly:
24821 fptr p1 = (fptr)(&A::foo);
24824 @opindex Wno-pmf-conversions
24825 You must specify @option{-Wno-pmf-conversions} to use this extension.
24827 @node C++ Attributes
24828 @section C++-Specific Variable, Function, and Type Attributes
24830 Some attributes only make sense for C++ programs.
24833 @item abi_tag ("@var{tag}", ...)
24834 @cindex @code{abi_tag} function attribute
24835 @cindex @code{abi_tag} variable attribute
24836 @cindex @code{abi_tag} type attribute
24837 The @code{abi_tag} attribute can be applied to a function, variable, or class
24838 declaration. It modifies the mangled name of the entity to
24839 incorporate the tag name, in order to distinguish the function or
24840 class from an earlier version with a different ABI; perhaps the class
24841 has changed size, or the function has a different return type that is
24842 not encoded in the mangled name.
24844 The attribute can also be applied to an inline namespace, but does not
24845 affect the mangled name of the namespace; in this case it is only used
24846 for @option{-Wabi-tag} warnings and automatic tagging of functions and
24847 variables. Tagging inline namespaces is generally preferable to
24848 tagging individual declarations, but the latter is sometimes
24849 necessary, such as when only certain members of a class need to be
24852 The argument can be a list of strings of arbitrary length. The
24853 strings are sorted on output, so the order of the list is
24856 A redeclaration of an entity must not add new ABI tags,
24857 since doing so would change the mangled name.
24859 The ABI tags apply to a name, so all instantiations and
24860 specializations of a template have the same tags. The attribute will
24861 be ignored if applied to an explicit specialization or instantiation.
24863 The @option{-Wabi-tag} flag enables a warning about a class which does
24864 not have all the ABI tags used by its subobjects and virtual functions; for users with code
24865 that needs to coexist with an earlier ABI, using this option can help
24866 to find all affected types that need to be tagged.
24868 When a type involving an ABI tag is used as the type of a variable or
24869 return type of a function where that tag is not already present in the
24870 signature of the function, the tag is automatically applied to the
24871 variable or function. @option{-Wabi-tag} also warns about this
24872 situation; this warning can be avoided by explicitly tagging the
24873 variable or function or moving it into a tagged inline namespace.
24875 @item init_priority (@var{priority})
24876 @cindex @code{init_priority} variable attribute
24878 In Standard C++, objects defined at namespace scope are guaranteed to be
24879 initialized in an order in strict accordance with that of their definitions
24880 @emph{in a given translation unit}. No guarantee is made for initializations
24881 across translation units. However, GNU C++ allows users to control the
24882 order of initialization of objects defined at namespace scope with the
24883 @code{init_priority} attribute by specifying a relative @var{priority},
24884 a constant integral expression currently bounded between 101 and 65535
24885 inclusive. Lower numbers indicate a higher priority.
24887 In the following example, @code{A} would normally be created before
24888 @code{B}, but the @code{init_priority} attribute reverses that order:
24891 Some_Class A __attribute__ ((init_priority (2000)));
24892 Some_Class B __attribute__ ((init_priority (543)));
24896 Note that the particular values of @var{priority} do not matter; only their
24900 @cindex @code{warn_unused} type attribute
24902 For C++ types with non-trivial constructors and/or destructors it is
24903 impossible for the compiler to determine whether a variable of this
24904 type is truly unused if it is not referenced. This type attribute
24905 informs the compiler that variables of this type should be warned
24906 about if they appear to be unused, just like variables of fundamental
24909 This attribute is appropriate for types which just represent a value,
24910 such as @code{std::string}; it is not appropriate for types which
24911 control a resource, such as @code{std::lock_guard}.
24913 This attribute is also accepted in C, but it is unnecessary because C
24914 does not have constructors or destructors.
24918 @node Function Multiversioning
24919 @section Function Multiversioning
24920 @cindex function versions
24922 With the GNU C++ front end, for x86 targets, you may specify multiple
24923 versions of a function, where each function is specialized for a
24924 specific target feature. At runtime, the appropriate version of the
24925 function is automatically executed depending on the characteristics of
24926 the execution platform. Here is an example.
24929 __attribute__ ((target ("default")))
24932 // The default version of foo.
24936 __attribute__ ((target ("sse4.2")))
24939 // foo version for SSE4.2
24943 __attribute__ ((target ("arch=atom")))
24946 // foo version for the Intel ATOM processor
24950 __attribute__ ((target ("arch=amdfam10")))
24953 // foo version for the AMD Family 0x10 processors.
24960 assert ((*p) () == foo ());
24965 In the above example, four versions of function foo are created. The
24966 first version of foo with the target attribute "default" is the default
24967 version. This version gets executed when no other target specific
24968 version qualifies for execution on a particular platform. A new version
24969 of foo is created by using the same function signature but with a
24970 different target string. Function foo is called or a pointer to it is
24971 taken just like a regular function. GCC takes care of doing the
24972 dispatching to call the right version at runtime. Refer to the
24973 @uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
24974 Function Multiversioning} for more details.
24977 @section Type Traits
24979 The C++ front end implements syntactic extensions that allow
24980 compile-time determination of
24981 various characteristics of a type (or of a
24985 @item __has_nothrow_assign (type)
24986 If @code{type} is @code{const}-qualified or is a reference type then
24987 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
24988 is @code{true} then the trait is @code{true}, else if @code{type} is
24989 a cv-qualified class or union type with copy assignment operators that are
24990 known not to throw an exception then the trait is @code{true}, else it is
24992 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24993 @code{void}, or an array of unknown bound.
24995 @item __has_nothrow_copy (type)
24996 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
24997 @code{true}, else if @code{type} is a cv-qualified class or union type
24998 with copy constructors that are known not to throw an exception then
24999 the trait is @code{true}, else it is @code{false}.
25000 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25001 @code{void}, or an array of unknown bound.
25003 @item __has_nothrow_constructor (type)
25004 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
25005 is @code{true}, else if @code{type} is a cv class or union type (or array
25006 thereof) with a default constructor that is known not to throw an
25007 exception then the trait is @code{true}, else it is @code{false}.
25008 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25009 @code{void}, or an array of unknown bound.
25011 @item __has_trivial_assign (type)
25012 If @code{type} is @code{const}- qualified or is a reference type then
25013 the trait is @code{false}. Otherwise if @code{__is_pod (type)} is
25014 @code{true} then the trait is @code{true}, else if @code{type} is
25015 a cv-qualified class or union type with a trivial copy assignment
25016 ([class.copy]) then the trait is @code{true}, else it is @code{false}.
25017 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25018 @code{void}, or an array of unknown bound.
25020 @item __has_trivial_copy (type)
25021 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference
25022 type then the trait is @code{true}, else if @code{type} is a cv class
25023 or union type with a trivial copy constructor ([class.copy]) then the trait
25024 is @code{true}, else it is @code{false}. Requires: @code{type} shall be
25025 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
25028 @item __has_trivial_constructor (type)
25029 If @code{__is_pod (type)} is @code{true} then the trait is @code{true},
25030 else if @code{type} is a cv-qualified class or union type (or array thereof)
25031 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
25032 else it is @code{false}.
25033 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25034 @code{void}, or an array of unknown bound.
25036 @item __has_trivial_destructor (type)
25037 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type
25038 then the trait is @code{true}, else if @code{type} is a cv class or union
25039 type (or array thereof) with a trivial destructor ([class.dtor]) then
25040 the trait is @code{true}, else it is @code{false}.
25041 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25042 @code{void}, or an array of unknown bound.
25044 @item __has_virtual_destructor (type)
25045 If @code{type} is a class type with a virtual destructor
25046 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
25047 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25048 @code{void}, or an array of unknown bound.
25050 @item __is_abstract (type)
25051 If @code{type} is an abstract class ([class.abstract]) then the trait
25052 is @code{true}, else it is @code{false}.
25053 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25054 @code{void}, or an array of unknown bound.
25056 @item __is_base_of (base_type, derived_type)
25057 If @code{base_type} is a base class of @code{derived_type}
25058 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
25059 Top-level cv-qualifications of @code{base_type} and
25060 @code{derived_type} are ignored. For the purposes of this trait, a
25061 class type is considered is own base.
25062 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
25063 are @code{true} and @code{base_type} and @code{derived_type} are not the same
25064 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
25065 type. A diagnostic is produced if this requirement is not met.
25067 @item __is_class (type)
25068 If @code{type} is a cv-qualified class type, and not a union type
25069 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
25071 @item __is_empty (type)
25072 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
25073 Otherwise @code{type} is considered empty if and only if: @code{type}
25074 has no non-static data members, or all non-static data members, if
25075 any, are bit-fields of length 0, and @code{type} has no virtual
25076 members, and @code{type} has no virtual base classes, and @code{type}
25077 has no base classes @code{base_type} for which
25078 @code{__is_empty (base_type)} is @code{false}.
25079 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25080 @code{void}, or an array of unknown bound.
25082 @item __is_enum (type)
25083 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
25084 @code{true}, else it is @code{false}.
25086 @item __is_literal_type (type)
25087 If @code{type} is a literal type ([basic.types]) the trait is
25088 @code{true}, else it is @code{false}.
25089 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25090 @code{void}, or an array of unknown bound.
25092 @item __is_pod (type)
25093 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
25094 else it is @code{false}.
25095 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25096 @code{void}, or an array of unknown bound.
25098 @item __is_polymorphic (type)
25099 If @code{type} is a polymorphic class ([class.virtual]) then the trait
25100 is @code{true}, else it is @code{false}.
25101 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25102 @code{void}, or an array of unknown bound.
25104 @item __is_standard_layout (type)
25105 If @code{type} is a standard-layout type ([basic.types]) the trait is
25106 @code{true}, else it is @code{false}.
25107 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25108 @code{void}, or an array of unknown bound.
25110 @item __is_trivial (type)
25111 If @code{type} is a trivial type ([basic.types]) the trait is
25112 @code{true}, else it is @code{false}.
25113 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25114 @code{void}, or an array of unknown bound.
25116 @item __is_union (type)
25117 If @code{type} is a cv union type ([basic.compound]) the trait is
25118 @code{true}, else it is @code{false}.
25120 @item __underlying_type (type)
25121 The underlying type of @code{type}.
25122 Requires: @code{type} shall be an enumeration type ([dcl.enum]).
25124 @item __integer_pack (length)
25125 When used as the pattern of a pack expansion within a template
25126 definition, expands to a template argument pack containing integers
25127 from @code{0} to @code{length-1}. This is provided for efficient
25128 implementation of @code{std::make_integer_sequence}.
25134 @section C++ Concepts
25136 C++ concepts provide much-improved support for generic programming. In
25137 particular, they allow the specification of constraints on template arguments.
25138 The constraints are used to extend the usual overloading and partial
25139 specialization capabilities of the language, allowing generic data structures
25140 and algorithms to be ``refined'' based on their properties rather than their
25143 The following keywords are reserved for concepts.
25147 States an expression as an assumption, and if possible, verifies that the
25148 assumption is valid. For example, @code{assume(n > 0)}.
25151 Introduces an axiom definition. Axioms introduce requirements on values.
25154 Introduces a universally quantified object in an axiom. For example,
25155 @code{forall (int n) n + 0 == n}).
25158 Introduces a concept definition. Concepts are sets of syntactic and semantic
25159 requirements on types and their values.
25162 Introduces constraints on template arguments or requirements for a member
25163 function of a class template.
25167 The front end also exposes a number of internal mechanism that can be used
25168 to simplify the writing of type traits. Note that some of these traits are
25169 likely to be removed in the future.
25172 @item __is_same (type1, type2)
25173 A binary type trait: @code{true} whenever the type arguments are the same.
25178 @node Deprecated Features
25179 @section Deprecated Features
25181 In the past, the GNU C++ compiler was extended to experiment with new
25182 features, at a time when the C++ language was still evolving. Now that
25183 the C++ standard is complete, some of those features are superseded by
25184 superior alternatives. Using the old features might cause a warning in
25185 some cases that the feature will be dropped in the future. In other
25186 cases, the feature might be gone already.
25188 G++ allows a virtual function returning @samp{void *} to be overridden
25189 by one returning a different pointer type. This extension to the
25190 covariant return type rules is now deprecated and will be removed from a
25193 The use of default arguments in function pointers, function typedefs
25194 and other places where they are not permitted by the standard is
25195 deprecated and will be removed from a future version of G++.
25197 G++ allows floating-point literals to appear in integral constant expressions,
25198 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
25199 This extension is deprecated and will be removed from a future version.
25201 G++ allows static data members of const floating-point type to be declared
25202 with an initializer in a class definition. The standard only allows
25203 initializers for static members of const integral types and const
25204 enumeration types so this extension has been deprecated and will be removed
25205 from a future version.
25207 G++ allows attributes to follow a parenthesized direct initializer,
25208 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
25209 has been ignored since G++ 3.3 and is deprecated.
25211 G++ allows anonymous structs and unions to have members that are not
25212 public non-static data members (i.e.@: fields). These extensions are
25215 @node Backwards Compatibility
25216 @section Backwards Compatibility
25217 @cindex Backwards Compatibility
25218 @cindex ARM [Annotated C++ Reference Manual]
25220 Now that there is a definitive ISO standard C++, G++ has a specification
25221 to adhere to. The C++ language evolved over time, and features that
25222 used to be acceptable in previous drafts of the standard, such as the ARM
25223 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
25224 compilation of C++ written to such drafts, G++ contains some backwards
25225 compatibilities. @emph{All such backwards compatibility features are
25226 liable to disappear in future versions of G++.} They should be considered
25227 deprecated. @xref{Deprecated Features}.
25231 @item Implicit C language
25232 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
25233 scope to set the language. On such systems, all system header files are
25234 implicitly scoped inside a C language scope. Such headers must
25235 correctly prototype function argument types, there is no leeway for
25236 @code{()} to indicate an unspecified set of arguments.
25240 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
25241 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr