1 c Copyright (C) 1988-2022 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 GCC can handle both implicit and explicit casts between the @code{_Complex}
990 types and other @code{_Complex} types as casting both the real and imaginary
991 parts to the scalar type.
992 GCC can handle implicit and explicit casts from a scalar type to a @code{_Complex}
993 type and where the imaginary part will be considered zero.
994 The C front-end can handle implicit and explicit casts from a @code{_Complex} type
995 to a scalar type where the imaginary part will be ignored. In C++ code, this cast
996 is considered illformed and G++ will error out.
998 GCC provides a built-in function @code{__builtin_complex} will can be used to
999 construct a complex value.
1001 @cindex @code{__real__} keyword
1002 @cindex @code{__imag__} keyword
1004 GCC has a few extensions which can be used to extract the real
1005 and the imaginary part of the complex-valued expression. Note
1006 these expressions are lvalues if the @var{exp} is an lvalue.
1007 These expressions operands have the type of a complex type
1008 which might get prompoted to a complex type from a scalar type.
1009 E.g. @code{__real__ (int)@var{x}} is the same as casting to
1010 @code{_Complex int} before @code{__real__} is done.
1012 @multitable @columnfractions .4 .6
1013 @headitem Expression @tab Description
1014 @item @code{__real__ @var{exp}}
1015 @tab Extract the real part of @var{exp}.
1016 @item @code{__imag__ @var{exp}}
1017 @tab Extract the imaginary part of @var{exp}.
1020 For values of floating point, you should use the ISO C99
1021 functions, declared in @code{<complex.h>} and also provided as
1022 built-in functions by GCC@.
1024 @multitable @columnfractions .4 .2 .2 .2
1025 @headitem Expression @tab float @tab double @tab long double
1026 @item @code{__real__ @var{exp}}
1027 @tab @code{crealf} @tab @code{creal} @tab @code{creall}
1028 @item @code{__imag__ @var{exp}}
1029 @tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl}
1032 @cindex complex conjugation
1033 The operator @samp{~} performs complex conjugation when used on a value
1034 with a complex type. This is a GNU extension; for values of
1035 floating type, you should use the ISO C99 functions @code{conjf},
1036 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
1037 provided as built-in functions by GCC@. Note unlike the @code{__real__}
1038 and @code{__imag__} operators, this operator will not do an implicit cast
1039 to the complex type because the @samp{~} is already a normal operator.
1041 GCC can allocate complex automatic variables in a noncontiguous
1042 fashion; it's even possible for the real part to be in a register while
1043 the imaginary part is on the stack (or vice versa). Only the DWARF
1044 debug info format can represent this, so use of DWARF is recommended.
1045 If you are using the stabs debug info format, GCC describes a noncontiguous
1046 complex variable as if it were two separate variables of noncomplex type.
1047 If the variable's actual name is @code{foo}, the two fictitious
1048 variables are named @code{foo$real} and @code{foo$imag}. You can
1049 examine and set these two fictitious variables with your debugger.
1051 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
1053 The built-in function @code{__builtin_complex} is provided for use in
1054 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
1055 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
1056 real binary floating-point type, and the result has the corresponding
1057 complex type with real and imaginary parts @var{real} and @var{imag}.
1058 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
1059 infinities, NaNs and negative zeros are involved.
1063 @node Floating Types
1064 @section Additional Floating Types
1065 @cindex additional floating types
1066 @cindex @code{_Float@var{n}} data types
1067 @cindex @code{_Float@var{n}x} data types
1068 @cindex @code{__float80} data type
1069 @cindex @code{__float128} data type
1070 @cindex @code{__ibm128} data type
1071 @cindex @code{w} floating point suffix
1072 @cindex @code{q} floating point suffix
1073 @cindex @code{W} floating point suffix
1074 @cindex @code{Q} floating point suffix
1076 ISO/IEC TS 18661-3:2015 defines C support for additional floating
1077 types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
1078 these type names; the set of types supported depends on the target
1079 architecture. These types are not supported when compiling C++.
1080 Constants with these types use suffixes @code{f@var{n}} or
1081 @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
1082 names can be used together with @code{_Complex} to declare complex
1085 As an extension, GNU C and GNU C++ support additional floating
1086 types, which are not supported by all targets.
1088 @item @code{__float128} is available on i386, x86_64, IA-64, and
1089 hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
1090 the vector scalar (VSX) instruction set. @code{__float128} supports
1091 the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64
1092 other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
1093 On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
1096 @item @code{__float80} is available on the i386, x86_64, and IA-64
1097 targets, and supports the 80-bit (@code{XFmode}) floating type. It is
1098 an alias for the type name @code{_Float64x} on these targets.
1100 @item @code{__ibm128} is available on PowerPC targets, and provides
1101 access to the IBM extended double format which is the current format
1102 used for @code{long double}. When @code{long double} transitions to
1103 @code{__float128} on PowerPC in the future, @code{__ibm128} will remain
1104 for use in conversions between the two types.
1107 Support for these additional types includes the arithmetic operators:
1108 add, subtract, multiply, divide; unary arithmetic operators;
1109 relational operators; equality operators; and conversions to and from
1110 integer and other floating types. Use a suffix @samp{w} or @samp{W}
1111 in a literal constant of type @code{__float80} or type
1112 @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}.
1114 In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
1115 on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
1116 expected in future versions of GCC that @code{_Float128} and @code{__float128}
1117 will be enabled automatically.
1119 The @code{_Float128} type is supported on all systems where
1120 @code{__float128} is supported or where @code{long double} has the
1121 IEEE binary128 format. The @code{_Float64x} type is supported on all
1122 systems where @code{__float128} is supported. The @code{_Float32}
1123 type is supported on all systems supporting IEEE binary32; the
1124 @code{_Float64} and @code{_Float32x} types are supported on all systems
1125 supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
1126 systems by default, on ARM systems when the IEEE format for 16-bit
1127 floating-point types is selected with @option{-mfp16-format=ieee} and,
1128 for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently
1129 support @code{_Float128x} on any systems.
1131 On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
1132 types using the corresponding internal complex type, @code{XCmode} for
1133 @code{__float80} type and @code{TCmode} for @code{__float128} type:
1136 typedef _Complex float __attribute__((mode(TC))) _Complex128;
1137 typedef _Complex float __attribute__((mode(XC))) _Complex80;
1140 On the PowerPC Linux VSX targets, you can declare complex types using
1141 the corresponding internal complex type, @code{KCmode} for
1142 @code{__float128} type and @code{ICmode} for @code{__ibm128} type:
1145 typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
1146 typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
1149 @node Half-Precision
1150 @section Half-Precision Floating Point
1151 @cindex half-precision floating point
1152 @cindex @code{__fp16} data type
1153 @cindex @code{__Float16} data type
1155 On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
1156 point via the @code{__fp16} type defined in the ARM C Language Extensions.
1157 On ARM systems, you must enable this type explicitly with the
1158 @option{-mfp16-format} command-line option in order to use it.
1159 On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit)
1160 floating point via the @code{_Float16} type. For C++, x86 provides a builtin
1161 type named @code{_Float16} which contains same data format as C.
1163 ARM targets support two incompatible representations for half-precision
1164 floating-point values. You must choose one of the representations and
1165 use it consistently in your program.
1167 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
1168 This format can represent normalized values in the range of @math{2^{-14}} to 65504.
1169 There are 11 bits of significand precision, approximately 3
1172 Specifying @option{-mfp16-format=alternative} selects the ARM
1173 alternative format. This representation is similar to the IEEE
1174 format, but does not support infinities or NaNs. Instead, the range
1175 of exponents is extended, so that this format can represent normalized
1176 values in the range of @math{2^{-14}} to 131008.
1178 The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
1179 not require use of the @option{-mfp16-format} command-line option.
1181 The @code{__fp16} type may only be used as an argument to intrinsics defined
1182 in @code{<arm_fp16.h>}, or as a storage format. For purposes of
1183 arithmetic and other operations, @code{__fp16} values in C or C++
1184 expressions are automatically promoted to @code{float}.
1186 The ARM target provides hardware support for conversions between
1187 @code{__fp16} and @code{float} values
1188 as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
1189 hardware support for conversions between @code{__fp16} and @code{double}
1190 values. GCC generates code using these hardware instructions if you
1191 compile with options to select an FPU that provides them;
1192 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
1193 in addition to the @option{-mfp16-format} option to select
1194 a half-precision format.
1196 Language-level support for the @code{__fp16} data type is
1197 independent of whether GCC generates code using hardware floating-point
1198 instructions. In cases where hardware support is not specified, GCC
1199 implements conversions between @code{__fp16} and other types as library
1202 It is recommended that portable code use the @code{_Float16} type defined
1203 by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
1205 On x86 targets with SSE2 enabled, without @option{-mavx512fp16},
1206 all operations will be emulated by software emulation and the @code{float}
1207 instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the
1208 intermediate result of the operation as 32-bit precision. This may lead to
1209 inconsistent behavior between software emulation and AVX512-FP16 instructions.
1210 Using @option{-fexcess-precision=16} will force round back after each operation.
1212 Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of
1213 software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round
1214 after each operation. The same is true with @option{-fexcess-precision=standard}
1215 and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse},
1216 @option{-fexcess-precision=standard} alone does the same thing as before,
1217 It is useful for code that does not have @code{_Float16} and runs on the x87
1221 @section Decimal Floating Types
1222 @cindex decimal floating types
1223 @cindex @code{_Decimal32} data type
1224 @cindex @code{_Decimal64} data type
1225 @cindex @code{_Decimal128} data type
1226 @cindex @code{df} integer suffix
1227 @cindex @code{dd} integer suffix
1228 @cindex @code{dl} integer suffix
1229 @cindex @code{DF} integer suffix
1230 @cindex @code{DD} integer suffix
1231 @cindex @code{DL} integer suffix
1233 As an extension, GNU C supports decimal floating types as
1234 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
1235 floating types in GCC will evolve as the draft technical report changes.
1236 Calling conventions for any target might also change. Not all targets
1237 support decimal floating types.
1239 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
1240 @code{_Decimal128}. They use a radix of ten, unlike the floating types
1241 @code{float}, @code{double}, and @code{long double} whose radix is not
1242 specified by the C standard but is usually two.
1244 Support for decimal floating types includes the arithmetic operators
1245 add, subtract, multiply, divide; unary arithmetic operators;
1246 relational operators; equality operators; and conversions to and from
1247 integer and other floating types. Use a suffix @samp{df} or
1248 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1249 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1252 GCC support of decimal float as specified by the draft technical report
1257 When the value of a decimal floating type cannot be represented in the
1258 integer type to which it is being converted, the result is undefined
1259 rather than the result value specified by the draft technical report.
1262 GCC does not provide the C library functionality associated with
1263 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1264 @file{wchar.h}, which must come from a separate C library implementation.
1265 Because of this the GNU C compiler does not define macro
1266 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1267 the technical report.
1270 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1271 are supported by the DWARF debug information format.
1277 ISO C99 and ISO C++17 support floating-point numbers written not only in
1278 the usual decimal notation, such as @code{1.55e1}, but also numbers such as
1279 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
1280 supports this in C90 mode (except in some cases when strictly
1281 conforming) and in C++98, C++11 and C++14 modes. In that format the
1282 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1283 mandatory. The exponent is a decimal number that indicates the power of
1284 2 by which the significant part is multiplied. Thus @samp{0x1.f} is
1291 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1292 is the same as @code{1.55e1}.
1294 Unlike for floating-point numbers in the decimal notation the exponent
1295 is always required in the hexadecimal notation. Otherwise the compiler
1296 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
1297 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1298 extension for floating-point constants of type @code{float}.
1301 @section Fixed-Point Types
1302 @cindex fixed-point types
1303 @cindex @code{_Fract} data type
1304 @cindex @code{_Accum} data type
1305 @cindex @code{_Sat} data type
1306 @cindex @code{hr} fixed-suffix
1307 @cindex @code{r} fixed-suffix
1308 @cindex @code{lr} fixed-suffix
1309 @cindex @code{llr} fixed-suffix
1310 @cindex @code{uhr} fixed-suffix
1311 @cindex @code{ur} fixed-suffix
1312 @cindex @code{ulr} fixed-suffix
1313 @cindex @code{ullr} fixed-suffix
1314 @cindex @code{hk} fixed-suffix
1315 @cindex @code{k} fixed-suffix
1316 @cindex @code{lk} fixed-suffix
1317 @cindex @code{llk} fixed-suffix
1318 @cindex @code{uhk} fixed-suffix
1319 @cindex @code{uk} fixed-suffix
1320 @cindex @code{ulk} fixed-suffix
1321 @cindex @code{ullk} fixed-suffix
1322 @cindex @code{HR} fixed-suffix
1323 @cindex @code{R} fixed-suffix
1324 @cindex @code{LR} fixed-suffix
1325 @cindex @code{LLR} fixed-suffix
1326 @cindex @code{UHR} fixed-suffix
1327 @cindex @code{UR} fixed-suffix
1328 @cindex @code{ULR} fixed-suffix
1329 @cindex @code{ULLR} fixed-suffix
1330 @cindex @code{HK} fixed-suffix
1331 @cindex @code{K} fixed-suffix
1332 @cindex @code{LK} fixed-suffix
1333 @cindex @code{LLK} fixed-suffix
1334 @cindex @code{UHK} fixed-suffix
1335 @cindex @code{UK} fixed-suffix
1336 @cindex @code{ULK} fixed-suffix
1337 @cindex @code{ULLK} fixed-suffix
1339 As an extension, GNU C supports fixed-point types as
1340 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
1341 types in GCC will evolve as the draft technical report changes.
1342 Calling conventions for any target might also change. Not all targets
1343 support fixed-point types.
1345 The fixed-point types are
1346 @code{short _Fract},
1349 @code{long long _Fract},
1350 @code{unsigned short _Fract},
1351 @code{unsigned _Fract},
1352 @code{unsigned long _Fract},
1353 @code{unsigned long long _Fract},
1354 @code{_Sat short _Fract},
1356 @code{_Sat long _Fract},
1357 @code{_Sat long long _Fract},
1358 @code{_Sat unsigned short _Fract},
1359 @code{_Sat unsigned _Fract},
1360 @code{_Sat unsigned long _Fract},
1361 @code{_Sat unsigned long long _Fract},
1362 @code{short _Accum},
1365 @code{long long _Accum},
1366 @code{unsigned short _Accum},
1367 @code{unsigned _Accum},
1368 @code{unsigned long _Accum},
1369 @code{unsigned long long _Accum},
1370 @code{_Sat short _Accum},
1372 @code{_Sat long _Accum},
1373 @code{_Sat long long _Accum},
1374 @code{_Sat unsigned short _Accum},
1375 @code{_Sat unsigned _Accum},
1376 @code{_Sat unsigned long _Accum},
1377 @code{_Sat unsigned long long _Accum}.
1379 Fixed-point data values contain fractional and optional integral parts.
1380 The format of fixed-point data varies and depends on the target machine.
1382 Support for fixed-point types includes:
1385 prefix and postfix increment and decrement operators (@code{++}, @code{--})
1387 unary arithmetic operators (@code{+}, @code{-}, @code{!})
1389 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1391 binary shift operators (@code{<<}, @code{>>})
1393 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1395 equality operators (@code{==}, @code{!=})
1397 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1398 @code{<<=}, @code{>>=})
1400 conversions to and from integer, floating-point, or fixed-point types
1403 Use a suffix in a fixed-point literal constant:
1405 @item @samp{hr} or @samp{HR} for @code{short _Fract} and
1406 @code{_Sat short _Fract}
1407 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1408 @item @samp{lr} or @samp{LR} for @code{long _Fract} and
1409 @code{_Sat long _Fract}
1410 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1411 @code{_Sat long long _Fract}
1412 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1413 @code{_Sat unsigned short _Fract}
1414 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1415 @code{_Sat unsigned _Fract}
1416 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1417 @code{_Sat unsigned long _Fract}
1418 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1419 and @code{_Sat unsigned long long _Fract}
1420 @item @samp{hk} or @samp{HK} for @code{short _Accum} and
1421 @code{_Sat short _Accum}
1422 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1423 @item @samp{lk} or @samp{LK} for @code{long _Accum} and
1424 @code{_Sat long _Accum}
1425 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1426 @code{_Sat long long _Accum}
1427 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1428 @code{_Sat unsigned short _Accum}
1429 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1430 @code{_Sat unsigned _Accum}
1431 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1432 @code{_Sat unsigned long _Accum}
1433 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1434 and @code{_Sat unsigned long long _Accum}
1437 GCC support of fixed-point types as specified by the draft technical report
1442 Pragmas to control overflow and rounding behaviors are not implemented.
1445 Fixed-point types are supported by the DWARF debug information format.
1447 @node Named Address Spaces
1448 @section Named Address Spaces
1449 @cindex Named Address Spaces
1451 As an extension, GNU C supports named address spaces as
1452 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
1453 address spaces in GCC will evolve as the draft technical report
1454 changes. Calling conventions for any target might also change. At
1455 present, only the AVR, M32C, PRU, RL78, and x86 targets support
1456 address spaces other than the generic address space.
1458 Address space identifiers may be used exactly like any other C type
1459 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1460 document for more details.
1462 @anchor{AVR Named Address Spaces}
1463 @subsection AVR Named Address Spaces
1465 On the AVR target, there are several address spaces that can be used
1466 in order to put read-only data into the flash memory and access that
1467 data by means of the special instructions @code{LPM} or @code{ELPM}
1468 needed to read from flash.
1470 Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
1471 flash memory by means of @code{LD*} instructions because the flash
1472 memory is mapped into the RAM address space. There is @emph{no need}
1473 for language extensions like @code{__flash} or attribute
1474 @ref{AVR Variable Attributes,,@code{progmem}}.
1475 The default linker description files for these devices cater for that
1476 feature and @code{.rodata} stays in flash: The compiler just generates
1477 @code{LD*} instructions, and the linker script adds core specific
1478 offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
1479 @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
1480 See @ref{AVR Options} for a list of respective devices.
1482 For devices not in @code{avrtiny} or @code{avrxmega3},
1483 any data including read-only data is located in RAM (the generic
1484 address space) because flash memory is not visible in the RAM address
1485 space. In order to locate read-only data in flash memory @emph{and}
1486 to generate the right instructions to access this data without
1487 using (inline) assembler code, special address spaces are needed.
1491 @cindex @code{__flash} AVR Named Address Spaces
1492 The @code{__flash} qualifier locates data in the
1493 @code{.progmem.data} section. Data is read using the @code{LPM}
1494 instruction. Pointers to this address space are 16 bits wide.
1501 @cindex @code{__flash1} AVR Named Address Spaces
1502 @cindex @code{__flash2} AVR Named Address Spaces
1503 @cindex @code{__flash3} AVR Named Address Spaces
1504 @cindex @code{__flash4} AVR Named Address Spaces
1505 @cindex @code{__flash5} AVR Named Address Spaces
1506 These are 16-bit address spaces locating data in section
1507 @code{.progmem@var{N}.data} where @var{N} refers to
1508 address space @code{__flash@var{N}}.
1509 The compiler sets the @code{RAMPZ} segment register appropriately
1510 before reading data by means of the @code{ELPM} instruction.
1513 @cindex @code{__memx} AVR Named Address Spaces
1514 This is a 24-bit address space that linearizes flash and RAM:
1515 If the high bit of the address is set, data is read from
1516 RAM using the lower two bytes as RAM address.
1517 If the high bit of the address is clear, data is read from flash
1518 with @code{RAMPZ} set according to the high byte of the address.
1519 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1521 Objects in this address space are located in @code{.progmemx.data}.
1527 char my_read (const __flash char ** p)
1529 /* p is a pointer to RAM that points to a pointer to flash.
1530 The first indirection of p reads that flash pointer
1531 from RAM and the second indirection reads a char from this
1537 /* Locate array[] in flash memory */
1538 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1544 /* Return 17 by reading from flash memory */
1545 return array[array[i]];
1550 For each named address space supported by avr-gcc there is an equally
1551 named but uppercase built-in macro defined.
1552 The purpose is to facilitate testing if respective address space
1553 support is available or not:
1557 const __flash int var = 1;
1564 #include <avr/pgmspace.h> /* From AVR-LibC */
1566 const int var PROGMEM = 1;
1570 return (int) pgm_read_word (&var);
1572 #endif /* __FLASH */
1576 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1577 locates data in flash but
1578 accesses to these data read from generic address space, i.e.@:
1580 so that you need special accessors like @code{pgm_read_byte}
1581 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1582 together with attribute @code{progmem}.
1585 @b{Limitations and caveats}
1589 Reading across the 64@tie{}KiB section boundary of
1590 the @code{__flash} or @code{__flash@var{N}} address spaces
1591 shows undefined behavior. The only address space that
1592 supports reading across the 64@tie{}KiB flash segment boundaries is
1596 If you use one of the @code{__flash@var{N}} address spaces
1597 you must arrange your linker script to locate the
1598 @code{.progmem@var{N}.data} sections according to your needs.
1601 Any data or pointers to the non-generic address spaces must
1602 be qualified as @code{const}, i.e.@: as read-only data.
1603 This still applies if the data in one of these address
1604 spaces like software version number or calibration lookup table are intended to
1605 be changed after load time by, say, a boot loader. In this case
1606 the right qualification is @code{const} @code{volatile} so that the compiler
1607 must not optimize away known values or insert them
1608 as immediates into operands of instructions.
1611 The following code initializes a variable @code{pfoo}
1612 located in static storage with a 24-bit address:
1614 extern const __memx char foo;
1615 const __memx void *pfoo = &foo;
1619 On the reduced Tiny devices like ATtiny40, no address spaces are supported.
1620 Just use vanilla C / C++ code without overhead as outlined above.
1621 Attribute @code{progmem} is supported but works differently,
1622 see @ref{AVR Variable Attributes}.
1626 @subsection M32C Named Address Spaces
1627 @cindex @code{__far} M32C Named Address Spaces
1629 On the M32C target, with the R8C and M16C CPU variants, variables
1630 qualified with @code{__far} are accessed using 32-bit addresses in
1631 order to access memory beyond the first 64@tie{}Ki bytes. If
1632 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1635 @subsection PRU Named Address Spaces
1636 @cindex @code{__regio_symbol} PRU Named Address Spaces
1638 On the PRU target, variables qualified with @code{__regio_symbol} are
1639 aliases used to access the special I/O CPU registers. They must be
1640 declared as @code{extern} because such variables will not be allocated in
1641 any data memory. They must also be marked as @code{volatile}, and can
1642 only be 32-bit integer types. The only names those variables can have
1643 are @code{__R30} and @code{__R31}, representing respectively the
1644 @code{R30} and @code{R31} special I/O CPU registers. Hence the following
1645 example is the only valid usage of @code{__regio_symbol}:
1648 extern volatile __regio_symbol uint32_t __R30;
1649 extern volatile __regio_symbol uint32_t __R31;
1652 @subsection RL78 Named Address Spaces
1653 @cindex @code{__far} RL78 Named Address Spaces
1655 On the RL78 target, variables qualified with @code{__far} are accessed
1656 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1657 addresses. Non-far variables are assumed to appear in the topmost
1658 64@tie{}KiB of the address space.
1660 @subsection x86 Named Address Spaces
1661 @cindex x86 named address spaces
1663 On the x86 target, variables may be declared as being relative
1664 to the @code{%fs} or @code{%gs} segments.
1669 @cindex @code{__seg_fs} x86 named address space
1670 @cindex @code{__seg_gs} x86 named address space
1671 The object is accessed with the respective segment override prefix.
1673 The respective segment base must be set via some method specific to
1674 the operating system. Rather than require an expensive system call
1675 to retrieve the segment base, these address spaces are not considered
1676 to be subspaces of the generic (flat) address space. This means that
1677 explicit casts are required to convert pointers between these address
1678 spaces and the generic address space. In practice the application
1679 should cast to @code{uintptr_t} and apply the segment base offset
1680 that it installed previously.
1682 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1683 defined when these address spaces are supported.
1687 @section Arrays of Length Zero
1688 @cindex arrays of length zero
1689 @cindex zero-length arrays
1690 @cindex length-zero arrays
1691 @cindex flexible array members
1693 Declaring zero-length arrays is allowed in GNU C as an extension.
1694 A zero-length array can be useful as the last element of a structure
1695 that is really a header for a variable-length object:
1703 struct line *thisline = (struct line *)
1704 malloc (sizeof (struct line) + this_length);
1705 thisline->length = this_length;
1708 Although the size of a zero-length array is zero, an array member of
1709 this kind may increase the size of the enclosing type as a result of tail
1710 padding. The offset of a zero-length array member from the beginning
1711 of the enclosing structure is the same as the offset of an array with
1712 one or more elements of the same type. The alignment of a zero-length
1713 array is the same as the alignment of its elements.
1715 Declaring zero-length arrays in other contexts, including as interior
1716 members of structure objects or as non-member objects, is discouraged.
1717 Accessing elements of zero-length arrays declared in such contexts is
1718 undefined and may be diagnosed.
1720 In the absence of the zero-length array extension, in ISO C90
1721 the @code{contents} array in the example above would typically be declared
1722 to have a single element. Unlike a zero-length array which only contributes
1723 to the size of the enclosing structure for the purposes of alignment,
1724 a one-element array always occupies at least as much space as a single
1725 object of the type. Although using one-element arrays this way is
1726 discouraged, GCC handles accesses to trailing one-element array members
1727 analogously to zero-length arrays.
1729 The preferred mechanism to declare variable-length types like
1730 @code{struct line} above is the ISO C99 @dfn{flexible array member},
1731 with slightly different syntax and semantics:
1735 Flexible array members are written as @code{contents[]} without
1739 Flexible array members have incomplete type, and so the @code{sizeof}
1740 operator may not be applied. As a quirk of the original implementation
1741 of zero-length arrays, @code{sizeof} evaluates to zero.
1744 Flexible array members may only appear as the last member of a
1745 @code{struct} that is otherwise non-empty.
1748 A structure containing a flexible array member, or a union containing
1749 such a structure (possibly recursively), may not be a member of a
1750 structure or an element of an array. (However, these uses are
1751 permitted by GCC as extensions.)
1754 Non-empty initialization of zero-length
1755 arrays is treated like any case where there are more initializer
1756 elements than the array holds, in that a suitable warning about ``excess
1757 elements in array'' is given, and the excess elements (all of them, in
1758 this case) are ignored.
1760 GCC allows static initialization of flexible array members.
1761 This is equivalent to defining a new structure containing the original
1762 structure followed by an array of sufficient size to contain the data.
1763 E.g.@: in the following, @code{f1} is constructed as if it were declared
1769 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1772 struct f1 f1; int data[3];
1773 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1777 The convenience of this extension is that @code{f1} has the desired
1778 type, eliminating the need to consistently refer to @code{f2.f1}.
1780 This has symmetry with normal static arrays, in that an array of
1781 unknown size is also written with @code{[]}.
1783 Of course, this extension only makes sense if the extra data comes at
1784 the end of a top-level object, as otherwise we would be overwriting
1785 data at subsequent offsets. To avoid undue complication and confusion
1786 with initialization of deeply nested arrays, we simply disallow any
1787 non-empty initialization except when the structure is the top-level
1788 object. For example:
1791 struct foo @{ int x; int y[]; @};
1792 struct bar @{ struct foo z; @};
1794 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1795 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1796 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1797 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1800 @node Empty Structures
1801 @section Structures with No Members
1802 @cindex empty structures
1803 @cindex zero-size structures
1805 GCC permits a C structure to have no members:
1812 The structure has size zero. In C++, empty structures are part
1813 of the language. G++ treats empty structures as if they had a single
1814 member of type @code{char}.
1816 @node Variable Length
1817 @section Arrays of Variable Length
1818 @cindex variable-length arrays
1819 @cindex arrays of variable length
1822 Variable-length automatic arrays are allowed in ISO C99, and as an
1823 extension GCC accepts them in C90 mode and in C++. These arrays are
1824 declared like any other automatic arrays, but with a length that is not
1825 a constant expression. The storage is allocated at the point of
1826 declaration and deallocated when the block scope containing the declaration
1832 concat_fopen (char *s1, char *s2, char *mode)
1834 char str[strlen (s1) + strlen (s2) + 1];
1837 return fopen (str, mode);
1841 @cindex scope of a variable length array
1842 @cindex variable-length array scope
1843 @cindex deallocating variable length arrays
1844 Jumping or breaking out of the scope of the array name deallocates the
1845 storage. Jumping into the scope is not allowed; you get an error
1848 @cindex variable-length array in a structure
1849 As an extension, GCC accepts variable-length arrays as a member of
1850 a structure or a union. For example:
1856 struct S @{ int x[n]; @};
1860 @cindex @code{alloca} vs variable-length arrays
1861 You can use the function @code{alloca} to get an effect much like
1862 variable-length arrays. The function @code{alloca} is available in
1863 many other C implementations (but not in all). On the other hand,
1864 variable-length arrays are more elegant.
1866 There are other differences between these two methods. Space allocated
1867 with @code{alloca} exists until the containing @emph{function} returns.
1868 The space for a variable-length array is deallocated as soon as the array
1869 name's scope ends, unless you also use @code{alloca} in this scope.
1871 You can also use variable-length arrays as arguments to functions:
1875 tester (int len, char data[len][len])
1881 The length of an array is computed once when the storage is allocated
1882 and is remembered for the scope of the array in case you access it with
1885 If you want to pass the array first and the length afterward, you can
1886 use a forward declaration in the parameter list---another GNU extension.
1890 tester (int len; char data[len][len], int len)
1896 @cindex parameter forward declaration
1897 The @samp{int len} before the semicolon is a @dfn{parameter forward
1898 declaration}, and it serves the purpose of making the name @code{len}
1899 known when the declaration of @code{data} is parsed.
1901 You can write any number of such parameter forward declarations in the
1902 parameter list. They can be separated by commas or semicolons, but the
1903 last one must end with a semicolon, which is followed by the ``real''
1904 parameter declarations. Each forward declaration must match a ``real''
1905 declaration in parameter name and data type. ISO C99 does not support
1906 parameter forward declarations.
1908 @node Variadic Macros
1909 @section Macros with a Variable Number of Arguments.
1910 @cindex variable number of arguments
1911 @cindex macro with variable arguments
1912 @cindex rest argument (in macro)
1913 @cindex variadic macros
1915 In the ISO C standard of 1999, a macro can be declared to accept a
1916 variable number of arguments much as a function can. The syntax for
1917 defining the macro is similar to that of a function. Here is an
1921 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1925 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1926 such a macro, it represents the zero or more tokens until the closing
1927 parenthesis that ends the invocation, including any commas. This set of
1928 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1929 wherever it appears. See the CPP manual for more information.
1931 GCC has long supported variadic macros, and used a different syntax that
1932 allowed you to give a name to the variable arguments just like any other
1933 argument. Here is an example:
1936 #define debug(format, args...) fprintf (stderr, format, args)
1940 This is in all ways equivalent to the ISO C example above, but arguably
1941 more readable and descriptive.
1943 GNU CPP has two further variadic macro extensions, and permits them to
1944 be used with either of the above forms of macro definition.
1946 In standard C, you are not allowed to leave the variable argument out
1947 entirely; but you are allowed to pass an empty argument. For example,
1948 this invocation is invalid in ISO C, because there is no comma after
1955 GNU CPP permits you to completely omit the variable arguments in this
1956 way. In the above examples, the compiler would complain, though since
1957 the expansion of the macro still has the extra comma after the format
1960 To help solve this problem, CPP behaves specially for variable arguments
1961 used with the token paste operator, @samp{##}. If instead you write
1964 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1968 and if the variable arguments are omitted or empty, the @samp{##}
1969 operator causes the preprocessor to remove the comma before it. If you
1970 do provide some variable arguments in your macro invocation, GNU CPP
1971 does not complain about the paste operation and instead places the
1972 variable arguments after the comma. Just like any other pasted macro
1973 argument, these arguments are not macro expanded.
1975 @node Escaped Newlines
1976 @section Slightly Looser Rules for Escaped Newlines
1977 @cindex escaped newlines
1978 @cindex newlines (escaped)
1980 The preprocessor treatment of escaped newlines is more relaxed
1981 than that specified by the C90 standard, which requires the newline
1982 to immediately follow a backslash.
1983 GCC's implementation allows whitespace in the form
1984 of spaces, horizontal and vertical tabs, and form feeds between the
1985 backslash and the subsequent newline. The preprocessor issues a
1986 warning, but treats it as a valid escaped newline and combines the two
1987 lines to form a single logical line. This works within comments and
1988 tokens, as well as between tokens. Comments are @emph{not} treated as
1989 whitespace for the purposes of this relaxation, since they have not
1990 yet been replaced with spaces.
1993 @section Non-Lvalue Arrays May Have Subscripts
1994 @cindex subscripting
1995 @cindex arrays, non-lvalue
1997 @cindex subscripting and function values
1998 In ISO C99, arrays that are not lvalues still decay to pointers, and
1999 may be subscripted, although they may not be modified or used after
2000 the next sequence point and the unary @samp{&} operator may not be
2001 applied to them. As an extension, GNU C allows such arrays to be
2002 subscripted in C90 mode, though otherwise they do not decay to
2003 pointers outside C99 mode. For example,
2004 this is valid in GNU C though not valid in C90:
2008 struct foo @{int a[4];@};
2014 return f().a[index];
2020 @section Arithmetic on @code{void}- and Function-Pointers
2021 @cindex void pointers, arithmetic
2022 @cindex void, size of pointer to
2023 @cindex function pointers, arithmetic
2024 @cindex function, size of pointer to
2026 In GNU C, addition and subtraction operations are supported on pointers to
2027 @code{void} and on pointers to functions. This is done by treating the
2028 size of a @code{void} or of a function as 1.
2030 A consequence of this is that @code{sizeof} is also allowed on @code{void}
2031 and on function types, and returns 1.
2033 @opindex Wpointer-arith
2034 The option @option{-Wpointer-arith} requests a warning if these extensions
2037 @node Variadic Pointer Args
2038 @section Pointer Arguments in Variadic Functions
2039 @cindex pointer arguments in variadic functions
2040 @cindex variadic functions, pointer arguments
2042 Standard C requires that pointer types used with @code{va_arg} in
2043 functions with variable argument lists either must be compatible with
2044 that of the actual argument, or that one type must be a pointer to
2045 @code{void} and the other a pointer to a character type. GNU C
2046 implements the POSIX XSI extension that additionally permits the use
2047 of @code{va_arg} with a pointer type to receive arguments of any other
2050 In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
2051 to consume an argument of any pointer type.
2053 @node Pointers to Arrays
2054 @section Pointers to Arrays with Qualifiers Work as Expected
2055 @cindex pointers to arrays
2056 @cindex const qualifier
2058 In GNU C, pointers to arrays with qualifiers work similar to pointers
2059 to other qualified types. For example, a value of type @code{int (*)[5]}
2060 can be used to initialize a variable of type @code{const int (*)[5]}.
2061 These types are incompatible in ISO C because the @code{const} qualifier
2062 is formally attached to the element type of the array and not the
2067 transpose (int N, int M, double out[M][N], const double in[N][M]);
2071 transpose(3, 2, y, x);
2075 @section Non-Constant Initializers
2076 @cindex initializers, non-constant
2077 @cindex non-constant initializers
2079 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
2080 automatic variable are not required to be constant expressions in GNU C@.
2081 Here is an example of an initializer with run-time varying elements:
2084 foo (float f, float g)
2086 float beat_freqs[2] = @{ f-g, f+g @};
2091 @node Compound Literals
2092 @section Compound Literals
2093 @cindex constructor expressions
2094 @cindex initializations in expressions
2095 @cindex structures, constructor expression
2096 @cindex expressions, constructor
2097 @cindex compound literals
2098 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
2100 A compound literal looks like a cast of a brace-enclosed aggregate
2101 initializer list. Its value is an object of the type specified in
2102 the cast, containing the elements specified in the initializer.
2103 Unlike the result of a cast, a compound literal is an lvalue. ISO
2104 C99 and later support compound literals. As an extension, GCC
2105 supports compound literals also in C90 mode and in C++, although
2106 as explained below, the C++ semantics are somewhat different.
2108 Usually, the specified type of a compound literal is a structure. Assume
2109 that @code{struct foo} and @code{structure} are declared as shown:
2112 struct foo @{int a; char b[2];@} structure;
2116 Here is an example of constructing a @code{struct foo} with a compound literal:
2119 structure = ((struct foo) @{x + y, 'a', 0@});
2123 This is equivalent to writing the following:
2127 struct foo temp = @{x + y, 'a', 0@};
2132 You can also construct an array, though this is dangerous in C++, as
2133 explained below. If all the elements of the compound literal are
2134 (made up of) simple constant expressions suitable for use in
2135 initializers of objects of static storage duration, then the compound
2136 literal can be coerced to a pointer to its first element and used in
2137 such an initializer, as shown here:
2140 char **foo = (char *[]) @{ "x", "y", "z" @};
2143 Compound literals for scalar types and union types are also allowed. In
2144 the following example the variable @code{i} is initialized to the value
2145 @code{2}, the result of incrementing the unnamed object created by
2146 the compound literal.
2149 int i = ++(int) @{ 1 @};
2152 As a GNU extension, GCC allows initialization of objects with static storage
2153 duration by compound literals (which is not possible in ISO C99 because
2154 the initializer is not a constant).
2155 It is handled as if the object were initialized only with the brace-enclosed
2156 list if the types of the compound literal and the object match.
2157 The elements of the compound literal must be constant.
2158 If the object being initialized has array type of unknown size, the size is
2159 determined by the size of the compound literal.
2162 static struct foo x = (struct foo) @{1, 'a', 'b'@};
2163 static int y[] = (int []) @{1, 2, 3@};
2164 static int z[] = (int [3]) @{1@};
2168 The above lines are equivalent to the following:
2170 static struct foo x = @{1, 'a', 'b'@};
2171 static int y[] = @{1, 2, 3@};
2172 static int z[] = @{1, 0, 0@};
2175 In C, a compound literal designates an unnamed object with static or
2176 automatic storage duration. In C++, a compound literal designates a
2177 temporary object that only lives until the end of its full-expression.
2178 As a result, well-defined C code that takes the address of a subobject
2179 of a compound literal can be undefined in C++, so G++ rejects
2180 the conversion of a temporary array to a pointer. For instance, if
2181 the array compound literal example above appeared inside a function,
2182 any subsequent use of @code{foo} in C++ would have undefined behavior
2183 because the lifetime of the array ends after the declaration of @code{foo}.
2185 As an optimization, G++ sometimes gives array compound literals longer
2186 lifetimes: when the array either appears outside a function or has
2187 a @code{const}-qualified type. If @code{foo} and its initializer had
2188 elements of type @code{char *const} rather than @code{char *}, or if
2189 @code{foo} were a global variable, the array would have static storage
2190 duration. But it is probably safest just to avoid the use of array
2191 compound literals in C++ code.
2193 @node Designated Inits
2194 @section Designated Initializers
2195 @cindex initializers with labeled elements
2196 @cindex labeled elements in initializers
2197 @cindex case labels in initializers
2198 @cindex designated initializers
2200 Standard C90 requires the elements of an initializer to appear in a fixed
2201 order, the same as the order of the elements in the array or structure
2204 In ISO C99 you can give the elements in any order, specifying the array
2205 indices or structure field names they apply to, and GNU C allows this as
2206 an extension in C90 mode as well. This extension is not
2207 implemented in GNU C++.
2209 To specify an array index, write
2210 @samp{[@var{index}] =} before the element value. For example,
2213 int a[6] = @{ [4] = 29, [2] = 15 @};
2220 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
2224 The index values must be constant expressions, even if the array being
2225 initialized is automatic.
2227 An alternative syntax for this that has been obsolete since GCC 2.5 but
2228 GCC still accepts is to write @samp{[@var{index}]} before the element
2229 value, with no @samp{=}.
2231 To initialize a range of elements to the same value, write
2232 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2233 extension. For example,
2236 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2240 If the value in it has side effects, the side effects happen only once,
2241 not for each initialized field by the range initializer.
2244 Note that the length of the array is the highest value specified
2247 In a structure initializer, specify the name of a field to initialize
2248 with @samp{.@var{fieldname} =} before the element value. For example,
2249 given the following structure,
2252 struct point @{ int x, y; @};
2256 the following initialization
2259 struct point p = @{ .y = yvalue, .x = xvalue @};
2266 struct point p = @{ xvalue, yvalue @};
2269 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2270 @samp{@var{fieldname}:}, as shown here:
2273 struct point p = @{ y: yvalue, x: xvalue @};
2276 Omitted fields are implicitly initialized the same as for objects
2277 that have static storage duration.
2280 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2281 @dfn{designator}. You can also use a designator (or the obsolete colon
2282 syntax) when initializing a union, to specify which element of the union
2283 should be used. For example,
2286 union foo @{ int i; double d; @};
2288 union foo f = @{ .d = 4 @};
2292 converts 4 to a @code{double} to store it in the union using
2293 the second element. By contrast, casting 4 to type @code{union foo}
2294 stores it into the union as the integer @code{i}, since it is
2295 an integer. @xref{Cast to Union}.
2297 You can combine this technique of naming elements with ordinary C
2298 initialization of successive elements. Each initializer element that
2299 does not have a designator applies to the next consecutive element of the
2300 array or structure. For example,
2303 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2310 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2313 Labeling the elements of an array initializer is especially useful
2314 when the indices are characters or belong to an @code{enum} type.
2319 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2320 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2323 @cindex designator lists
2324 You can also write a series of @samp{.@var{fieldname}} and
2325 @samp{[@var{index}]} designators before an @samp{=} to specify a
2326 nested subobject to initialize; the list is taken relative to the
2327 subobject corresponding to the closest surrounding brace pair. For
2328 example, with the @samp{struct point} declaration above:
2331 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2334 If the same field is initialized multiple times, or overlapping
2335 fields of a union are initialized, the value from the last
2336 initialization is used. When a field of a union is itself a structure,
2337 the entire structure from the last field initialized is used. If any previous
2338 initializer has side effect, it is unspecified whether the side effect
2339 happens or not. Currently, GCC discards the side-effecting
2340 initializer expressions and issues a warning.
2343 @section Case Ranges
2345 @cindex ranges in case statements
2347 You can specify a range of consecutive values in a single @code{case} label,
2351 case @var{low} ... @var{high}:
2355 This has the same effect as the proper number of individual @code{case}
2356 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2358 This feature is especially useful for ranges of ASCII character codes:
2364 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2365 it may be parsed wrong when you use it with integer values. For example,
2380 @section Cast to a Union Type
2381 @cindex cast to a union
2382 @cindex union, casting to a
2384 A cast to a union type is a C extension not available in C++. It looks
2385 just like ordinary casts with the constraint that the type specified is
2386 a union type. You can specify the type either with the @code{union}
2387 keyword or with a @code{typedef} name that refers to a union. The result
2388 of a cast to a union is a temporary rvalue of the union type with a member
2389 whose type matches that of the operand initialized to the value of
2390 the operand. The effect of a cast to a union is similar to a compound
2391 literal except that it yields an rvalue like standard casts do.
2392 @xref{Compound Literals}.
2394 Expressions that may be cast to the union type are those whose type matches
2395 at least one of the members of the union. Thus, given the following union
2399 union foo @{ int i; double d; @};
2406 both @code{x} and @code{y} can be cast to type @code{union foo} and
2407 the following assignments
2412 are shorthand equivalents of these
2414 z = (union foo) @{ .i = x @};
2415 z = (union foo) @{ .d = y @};
2418 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
2419 has no member of type @code{float}.
2421 Using the cast as the right-hand side of an assignment to a variable of
2422 union type is equivalent to storing in a member of the union with
2428 u = (union foo) x @equiv{} u.i = x
2429 u = (union foo) y @equiv{} u.d = y
2432 You can also use the union cast as a function argument:
2435 void hack (union foo);
2437 hack ((union foo) x);
2440 @node Mixed Labels and Declarations
2441 @section Mixed Declarations, Labels and Code
2442 @cindex mixed declarations and code
2443 @cindex declarations, mixed with code
2444 @cindex code, mixed with declarations
2446 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2447 within compound statements. ISO C2X allows labels to be
2448 placed before declarations and at the end of a compound statement.
2449 As an extension, GNU C also allows all this in C90 mode. For example,
2459 Each identifier is visible from where it is declared until the end of
2460 the enclosing block.
2462 @node Function Attributes
2463 @section Declaring Attributes of Functions
2464 @cindex function attributes
2465 @cindex declaring attributes of functions
2466 @cindex @code{volatile} applied to function
2467 @cindex @code{const} applied to function
2469 In GNU C and C++, you can use function attributes to specify certain
2470 function properties that may help the compiler optimize calls or
2471 check code more carefully for correctness. For example, you
2472 can use attributes to specify that a function never returns
2473 (@code{noreturn}), returns a value depending only on the values of
2474 its arguments (@code{const}), or has @code{printf}-style arguments
2477 You can also use attributes to control memory placement, code
2478 generation options or call/return conventions within the function
2479 being annotated. Many of these attributes are target-specific. For
2480 example, many targets support attributes for defining interrupt
2481 handler functions, which typically must follow special register usage
2482 and return conventions. Such attributes are described in the subsection
2483 for each target. However, a considerable number of attributes are
2484 supported by most, if not all targets. Those are described in
2485 the @ref{Common Function Attributes} section.
2487 Function attributes are introduced by the @code{__attribute__} keyword
2488 in the declaration of a function, followed by an attribute specification
2489 enclosed in double parentheses. You can specify multiple attributes in
2490 a declaration by separating them by commas within the double parentheses
2491 or by immediately following one attribute specification with another.
2492 @xref{Attribute Syntax}, for the exact rules on attribute syntax and
2493 placement. Compatible attribute specifications on distinct declarations
2494 of the same function are merged. An attribute specification that is not
2495 compatible with attributes already applied to a declaration of the same
2496 function is ignored with a warning.
2498 Some function attributes take one or more arguments that refer to
2499 the function's parameters by their positions within the function parameter
2500 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2501 Unless specified otherwise, positional arguments that specify properties
2502 of parameters with pointer types can also specify the same properties of
2503 the implicit C++ @code{this} argument in non-static member functions, and
2504 of parameters of reference to a pointer type. For ordinary functions,
2505 position one refers to the first parameter on the list. In C++ non-static
2506 member functions, position one refers to the implicit @code{this} pointer.
2507 The same restrictions and effects apply to function attributes used with
2508 ordinary functions or C++ member functions.
2510 GCC also supports attributes on
2511 variable declarations (@pxref{Variable Attributes}),
2512 labels (@pxref{Label Attributes}),
2513 enumerators (@pxref{Enumerator Attributes}),
2514 statements (@pxref{Statement Attributes}),
2515 types (@pxref{Type Attributes}),
2516 and on field declarations (for @code{tainted_args}).
2518 There is some overlap between the purposes of attributes and pragmas
2519 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2520 found convenient to use @code{__attribute__} to achieve a natural
2521 attachment of attributes to their corresponding declarations, whereas
2522 @code{#pragma} is of use for compatibility with other compilers
2523 or constructs that do not naturally form part of the grammar.
2525 In addition to the attributes documented here,
2526 GCC plugins may provide their own attributes.
2529 * Common Function Attributes::
2530 * AArch64 Function Attributes::
2531 * AMD GCN Function Attributes::
2532 * ARC Function Attributes::
2533 * ARM Function Attributes::
2534 * AVR Function Attributes::
2535 * Blackfin Function Attributes::
2536 * BPF Function Attributes::
2537 * CR16 Function Attributes::
2538 * C-SKY Function Attributes::
2539 * Epiphany Function Attributes::
2540 * H8/300 Function Attributes::
2541 * IA-64 Function Attributes::
2542 * M32C Function Attributes::
2543 * M32R/D Function Attributes::
2544 * m68k Function Attributes::
2545 * MCORE Function Attributes::
2546 * MeP Function Attributes::
2547 * MicroBlaze Function Attributes::
2548 * Microsoft Windows Function Attributes::
2549 * MIPS Function Attributes::
2550 * MSP430 Function Attributes::
2551 * NDS32 Function Attributes::
2552 * Nios II Function Attributes::
2553 * Nvidia PTX Function Attributes::
2554 * PowerPC Function Attributes::
2555 * RISC-V Function Attributes::
2556 * RL78 Function Attributes::
2557 * RX Function Attributes::
2558 * S/390 Function Attributes::
2559 * SH Function Attributes::
2560 * Symbian OS Function Attributes::
2561 * V850 Function Attributes::
2562 * Visium Function Attributes::
2563 * x86 Function Attributes::
2564 * Xstormy16 Function Attributes::
2567 @node Common Function Attributes
2568 @subsection Common Function Attributes
2570 The following attributes are supported on most targets.
2573 @c Keep this table alphabetized by attribute name. Treat _ as space.
2575 @item access (@var{access-mode}, @var{ref-index})
2576 @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
2578 The @code{access} attribute enables the detection of invalid or unsafe
2579 accesses by functions to which they apply or their callers, as well as
2580 write-only accesses to objects that are never read from. Such accesses
2581 may be diagnosed by warnings such as @option{-Wstringop-overflow},
2582 @option{-Wuninitialized}, @option{-Wunused}, and others.
2584 The @code{access} attribute specifies that a function to whose by-reference
2585 arguments the attribute applies accesses the referenced object according to
2586 @var{access-mode}. The @var{access-mode} argument is required and must be
2587 one of four names: @code{read_only}, @code{read_write}, @code{write_only},
2588 or @code{none}. The remaining two are positional arguments.
2590 The required @var{ref-index} positional argument denotes a function
2591 argument of pointer (or in C++, reference) type that is subject to
2592 the access. The same pointer argument can be referenced by at most one
2593 distinct @code{access} attribute.
2595 The optional @var{size-index} positional argument denotes a function
2596 argument of integer type that specifies the maximum size of the access.
2597 The size is the number of elements of the type referenced by @var{ref-index},
2598 or the number of bytes when the pointer type is @code{void*}. When no
2599 @var{size-index} argument is specified, the pointer argument must be either
2600 null or point to a space that is suitably aligned and large for at least one
2601 object of the referenced type (this implies that a past-the-end pointer is
2602 not a valid argument). The actual size of the access may be less but it
2605 The @code{read_only} access mode specifies that the pointer to which it
2606 applies is used to read the referenced object but not write to it. Unless
2607 the argument specifying the size of the access denoted by @var{size-index}
2608 is zero, the referenced object must be initialized. The mode implies
2609 a stronger guarantee than the @code{const} qualifier which, when cast away
2610 from a pointer, does not prevent the pointed-to object from being modified.
2611 Examples of the use of the @code{read_only} access mode is the argument to
2612 the @code{puts} function, or the second and third arguments to
2613 the @code{memcpy} function.
2616 __attribute__ ((access (read_only, 1))) int puts (const char*);
2617 __attribute__ ((access (read_only, 2, 3))) void* memcpy (void*, const void*, size_t);
2620 The @code{read_write} access mode applies to arguments of pointer types
2621 without the @code{const} qualifier. It specifies that the pointer to which
2622 it applies is used to both read and write the referenced object. Unless
2623 the argument specifying the size of the access denoted by @var{size-index}
2624 is zero, the object referenced by the pointer must be initialized. An example
2625 of the use of the @code{read_write} access mode is the first argument to
2626 the @code{strcat} function.
2629 __attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*);
2632 The @code{write_only} access mode applies to arguments of pointer types
2633 without the @code{const} qualifier. It specifies that the pointer to which
2634 it applies is used to write to the referenced object but not read from it.
2635 The object referenced by the pointer need not be initialized. An example
2636 of the use of the @code{write_only} access mode is the first argument to
2637 the @code{strcpy} function, or the first two arguments to the @code{fgets}
2641 __attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*);
2642 __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*);
2645 The access mode @code{none} specifies that the pointer to which it applies
2646 is not used to access the referenced object at all. Unless the pointer is
2647 null the pointed-to object must exist and have at least the size as denoted
2648 by the @var{size-index} argument. When the optional @var{size-index}
2649 argument is omitted for an argument of @code{void*} type the actual pointer
2650 agument is ignored. The referenced object need not be initialized.
2651 The mode is intended to be used as a means to help validate the expected
2652 object size, for example in functions that call @code{__builtin_object_size}.
2653 @xref{Object Size Checking}.
2655 Note that the @code{access} attribute merely specifies how an object
2656 referenced by the pointer argument can be accessed; it does not imply that
2657 an access @strong{will} happen. Also, the @code{access} attribute does not
2658 imply the attribute @code{nonnull}; it may be appropriate to add both attributes
2659 at the declaration of a function that unconditionally manipulates a buffer via
2660 a pointer argument. See the @code{nonnull} attribute for more information and
2663 @item alias ("@var{target}")
2664 @cindex @code{alias} function attribute
2665 The @code{alias} attribute causes the declaration to be emitted as an alias
2666 for another symbol, which must have been previously declared with the same
2667 type, and for variables, also the same size and alignment. Declaring an alias
2668 with a different type than the target is undefined and may be diagnosed. As
2669 an example, the following declarations:
2672 void __f () @{ /* @r{Do something.} */; @}
2673 void f () __attribute__ ((weak, alias ("__f")));
2677 define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
2678 for the target must be used. It is an error if @samp{__f} is not defined in
2679 the same translation unit.
2681 This attribute requires assembler and object file support,
2682 and may not be available on all targets.
2685 @itemx aligned (@var{alignment})
2686 @cindex @code{aligned} function attribute
2687 The @code{aligned} attribute specifies a minimum alignment for
2688 the first instruction of the function, measured in bytes. When specified,
2689 @var{alignment} must be an integer constant power of 2. Specifying no
2690 @var{alignment} argument implies the ideal alignment for the target.
2691 The @code{__alignof__} operator can be used to determine what that is
2692 (@pxref{Alignment}). The attribute has no effect when a definition for
2693 the function is not provided in the same translation unit.
2695 The attribute cannot be used to decrease the alignment of a function
2696 previously declared with a more restrictive alignment; only to increase
2697 it. Attempts to do otherwise are diagnosed. Some targets specify
2698 a minimum default alignment for functions that is greater than 1. On
2699 such targets, specifying a less restrictive alignment is silently ignored.
2700 Using the attribute overrides the effect of the @option{-falign-functions}
2701 (@pxref{Optimize Options}) option for this function.
2703 Note that the effectiveness of @code{aligned} attributes may be
2704 limited by inherent limitations in the system linker
2705 and/or object file format. On some systems, the
2706 linker is only able to arrange for functions to be aligned up to a
2707 certain maximum alignment. (For some linkers, the maximum supported
2708 alignment may be very very small.) See your linker documentation for
2709 further information.
2711 The @code{aligned} attribute can also be used for variables and fields
2712 (@pxref{Variable Attributes}.)
2714 @item alloc_align (@var{position})
2715 @cindex @code{alloc_align} function attribute
2716 The @code{alloc_align} attribute may be applied to a function that
2717 returns a pointer and takes at least one argument of an integer or
2719 It indicates that the returned pointer is aligned on a boundary given
2720 by the function argument at @var{position}. Meaningful alignments are
2721 powers of 2 greater than one. GCC uses this information to improve
2722 pointer alignment analysis.
2724 The function parameter denoting the allocated alignment is specified by
2725 one constant integer argument whose number is the argument of the attribute.
2726 Argument numbering starts at one.
2731 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2735 declares that @code{my_memalign} returns memory with minimum alignment
2736 given by parameter 1.
2738 @item alloc_size (@var{position})
2739 @itemx alloc_size (@var{position-1}, @var{position-2})
2740 @cindex @code{alloc_size} function attribute
2741 The @code{alloc_size} attribute may be applied to a function that
2742 returns a pointer and takes at least one argument of an integer or
2744 It indicates that the returned pointer points to memory whose size is
2745 given by the function argument at @var{position-1}, or by the product
2746 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2747 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2748 information to improve the results of @code{__builtin_object_size}.
2750 The function parameter(s) denoting the allocated size are specified by
2751 one or two integer arguments supplied to the attribute. The allocated size
2752 is either the value of the single function argument specified or the product
2753 of the two function arguments specified. Argument numbering starts at
2754 one for ordinary functions, and at two for C++ non-static member functions.
2759 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2760 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2764 declares that @code{my_calloc} returns memory of the size given by
2765 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2766 of the size given by parameter 2.
2769 @cindex @code{always_inline} function attribute
2770 Generally, functions are not inlined unless optimization is specified.
2771 For functions declared inline, this attribute inlines the function
2772 independent of any restrictions that otherwise apply to inlining.
2773 Failure to inline such a function is diagnosed as an error.
2774 Note that if such a function is called indirectly the compiler may
2775 or may not inline it depending on optimization level and a failure
2776 to inline an indirect call may or may not be diagnosed.
2779 @cindex @code{artificial} function attribute
2780 This attribute is useful for small inline wrappers that if possible
2781 should appear during debugging as a unit. Depending on the debug
2782 info format it either means marking the function as artificial
2783 or using the caller location for all instructions within the inlined
2786 @item assume_aligned (@var{alignment})
2787 @itemx assume_aligned (@var{alignment}, @var{offset})
2788 @cindex @code{assume_aligned} function attribute
2789 The @code{assume_aligned} attribute may be applied to a function that
2790 returns a pointer. It indicates that the returned pointer is aligned
2791 on a boundary given by @var{alignment}. If the attribute has two
2792 arguments, the second argument is misalignment @var{offset}. Meaningful
2793 values of @var{alignment} are powers of 2 greater than one. Meaningful
2794 values of @var{offset} are greater than zero and less than @var{alignment}.
2799 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2800 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2804 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2805 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2809 @cindex @code{cold} function attribute
2810 The @code{cold} attribute on functions is used to inform the compiler that
2811 the function is unlikely to be executed. The function is optimized for
2812 size rather than speed and on many targets it is placed into a special
2813 subsection of the text section so all cold functions appear close together,
2814 improving code locality of non-cold parts of program. The paths leading
2815 to calls of cold functions within code are marked as unlikely by the branch
2816 prediction mechanism. It is thus useful to mark functions used to handle
2817 unlikely conditions, such as @code{perror}, as cold to improve optimization
2818 of hot functions that do call marked functions in rare occasions.
2820 When profile feedback is available, via @option{-fprofile-use}, cold functions
2821 are automatically detected and this attribute is ignored.
2824 @cindex @code{const} function attribute
2825 @cindex functions that have no side effects
2826 Calls to functions whose return value is not affected by changes to
2827 the observable state of the program and that have no observable effects
2828 on such state other than to return a value may lend themselves to
2829 optimizations such as common subexpression elimination. Declaring such
2830 functions with the @code{const} attribute allows GCC to avoid emitting
2831 some calls in repeated invocations of the function with the same argument
2837 int square (int) __attribute__ ((const));
2841 tells GCC that subsequent calls to function @code{square} with the same
2842 argument value can be replaced by the result of the first call regardless
2843 of the statements in between.
2845 The @code{const} attribute prohibits a function from reading objects
2846 that affect its return value between successive invocations. However,
2847 functions declared with the attribute can safely read objects that do
2848 not change their return value, such as non-volatile constants.
2850 The @code{const} attribute imposes greater restrictions on a function's
2851 definition than the similar @code{pure} attribute. Declaring the same
2852 function with both the @code{const} and the @code{pure} attribute is
2853 diagnosed. Because a const function cannot have any observable side
2854 effects it does not make sense for it to return @code{void}. Declaring
2855 such a function is diagnosed.
2857 @cindex pointer arguments
2858 Note that a function that has pointer arguments and examines the data
2859 pointed to must @emph{not} be declared @code{const} if the pointed-to
2860 data might change between successive invocations of the function. In
2861 general, since a function cannot distinguish data that might change
2862 from data that cannot, const functions should never take pointer or,
2863 in C++, reference arguments. Likewise, a function that calls a non-const
2864 function usually must not be const itself.
2868 @itemx constructor (@var{priority})
2869 @itemx destructor (@var{priority})
2870 @cindex @code{constructor} function attribute
2871 @cindex @code{destructor} function attribute
2872 The @code{constructor} attribute causes the function to be called
2873 automatically before execution enters @code{main ()}. Similarly, the
2874 @code{destructor} attribute causes the function to be called
2875 automatically after @code{main ()} completes or @code{exit ()} is
2876 called. Functions with these attributes are useful for
2877 initializing data that is used implicitly during the execution of
2880 On some targets the attributes also accept an integer argument to
2881 specify a priority to control the order in which constructor and
2882 destructor functions are run. A constructor
2883 with a smaller priority number runs before a constructor with a larger
2884 priority number; the opposite relationship holds for destructors. Note
2885 that priorities 0-100 are reserved. So, if you have a constructor that
2886 allocates a resource and a destructor that deallocates the same
2887 resource, both functions typically have the same priority. The
2888 priorities for constructor and destructor functions are the same as
2889 those specified for namespace-scope C++ objects (@pxref{C++ Attributes}).
2890 However, at present, the order in which constructors for C++ objects
2891 with static storage duration and functions decorated with attribute
2892 @code{constructor} are invoked is unspecified. In mixed declarations,
2893 attribute @code{init_priority} can be used to impose a specific ordering.
2895 Using the argument forms of the @code{constructor} and @code{destructor}
2896 attributes on targets where the feature is not supported is rejected with
2900 @itemx copy (@var{function})
2901 @cindex @code{copy} function attribute
2902 The @code{copy} attribute applies the set of attributes with which
2903 @var{function} has been declared to the declaration of the function
2904 to which the attribute is applied. The attribute is designed for
2905 libraries that define aliases or function resolvers that are expected
2906 to specify the same set of attributes as their targets. The @code{copy}
2907 attribute can be used with functions, variables, or types. However,
2908 the kind of symbol to which the attribute is applied (either function
2909 or variable) must match the kind of symbol to which the argument refers.
2910 The @code{copy} attribute copies only syntactic and semantic attributes
2911 but not attributes that affect a symbol's linkage or visibility such as
2912 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2913 and @code{target_clones} attribute are also not copied.
2914 @xref{Common Type Attributes}.
2915 @xref{Common Variable Attributes}.
2917 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2918 and @code{copy} attributes to define an alias named @var{alloc} for function
2919 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2920 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2921 the same type as the target function. As a result of the @code{copy}
2922 attribute the alias also shares the same attributes as the target.
2925 #define StrongAlias(TargetFunc, AliasDecl) \
2926 extern __typeof__ (TargetFunc) AliasDecl \
2927 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2929 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2930 void* allocate (size_t);
2931 StrongAlias (allocate, alloc);
2935 @itemx deprecated (@var{msg})
2936 @cindex @code{deprecated} function attribute
2937 The @code{deprecated} attribute results in a warning if the function
2938 is used anywhere in the source file. This is useful when identifying
2939 functions that are expected to be removed in a future version of a
2940 program. The warning also includes the location of the declaration
2941 of the deprecated function, to enable users to easily find further
2942 information about why the function is deprecated, or what they should
2943 do instead. Note that the warnings only occurs for uses:
2946 int old_fn () __attribute__ ((deprecated));
2948 int (*fn_ptr)() = old_fn;
2952 results in a warning on line 3 but not line 2. The optional @var{msg}
2953 argument, which must be a string, is printed in the warning if
2956 The @code{deprecated} attribute can also be used for variables and
2957 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2959 The message attached to the attribute is affected by the setting of
2960 the @option{-fmessage-length} option.
2963 @itemx unavailable (@var{msg})
2964 @cindex @code{unavailable} function attribute
2965 The @code{unavailable} attribute results in an error if the function
2966 is used anywhere in the source file. This is useful when identifying
2967 functions that have been removed from a particular variation of an
2968 interface. Other than emitting an error rather than a warning, the
2969 @code{unavailable} attribute behaves in the same manner as
2972 The @code{unavailable} attribute can also be used for variables and
2973 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2975 @item error ("@var{message}")
2976 @itemx warning ("@var{message}")
2977 @cindex @code{error} function attribute
2978 @cindex @code{warning} function attribute
2979 If the @code{error} or @code{warning} attribute
2980 is used on a function declaration and a call to such a function
2981 is not eliminated through dead code elimination or other optimizations,
2982 an error or warning (respectively) that includes @var{message} is diagnosed.
2984 for compile-time checking, especially together with @code{__builtin_constant_p}
2985 and inline functions where checking the inline function arguments is not
2986 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2988 While it is possible to leave the function undefined and thus invoke
2989 a link failure (to define the function with
2990 a message in @code{.gnu.warning*} section),
2991 when using these attributes the problem is diagnosed
2992 earlier and with exact location of the call even in presence of inline
2993 functions or when not emitting debugging information.
2995 @item externally_visible
2996 @cindex @code{externally_visible} function attribute
2997 This attribute, attached to a global variable or function, nullifies
2998 the effect of the @option{-fwhole-program} command-line option, so the
2999 object remains visible outside the current compilation unit.
3001 If @option{-fwhole-program} is used together with @option{-flto} and
3002 @command{gold} is used as the linker plugin,
3003 @code{externally_visible} attributes are automatically added to functions
3004 (not variable yet due to a current @command{gold} issue)
3005 that are accessed outside of LTO objects according to resolution file
3006 produced by @command{gold}.
3007 For other linkers that cannot generate resolution file,
3008 explicit @code{externally_visible} attributes are still necessary.
3011 @cindex @code{flatten} function attribute
3012 Generally, inlining into a function is limited. For a function marked with
3013 this attribute, every call inside this function is inlined, if possible.
3014 Functions declared with attribute @code{noinline} and similar are not
3015 inlined. Whether the function itself is considered for inlining depends
3016 on its size and the current inlining parameters.
3018 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
3019 @cindex @code{format} function attribute
3020 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
3022 The @code{format} attribute specifies that a function takes @code{printf},
3023 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
3024 should be type-checked against a format string. For example, the
3029 my_printf (void *my_object, const char *my_format, ...)
3030 __attribute__ ((format (printf, 2, 3)));
3034 causes the compiler to check the arguments in calls to @code{my_printf}
3035 for consistency with the @code{printf} style format string argument
3038 The parameter @var{archetype} determines how the format string is
3039 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
3040 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
3041 @code{strfmon}. (You can also use @code{__printf__},
3042 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
3043 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
3044 @code{ms_strftime} are also present.
3045 @var{archetype} values such as @code{printf} refer to the formats accepted
3046 by the system's C runtime library,
3047 while values prefixed with @samp{gnu_} always refer
3048 to the formats accepted by the GNU C Library. On Microsoft Windows
3049 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
3050 @file{msvcrt.dll} library.
3051 The parameter @var{string-index}
3052 specifies which argument is the format string argument (starting
3053 from 1), while @var{first-to-check} is the number of the first
3054 argument to check against the format string. For functions
3055 where the arguments are not available to be checked (such as
3056 @code{vprintf}), specify the third parameter as zero. In this case the
3057 compiler only checks the format string for consistency. For
3058 @code{strftime} formats, the third parameter is required to be zero.
3059 Since non-static C++ methods have an implicit @code{this} argument, the
3060 arguments of such methods should be counted from two, not one, when
3061 giving values for @var{string-index} and @var{first-to-check}.
3063 In the example above, the format string (@code{my_format}) is the second
3064 argument of the function @code{my_print}, and the arguments to check
3065 start with the third argument, so the correct parameters for the format
3066 attribute are 2 and 3.
3068 @opindex ffreestanding
3069 @opindex fno-builtin
3070 The @code{format} attribute allows you to identify your own functions
3071 that take format strings as arguments, so that GCC can check the
3072 calls to these functions for errors. The compiler always (unless
3073 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
3074 for the standard library functions @code{printf}, @code{fprintf},
3075 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
3076 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
3077 warnings are requested (using @option{-Wformat}), so there is no need to
3078 modify the header file @file{stdio.h}. In C99 mode, the functions
3079 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
3080 @code{vsscanf} are also checked. Except in strictly conforming C
3081 standard modes, the X/Open function @code{strfmon} is also checked as
3082 are @code{printf_unlocked} and @code{fprintf_unlocked}.
3083 @xref{C Dialect Options,,Options Controlling C Dialect}.
3085 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
3086 recognized in the same context. Declarations including these format attributes
3087 are parsed for correct syntax, however the result of checking of such format
3088 strings is not yet defined, and is not carried out by this version of the
3091 The target may also provide additional types of format checks.
3092 @xref{Target Format Checks,,Format Checks Specific to Particular
3095 @item format_arg (@var{string-index})
3096 @cindex @code{format_arg} function attribute
3097 @opindex Wformat-nonliteral
3098 The @code{format_arg} attribute specifies that a function takes one or
3099 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
3100 @code{strfmon} style function and modifies it (for example, to translate
3101 it into another language), so the result can be passed to a
3102 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
3103 function (with the remaining arguments to the format function the same
3104 as they would have been for the unmodified string). Multiple
3105 @code{format_arg} attributes may be applied to the same function, each
3106 designating a distinct parameter as a format string. For example, the
3111 my_dgettext (char *my_domain, const char *my_format)
3112 __attribute__ ((format_arg (2)));
3116 causes the compiler to check the arguments in calls to a @code{printf},
3117 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
3118 format string argument is a call to the @code{my_dgettext} function, for
3119 consistency with the format string argument @code{my_format}. If the
3120 @code{format_arg} attribute had not been specified, all the compiler
3121 could tell in such calls to format functions would be that the format
3122 string argument is not constant; this would generate a warning when
3123 @option{-Wformat-nonliteral} is used, but the calls could not be checked
3124 without the attribute.
3126 In calls to a function declared with more than one @code{format_arg}
3127 attribute, each with a distinct argument value, the corresponding
3128 actual function arguments are checked against all format strings
3129 designated by the attributes. This capability is designed to support
3130 the GNU @code{ngettext} family of functions.
3132 The parameter @var{string-index} specifies which argument is the format
3133 string argument (starting from one). Since non-static C++ methods have
3134 an implicit @code{this} argument, the arguments of such methods should
3135 be counted from two.
3137 The @code{format_arg} attribute allows you to identify your own
3138 functions that modify format strings, so that GCC can check the
3139 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
3140 type function whose operands are a call to one of your own function.
3141 The compiler always treats @code{gettext}, @code{dgettext}, and
3142 @code{dcgettext} in this manner except when strict ISO C support is
3143 requested by @option{-ansi} or an appropriate @option{-std} option, or
3144 @option{-ffreestanding} or @option{-fno-builtin}
3145 is used. @xref{C Dialect Options,,Options
3146 Controlling C Dialect}.
3148 For Objective-C dialects, the @code{format-arg} attribute may refer to an
3149 @code{NSString} reference for compatibility with the @code{format} attribute
3152 The target may also allow additional types in @code{format-arg} attributes.
3153 @xref{Target Format Checks,,Format Checks Specific to Particular
3157 @cindex @code{gnu_inline} function attribute
3158 This attribute should be used with a function that is also declared
3159 with the @code{inline} keyword. It directs GCC to treat the function
3160 as if it were defined in gnu90 mode even when compiling in C99 or
3163 If the function is declared @code{extern}, then this definition of the
3164 function is used only for inlining. In no case is the function
3165 compiled as a standalone function, not even if you take its address
3166 explicitly. Such an address becomes an external reference, as if you
3167 had only declared the function, and had not defined it. This has
3168 almost the effect of a macro. The way to use this is to put a
3169 function definition in a header file with this attribute, and put
3170 another copy of the function, without @code{extern}, in a library
3171 file. The definition in the header file causes most calls to the
3172 function to be inlined. If any uses of the function remain, they
3173 refer to the single copy in the library. Note that the two
3174 definitions of the functions need not be precisely the same, although
3175 if they do not have the same effect your program may behave oddly.
3177 In C, if the function is neither @code{extern} nor @code{static}, then
3178 the function is compiled as a standalone function, as well as being
3179 inlined where possible.
3181 This is how GCC traditionally handled functions declared
3182 @code{inline}. Since ISO C99 specifies a different semantics for
3183 @code{inline}, this function attribute is provided as a transition
3184 measure and as a useful feature in its own right. This attribute is
3185 available in GCC 4.1.3 and later. It is available if either of the
3186 preprocessor macros @code{__GNUC_GNU_INLINE__} or
3187 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
3188 Function is As Fast As a Macro}.
3190 In C++, this attribute does not depend on @code{extern} in any way,
3191 but it still requires the @code{inline} keyword to enable its special
3195 @cindex @code{hot} function attribute
3196 The @code{hot} attribute on a function is used to inform the compiler that
3197 the function is a hot spot of the compiled program. The function is
3198 optimized more aggressively and on many targets it is placed into a special
3199 subsection of the text section so all hot functions appear close together,
3202 When profile feedback is available, via @option{-fprofile-use}, hot functions
3203 are automatically detected and this attribute is ignored.
3205 @item ifunc ("@var{resolver}")
3206 @cindex @code{ifunc} function attribute
3207 @cindex indirect functions
3208 @cindex functions that are dynamically resolved
3209 The @code{ifunc} attribute is used to mark a function as an indirect
3210 function using the STT_GNU_IFUNC symbol type extension to the ELF
3211 standard. This allows the resolution of the symbol value to be
3212 determined dynamically at load time, and an optimized version of the
3213 routine to be selected for the particular processor or other system
3214 characteristics determined then. To use this attribute, first define
3215 the implementation functions available, and a resolver function that
3216 returns a pointer to the selected implementation function. The
3217 implementation functions' declarations must match the API of the
3218 function being implemented. The resolver should be declared to
3219 be a function taking no arguments and returning a pointer to
3220 a function of the same type as the implementation. For example:
3223 void *my_memcpy (void *dst, const void *src, size_t len)
3229 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3231 return my_memcpy; // we will just always select this routine
3236 The exported header file declaring the function the user calls would
3240 extern void *memcpy (void *, const void *, size_t);
3244 allowing the user to call @code{memcpy} as a regular function, unaware of
3245 the actual implementation. Finally, the indirect function needs to be
3246 defined in the same translation unit as the resolver function:
3249 void *memcpy (void *, const void *, size_t)
3250 __attribute__ ((ifunc ("resolve_memcpy")));
3253 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3254 of the resolver function. A C++ resolver for a non-static member function
3255 of class @code{C} should be declared to return a pointer to a non-member
3256 function taking pointer to @code{C} as the first argument, followed by
3257 the same arguments as of the implementation function. G++ checks
3258 the signatures of the two functions and issues
3259 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3260 for the necessary cast from a pointer to the implementation member function
3261 to the type of the corresponding non-member function use
3262 the @option{-Wno-pmf-conversions} option. For example:
3268 int debug_impl (int);
3269 int optimized_impl (int);
3271 typedef int Func (S*, int);
3273 static Func* resolver ();
3276 int interface (int);
3279 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3280 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3282 S::Func* S::resolver ()
3284 int (S::*pimpl) (int)
3285 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3287 // Cast triggers -Wno-pmf-conversions.
3288 return reinterpret_cast<Func*>(pimpl);
3291 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3294 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3295 and GNU C Library version 2.11.1 are required to use this feature.
3298 @itemx interrupt_handler
3299 Many GCC back ends support attributes to indicate that a function is
3300 an interrupt handler, which tells the compiler to generate function
3301 entry and exit sequences that differ from those from regular
3302 functions. The exact syntax and behavior are target-specific;
3303 refer to the following subsections for details.
3306 @cindex @code{leaf} function attribute
3307 Calls to external functions with this attribute must return to the
3308 current compilation unit only by return or by exception handling. In
3309 particular, a leaf function is not allowed to invoke callback functions
3310 passed to it from the current compilation unit, directly call functions
3311 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3312 might still call functions from other compilation units and thus they
3313 are not necessarily leaf in the sense that they contain no function
3316 The attribute is intended for library functions to improve dataflow
3317 analysis. The compiler takes the hint that any data not escaping the
3318 current compilation unit cannot be used or modified by the leaf
3319 function. For example, the @code{sin} function is a leaf function, but
3320 @code{qsort} is not.
3322 Note that leaf functions might indirectly run a signal handler defined
3323 in the current compilation unit that uses static variables. Similarly,
3324 when lazy symbol resolution is in effect, leaf functions might invoke
3325 indirect functions whose resolver function or implementation function is
3326 defined in the current compilation unit and uses static variables. There
3327 is no standard-compliant way to write such a signal handler, resolver
3328 function, or implementation function, and the best that you can do is to
3329 remove the @code{leaf} attribute or mark all such static variables
3330 @code{volatile}. Lastly, for ELF-based systems that support symbol
3331 interposition, care should be taken that functions defined in the
3332 current compilation unit do not unexpectedly interpose other symbols
3333 based on the defined standards mode and defined feature test macros;
3334 otherwise an inadvertent callback would be added.
3336 The attribute has no effect on functions defined within the current
3337 compilation unit. This is to allow easy merging of multiple compilation
3338 units into one, for example, by using the link-time optimization. For
3339 this reason the attribute is not allowed on types to annotate indirect
3343 @item malloc (@var{deallocator})
3344 @item malloc (@var{deallocator}, @var{ptr-index})
3345 @cindex @code{malloc} function attribute
3346 @cindex functions that behave like malloc
3347 Attribute @code{malloc} indicates that a function is @code{malloc}-like,
3348 i.e., that the pointer @var{P} returned by the function cannot alias any
3349 other pointer valid when the function returns, and moreover no
3350 pointers to valid objects occur in any storage addressed by @var{P}. In
3351 addition, the GCC predicts that a function with the attribute returns
3352 non-null in most cases.
3354 Independently, the form of the attribute with one or two arguments
3355 associates @code{deallocator} as a suitable deallocation function for
3356 pointers returned from the @code{malloc}-like function. @var{ptr-index}
3357 denotes the positional argument to which when the pointer is passed in
3358 calls to @code{deallocator} has the effect of deallocating it.
3360 Using the attribute with no arguments is designed to improve optimization
3361 by relying on the aliasing property it implies. Functions like @code{malloc}
3362 and @code{calloc} have this property because they return a pointer to
3363 uninitialized or zeroed-out, newly obtained storage. However, functions
3364 like @code{realloc} do not have this property, as they may return pointers
3365 to storage containing pointers to existing objects. Additionally, since
3366 all such functions are assumed to return null only infrequently, callers
3367 can be optimized based on that assumption.
3369 Associating a function with a @var{deallocator} helps detect calls to
3370 mismatched allocation and deallocation functions and diagnose them under
3371 the control of options such as @option{-Wmismatched-dealloc}. It also
3372 makes it possible to diagnose attempts to deallocate objects that were not
3373 allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate
3374 that an allocation function both satisifies the nonaliasing property and
3375 has a deallocator associated with it, both the plain form of the attribute
3376 and the one with the @var{deallocator} argument must be used. The same
3377 function can be both an allocator and a deallocator. Since inlining one
3378 of the associated functions but not the other could result in apparent
3379 mismatches, this form of attribute @code{malloc} is not accepted on inline
3380 functions. For the same reason, using the attribute prevents both
3381 the allocation and deallocation functions from being expanded inline.
3383 For example, besides stating that the functions return pointers that do
3384 not alias any others, the following declarations make @code{fclose}
3385 a suitable deallocator for pointers returned from all functions except
3386 @code{popen}, and @code{pclose} as the only suitable deallocator for
3387 pointers returned from @code{popen}. The deallocator functions must
3388 be declared before they can be referenced in the attribute.
3394 __attribute__ ((malloc, malloc (fclose, 1)))
3395 FILE* fdopen (int, const char*);
3396 __attribute__ ((malloc, malloc (fclose, 1)))
3397 FILE* fopen (const char*, const char*);
3398 __attribute__ ((malloc, malloc (fclose, 1)))
3399 FILE* fmemopen(void *, size_t, const char *);
3400 __attribute__ ((malloc, malloc (pclose, 1)))
3401 FILE* popen (const char*, const char*);
3402 __attribute__ ((malloc, malloc (fclose, 1)))
3403 FILE* tmpfile (void);
3406 The warnings guarded by @option{-fanalyzer} respect allocation and
3407 deallocation pairs marked with the @code{malloc}. In particular:
3412 The analyzer will emit a @option{-Wanalyzer-mismatching-deallocation}
3413 diagnostic if there is an execution path in which the result of an
3414 allocation call is passed to a different deallocator.
3417 The analyzer will emit a @option{-Wanalyzer-double-free}
3418 diagnostic if there is an execution path in which a value is passed
3419 more than once to a deallocation call.
3422 The analyzer will consider the possibility that an allocation function
3423 could fail and return NULL. It will emit
3424 @option{-Wanalyzer-possible-null-dereference} and
3425 @option{-Wanalyzer-possible-null-argument} diagnostics if there are
3426 execution paths in which an unchecked result of an allocation call is
3427 dereferenced or passed to a function requiring a non-null argument.
3428 If the allocator always returns non-null, use
3429 @code{__attribute__ ((returns_nonnull))} to suppress these warnings.
3432 char *xstrdup (const char *)
3433 __attribute__((malloc (free), returns_nonnull));
3437 The analyzer will emit a @option{-Wanalyzer-use-after-free}
3438 diagnostic if there is an execution path in which the memory passed
3439 by pointer to a deallocation call is used after the deallocation.
3442 The analyzer will emit a @option{-Wanalyzer-malloc-leak} diagnostic if
3443 there is an execution path in which the result of an allocation call
3444 is leaked (without being passed to the deallocation function).
3447 The analyzer will emit a @option{-Wanalyzer-free-of-non-heap} diagnostic
3448 if a deallocation function is used on a global or on-stack variable.
3452 The analyzer assumes that deallocators can gracefully handle the @code{NULL}
3453 pointer. If this is not the case, the deallocator can be marked with
3454 @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit
3455 a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
3456 in which the deallocator is called with NULL.
3459 @cindex @code{no_icf} function attribute
3460 This function attribute prevents a functions from being merged with another
3461 semantically equivalent function.
3463 @item no_instrument_function
3464 @cindex @code{no_instrument_function} function attribute
3465 @opindex finstrument-functions
3468 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3469 given, profiling function calls are
3470 generated at entry and exit of most user-compiled functions.
3471 Functions with this attribute are not so instrumented.
3473 @item no_profile_instrument_function
3474 @cindex @code{no_profile_instrument_function} function attribute
3475 The @code{no_profile_instrument_function} attribute on functions is used
3476 to inform the compiler that it should not process any profile feedback based
3477 optimization code instrumentation.
3480 @cindex @code{no_reorder} function attribute
3481 Do not reorder functions or variables marked @code{no_reorder}
3482 against each other or top level assembler statements the executable.
3483 The actual order in the program will depend on the linker command
3484 line. Static variables marked like this are also not removed.
3485 This has a similar effect
3486 as the @option{-fno-toplevel-reorder} option, but only applies to the
3489 @item no_sanitize ("@var{sanitize_option}")
3490 @cindex @code{no_sanitize} function attribute
3491 The @code{no_sanitize} attribute on functions is used
3492 to inform the compiler that it should not do sanitization of any option
3493 mentioned in @var{sanitize_option}. A list of values acceptable by
3494 the @option{-fsanitize} option can be provided.
3497 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3498 f () @{ /* @r{Do something.} */; @}
3499 void __attribute__ ((no_sanitize ("alignment,object-size")))
3500 g () @{ /* @r{Do something.} */; @}
3503 @item no_sanitize_address
3504 @itemx no_address_safety_analysis
3505 @cindex @code{no_sanitize_address} function attribute
3506 The @code{no_sanitize_address} attribute on functions is used
3507 to inform the compiler that it should not instrument memory accesses
3508 in the function when compiling with the @option{-fsanitize=address} option.
3509 The @code{no_address_safety_analysis} is a deprecated alias of the
3510 @code{no_sanitize_address} attribute, new code should use
3511 @code{no_sanitize_address}.
3513 @item no_sanitize_thread
3514 @cindex @code{no_sanitize_thread} function attribute
3515 The @code{no_sanitize_thread} attribute on functions is used
3516 to inform the compiler that it should not instrument memory accesses
3517 in the function when compiling with the @option{-fsanitize=thread} option.
3519 @item no_sanitize_undefined
3520 @cindex @code{no_sanitize_undefined} function attribute
3521 The @code{no_sanitize_undefined} attribute on functions is used
3522 to inform the compiler that it should not check for undefined behavior
3523 in the function when compiling with the @option{-fsanitize=undefined} option.
3525 @item no_sanitize_coverage
3526 @cindex @code{no_sanitize_coverage} function attribute
3527 The @code{no_sanitize_coverage} attribute on functions is used
3528 to inform the compiler that it should not do coverage-guided
3529 fuzzing code instrumentation (@option{-fsanitize-coverage}).
3531 @item no_split_stack
3532 @cindex @code{no_split_stack} function attribute
3533 @opindex fsplit-stack
3534 If @option{-fsplit-stack} is given, functions have a small
3535 prologue which decides whether to split the stack. Functions with the
3536 @code{no_split_stack} attribute do not have that prologue, and thus
3537 may run with only a small amount of stack space available.
3539 @item no_stack_limit
3540 @cindex @code{no_stack_limit} function attribute
3541 This attribute locally overrides the @option{-fstack-limit-register}
3542 and @option{-fstack-limit-symbol} command-line options; it has the effect
3543 of disabling stack limit checking in the function it applies to.
3546 @cindex @code{noclone} function attribute
3547 This function attribute prevents a function from being considered for
3548 cloning---a mechanism that produces specialized copies of functions
3549 and which is (currently) performed by interprocedural constant
3553 @cindex @code{noinline} function attribute
3554 This function attribute prevents a function from being considered for
3556 @c Don't enumerate the optimizations by name here; we try to be
3557 @c future-compatible with this mechanism.
3558 If the function does not have side effects, there are optimizations
3559 other than inlining that cause function calls to be optimized away,
3560 although the function call is live. To keep such calls from being
3567 (@pxref{Extended Asm}) in the called function, to serve as a special
3571 @cindex @code{noipa} function attribute
3572 Disable interprocedural optimizations between the function with this
3573 attribute and its callers, as if the body of the function is not available
3574 when optimizing callers and the callers are unavailable when optimizing
3575 the body. This attribute implies @code{noinline}, @code{noclone} and
3576 @code{no_icf} attributes. However, this attribute is not equivalent
3577 to a combination of other attributes, because its purpose is to suppress
3578 existing and future optimizations employing interprocedural analysis,
3579 including those that do not have an attribute suitable for disabling
3580 them individually. This attribute is supported mainly for the purpose
3581 of testing the compiler.
3584 @itemx nonnull (@var{arg-index}, @dots{})
3585 @cindex @code{nonnull} function attribute
3586 @cindex functions with non-null pointer arguments
3587 The @code{nonnull} attribute may be applied to a function that takes at
3588 least one argument of a pointer type. It indicates that the referenced
3589 arguments must be non-null pointers. For instance, the declaration:
3593 my_memcpy (void *dest, const void *src, size_t len)
3594 __attribute__((nonnull (1, 2)));
3598 informs the compiler that, in calls to @code{my_memcpy}, arguments
3599 @var{dest} and @var{src} must be non-null.
3601 The attribute has an effect both on functions calls and function definitions.
3605 @item If the compiler determines that a null pointer is
3606 passed in an argument slot marked as non-null, and the
3607 @option{-Wnonnull} option is enabled, a warning is issued.
3608 @xref{Warning Options}.
3609 @item The @option{-fisolate-erroneous-paths-attribute} option can be
3610 specified to have GCC transform calls with null arguments to non-null
3611 functions into traps. @xref{Optimize Options}.
3612 @item The compiler may also perform optimizations based on the
3613 knowledge that certain function arguments cannot be null. These
3614 optimizations can be disabled by the
3615 @option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}.
3618 For function definitions:
3620 @item If the compiler determines that a function parameter that is
3621 marked with nonnull is compared with null, and
3622 @option{-Wnonnull-compare} option is enabled, a warning is issued.
3623 @xref{Warning Options}.
3624 @item The compiler may also perform optimizations based on the
3625 knowledge that @code{nonnul} parameters cannot be null. This can
3626 currently not be disabled other than by removing the nonnull
3630 If no @var{arg-index} is given to the @code{nonnull} attribute,
3631 all pointer arguments are marked as non-null. To illustrate, the
3632 following declaration is equivalent to the previous example:
3636 my_memcpy (void *dest, const void *src, size_t len)
3637 __attribute__((nonnull));
3641 @cindex @code{noplt} function attribute
3642 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3643 Calls to functions marked with this attribute in position-independent code
3648 /* Externally defined function foo. */
3649 int foo () __attribute__ ((noplt));
3652 main (/* @r{@dots{}} */)
3661 The @code{noplt} attribute on function @code{foo}
3662 tells the compiler to assume that
3663 the function @code{foo} is externally defined and that the call to
3664 @code{foo} must avoid the PLT
3665 in position-independent code.
3667 In position-dependent code, a few targets also convert calls to
3668 functions that are marked to not use the PLT to use the GOT instead.
3671 @cindex @code{noreturn} function attribute
3672 @cindex functions that never return
3673 A few standard library functions, such as @code{abort} and @code{exit},
3674 cannot return. GCC knows this automatically. Some programs define
3675 their own functions that never return. You can declare them
3676 @code{noreturn} to tell the compiler this fact. For example,
3680 void fatal () __attribute__ ((noreturn));
3683 fatal (/* @r{@dots{}} */)
3685 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3691 The @code{noreturn} keyword tells the compiler to assume that
3692 @code{fatal} cannot return. It can then optimize without regard to what
3693 would happen if @code{fatal} ever did return. This makes slightly
3694 better code. More importantly, it helps avoid spurious warnings of
3695 uninitialized variables.
3697 The @code{noreturn} keyword does not affect the exceptional path when that
3698 applies: a @code{noreturn}-marked function may still return to the caller
3699 by throwing an exception or calling @code{longjmp}.
3701 In order to preserve backtraces, GCC will never turn calls to
3702 @code{noreturn} functions into tail calls.
3704 Do not assume that registers saved by the calling function are
3705 restored before calling the @code{noreturn} function.
3707 It does not make sense for a @code{noreturn} function to have a return
3708 type other than @code{void}.
3711 @cindex @code{nothrow} function attribute
3712 The @code{nothrow} attribute is used to inform the compiler that a
3713 function cannot throw an exception. For example, most functions in
3714 the standard C library can be guaranteed not to throw an exception
3715 with the notable exceptions of @code{qsort} and @code{bsearch} that
3716 take function pointer arguments.
3718 @item optimize (@var{level}, @dots{})
3719 @item optimize (@var{string}, @dots{})
3720 @cindex @code{optimize} function attribute
3721 The @code{optimize} attribute is used to specify that a function is to
3722 be compiled with different optimization options than specified on the
3723 command line. The optimize attribute arguments of a function behave
3724 behave as if appended to the command-line.
3726 Valid arguments are constant non-negative integers and
3727 strings. Each numeric argument specifies an optimization @var{level}.
3728 Each @var{string} argument consists of one or more comma-separated
3729 substrings. Each substring that begins with the letter @code{O} refers
3730 to an optimization option such as @option{-O0} or @option{-Os}. Other
3731 substrings are taken as suffixes to the @code{-f} prefix jointly
3732 forming the name of an optimization option. @xref{Optimize Options}.
3734 @samp{#pragma GCC optimize} can be used to set optimization options
3735 for more than one function. @xref{Function Specific Option Pragmas},
3736 for details about the pragma.
3738 Providing multiple strings as arguments separated by commas to specify
3739 multiple options is equivalent to separating the option suffixes with
3740 a comma (@samp{,}) within a single string. Spaces are not permitted
3743 Not every optimization option that starts with the @var{-f} prefix
3744 specified by the attribute necessarily has an effect on the function.
3745 The @code{optimize} attribute should be used for debugging purposes only.
3746 It is not suitable in production code.
3748 @item patchable_function_entry
3749 @cindex @code{patchable_function_entry} function attribute
3750 @cindex extra NOP instructions at the function entry point
3751 In case the target's text segment can be made writable at run time by
3752 any means, padding the function entry with a number of NOPs can be
3753 used to provide a universal tool for instrumentation.
3755 The @code{patchable_function_entry} function attribute can be used to
3756 change the number of NOPs to any desired value. The two-value syntax
3757 is the same as for the command-line switch
3758 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3759 the function entry point before the @var{M}th NOP instruction.
3760 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3763 If patchable function entries are enabled globally using the command-line
3764 option @option{-fpatchable-function-entry=N,M}, then you must disable
3765 instrumentation on all functions that are part of the instrumentation
3766 framework with the attribute @code{patchable_function_entry (0)}
3767 to prevent recursion.
3770 @cindex @code{pure} function attribute
3771 @cindex functions that have no side effects
3773 Calls to functions that have no observable effects on the state of
3774 the program other than to return a value may lend themselves to optimizations
3775 such as common subexpression elimination. Declaring such functions with
3776 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3777 invocations of the function with the same argument values.
3779 The @code{pure} attribute prohibits a function from modifying the state
3780 of the program that is observable by means other than inspecting
3781 the function's return value. However, functions declared with the @code{pure}
3782 attribute can safely read any non-volatile objects, and modify the value of
3783 objects in a way that does not affect their return value or the observable
3784 state of the program.
3789 int hash (char *) __attribute__ ((pure));
3793 tells GCC that subsequent calls to the function @code{hash} with the same
3794 string can be replaced by the result of the first call provided the state
3795 of the program observable by @code{hash}, including the contents of the array
3796 itself, does not change in between. Even though @code{hash} takes a non-const
3797 pointer argument it must not modify the array it points to, or any other object
3798 whose value the rest of the program may depend on. However, the caller may
3799 safely change the contents of the array between successive calls to
3800 the function (doing so disables the optimization). The restriction also
3801 applies to member objects referenced by the @code{this} pointer in C++
3802 non-static member functions.
3804 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3805 Interesting non-pure functions are functions with infinite loops or those
3806 depending on volatile memory or other system resource, that may change between
3807 consecutive calls (such as the standard C @code{feof} function in
3808 a multithreading environment).
3810 The @code{pure} attribute imposes similar but looser restrictions on
3811 a function's definition than the @code{const} attribute: @code{pure}
3812 allows the function to read any non-volatile memory, even if it changes
3813 in between successive invocations of the function. Declaring the same
3814 function with both the @code{pure} and the @code{const} attribute is
3815 diagnosed. Because a pure function cannot have any observable side
3816 effects it does not make sense for such a function to return @code{void}.
3817 Declaring such a function is diagnosed.
3819 @item returns_nonnull
3820 @cindex @code{returns_nonnull} function attribute
3821 The @code{returns_nonnull} attribute specifies that the function
3822 return value should be a non-null pointer. For instance, the declaration:
3826 mymalloc (size_t len) __attribute__((returns_nonnull));
3830 lets the compiler optimize callers based on the knowledge
3831 that the return value will never be null.
3834 @cindex @code{returns_twice} function attribute
3835 @cindex functions that return more than once
3836 The @code{returns_twice} attribute tells the compiler that a function may
3837 return more than one time. The compiler ensures that all registers
3838 are dead before calling such a function and emits a warning about
3839 the variables that may be clobbered after the second return from the
3840 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3841 The @code{longjmp}-like counterpart of such function, if any, might need
3842 to be marked with the @code{noreturn} attribute.
3844 @item section ("@var{section-name}")
3845 @cindex @code{section} function attribute
3846 @cindex functions in arbitrary sections
3847 Normally, the compiler places the code it generates in the @code{text} section.
3848 Sometimes, however, you need additional sections, or you need certain
3849 particular functions to appear in special sections. The @code{section}
3850 attribute specifies that a function lives in a particular section.
3851 For example, the declaration:
3854 extern void foobar (void) __attribute__ ((section ("bar")));
3858 puts the function @code{foobar} in the @code{bar} section.
3860 Some file formats do not support arbitrary sections so the @code{section}
3861 attribute is not available on all platforms.
3862 If you need to map the entire contents of a module to a particular
3863 section, consider using the facilities of the linker instead.
3866 @itemx sentinel (@var{position})
3867 @cindex @code{sentinel} function attribute
3868 This function attribute indicates that an argument in a call to the function
3869 is expected to be an explicit @code{NULL}. The attribute is only valid on
3870 variadic functions. By default, the sentinel is expected to be the last
3871 argument of the function call. If the optional @var{position} argument
3872 is specified to the attribute, the sentinel must be located at
3873 @var{position} counting backwards from the end of the argument list.
3876 __attribute__ ((sentinel))
3878 __attribute__ ((sentinel(0)))
3881 The attribute is automatically set with a position of 0 for the built-in
3882 functions @code{execl} and @code{execlp}. The built-in function
3883 @code{execle} has the attribute set with a position of 1.
3885 A valid @code{NULL} in this context is defined as zero with any object
3886 pointer type. If your system defines the @code{NULL} macro with
3887 an integer type then you need to add an explicit cast. During
3888 installation GCC replaces the system @code{<stddef.h>} header with
3889 a copy that redefines NULL appropriately.
3891 The warnings for missing or incorrect sentinels are enabled with
3895 @itemx simd("@var{mask}")
3896 @cindex @code{simd} function attribute
3897 This attribute enables creation of one or more function versions that
3898 can process multiple arguments using SIMD instructions from a
3899 single invocation. Specifying this attribute allows compiler to
3900 assume that such versions are available at link time (provided
3901 in the same or another translation unit). Generated versions are
3902 target-dependent and described in the corresponding Vector ABI document. For
3903 x86_64 target this document can be found
3904 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3906 The optional argument @var{mask} may have the value
3907 @code{notinbranch} or @code{inbranch},
3908 and instructs the compiler to generate non-masked or masked
3909 clones correspondingly. By default, all clones are generated.
3911 If the attribute is specified and @code{#pragma omp declare simd} is
3912 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3913 switch is specified, then the attribute is ignored.
3916 @cindex @code{stack_protect} function attribute
3917 This attribute adds stack protection code to the function if
3918 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3919 or @option{-fstack-protector-explicit} are set.
3921 @item no_stack_protector
3922 @cindex @code{no_stack_protector} function attribute
3923 This attribute prevents stack protection code for the function.
3925 @item target (@var{string}, @dots{})
3926 @cindex @code{target} function attribute
3927 Multiple target back ends implement the @code{target} attribute
3928 to specify that a function is to
3929 be compiled with different target options than specified on the
3930 command line. The original target command-line options are ignored.
3931 One or more strings can be provided as arguments.
3932 Each string consists of one or more comma-separated suffixes to
3933 the @code{-m} prefix jointly forming the name of a machine-dependent
3934 option. @xref{Submodel Options,,Machine-Dependent Options}.
3936 The @code{target} attribute can be used for instance to have a function
3937 compiled with a different ISA (instruction set architecture) than the
3938 default. @samp{#pragma GCC target} can be used to specify target-specific
3939 options for more than one function. @xref{Function Specific Option Pragmas},
3940 for details about the pragma.
3942 For instance, on an x86, you could declare one function with the
3943 @code{target("sse4.1,arch=core2")} attribute and another with
3944 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3945 compiling the first function with @option{-msse4.1} and
3946 @option{-march=core2} options, and the second function with
3947 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3948 to make sure that a function is only invoked on a machine that
3949 supports the particular ISA it is compiled for (for example by using
3950 @code{cpuid} on x86 to determine what feature bits and architecture
3954 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3955 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3958 Providing multiple strings as arguments separated by commas to specify
3959 multiple options is equivalent to separating the option suffixes with
3960 a comma (@samp{,}) within a single string. Spaces are not permitted
3963 The options supported are specific to each target; refer to @ref{x86
3964 Function Attributes}, @ref{PowerPC Function Attributes},
3965 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
3966 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
3969 @item symver ("@var{name2}@@@var{nodename}")
3970 @cindex @code{symver} function attribute
3971 On ELF targets this attribute creates a symbol version. The @var{name2} part
3972 of the parameter is the actual name of the symbol by which it will be
3973 externally referenced. The @code{nodename} portion should be the name of a
3974 node specified in the version script supplied to the linker when building a
3975 shared library. Versioned symbol must be defined and must be exported with
3979 __attribute__ ((__symver__ ("foo@@VERS_1"))) int
3985 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
3988 One can also define multiple version for a given symbol
3989 (starting from binutils 2.35).
3992 __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
3993 int symver_foo_v1 (void)
3998 This example creates a symbol name @code{symver_foo_v1}
3999 which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
4001 If you have an older release of binutils, then symbol alias needs to
4005 __attribute__ ((__symver__ ("foo@@VERS_2")))
4011 __attribute__ ((__symver__ ("foo@@VERS_3")))
4012 __attribute__ ((alias ("foo_v1")))
4013 int symver_foo_v1 (void);
4016 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
4017 addition to creating a symbol version (as if
4018 @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
4019 to resolve @var{name2} by the linker.
4022 @cindex @code{tainted_args} function attribute
4023 The @code{tainted_args} attribute is used to specify that a function is called
4024 in a way that requires sanitization of its arguments, such as a system
4025 call in an operating system kernel. Such a function can be considered part
4026 of the ``attack surface'' of the program. The attribute can be used both
4027 on function declarations, and on field declarations containing function
4028 pointers. In the latter case, any function used as an initializer of
4029 such a callback field will be treated as being called with tainted
4032 The analyzer will pay particular attention to such functions when both
4033 @option{-fanalyzer} and @option{-fanalyzer-checker=taint} are supplied,
4034 potentially issuing warnings guarded by
4035 @option{-Wanalyzer-tainted-allocation-size},
4036 @option{-Wanalyzer-tainted-array-index},
4037 @option{-Wanalyzer-tainted-divisor},
4038 @option{-Wanalyzer-tainted-offset},
4039 and @option{-Wanalyzer-tainted-size}.
4041 @item target_clones (@var{options})
4042 @cindex @code{target_clones} function attribute
4043 The @code{target_clones} attribute is used to specify that a function
4044 be cloned into multiple versions compiled with different target options
4045 than specified on the command line. The supported options and restrictions
4046 are the same as for @code{target} attribute.
4048 For instance, on an x86, you could compile a function with
4049 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
4050 one compiled with @option{-msse4.1} and another with @option{-mavx}.
4052 On a PowerPC, you can compile a function with
4053 @code{target_clones("cpu=power9,default")}. GCC will create two
4054 function clones, one compiled with @option{-mcpu=power9} and another
4055 with the default options. GCC must be configured to use GLIBC 2.23 or
4056 newer in order to use the @code{target_clones} attribute.
4058 It also creates a resolver function (see
4059 the @code{ifunc} attribute above) that dynamically selects a clone
4060 suitable for current architecture. The resolver is created only if there
4061 is a usage of a function with @code{target_clones} attribute.
4063 Note that any subsequent call of a function without @code{target_clone}
4064 from a @code{target_clone} caller will not lead to copying
4065 (target clone) of the called function.
4066 If you want to enforce such behaviour,
4067 we recommend declaring the calling function with the @code{flatten} attribute?
4070 @cindex @code{unused} function attribute
4071 This attribute, attached to a function, means that the function is meant
4072 to be possibly unused. GCC does not produce a warning for this
4076 @cindex @code{used} function attribute
4077 This attribute, attached to a function, means that code must be emitted
4078 for the function even if it appears that the function is not referenced.
4079 This is useful, for example, when the function is referenced only in
4082 When applied to a member function of a C++ class template, the
4083 attribute also means that the function is instantiated if the
4084 class itself is instantiated.
4087 @cindex @code{retain} function attribute
4088 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
4089 will save the function from linker garbage collection. To support
4090 this behavior, functions that have not been placed in specific sections
4091 (e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
4092 option), will be placed in new, unique sections.
4094 This additional functionality requires Binutils version 2.36 or later.
4096 @item visibility ("@var{visibility_type}")
4097 @cindex @code{visibility} function attribute
4098 This attribute affects the linkage of the declaration to which it is attached.
4099 It can be applied to variables (@pxref{Common Variable Attributes}) and types
4100 (@pxref{Common Type Attributes}) as well as functions.
4102 There are four supported @var{visibility_type} values: default,
4103 hidden, protected or internal visibility.
4106 void __attribute__ ((visibility ("protected")))
4107 f () @{ /* @r{Do something.} */; @}
4108 int i __attribute__ ((visibility ("hidden")));
4111 The possible values of @var{visibility_type} correspond to the
4112 visibility settings in the ELF gABI.
4115 @c keep this list of visibilities in alphabetical order.
4118 Default visibility is the normal case for the object file format.
4119 This value is available for the visibility attribute to override other
4120 options that may change the assumed visibility of entities.
4122 On ELF, default visibility means that the declaration is visible to other
4123 modules and, in shared libraries, means that the declared entity may be
4126 On Darwin, default visibility means that the declaration is visible to
4129 Default visibility corresponds to ``external linkage'' in the language.
4132 Hidden visibility indicates that the entity declared has a new
4133 form of linkage, which we call ``hidden linkage''. Two
4134 declarations of an object with hidden linkage refer to the same object
4135 if they are in the same shared object.
4138 Internal visibility is like hidden visibility, but with additional
4139 processor specific semantics. Unless otherwise specified by the
4140 psABI, GCC defines internal visibility to mean that a function is
4141 @emph{never} called from another module. Compare this with hidden
4142 functions which, while they cannot be referenced directly by other
4143 modules, can be referenced indirectly via function pointers. By
4144 indicating that a function cannot be called from outside the module,
4145 GCC may for instance omit the load of a PIC register since it is known
4146 that the calling function loaded the correct value.
4149 Protected visibility is like default visibility except that it
4150 indicates that references within the defining module bind to the
4151 definition in that module. That is, the declared entity cannot be
4152 overridden by another module.
4156 All visibilities are supported on many, but not all, ELF targets
4157 (supported when the assembler supports the @samp{.visibility}
4158 pseudo-op). Default visibility is supported everywhere. Hidden
4159 visibility is supported on Darwin targets.
4161 The visibility attribute should be applied only to declarations that
4162 would otherwise have external linkage. The attribute should be applied
4163 consistently, so that the same entity should not be declared with
4164 different settings of the attribute.
4166 In C++, the visibility attribute applies to types as well as functions
4167 and objects, because in C++ types have linkage. A class must not have
4168 greater visibility than its non-static data member types and bases,
4169 and class members default to the visibility of their class. Also, a
4170 declaration without explicit visibility is limited to the visibility
4173 In C++, you can mark member functions and static member variables of a
4174 class with the visibility attribute. This is useful if you know a
4175 particular method or static member variable should only be used from
4176 one shared object; then you can mark it hidden while the rest of the
4177 class has default visibility. Care must be taken to avoid breaking
4178 the One Definition Rule; for example, it is usually not useful to mark
4179 an inline method as hidden without marking the whole class as hidden.
4181 A C++ namespace declaration can also have the visibility attribute.
4184 namespace nspace1 __attribute__ ((visibility ("protected")))
4185 @{ /* @r{Do something.} */; @}
4188 This attribute applies only to the particular namespace body, not to
4189 other definitions of the same namespace; it is equivalent to using
4190 @samp{#pragma GCC visibility} before and after the namespace
4191 definition (@pxref{Visibility Pragmas}).
4193 In C++, if a template argument has limited visibility, this
4194 restriction is implicitly propagated to the template instantiation.
4195 Otherwise, template instantiations and specializations default to the
4196 visibility of their template.
4198 If both the template and enclosing class have explicit visibility, the
4199 visibility from the template is used.
4201 @item warn_unused_result
4202 @cindex @code{warn_unused_result} function attribute
4203 The @code{warn_unused_result} attribute causes a warning to be emitted
4204 if a caller of the function with this attribute does not use its
4205 return value. This is useful for functions where not checking
4206 the result is either a security problem or always a bug, such as
4210 int fn () __attribute__ ((warn_unused_result));
4213 if (fn () < 0) return -1;
4220 results in warning on line 5.
4223 @cindex @code{weak} function attribute
4224 The @code{weak} attribute causes a declaration of an external symbol
4225 to be emitted as a weak symbol rather than a global. This is primarily
4226 useful in defining library functions that can be overridden in user code,
4227 though it can also be used with non-function declarations. The overriding
4228 symbol must have the same type as the weak symbol. In addition, if it
4229 designates a variable it must also have the same size and alignment as
4230 the weak symbol. Weak symbols are supported for ELF targets, and also
4231 for a.out targets when using the GNU assembler and linker.
4234 @itemx weakref ("@var{target}")
4235 @cindex @code{weakref} function attribute
4236 The @code{weakref} attribute marks a declaration as a weak reference.
4237 Without arguments, it should be accompanied by an @code{alias} attribute
4238 naming the target symbol. Alternatively, @var{target} may be given as
4239 an argument to @code{weakref} itself, naming the target definition of
4240 the alias. The @var{target} must have the same type as the declaration.
4241 In addition, if it designates a variable it must also have the same size
4242 and alignment as the declaration. In either form of the declaration
4243 @code{weakref} implicitly marks the declared symbol as @code{weak}. Without
4244 a @var{target} given as an argument to @code{weakref} or to @code{alias},
4245 @code{weakref} is equivalent to @code{weak} (in that case the declaration
4246 may be @code{extern}).
4249 /* Given the declaration: */
4250 extern int y (void);
4252 /* the following... */
4253 static int x (void) __attribute__ ((weakref ("y")));
4255 /* is equivalent to... */
4256 static int x (void) __attribute__ ((weakref, alias ("y")));
4258 /* or, alternatively, to... */
4259 static int x (void) __attribute__ ((weakref));
4260 static int x (void) __attribute__ ((alias ("y")));
4263 A weak reference is an alias that does not by itself require a
4264 definition to be given for the target symbol. If the target symbol is
4265 only referenced through weak references, then it becomes a @code{weak}
4266 undefined symbol. If it is directly referenced, however, then such
4267 strong references prevail, and a definition is required for the
4268 symbol, not necessarily in the same translation unit.
4270 The effect is equivalent to moving all references to the alias to a
4271 separate translation unit, renaming the alias to the aliased symbol,
4272 declaring it as weak, compiling the two separate translation units and
4273 performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
4275 A declaration to which @code{weakref} is attached and that is associated
4276 with a named @code{target} must be @code{static}.
4278 @item zero_call_used_regs ("@var{choice}")
4279 @cindex @code{zero_call_used_regs} function attribute
4281 The @code{zero_call_used_regs} attribute causes the compiler to zero
4282 a subset of all call-used registers@footnote{A ``call-used'' register
4283 is a register whose contents can be changed by a function call;
4284 therefore, a caller cannot assume that the register has the same contents
4285 on return from the function as it had before calling the function. Such
4286 registers are also called ``call-clobbered'', ``caller-saved'', or
4287 ``volatile''.} at function return.
4288 This is used to increase program security by either mitigating
4289 Return-Oriented Programming (ROP) attacks or preventing information leakage
4292 In order to satisfy users with different security needs and control the
4293 run-time overhead at the same time, the @var{choice} parameter provides a
4294 flexible way to choose the subset of the call-used registers to be zeroed.
4295 The three basic values of @var{choice} are:
4299 @samp{skip} doesn't zero any call-used registers.
4302 @samp{used} only zeros call-used registers that are used in the function.
4303 A ``used'' register is one whose content has been set or referenced in
4307 @samp{all} zeros all call-used registers.
4310 In addition to these three basic choices, it is possible to modify
4311 @samp{used} or @samp{all} as follows:
4315 Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
4318 Adding @samp{-arg} restricts the zeroing to registers that can sometimes
4319 be used to pass function arguments. This includes all argument registers
4320 defined by the platform's calling conversion, regardless of whether the
4321 function uses those registers for function arguments or not.
4324 The modifiers can be used individually or together. If they are used
4325 together, they must appear in the order above.
4327 The full list of @var{choice}s is therefore:
4331 doesn't zero any call-used register.
4334 only zeros call-used registers that are used in the function.
4337 only zeros call-used general purpose registers that are used in the function.
4340 only zeros call-used registers that are used in the function and pass arguments.
4343 only zeros call-used general purpose registers that are used in the function
4347 zeros all call-used registers.
4350 zeros all call-used general purpose registers.
4353 zeros all call-used registers that pass arguments.
4356 zeros all call-used general purpose registers that pass
4360 Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
4361 and @samp{all-gpr-arg} are mainly used for ROP mitigation.
4363 The default for the attribute is controlled by @option{-fzero-call-used-regs}.
4366 @c This is the end of the target-independent attribute table
4368 @node AArch64 Function Attributes
4369 @subsection AArch64 Function Attributes
4371 The following target-specific function attributes are available for the
4372 AArch64 target. For the most part, these options mirror the behavior of
4373 similar command-line options (@pxref{AArch64 Options}), but on a
4377 @item general-regs-only
4378 @cindex @code{general-regs-only} function attribute, AArch64
4379 Indicates that no floating-point or Advanced SIMD registers should be
4380 used when generating code for this function. If the function explicitly
4381 uses floating-point code, then the compiler gives an error. This is
4382 the same behavior as that of the command-line option
4383 @option{-mgeneral-regs-only}.
4385 @item fix-cortex-a53-835769
4386 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
4387 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
4388 applied to this function. To explicitly disable the workaround for this
4389 function specify the negated form: @code{no-fix-cortex-a53-835769}.
4390 This corresponds to the behavior of the command line options
4391 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
4394 @cindex @code{cmodel=} function attribute, AArch64
4395 Indicates that code should be generated for a particular code model for
4396 this function. The behavior and permissible arguments are the same as
4397 for the command line option @option{-mcmodel=}.
4400 @itemx no-strict-align
4401 @cindex @code{strict-align} function attribute, AArch64
4402 @code{strict-align} indicates that the compiler should not assume that unaligned
4403 memory references are handled by the system. To allow the compiler to assume
4404 that aligned memory references are handled by the system, the inverse attribute
4405 @code{no-strict-align} can be specified. The behavior is same as for the
4406 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
4408 @item omit-leaf-frame-pointer
4409 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
4410 Indicates that the frame pointer should be omitted for a leaf function call.
4411 To keep the frame pointer, the inverse attribute
4412 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
4413 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
4414 and @option{-mno-omit-leaf-frame-pointer}.
4417 @cindex @code{tls-dialect=} function attribute, AArch64
4418 Specifies the TLS dialect to use for this function. The behavior and
4419 permissible arguments are the same as for the command-line option
4420 @option{-mtls-dialect=}.
4423 @cindex @code{arch=} function attribute, AArch64
4424 Specifies the architecture version and architectural extensions to use
4425 for this function. The behavior and permissible arguments are the same as
4426 for the @option{-march=} command-line option.
4429 @cindex @code{tune=} function attribute, AArch64
4430 Specifies the core for which to tune the performance of this function.
4431 The behavior and permissible arguments are the same as for the @option{-mtune=}
4432 command-line option.
4435 @cindex @code{cpu=} function attribute, AArch64
4436 Specifies the core for which to tune the performance of this function and also
4437 whose architectural features to use. The behavior and valid arguments are the
4438 same as for the @option{-mcpu=} command-line option.
4440 @item sign-return-address
4441 @cindex @code{sign-return-address} function attribute, AArch64
4442 Select the function scope on which return address signing will be applied. The
4443 behavior and permissible arguments are the same as for the command-line option
4444 @option{-msign-return-address=}. The default value is @code{none}. This
4445 attribute is deprecated. The @code{branch-protection} attribute should
4448 @item branch-protection
4449 @cindex @code{branch-protection} function attribute, AArch64
4450 Select the function scope on which branch protection will be applied. The
4451 behavior and permissible arguments are the same as for the command-line option
4452 @option{-mbranch-protection=}. The default value is @code{none}.
4454 @item outline-atomics
4455 @cindex @code{outline-atomics} function attribute, AArch64
4456 Enable or disable calls to out-of-line helpers to implement atomic operations.
4457 This corresponds to the behavior of the command line options
4458 @option{-moutline-atomics} and @option{-mno-outline-atomics}.
4462 The above target attributes can be specified as follows:
4465 __attribute__((target("@var{attr-string}")))
4473 where @code{@var{attr-string}} is one of the attribute strings specified above.
4475 Additionally, the architectural extension string may be specified on its
4476 own. This can be used to turn on and off particular architectural extensions
4477 without having to specify a particular architecture version or core. Example:
4480 __attribute__((target("+crc+nocrypto")))
4488 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4489 extension and disables the @code{crypto} extension for the function @code{foo}
4490 without modifying an existing @option{-march=} or @option{-mcpu} option.
4492 Multiple target function attributes can be specified by separating them with
4493 a comma. For example:
4495 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
4503 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
4504 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
4506 @subsubsection Inlining rules
4507 Specifying target attributes on individual functions or performing link-time
4508 optimization across translation units compiled with different target options
4509 can affect function inlining rules:
4511 In particular, a caller function can inline a callee function only if the
4512 architectural features available to the callee are a subset of the features
4513 available to the caller.
4514 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
4515 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
4516 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
4517 because the all the architectural features that function @code{bar} requires
4518 are available to function @code{foo}. Conversely, function @code{bar} cannot
4519 inline function @code{foo}.
4521 Additionally inlining a function compiled with @option{-mstrict-align} into a
4522 function compiled without @code{-mstrict-align} is not allowed.
4523 However, inlining a function compiled without @option{-mstrict-align} into a
4524 function compiled with @option{-mstrict-align} is allowed.
4526 Note that CPU tuning options and attributes such as the @option{-mcpu=},
4527 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
4528 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
4529 architectural feature rules specified above.
4531 @node AMD GCN Function Attributes
4532 @subsection AMD GCN Function Attributes
4534 These function attributes are supported by the AMD GCN back end:
4537 @item amdgpu_hsa_kernel
4538 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
4539 This attribute indicates that the corresponding function should be compiled as
4540 a kernel function, that is an entry point that can be invoked from the host
4541 via the HSA runtime library. By default functions are only callable only from
4542 other GCN functions.
4544 This attribute is implicitly applied to any function named @code{main}, using
4547 Kernel functions may return an integer value, which will be written to a
4548 conventional place within the HSA "kernargs" region.
4550 The attribute parameters configure what values are passed into the kernel
4551 function by the GPU drivers, via the initial register state. Some values are
4552 used by the compiler, and therefore forced on. Enabling other options may
4553 break assumptions in the compiler and/or run-time libraries.
4556 @item private_segment_buffer
4557 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4561 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4565 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4568 @item kernarg_segment_ptr
4569 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4570 locate the kernel arguments, "kernargs").
4573 Set @code{enable_sgpr_dispatch_id} flag.
4575 @item flat_scratch_init
4576 Set @code{enable_sgpr_flat_scratch_init} flag.
4578 @item private_segment_size
4579 Set @code{enable_sgpr_private_segment_size} flag.
4581 @item grid_workgroup_count_X
4582 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4583 use OpenACC/OpenMP).
4585 @item grid_workgroup_count_Y
4586 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4588 @item grid_workgroup_count_Z
4589 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4591 @item workgroup_id_X
4592 Set @code{enable_sgpr_workgroup_id_x} flag.
4594 @item workgroup_id_Y
4595 Set @code{enable_sgpr_workgroup_id_y} flag.
4597 @item workgroup_id_Z
4598 Set @code{enable_sgpr_workgroup_id_z} flag.
4600 @item workgroup_info
4601 Set @code{enable_sgpr_workgroup_info} flag.
4603 @item private_segment_wave_offset
4604 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4605 (required to locate the stack).
4607 @item work_item_id_X
4608 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4610 @item work_item_id_Y
4611 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4614 @item work_item_id_Z
4615 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4621 @node ARC Function Attributes
4622 @subsection ARC Function Attributes
4624 These function attributes are supported by the ARC back end:
4628 @cindex @code{interrupt} function attribute, ARC
4629 Use this attribute to indicate
4630 that the specified function is an interrupt handler. The compiler generates
4631 function entry and exit sequences suitable for use in an interrupt handler
4632 when this attribute is present.
4634 On the ARC, you must specify the kind of interrupt to be handled
4635 in a parameter to the interrupt attribute like this:
4638 void f () __attribute__ ((interrupt ("ilink1")));
4641 Permissible values for this parameter are: @w{@code{ilink1}} and
4642 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
4643 @w{@code{firq}} for ARCv2 architecture.
4648 @cindex @code{long_call} function attribute, ARC
4649 @cindex @code{medium_call} function attribute, ARC
4650 @cindex @code{short_call} function attribute, ARC
4651 @cindex indirect calls, ARC
4652 These attributes specify how a particular function is called.
4653 These attributes override the
4654 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4655 command-line switches and @code{#pragma long_calls} settings.
4657 For ARC, a function marked with the @code{long_call} attribute is
4658 always called using register-indirect jump-and-link instructions,
4659 thereby enabling the called function to be placed anywhere within the
4660 32-bit address space. A function marked with the @code{medium_call}
4661 attribute will always be close enough to be called with an unconditional
4662 branch-and-link instruction, which has a 25-bit offset from
4663 the call site. A function marked with the @code{short_call}
4664 attribute will always be close enough to be called with a conditional
4665 branch-and-link instruction, which has a 21-bit offset from
4669 @cindex @code{jli_always} function attribute, ARC
4670 Forces a particular function to be called using @code{jli}
4671 instruction. The @code{jli} instruction makes use of a table stored
4672 into @code{.jlitab} section, which holds the location of the functions
4673 which are addressed using this instruction.
4676 @cindex @code{jli_fixed} function attribute, ARC
4677 Identical like the above one, but the location of the function in the
4678 @code{jli} table is known and given as an attribute parameter.
4681 @cindex @code{secure_call} function attribute, ARC
4682 This attribute allows one to mark secure-code functions that are
4683 callable from normal mode. The location of the secure call function
4684 into the @code{sjli} table needs to be passed as argument.
4687 @cindex @code{naked} function attribute, ARC
4688 This attribute allows the compiler to construct the requisite function
4689 declaration, while allowing the body of the function to be assembly
4690 code. The specified function will not have prologue/epilogue
4691 sequences generated by the compiler. Only basic @code{asm} statements
4692 can safely be included in naked functions (@pxref{Basic Asm}). While
4693 using extended @code{asm} or a mixture of basic @code{asm} and C code
4694 may appear to work, they cannot be depended upon to work reliably and
4699 @node ARM Function Attributes
4700 @subsection ARM Function Attributes
4702 These function attributes are supported for ARM targets:
4706 @item general-regs-only
4707 @cindex @code{general-regs-only} function attribute, ARM
4708 Indicates that no floating-point or Advanced SIMD registers should be
4709 used when generating code for this function. If the function explicitly
4710 uses floating-point code, then the compiler gives an error. This is
4711 the same behavior as that of the command-line option
4712 @option{-mgeneral-regs-only}.
4715 @cindex @code{interrupt} function attribute, ARM
4716 Use this attribute to indicate
4717 that the specified function is an interrupt handler. The compiler generates
4718 function entry and exit sequences suitable for use in an interrupt handler
4719 when this attribute is present.
4721 You can specify the kind of interrupt to be handled by
4722 adding an optional parameter to the interrupt attribute like this:
4725 void f () __attribute__ ((interrupt ("IRQ")));
4729 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4730 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4732 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4733 may be called with a word-aligned stack pointer.
4736 @cindex @code{isr} function attribute, ARM
4737 Use this attribute on ARM to write Interrupt Service Routines. This is an
4738 alias to the @code{interrupt} attribute above.
4742 @cindex @code{long_call} function attribute, ARM
4743 @cindex @code{short_call} function attribute, ARM
4744 @cindex indirect calls, ARM
4745 These attributes specify how a particular function is called.
4746 These attributes override the
4747 @option{-mlong-calls} (@pxref{ARM Options})
4748 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4749 @code{long_call} attribute indicates that the function might be far
4750 away from the call site and require a different (more expensive)
4751 calling sequence. The @code{short_call} attribute always places
4752 the offset to the function from the call site into the @samp{BL}
4753 instruction directly.
4756 @cindex @code{naked} function attribute, ARM
4757 This attribute allows the compiler to construct the
4758 requisite function declaration, while allowing the body of the
4759 function to be assembly code. The specified function will not have
4760 prologue/epilogue sequences generated by the compiler. Only basic
4761 @code{asm} statements can safely be included in naked functions
4762 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4763 basic @code{asm} and C code may appear to work, they cannot be
4764 depended upon to work reliably and are not supported.
4767 @cindex @code{pcs} function attribute, ARM
4769 The @code{pcs} attribute can be used to control the calling convention
4770 used for a function on ARM. The attribute takes an argument that specifies
4771 the calling convention to use.
4773 When compiling using the AAPCS ABI (or a variant of it) then valid
4774 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4775 order to use a variant other than @code{"aapcs"} then the compiler must
4776 be permitted to use the appropriate co-processor registers (i.e., the
4777 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4781 /* Argument passed in r0, and result returned in r0+r1. */
4782 double f2d (float) __attribute__((pcs("aapcs")));
4785 Variadic functions always use the @code{"aapcs"} calling convention and
4786 the compiler rejects attempts to specify an alternative.
4788 @item target (@var{options})
4789 @cindex @code{target} function attribute
4790 As discussed in @ref{Common Function Attributes}, this attribute
4791 allows specification of target-specific compilation options.
4793 On ARM, the following options are allowed:
4797 @cindex @code{target("thumb")} function attribute, ARM
4798 Force code generation in the Thumb (T16/T32) ISA, depending on the
4802 @cindex @code{target("arm")} function attribute, ARM
4803 Force code generation in the ARM (A32) ISA.
4805 Functions from different modes can be inlined in the caller's mode.
4808 @cindex @code{target("fpu=")} function attribute, ARM
4809 Specifies the fpu for which to tune the performance of this function.
4810 The behavior and permissible arguments are the same as for the @option{-mfpu=}
4811 command-line option.
4814 @cindex @code{arch=} function attribute, ARM
4815 Specifies the architecture version and architectural extensions to use
4816 for this function. The behavior and permissible arguments are the same as
4817 for the @option{-march=} command-line option.
4819 The above target attributes can be specified as follows:
4822 __attribute__((target("arch=armv8-a+crc")))
4830 Additionally, the architectural extension string may be specified on its
4831 own. This can be used to turn on and off particular architectural extensions
4832 without having to specify a particular architecture version or core. Example:
4835 __attribute__((target("+crc+nocrypto")))
4843 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4844 extension and disables the @code{crypto} extension for the function @code{foo}
4845 without modifying an existing @option{-march=} or @option{-mcpu} option.
4851 @node AVR Function Attributes
4852 @subsection AVR Function Attributes
4854 These function attributes are supported by the AVR back end:
4858 @cindex @code{interrupt} function attribute, AVR
4859 Use this attribute to indicate
4860 that the specified function is an interrupt handler. The compiler generates
4861 function entry and exit sequences suitable for use in an interrupt handler
4862 when this attribute is present.
4864 On the AVR, the hardware globally disables interrupts when an
4865 interrupt is executed. The first instruction of an interrupt handler
4866 declared with this attribute is a @code{SEI} instruction to
4867 re-enable interrupts. See also the @code{signal} function attribute
4868 that does not insert a @code{SEI} instruction. If both @code{signal} and
4869 @code{interrupt} are specified for the same function, @code{signal}
4870 is silently ignored.
4873 @cindex @code{naked} function attribute, AVR
4874 This attribute allows the compiler to construct the
4875 requisite function declaration, while allowing the body of the
4876 function to be assembly code. The specified function will not have
4877 prologue/epilogue sequences generated by the compiler. Only basic
4878 @code{asm} statements can safely be included in naked functions
4879 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4880 basic @code{asm} and C code may appear to work, they cannot be
4881 depended upon to work reliably and are not supported.
4884 @cindex @code{no_gccisr} function attribute, AVR
4885 Do not use @code{__gcc_isr} pseudo instructions in a function with
4886 the @code{interrupt} or @code{signal} attribute aka. interrupt
4887 service routine (ISR).
4888 Use this attribute if the preamble of the ISR prologue should always read
4892 in __tmp_reg__, __SREG__
4896 and accordingly for the postamble of the epilogue --- no matter whether
4897 the mentioned registers are actually used in the ISR or not.
4898 Situations where you might want to use this attribute include:
4901 Code that (effectively) clobbers bits of @code{SREG} other than the
4902 @code{I}-flag by writing to the memory location of @code{SREG}.
4904 Code that uses inline assembler to jump to a different function which
4905 expects (parts of) the prologue code as outlined above to be present.
4907 To disable @code{__gcc_isr} generation for the whole compilation unit,
4908 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
4912 @cindex @code{OS_main} function attribute, AVR
4913 @cindex @code{OS_task} function attribute, AVR
4914 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
4915 do not save/restore any call-saved register in their prologue/epilogue.
4917 The @code{OS_main} attribute can be used when there @emph{is
4918 guarantee} that interrupts are disabled at the time when the function
4919 is entered. This saves resources when the stack pointer has to be
4920 changed to set up a frame for local variables.
4922 The @code{OS_task} attribute can be used when there is @emph{no
4923 guarantee} that interrupts are disabled at that time when the function
4924 is entered like for, e@.g@. task functions in a multi-threading operating
4925 system. In that case, changing the stack pointer register is
4926 guarded by save/clear/restore of the global interrupt enable flag.
4928 The differences to the @code{naked} function attribute are:
4930 @item @code{naked} functions do not have a return instruction whereas
4931 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
4932 @code{RETI} return instruction.
4933 @item @code{naked} functions do not set up a frame for local variables
4934 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
4939 @cindex @code{signal} function attribute, AVR
4940 Use this attribute on the AVR to indicate that the specified
4941 function is an interrupt handler. The compiler generates function
4942 entry and exit sequences suitable for use in an interrupt handler when this
4943 attribute is present.
4945 See also the @code{interrupt} function attribute.
4947 The AVR hardware globally disables interrupts when an interrupt is executed.
4948 Interrupt handler functions defined with the @code{signal} attribute
4949 do not re-enable interrupts. It is save to enable interrupts in a
4950 @code{signal} handler. This ``save'' only applies to the code
4951 generated by the compiler and not to the IRQ layout of the
4952 application which is responsibility of the application.
4954 If both @code{signal} and @code{interrupt} are specified for the same
4955 function, @code{signal} is silently ignored.
4958 @node Blackfin Function Attributes
4959 @subsection Blackfin Function Attributes
4961 These function attributes are supported by the Blackfin back end:
4965 @item exception_handler
4966 @cindex @code{exception_handler} function attribute
4967 @cindex exception handler functions, Blackfin
4968 Use this attribute on the Blackfin to indicate that the specified function
4969 is an exception handler. The compiler generates function entry and
4970 exit sequences suitable for use in an exception handler when this
4971 attribute is present.
4973 @item interrupt_handler
4974 @cindex @code{interrupt_handler} function attribute, Blackfin
4975 Use this attribute to
4976 indicate that the specified function is an interrupt handler. The compiler
4977 generates function entry and exit sequences suitable for use in an
4978 interrupt handler when this attribute is present.
4981 @cindex @code{kspisusp} function attribute, Blackfin
4982 @cindex User stack pointer in interrupts on the Blackfin
4983 When used together with @code{interrupt_handler}, @code{exception_handler}
4984 or @code{nmi_handler}, code is generated to load the stack pointer
4985 from the USP register in the function prologue.
4988 @cindex @code{l1_text} function attribute, Blackfin
4989 This attribute specifies a function to be placed into L1 Instruction
4990 SRAM@. The function is put into a specific section named @code{.l1.text}.
4991 With @option{-mfdpic}, function calls with a such function as the callee
4992 or caller uses inlined PLT.
4995 @cindex @code{l2} function attribute, Blackfin
4996 This attribute specifies a function to be placed into L2
4997 SRAM. The function is put into a specific section named
4998 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
5003 @cindex indirect calls, Blackfin
5004 @cindex @code{longcall} function attribute, Blackfin
5005 @cindex @code{shortcall} function attribute, Blackfin
5006 The @code{longcall} attribute
5007 indicates that the function might be far away from the call site and
5008 require a different (more expensive) calling sequence. The
5009 @code{shortcall} attribute indicates that the function is always close
5010 enough for the shorter calling sequence to be used. These attributes
5011 override the @option{-mlongcall} switch.
5014 @cindex @code{nesting} function attribute, Blackfin
5015 @cindex Allow nesting in an interrupt handler on the Blackfin processor
5016 Use this attribute together with @code{interrupt_handler},
5017 @code{exception_handler} or @code{nmi_handler} to indicate that the function
5018 entry code should enable nested interrupts or exceptions.
5021 @cindex @code{nmi_handler} function attribute, Blackfin
5022 @cindex NMI handler functions on the Blackfin processor
5023 Use this attribute on the Blackfin to indicate that the specified function
5024 is an NMI handler. The compiler generates function entry and
5025 exit sequences suitable for use in an NMI handler when this
5026 attribute is present.
5029 @cindex @code{saveall} function attribute, Blackfin
5030 @cindex save all registers on the Blackfin
5031 Use this attribute to indicate that
5032 all registers except the stack pointer should be saved in the prologue
5033 regardless of whether they are used or not.
5036 @node BPF Function Attributes
5037 @subsection BPF Function Attributes
5039 These function attributes are supported by the BPF back end:
5043 @cindex @code{kernel helper}, function attribute, BPF
5044 use this attribute to indicate the specified function declaration is a
5045 kernel helper. The helper function is passed as an argument to the
5049 int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
5050 __attribute__ ((kernel_helper (4)));
5054 @node CR16 Function Attributes
5055 @subsection CR16 Function Attributes
5057 These function attributes are supported by the CR16 back end:
5061 @cindex @code{interrupt} function attribute, CR16
5062 Use this attribute to indicate
5063 that the specified function is an interrupt handler. The compiler generates
5064 function entry and exit sequences suitable for use in an interrupt handler
5065 when this attribute is present.
5068 @node C-SKY Function Attributes
5069 @subsection C-SKY Function Attributes
5071 These function attributes are supported by the C-SKY back end:
5076 @cindex @code{interrupt} function attribute, C-SKY
5077 @cindex @code{isr} function attribute, C-SKY
5078 Use these attributes to indicate that the specified function
5079 is an interrupt handler.
5080 The compiler generates function entry and exit sequences suitable for
5081 use in an interrupt handler when either of these attributes are present.
5083 Use of these options requires the @option{-mistack} command-line option
5084 to enable support for the necessary interrupt stack instructions. They
5085 are ignored with a warning otherwise. @xref{C-SKY Options}.
5088 @cindex @code{naked} function attribute, C-SKY
5089 This attribute allows the compiler to construct the
5090 requisite function declaration, while allowing the body of the
5091 function to be assembly code. The specified function will not have
5092 prologue/epilogue sequences generated by the compiler. Only basic
5093 @code{asm} statements can safely be included in naked functions
5094 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5095 basic @code{asm} and C code may appear to work, they cannot be
5096 depended upon to work reliably and are not supported.
5100 @node Epiphany Function Attributes
5101 @subsection Epiphany Function Attributes
5103 These function attributes are supported by the Epiphany back end:
5107 @cindex @code{disinterrupt} function attribute, Epiphany
5108 This attribute causes the compiler to emit
5109 instructions to disable interrupts for the duration of the given
5112 @item forwarder_section
5113 @cindex @code{forwarder_section} function attribute, Epiphany
5114 This attribute modifies the behavior of an interrupt handler.
5115 The interrupt handler may be in external memory which cannot be
5116 reached by a branch instruction, so generate a local memory trampoline
5117 to transfer control. The single parameter identifies the section where
5118 the trampoline is placed.
5121 @cindex @code{interrupt} function attribute, Epiphany
5122 Use this attribute to indicate
5123 that the specified function is an interrupt handler. The compiler generates
5124 function entry and exit sequences suitable for use in an interrupt handler
5125 when this attribute is present. It may also generate
5126 a special section with code to initialize the interrupt vector table.
5128 On Epiphany targets one or more optional parameters can be added like this:
5131 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
5134 Permissible values for these parameters are: @w{@code{reset}},
5135 @w{@code{software_exception}}, @w{@code{page_miss}},
5136 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
5137 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
5138 Multiple parameters indicate that multiple entries in the interrupt
5139 vector table should be initialized for this function, i.e.@: for each
5140 parameter @w{@var{name}}, a jump to the function is emitted in
5141 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
5142 entirely, in which case no interrupt vector table entry is provided.
5144 Note that interrupts are enabled inside the function
5145 unless the @code{disinterrupt} attribute is also specified.
5147 The following examples are all valid uses of these attributes on
5150 void __attribute__ ((interrupt)) universal_handler ();
5151 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
5152 void __attribute__ ((interrupt ("dma0, dma1")))
5153 universal_dma_handler ();
5154 void __attribute__ ((interrupt ("timer0"), disinterrupt))
5155 fast_timer_handler ();
5156 void __attribute__ ((interrupt ("dma0, dma1"),
5157 forwarder_section ("tramp")))
5158 external_dma_handler ();
5163 @cindex @code{long_call} function attribute, Epiphany
5164 @cindex @code{short_call} function attribute, Epiphany
5165 @cindex indirect calls, Epiphany
5166 These attributes specify how a particular function is called.
5167 These attributes override the
5168 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
5169 command-line switch and @code{#pragma long_calls} settings.
5173 @node H8/300 Function Attributes
5174 @subsection H8/300 Function Attributes
5176 These function attributes are available for H8/300 targets:
5179 @item function_vector
5180 @cindex @code{function_vector} function attribute, H8/300
5181 Use this attribute on the H8/300, H8/300H, and H8S to indicate
5182 that the specified function should be called through the function vector.
5183 Calling a function through the function vector reduces code size; however,
5184 the function vector has a limited size (maximum 128 entries on the H8/300
5185 and 64 entries on the H8/300H and H8S)
5186 and shares space with the interrupt vector.
5188 @item interrupt_handler
5189 @cindex @code{interrupt_handler} function attribute, H8/300
5190 Use this attribute on the H8/300, H8/300H, and H8S to
5191 indicate that the specified function is an interrupt handler. The compiler
5192 generates function entry and exit sequences suitable for use in an
5193 interrupt handler when this attribute is present.
5196 @cindex @code{saveall} function attribute, H8/300
5197 @cindex save all registers on the H8/300, H8/300H, and H8S
5198 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
5199 all registers except the stack pointer should be saved in the prologue
5200 regardless of whether they are used or not.
5203 @node IA-64 Function Attributes
5204 @subsection IA-64 Function Attributes
5206 These function attributes are supported on IA-64 targets:
5209 @item syscall_linkage
5210 @cindex @code{syscall_linkage} function attribute, IA-64
5211 This attribute is used to modify the IA-64 calling convention by marking
5212 all input registers as live at all function exits. This makes it possible
5213 to restart a system call after an interrupt without having to save/restore
5214 the input registers. This also prevents kernel data from leaking into
5218 @cindex @code{version_id} function attribute, IA-64
5219 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
5220 symbol to contain a version string, thus allowing for function level
5221 versioning. HP-UX system header files may use function level versioning
5222 for some system calls.
5225 extern int foo () __attribute__((version_id ("20040821")));
5229 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
5232 @node M32C Function Attributes
5233 @subsection M32C Function Attributes
5235 These function attributes are supported by the M32C back end:
5239 @cindex @code{bank_switch} function attribute, M32C
5240 When added to an interrupt handler with the M32C port, causes the
5241 prologue and epilogue to use bank switching to preserve the registers
5242 rather than saving them on the stack.
5244 @item fast_interrupt
5245 @cindex @code{fast_interrupt} function attribute, M32C
5246 Use this attribute on the M32C port to indicate that the specified
5247 function is a fast interrupt handler. This is just like the
5248 @code{interrupt} attribute, except that @code{freit} is used to return
5249 instead of @code{reit}.
5251 @item function_vector
5252 @cindex @code{function_vector} function attribute, M16C/M32C
5253 On M16C/M32C targets, the @code{function_vector} attribute declares a
5254 special page subroutine call function. Use of this attribute reduces
5255 the code size by 2 bytes for each call generated to the
5256 subroutine. The argument to the attribute is the vector number entry
5257 from the special page vector table which contains the 16 low-order
5258 bits of the subroutine's entry address. Each vector table has special
5259 page number (18 to 255) that is used in @code{jsrs} instructions.
5260 Jump addresses of the routines are generated by adding 0x0F0000 (in
5261 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
5262 2-byte addresses set in the vector table. Therefore you need to ensure
5263 that all the special page vector routines should get mapped within the
5264 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
5267 In the following example 2 bytes are saved for each call to
5268 function @code{foo}.
5271 void foo (void) __attribute__((function_vector(0x18)));
5282 If functions are defined in one file and are called in another file,
5283 then be sure to write this declaration in both files.
5285 This attribute is ignored for R8C target.
5288 @cindex @code{interrupt} function attribute, M32C
5289 Use this attribute to indicate
5290 that the specified function is an interrupt handler. The compiler generates
5291 function entry and exit sequences suitable for use in an interrupt handler
5292 when this attribute is present.
5295 @node M32R/D Function Attributes
5296 @subsection M32R/D Function Attributes
5298 These function attributes are supported by the M32R/D back end:
5302 @cindex @code{interrupt} function attribute, M32R/D
5303 Use this attribute to indicate
5304 that the specified function is an interrupt handler. The compiler generates
5305 function entry and exit sequences suitable for use in an interrupt handler
5306 when this attribute is present.
5308 @item model (@var{model-name})
5309 @cindex @code{model} function attribute, M32R/D
5310 @cindex function addressability on the M32R/D
5312 On the M32R/D, use this attribute to set the addressability of an
5313 object, and of the code generated for a function. The identifier
5314 @var{model-name} is one of @code{small}, @code{medium}, or
5315 @code{large}, representing each of the code models.
5317 Small model objects live in the lower 16MB of memory (so that their
5318 addresses can be loaded with the @code{ld24} instruction), and are
5319 callable with the @code{bl} instruction.
5321 Medium model objects may live anywhere in the 32-bit address space (the
5322 compiler generates @code{seth/add3} instructions to load their addresses),
5323 and are callable with the @code{bl} instruction.
5325 Large model objects may live anywhere in the 32-bit address space (the
5326 compiler generates @code{seth/add3} instructions to load their addresses),
5327 and may not be reachable with the @code{bl} instruction (the compiler
5328 generates the much slower @code{seth/add3/jl} instruction sequence).
5331 @node m68k Function Attributes
5332 @subsection m68k Function Attributes
5334 These function attributes are supported by the m68k back end:
5338 @itemx interrupt_handler
5339 @cindex @code{interrupt} function attribute, m68k
5340 @cindex @code{interrupt_handler} function attribute, m68k
5341 Use this attribute to
5342 indicate that the specified function is an interrupt handler. The compiler
5343 generates function entry and exit sequences suitable for use in an
5344 interrupt handler when this attribute is present. Either name may be used.
5346 @item interrupt_thread
5347 @cindex @code{interrupt_thread} function attribute, fido
5348 Use this attribute on fido, a subarchitecture of the m68k, to indicate
5349 that the specified function is an interrupt handler that is designed
5350 to run as a thread. The compiler omits generate prologue/epilogue
5351 sequences and replaces the return instruction with a @code{sleep}
5352 instruction. This attribute is available only on fido.
5355 @node MCORE Function Attributes
5356 @subsection MCORE Function Attributes
5358 These function attributes are supported by the MCORE back end:
5362 @cindex @code{naked} function attribute, MCORE
5363 This attribute allows the compiler to construct the
5364 requisite function declaration, while allowing the body of the
5365 function to be assembly code. The specified function will not have
5366 prologue/epilogue sequences generated by the compiler. Only basic
5367 @code{asm} statements can safely be included in naked functions
5368 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5369 basic @code{asm} and C code may appear to work, they cannot be
5370 depended upon to work reliably and are not supported.
5373 @node MeP Function Attributes
5374 @subsection MeP Function Attributes
5376 These function attributes are supported by the MeP back end:
5380 @cindex @code{disinterrupt} function attribute, MeP
5381 On MeP targets, this attribute causes the compiler to emit
5382 instructions to disable interrupts for the duration of the given
5386 @cindex @code{interrupt} function attribute, MeP
5387 Use this attribute to indicate
5388 that the specified function is an interrupt handler. The compiler generates
5389 function entry and exit sequences suitable for use in an interrupt handler
5390 when this attribute is present.
5393 @cindex @code{near} function attribute, MeP
5394 This attribute causes the compiler to assume the called
5395 function is close enough to use the normal calling convention,
5396 overriding the @option{-mtf} command-line option.
5399 @cindex @code{far} function attribute, MeP
5400 On MeP targets this causes the compiler to use a calling convention
5401 that assumes the called function is too far away for the built-in
5405 @cindex @code{vliw} function attribute, MeP
5406 The @code{vliw} attribute tells the compiler to emit
5407 instructions in VLIW mode instead of core mode. Note that this
5408 attribute is not allowed unless a VLIW coprocessor has been configured
5409 and enabled through command-line options.
5412 @node MicroBlaze Function Attributes
5413 @subsection MicroBlaze Function Attributes
5415 These function attributes are supported on MicroBlaze targets:
5418 @item save_volatiles
5419 @cindex @code{save_volatiles} function attribute, MicroBlaze
5420 Use this attribute to indicate that the function is
5421 an interrupt handler. All volatile registers (in addition to non-volatile
5422 registers) are saved in the function prologue. If the function is a leaf
5423 function, only volatiles used by the function are saved. A normal function
5424 return is generated instead of a return from interrupt.
5427 @cindex @code{break_handler} function attribute, MicroBlaze
5428 @cindex break handler functions
5429 Use this attribute to indicate that
5430 the specified function is a break handler. The compiler generates function
5431 entry and exit sequences suitable for use in an break handler when this
5432 attribute is present. The return from @code{break_handler} is done through
5433 the @code{rtbd} instead of @code{rtsd}.
5436 void f () __attribute__ ((break_handler));
5439 @item interrupt_handler
5440 @itemx fast_interrupt
5441 @cindex @code{interrupt_handler} function attribute, MicroBlaze
5442 @cindex @code{fast_interrupt} function attribute, MicroBlaze
5443 These attributes indicate that the specified function is an interrupt
5444 handler. Use the @code{fast_interrupt} attribute to indicate handlers
5445 used in low-latency interrupt mode, and @code{interrupt_handler} for
5446 interrupts that do not use low-latency handlers. In both cases, GCC
5447 emits appropriate prologue code and generates a return from the handler
5448 using @code{rtid} instead of @code{rtsd}.
5451 @node Microsoft Windows Function Attributes
5452 @subsection Microsoft Windows Function Attributes
5454 The following attributes are available on Microsoft Windows and Symbian OS
5459 @cindex @code{dllexport} function attribute
5460 @cindex @code{__declspec(dllexport)}
5461 On Microsoft Windows targets and Symbian OS targets the
5462 @code{dllexport} attribute causes the compiler to provide a global
5463 pointer to a pointer in a DLL, so that it can be referenced with the
5464 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
5465 name is formed by combining @code{_imp__} and the function or variable
5468 You can use @code{__declspec(dllexport)} as a synonym for
5469 @code{__attribute__ ((dllexport))} for compatibility with other
5472 On systems that support the @code{visibility} attribute, this
5473 attribute also implies ``default'' visibility. It is an error to
5474 explicitly specify any other visibility.
5476 GCC's default behavior is to emit all inline functions with the
5477 @code{dllexport} attribute. Since this can cause object file-size bloat,
5478 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
5479 ignore the attribute for inlined functions unless the
5480 @option{-fkeep-inline-functions} flag is used instead.
5482 The attribute is ignored for undefined symbols.
5484 When applied to C++ classes, the attribute marks defined non-inlined
5485 member functions and static data members as exports. Static consts
5486 initialized in-class are not marked unless they are also defined
5489 For Microsoft Windows targets there are alternative methods for
5490 including the symbol in the DLL's export table such as using a
5491 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
5492 the @option{--export-all} linker flag.
5495 @cindex @code{dllimport} function attribute
5496 @cindex @code{__declspec(dllimport)}
5497 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
5498 attribute causes the compiler to reference a function or variable via
5499 a global pointer to a pointer that is set up by the DLL exporting the
5500 symbol. The attribute implies @code{extern}. On Microsoft Windows
5501 targets, the pointer name is formed by combining @code{_imp__} and the
5502 function or variable name.
5504 You can use @code{__declspec(dllimport)} as a synonym for
5505 @code{__attribute__ ((dllimport))} for compatibility with other
5508 On systems that support the @code{visibility} attribute, this
5509 attribute also implies ``default'' visibility. It is an error to
5510 explicitly specify any other visibility.
5512 Currently, the attribute is ignored for inlined functions. If the
5513 attribute is applied to a symbol @emph{definition}, an error is reported.
5514 If a symbol previously declared @code{dllimport} is later defined, the
5515 attribute is ignored in subsequent references, and a warning is emitted.
5516 The attribute is also overridden by a subsequent declaration as
5519 When applied to C++ classes, the attribute marks non-inlined
5520 member functions and static data members as imports. However, the
5521 attribute is ignored for virtual methods to allow creation of vtables
5524 On the SH Symbian OS target the @code{dllimport} attribute also has
5525 another affect---it can cause the vtable and run-time type information
5526 for a class to be exported. This happens when the class has a
5527 dllimported constructor or a non-inline, non-pure virtual function
5528 and, for either of those two conditions, the class also has an inline
5529 constructor or destructor and has a key function that is defined in
5530 the current translation unit.
5532 For Microsoft Windows targets the use of the @code{dllimport}
5533 attribute on functions is not necessary, but provides a small
5534 performance benefit by eliminating a thunk in the DLL@. The use of the
5535 @code{dllimport} attribute on imported variables can be avoided by passing the
5536 @option{--enable-auto-import} switch to the GNU linker. As with
5537 functions, using the attribute for a variable eliminates a thunk in
5540 One drawback to using this attribute is that a pointer to a
5541 @emph{variable} marked as @code{dllimport} cannot be used as a constant
5542 address. However, a pointer to a @emph{function} with the
5543 @code{dllimport} attribute can be used as a constant initializer; in
5544 this case, the address of a stub function in the import lib is
5545 referenced. On Microsoft Windows targets, the attribute can be disabled
5546 for functions by setting the @option{-mnop-fun-dllimport} flag.
5549 @node MIPS Function Attributes
5550 @subsection MIPS Function Attributes
5552 These function attributes are supported by the MIPS back end:
5556 @cindex @code{interrupt} function attribute, MIPS
5557 Use this attribute to indicate that the specified function is an interrupt
5558 handler. The compiler generates function entry and exit sequences suitable
5559 for use in an interrupt handler when this attribute is present.
5560 An optional argument is supported for the interrupt attribute which allows
5561 the interrupt mode to be described. By default GCC assumes the external
5562 interrupt controller (EIC) mode is in use, this can be explicitly set using
5563 @code{eic}. When interrupts are non-masked then the requested Interrupt
5564 Priority Level (IPL) is copied to the current IPL which has the effect of only
5565 enabling higher priority interrupts. To use vectored interrupt mode use
5566 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
5567 the behavior of the non-masked interrupt support and GCC will arrange to mask
5568 all interrupts from sw0 up to and including the specified interrupt vector.
5570 You can use the following attributes to modify the behavior
5571 of an interrupt handler:
5573 @item use_shadow_register_set
5574 @cindex @code{use_shadow_register_set} function attribute, MIPS
5575 Assume that the handler uses a shadow register set, instead of
5576 the main general-purpose registers. An optional argument @code{intstack} is
5577 supported to indicate that the shadow register set contains a valid stack
5580 @item keep_interrupts_masked
5581 @cindex @code{keep_interrupts_masked} function attribute, MIPS
5582 Keep interrupts masked for the whole function. Without this attribute,
5583 GCC tries to reenable interrupts for as much of the function as it can.
5585 @item use_debug_exception_return
5586 @cindex @code{use_debug_exception_return} function attribute, MIPS
5587 Return using the @code{deret} instruction. Interrupt handlers that don't
5588 have this attribute return using @code{eret} instead.
5591 You can use any combination of these attributes, as shown below:
5593 void __attribute__ ((interrupt)) v0 ();
5594 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5595 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5596 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5597 void __attribute__ ((interrupt, use_shadow_register_set,
5598 keep_interrupts_masked)) v4 ();
5599 void __attribute__ ((interrupt, use_shadow_register_set,
5600 use_debug_exception_return)) v5 ();
5601 void __attribute__ ((interrupt, keep_interrupts_masked,
5602 use_debug_exception_return)) v6 ();
5603 void __attribute__ ((interrupt, use_shadow_register_set,
5604 keep_interrupts_masked,
5605 use_debug_exception_return)) v7 ();
5606 void __attribute__ ((interrupt("eic"))) v8 ();
5607 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5614 @cindex indirect calls, MIPS
5615 @cindex @code{long_call} function attribute, MIPS
5616 @cindex @code{short_call} function attribute, MIPS
5617 @cindex @code{near} function attribute, MIPS
5618 @cindex @code{far} function attribute, MIPS
5619 These attributes specify how a particular function is called on MIPS@.
5620 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5621 command-line switch. The @code{long_call} and @code{far} attributes are
5622 synonyms, and cause the compiler to always call
5623 the function by first loading its address into a register, and then using
5624 the contents of that register. The @code{short_call} and @code{near}
5625 attributes are synonyms, and have the opposite
5626 effect; they specify that non-PIC calls should be made using the more
5627 efficient @code{jal} instruction.
5631 @cindex @code{mips16} function attribute, MIPS
5632 @cindex @code{nomips16} function attribute, MIPS
5634 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5635 function attributes to locally select or turn off MIPS16 code generation.
5636 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5637 while MIPS16 code generation is disabled for functions with the
5638 @code{nomips16} attribute. These attributes override the
5639 @option{-mips16} and @option{-mno-mips16} options on the command line
5640 (@pxref{MIPS Options}).
5642 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5643 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5644 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5645 may interact badly with some GCC extensions such as @code{__builtin_apply}
5646 (@pxref{Constructing Calls}).
5648 @item micromips, MIPS
5649 @itemx nomicromips, MIPS
5650 @cindex @code{micromips} function attribute
5651 @cindex @code{nomicromips} function attribute
5653 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5654 function attributes to locally select or turn off microMIPS code generation.
5655 A function with the @code{micromips} attribute is emitted as microMIPS code,
5656 while microMIPS code generation is disabled for functions with the
5657 @code{nomicromips} attribute. These attributes override the
5658 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5659 (@pxref{MIPS Options}).
5661 When compiling files containing mixed microMIPS and non-microMIPS code, the
5662 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5664 not that within individual functions. Mixed microMIPS and non-microMIPS code
5665 may interact badly with some GCC extensions such as @code{__builtin_apply}
5666 (@pxref{Constructing Calls}).
5669 @cindex @code{nocompression} function attribute, MIPS
5670 On MIPS targets, you can use the @code{nocompression} function attribute
5671 to locally turn off MIPS16 and microMIPS code generation. This attribute
5672 overrides the @option{-mips16} and @option{-mmicromips} options on the
5673 command line (@pxref{MIPS Options}).
5676 @node MSP430 Function Attributes
5677 @subsection MSP430 Function Attributes
5679 These function attributes are supported by the MSP430 back end:
5683 @cindex @code{critical} function attribute, MSP430
5684 Critical functions disable interrupts upon entry and restore the
5685 previous interrupt state upon exit. Critical functions cannot also
5686 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5688 The MSP430 hardware ensures that interrupts are disabled on entry to
5689 @code{interrupt} functions, and restores the previous interrupt state
5690 on exit. The @code{critical} attribute is therefore redundant on
5691 @code{interrupt} functions.
5694 @cindex @code{interrupt} function attribute, MSP430
5695 Use this attribute to indicate
5696 that the specified function is an interrupt handler. The compiler generates
5697 function entry and exit sequences suitable for use in an interrupt handler
5698 when this attribute is present.
5700 You can provide an argument to the interrupt
5701 attribute which specifies a name or number. If the argument is a
5702 number it indicates the slot in the interrupt vector table (0 - 31) to
5703 which this handler should be assigned. If the argument is a name it
5704 is treated as a symbolic name for the vector slot. These names should
5705 match up with appropriate entries in the linker script. By default
5706 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5707 @code{reset} for vector 31 are recognized.
5710 @cindex @code{naked} function attribute, MSP430
5711 This attribute allows the compiler to construct the
5712 requisite function declaration, while allowing the body of the
5713 function to be assembly code. The specified function will not have
5714 prologue/epilogue sequences generated by the compiler. Only basic
5715 @code{asm} statements can safely be included in naked functions
5716 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5717 basic @code{asm} and C code may appear to work, they cannot be
5718 depended upon to work reliably and are not supported.
5721 @cindex @code{reentrant} function attribute, MSP430
5722 Reentrant functions disable interrupts upon entry and enable them
5723 upon exit. Reentrant functions cannot also have the @code{naked}
5724 or @code{critical} attributes. They can have the @code{interrupt}
5728 @cindex @code{wakeup} function attribute, MSP430
5729 This attribute only applies to interrupt functions. It is silently
5730 ignored if applied to a non-interrupt function. A wakeup interrupt
5731 function will rouse the processor from any low-power state that it
5732 might be in when the function exits.
5737 @cindex @code{lower} function attribute, MSP430
5738 @cindex @code{upper} function attribute, MSP430
5739 @cindex @code{either} function attribute, MSP430
5740 On the MSP430 target these attributes can be used to specify whether
5741 the function or variable should be placed into low memory, high
5742 memory, or the placement should be left to the linker to decide. The
5743 attributes are only significant if compiling for the MSP430X
5744 architecture in the large memory model.
5746 The attributes work in conjunction with a linker script that has been
5747 augmented to specify where to place sections with a @code{.lower} and
5748 a @code{.upper} prefix. So, for example, as well as placing the
5749 @code{.data} section, the script also specifies the placement of a
5750 @code{.lower.data} and a @code{.upper.data} section. The intention
5751 is that @code{lower} sections are placed into a small but easier to
5752 access memory region and the upper sections are placed into a larger, but
5753 slower to access, region.
5755 The @code{either} attribute is special. It tells the linker to place
5756 the object into the corresponding @code{lower} section if there is
5757 room for it. If there is insufficient room then the object is placed
5758 into the corresponding @code{upper} section instead. Note that the
5759 placement algorithm is not very sophisticated. It does not attempt to
5760 find an optimal packing of the @code{lower} sections. It just makes
5761 one pass over the objects and does the best that it can. Using the
5762 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5763 options can help the packing, however, since they produce smaller,
5764 easier to pack regions.
5767 @node NDS32 Function Attributes
5768 @subsection NDS32 Function Attributes
5770 These function attributes are supported by the NDS32 back end:
5774 @cindex @code{exception} function attribute
5775 @cindex exception handler functions, NDS32
5776 Use this attribute on the NDS32 target to indicate that the specified function
5777 is an exception handler. The compiler will generate corresponding sections
5778 for use in an exception handler.
5781 @cindex @code{interrupt} function attribute, NDS32
5782 On NDS32 target, this attribute indicates that the specified function
5783 is an interrupt handler. The compiler generates corresponding sections
5784 for use in an interrupt handler. You can use the following attributes
5785 to modify the behavior:
5788 @cindex @code{nested} function attribute, NDS32
5789 This interrupt service routine is interruptible.
5791 @cindex @code{not_nested} function attribute, NDS32
5792 This interrupt service routine is not interruptible.
5794 @cindex @code{nested_ready} function attribute, NDS32
5795 This interrupt service routine is interruptible after @code{PSW.GIE}
5796 (global interrupt enable) is set. This allows interrupt service routine to
5797 finish some short critical code before enabling interrupts.
5799 @cindex @code{save_all} function attribute, NDS32
5800 The system will help save all registers into stack before entering
5803 @cindex @code{partial_save} function attribute, NDS32
5804 The system will help save caller registers into stack before entering
5809 @cindex @code{naked} function attribute, NDS32
5810 This attribute allows the compiler to construct the
5811 requisite function declaration, while allowing the body of the
5812 function to be assembly code. The specified function will not have
5813 prologue/epilogue sequences generated by the compiler. Only basic
5814 @code{asm} statements can safely be included in naked functions
5815 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5816 basic @code{asm} and C code may appear to work, they cannot be
5817 depended upon to work reliably and are not supported.
5820 @cindex @code{reset} function attribute, NDS32
5821 @cindex reset handler functions
5822 Use this attribute on the NDS32 target to indicate that the specified function
5823 is a reset handler. The compiler will generate corresponding sections
5824 for use in a reset handler. You can use the following attributes
5825 to provide extra exception handling:
5828 @cindex @code{nmi} function attribute, NDS32
5829 Provide a user-defined function to handle NMI exception.
5831 @cindex @code{warm} function attribute, NDS32
5832 Provide a user-defined function to handle warm reset exception.
5836 @node Nios II Function Attributes
5837 @subsection Nios II Function Attributes
5839 These function attributes are supported by the Nios II back end:
5842 @item target (@var{options})
5843 @cindex @code{target} function attribute
5844 As discussed in @ref{Common Function Attributes}, this attribute
5845 allows specification of target-specific compilation options.
5847 When compiling for Nios II, the following options are allowed:
5850 @item custom-@var{insn}=@var{N}
5851 @itemx no-custom-@var{insn}
5852 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
5853 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
5854 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
5855 custom instruction with encoding @var{N} when generating code that uses
5856 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
5857 the custom instruction @var{insn}.
5858 These target attributes correspond to the
5859 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
5860 command-line options, and support the same set of @var{insn} keywords.
5861 @xref{Nios II Options}, for more information.
5863 @item custom-fpu-cfg=@var{name}
5864 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
5865 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
5866 command-line option, to select a predefined set of custom instructions
5868 @xref{Nios II Options}, for more information.
5872 @node Nvidia PTX Function Attributes
5873 @subsection Nvidia PTX Function Attributes
5875 These function attributes are supported by the Nvidia PTX back end:
5879 @cindex @code{kernel} attribute, Nvidia PTX
5880 This attribute indicates that the corresponding function should be compiled
5881 as a kernel function, which can be invoked from the host via the CUDA RT
5883 By default functions are only callable only from other PTX functions.
5885 Kernel functions must have @code{void} return type.
5888 @node PowerPC Function Attributes
5889 @subsection PowerPC Function Attributes
5891 These function attributes are supported by the PowerPC back end:
5896 @cindex indirect calls, PowerPC
5897 @cindex @code{longcall} function attribute, PowerPC
5898 @cindex @code{shortcall} function attribute, PowerPC
5899 The @code{longcall} attribute
5900 indicates that the function might be far away from the call site and
5901 require a different (more expensive) calling sequence. The
5902 @code{shortcall} attribute indicates that the function is always close
5903 enough for the shorter calling sequence to be used. These attributes
5904 override both the @option{-mlongcall} switch and
5905 the @code{#pragma longcall} setting.
5907 @xref{RS/6000 and PowerPC Options}, for more information on whether long
5908 calls are necessary.
5910 @item target (@var{options})
5911 @cindex @code{target} function attribute
5912 As discussed in @ref{Common Function Attributes}, this attribute
5913 allows specification of target-specific compilation options.
5915 On the PowerPC, the following options are allowed:
5920 @cindex @code{target("altivec")} function attribute, PowerPC
5921 Generate code that uses (does not use) AltiVec instructions. In
5922 32-bit code, you cannot enable AltiVec instructions unless
5923 @option{-mabi=altivec} is used on the command line.
5927 @cindex @code{target("cmpb")} function attribute, PowerPC
5928 Generate code that uses (does not use) the compare bytes instruction
5929 implemented on the POWER6 processor and other processors that support
5930 the PowerPC V2.05 architecture.
5934 @cindex @code{target("dlmzb")} function attribute, PowerPC
5935 Generate code that uses (does not use) the string-search @samp{dlmzb}
5936 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
5937 generated by default when targeting those processors.
5941 @cindex @code{target("fprnd")} function attribute, PowerPC
5942 Generate code that uses (does not use) the FP round to integer
5943 instructions implemented on the POWER5+ processor and other processors
5944 that support the PowerPC V2.03 architecture.
5948 @cindex @code{target("hard-dfp")} function attribute, PowerPC
5949 Generate code that uses (does not use) the decimal floating-point
5950 instructions implemented on some POWER processors.
5954 @cindex @code{target("isel")} function attribute, PowerPC
5955 Generate code that uses (does not use) ISEL instruction.
5959 @cindex @code{target("mfcrf")} function attribute, PowerPC
5960 Generate code that uses (does not use) the move from condition
5961 register field instruction implemented on the POWER4 processor and
5962 other processors that support the PowerPC V2.01 architecture.
5966 @cindex @code{target("mulhw")} function attribute, PowerPC
5967 Generate code that uses (does not use) the half-word multiply and
5968 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
5969 These instructions are generated by default when targeting those
5974 @cindex @code{target("multiple")} function attribute, PowerPC
5975 Generate code that uses (does not use) the load multiple word
5976 instructions and the store multiple word instructions.
5980 @cindex @code{target("update")} function attribute, PowerPC
5981 Generate code that uses (does not use) the load or store instructions
5982 that update the base register to the address of the calculated memory
5987 @cindex @code{target("popcntb")} function attribute, PowerPC
5988 Generate code that uses (does not use) the popcount and double-precision
5989 FP reciprocal estimate instruction implemented on the POWER5
5990 processor and other processors that support the PowerPC V2.02
5995 @cindex @code{target("popcntd")} function attribute, PowerPC
5996 Generate code that uses (does not use) the popcount instruction
5997 implemented on the POWER7 processor and other processors that support
5998 the PowerPC V2.06 architecture.
6000 @item powerpc-gfxopt
6001 @itemx no-powerpc-gfxopt
6002 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
6003 Generate code that uses (does not use) the optional PowerPC
6004 architecture instructions in the Graphics group, including
6005 floating-point select.
6008 @itemx no-powerpc-gpopt
6009 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
6010 Generate code that uses (does not use) the optional PowerPC
6011 architecture instructions in the General Purpose group, including
6012 floating-point square root.
6014 @item recip-precision
6015 @itemx no-recip-precision
6016 @cindex @code{target("recip-precision")} function attribute, PowerPC
6017 Assume (do not assume) that the reciprocal estimate instructions
6018 provide higher-precision estimates than is mandated by the PowerPC
6023 @cindex @code{target("string")} function attribute, PowerPC
6024 Generate code that uses (does not use) the load string instructions
6025 and the store string word instructions to save multiple registers and
6026 do small block moves.
6030 @cindex @code{target("vsx")} function attribute, PowerPC
6031 Generate code that uses (does not use) vector/scalar (VSX)
6032 instructions, and also enable the use of built-in functions that allow
6033 more direct access to the VSX instruction set. In 32-bit code, you
6034 cannot enable VSX or AltiVec instructions unless
6035 @option{-mabi=altivec} is used on the command line.
6039 @cindex @code{target("friz")} function attribute, PowerPC
6040 Generate (do not generate) the @code{friz} instruction when the
6041 @option{-funsafe-math-optimizations} option is used to optimize
6042 rounding a floating-point value to 64-bit integer and back to floating
6043 point. The @code{friz} instruction does not return the same value if
6044 the floating-point number is too large to fit in an integer.
6046 @item avoid-indexed-addresses
6047 @itemx no-avoid-indexed-addresses
6048 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
6049 Generate code that tries to avoid (not avoid) the use of indexed load
6050 or store instructions.
6054 @cindex @code{target("paired")} function attribute, PowerPC
6055 Generate code that uses (does not use) the generation of PAIRED simd
6060 @cindex @code{target("longcall")} function attribute, PowerPC
6061 Generate code that assumes (does not assume) that all calls are far
6062 away so that a longer more expensive calling sequence is required.
6065 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
6066 Specify the architecture to generate code for when compiling the
6067 function. If you select the @code{target("cpu=power7")} attribute when
6068 generating 32-bit code, VSX and AltiVec instructions are not generated
6069 unless you use the @option{-mabi=altivec} option on the command line.
6071 @item tune=@var{TUNE}
6072 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
6073 Specify the architecture to tune for when compiling the function. If
6074 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
6075 you do specify the @code{target("cpu=@var{CPU}")} attribute,
6076 compilation tunes for the @var{CPU} architecture, and not the
6077 default tuning specified on the command line.
6080 On the PowerPC, the inliner does not inline a
6081 function that has different target options than the caller, unless the
6082 callee has a subset of the target options of the caller.
6085 @node RISC-V Function Attributes
6086 @subsection RISC-V Function Attributes
6088 These function attributes are supported by the RISC-V back end:
6092 @cindex @code{naked} function attribute, RISC-V
6093 This attribute allows the compiler to construct the
6094 requisite function declaration, while allowing the body of the
6095 function to be assembly code. The specified function will not have
6096 prologue/epilogue sequences generated by the compiler. Only basic
6097 @code{asm} statements can safely be included in naked functions
6098 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6099 basic @code{asm} and C code may appear to work, they cannot be
6100 depended upon to work reliably and are not supported.
6103 @cindex @code{interrupt} function attribute, RISC-V
6104 Use this attribute to indicate that the specified function is an interrupt
6105 handler. The compiler generates function entry and exit sequences suitable
6106 for use in an interrupt handler when this attribute is present.
6108 You can specify the kind of interrupt to be handled by adding an optional
6109 parameter to the interrupt attribute like this:
6112 void f (void) __attribute__ ((interrupt ("user")));
6115 Permissible values for this parameter are @code{user}, @code{supervisor},
6116 and @code{machine}. If there is no parameter, then it defaults to
6120 @node RL78 Function Attributes
6121 @subsection RL78 Function Attributes
6123 These function attributes are supported by the RL78 back end:
6127 @itemx brk_interrupt
6128 @cindex @code{interrupt} function attribute, RL78
6129 @cindex @code{brk_interrupt} function attribute, RL78
6130 These attributes indicate
6131 that the specified function is an interrupt handler. The compiler generates
6132 function entry and exit sequences suitable for use in an interrupt handler
6133 when this attribute is present.
6135 Use @code{brk_interrupt} instead of @code{interrupt} for
6136 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
6137 that must end with @code{RETB} instead of @code{RETI}).
6140 @cindex @code{naked} function attribute, RL78
6141 This attribute allows the compiler to construct the
6142 requisite function declaration, while allowing the body of the
6143 function to be assembly code. The specified function will not have
6144 prologue/epilogue sequences generated by the compiler. Only basic
6145 @code{asm} statements can safely be included in naked functions
6146 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6147 basic @code{asm} and C code may appear to work, they cannot be
6148 depended upon to work reliably and are not supported.
6151 @node RX Function Attributes
6152 @subsection RX Function Attributes
6154 These function attributes are supported by the RX back end:
6157 @item fast_interrupt
6158 @cindex @code{fast_interrupt} function attribute, RX
6159 Use this attribute on the RX port to indicate that the specified
6160 function is a fast interrupt handler. This is just like the
6161 @code{interrupt} attribute, except that @code{freit} is used to return
6162 instead of @code{reit}.
6165 @cindex @code{interrupt} function attribute, RX
6166 Use this attribute to indicate
6167 that the specified function is an interrupt handler. The compiler generates
6168 function entry and exit sequences suitable for use in an interrupt handler
6169 when this attribute is present.
6171 On RX and RL78 targets, you may specify one or more vector numbers as arguments
6172 to the attribute, as well as naming an alternate table name.
6173 Parameters are handled sequentially, so one handler can be assigned to
6174 multiple entries in multiple tables. One may also pass the magic
6175 string @code{"$default"} which causes the function to be used for any
6176 unfilled slots in the current table.
6178 This example shows a simple assignment of a function to one vector in
6179 the default table (note that preprocessor macros may be used for
6180 chip-specific symbolic vector names):
6182 void __attribute__ ((interrupt (5))) txd1_handler ();
6185 This example assigns a function to two slots in the default table
6186 (using preprocessor macros defined elsewhere) and makes it the default
6187 for the @code{dct} table:
6189 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
6194 @cindex @code{naked} function attribute, RX
6195 This attribute allows the compiler to construct the
6196 requisite function declaration, while allowing the body of the
6197 function to be assembly code. The specified function will not have
6198 prologue/epilogue sequences generated by the compiler. Only basic
6199 @code{asm} statements can safely be included in naked functions
6200 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6201 basic @code{asm} and C code may appear to work, they cannot be
6202 depended upon to work reliably and are not supported.
6205 @cindex @code{vector} function attribute, RX
6206 This RX attribute is similar to the @code{interrupt} attribute, including its
6207 parameters, but does not make the function an interrupt-handler type
6208 function (i.e.@: it retains the normal C function calling ABI). See the
6209 @code{interrupt} attribute for a description of its arguments.
6212 @node S/390 Function Attributes
6213 @subsection S/390 Function Attributes
6215 These function attributes are supported on the S/390:
6218 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
6219 @cindex @code{hotpatch} function attribute, S/390
6221 On S/390 System z targets, you can use this function attribute to
6222 make GCC generate a ``hot-patching'' function prologue. If the
6223 @option{-mhotpatch=} command-line option is used at the same time,
6224 the @code{hotpatch} attribute takes precedence. The first of the
6225 two arguments specifies the number of halfwords to be added before
6226 the function label. A second argument can be used to specify the
6227 number of halfwords to be added after the function label. For
6228 both arguments the maximum allowed value is 1000000.
6230 If both arguments are zero, hotpatching is disabled.
6232 @item target (@var{options})
6233 @cindex @code{target} function attribute
6234 As discussed in @ref{Common Function Attributes}, this attribute
6235 allows specification of target-specific compilation options.
6237 On S/390, the following options are supported:
6245 @item warn-framesize=
6257 @itemx no-packed-stack
6259 @itemx no-small-exec
6262 @item warn-dynamicstack
6263 @itemx no-warn-dynamicstack
6266 The options work exactly like the S/390 specific command line
6267 options (without the prefix @option{-m}) except that they do not
6268 change any feature macros. For example,
6271 @code{target("no-vx")}
6274 does not undefine the @code{__VEC__} macro.
6277 @node SH Function Attributes
6278 @subsection SH Function Attributes
6280 These function attributes are supported on the SH family of processors:
6283 @item function_vector
6284 @cindex @code{function_vector} function attribute, SH
6285 @cindex calling functions through the function vector on SH2A
6286 On SH2A targets, this attribute declares a function to be called using the
6287 TBR relative addressing mode. The argument to this attribute is the entry
6288 number of the same function in a vector table containing all the TBR
6289 relative addressable functions. For correct operation the TBR must be setup
6290 accordingly to point to the start of the vector table before any functions with
6291 this attribute are invoked. Usually a good place to do the initialization is
6292 the startup routine. The TBR relative vector table can have at max 256 function
6293 entries. The jumps to these functions are generated using a SH2A specific,
6294 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
6295 from GNU binutils version 2.7 or later for this attribute to work correctly.
6297 In an application, for a function being called once, this attribute
6298 saves at least 8 bytes of code; and if other successive calls are being
6299 made to the same function, it saves 2 bytes of code per each of these
6302 @item interrupt_handler
6303 @cindex @code{interrupt_handler} function attribute, SH
6304 Use this attribute to
6305 indicate that the specified function is an interrupt handler. The compiler
6306 generates function entry and exit sequences suitable for use in an
6307 interrupt handler when this attribute is present.
6309 @item nosave_low_regs
6310 @cindex @code{nosave_low_regs} function attribute, SH
6311 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
6312 function should not save and restore registers R0..R7. This can be used on SH3*
6313 and SH4* targets that have a second R0..R7 register bank for non-reentrant
6317 @cindex @code{renesas} function attribute, SH
6318 On SH targets this attribute specifies that the function or struct follows the
6322 @cindex @code{resbank} function attribute, SH
6323 On the SH2A target, this attribute enables the high-speed register
6324 saving and restoration using a register bank for @code{interrupt_handler}
6325 routines. Saving to the bank is performed automatically after the CPU
6326 accepts an interrupt that uses a register bank.
6328 The nineteen 32-bit registers comprising general register R0 to R14,
6329 control register GBR, and system registers MACH, MACL, and PR and the
6330 vector table address offset are saved into a register bank. Register
6331 banks are stacked in first-in last-out (FILO) sequence. Restoration
6332 from the bank is executed by issuing a RESBANK instruction.
6335 @cindex @code{sp_switch} function attribute, SH
6336 Use this attribute on the SH to indicate an @code{interrupt_handler}
6337 function should switch to an alternate stack. It expects a string
6338 argument that names a global variable holding the address of the
6343 void f () __attribute__ ((interrupt_handler,
6344 sp_switch ("alt_stack")));
6348 @cindex @code{trap_exit} function attribute, SH
6349 Use this attribute on the SH for an @code{interrupt_handler} to return using
6350 @code{trapa} instead of @code{rte}. This attribute expects an integer
6351 argument specifying the trap number to be used.
6354 @cindex @code{trapa_handler} function attribute, SH
6355 On SH targets this function attribute is similar to @code{interrupt_handler}
6356 but it does not save and restore all registers.
6359 @node Symbian OS Function Attributes
6360 @subsection Symbian OS Function Attributes
6362 @xref{Microsoft Windows Function Attributes}, for discussion of the
6363 @code{dllexport} and @code{dllimport} attributes.
6365 @node V850 Function Attributes
6366 @subsection V850 Function Attributes
6368 The V850 back end supports these function attributes:
6372 @itemx interrupt_handler
6373 @cindex @code{interrupt} function attribute, V850
6374 @cindex @code{interrupt_handler} function attribute, V850
6375 Use these attributes to indicate
6376 that the specified function is an interrupt handler. The compiler generates
6377 function entry and exit sequences suitable for use in an interrupt handler
6378 when either attribute is present.
6381 @node Visium Function Attributes
6382 @subsection Visium Function Attributes
6384 These function attributes are supported by the Visium back end:
6388 @cindex @code{interrupt} function attribute, Visium
6389 Use this attribute to indicate
6390 that the specified function is an interrupt handler. The compiler generates
6391 function entry and exit sequences suitable for use in an interrupt handler
6392 when this attribute is present.
6395 @node x86 Function Attributes
6396 @subsection x86 Function Attributes
6398 These function attributes are supported by the x86 back end:
6402 @cindex @code{cdecl} function attribute, x86-32
6403 @cindex functions that pop the argument stack on x86-32
6405 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
6406 assume that the calling function pops off the stack space used to
6407 pass arguments. This is
6408 useful to override the effects of the @option{-mrtd} switch.
6411 @cindex @code{fastcall} function attribute, x86-32
6412 @cindex functions that pop the argument stack on x86-32
6413 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
6414 pass the first argument (if of integral type) in the register ECX and
6415 the second argument (if of integral type) in the register EDX@. Subsequent
6416 and other typed arguments are passed on the stack. The called function
6417 pops the arguments off the stack. If the number of arguments is variable all
6418 arguments are pushed on the stack.
6421 @cindex @code{thiscall} function attribute, x86-32
6422 @cindex functions that pop the argument stack on x86-32
6423 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
6424 pass the first argument (if of integral type) in the register ECX.
6425 Subsequent and other typed arguments are passed on the stack. The called
6426 function pops the arguments off the stack.
6427 If the number of arguments is variable all arguments are pushed on the
6429 The @code{thiscall} attribute is intended for C++ non-static member functions.
6430 As a GCC extension, this calling convention can be used for C functions
6431 and for static member methods.
6435 @cindex @code{ms_abi} function attribute, x86
6436 @cindex @code{sysv_abi} function attribute, x86
6438 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
6439 to indicate which calling convention should be used for a function. The
6440 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
6441 while the @code{sysv_abi} attribute tells the compiler to use the System V
6442 ELF ABI, which is used on GNU/Linux and other systems. The default is to use
6443 the Microsoft ABI when targeting Windows. On all other systems, the default
6444 is the System V ELF ABI.
6446 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
6447 requires the @option{-maccumulate-outgoing-args} option.
6449 @item callee_pop_aggregate_return (@var{number})
6450 @cindex @code{callee_pop_aggregate_return} function attribute, x86
6452 On x86-32 targets, you can use this attribute to control how
6453 aggregates are returned in memory. If the caller is responsible for
6454 popping the hidden pointer together with the rest of the arguments, specify
6455 @var{number} equal to zero. If callee is responsible for popping the
6456 hidden pointer, specify @var{number} equal to one.
6458 The default x86-32 ABI assumes that the callee pops the
6459 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
6460 the compiler assumes that the
6461 caller pops the stack for hidden pointer.
6463 @item ms_hook_prologue
6464 @cindex @code{ms_hook_prologue} function attribute, x86
6466 On 32-bit and 64-bit x86 targets, you can use
6467 this function attribute to make GCC generate the ``hot-patching'' function
6468 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
6472 @cindex @code{naked} function attribute, x86
6473 This attribute allows the compiler to construct the
6474 requisite function declaration, while allowing the body of the
6475 function to be assembly code. The specified function will not have
6476 prologue/epilogue sequences generated by the compiler. Only basic
6477 @code{asm} statements can safely be included in naked functions
6478 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6479 basic @code{asm} and C code may appear to work, they cannot be
6480 depended upon to work reliably and are not supported.
6482 @item regparm (@var{number})
6483 @cindex @code{regparm} function attribute, x86
6484 @cindex functions that are passed arguments in registers on x86-32
6485 On x86-32 targets, the @code{regparm} attribute causes the compiler to
6486 pass arguments number one to @var{number} if they are of integral type
6487 in registers EAX, EDX, and ECX instead of on the stack. Functions that
6488 take a variable number of arguments continue to be passed all of their
6489 arguments on the stack.
6491 Beware that on some ELF systems this attribute is unsuitable for
6492 global functions in shared libraries with lazy binding (which is the
6493 default). Lazy binding sends the first call via resolving code in
6494 the loader, which might assume EAX, EDX and ECX can be clobbered, as
6495 per the standard calling conventions. Solaris 8 is affected by this.
6496 Systems with the GNU C Library version 2.1 or higher
6497 and FreeBSD are believed to be
6498 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
6499 disabled with the linker or the loader if desired, to avoid the
6503 @cindex @code{sseregparm} function attribute, x86
6504 On x86-32 targets with SSE support, the @code{sseregparm} attribute
6505 causes the compiler to pass up to 3 floating-point arguments in
6506 SSE registers instead of on the stack. Functions that take a
6507 variable number of arguments continue to pass all of their
6508 floating-point arguments on the stack.
6510 @item force_align_arg_pointer
6511 @cindex @code{force_align_arg_pointer} function attribute, x86
6512 On x86 targets, the @code{force_align_arg_pointer} attribute may be
6513 applied to individual function definitions, generating an alternate
6514 prologue and epilogue that realigns the run-time stack if necessary.
6515 This supports mixing legacy codes that run with a 4-byte aligned stack
6516 with modern codes that keep a 16-byte stack for SSE compatibility.
6519 @cindex @code{stdcall} function attribute, x86-32
6520 @cindex functions that pop the argument stack on x86-32
6521 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
6522 assume that the called function pops off the stack space used to
6523 pass arguments, unless it takes a variable number of arguments.
6525 @item no_caller_saved_registers
6526 @cindex @code{no_caller_saved_registers} function attribute, x86
6527 Use this attribute to indicate that the specified function has no
6528 caller-saved registers. That is, all registers are callee-saved. For
6529 example, this attribute can be used for a function called from an
6530 interrupt handler. The compiler generates proper function entry and
6531 exit sequences to save and restore any modified registers, except for
6532 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
6533 states, the GCC option @option{-mgeneral-regs-only} should be used to
6534 compile functions with @code{no_caller_saved_registers} attribute.
6537 @cindex @code{interrupt} function attribute, x86
6538 Use this attribute to indicate that the specified function is an
6539 interrupt handler or an exception handler (depending on parameters passed
6540 to the function, explained further). The compiler generates function
6541 entry and exit sequences suitable for use in an interrupt handler when
6542 this attribute is present. The @code{IRET} instruction, instead of the
6543 @code{RET} instruction, is used to return from interrupt handlers. All
6544 registers, except for the EFLAGS register which is restored by the
6545 @code{IRET} instruction, are preserved by the compiler. Since GCC
6546 doesn't preserve SSE, MMX nor x87 states, the GCC option
6547 @option{-mgeneral-regs-only} should be used to compile interrupt and
6550 Any interruptible-without-stack-switch code must be compiled with
6551 @option{-mno-red-zone} since interrupt handlers can and will, because
6552 of the hardware design, touch the red zone.
6554 An interrupt handler must be declared with a mandatory pointer
6558 struct interrupt_frame;
6560 __attribute__ ((interrupt))
6562 f (struct interrupt_frame *frame)
6568 and you must define @code{struct interrupt_frame} as described in the
6571 Exception handlers differ from interrupt handlers because the system
6572 pushes an error code on the stack. An exception handler declaration is
6573 similar to that for an interrupt handler, but with a different mandatory
6574 function signature. The compiler arranges to pop the error code off the
6575 stack before the @code{IRET} instruction.
6579 typedef unsigned long long int uword_t;
6581 typedef unsigned int uword_t;
6584 struct interrupt_frame;
6586 __attribute__ ((interrupt))
6588 f (struct interrupt_frame *frame, uword_t error_code)
6594 Exception handlers should only be used for exceptions that push an error
6595 code; you should use an interrupt handler in other cases. The system
6596 will crash if the wrong kind of handler is used.
6598 @item target (@var{options})
6599 @cindex @code{target} function attribute
6600 As discussed in @ref{Common Function Attributes}, this attribute
6601 allows specification of target-specific compilation options.
6603 On the x86, the following options are allowed:
6607 @cindex @code{target("3dnow")} function attribute, x86
6608 Enable/disable the generation of the 3DNow!@: instructions.
6612 @cindex @code{target("3dnowa")} function attribute, x86
6613 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6617 @cindex @code{target("abm")} function attribute, x86
6618 Enable/disable the generation of the advanced bit instructions.
6622 @cindex @code{target("adx")} function attribute, x86
6623 Enable/disable the generation of the ADX instructions.
6627 @cindex @code{target("aes")} function attribute, x86
6628 Enable/disable the generation of the AES instructions.
6632 @cindex @code{target("avx")} function attribute, x86
6633 Enable/disable the generation of the AVX instructions.
6637 @cindex @code{target("avx2")} function attribute, x86
6638 Enable/disable the generation of the AVX2 instructions.
6641 @itemx no-avx5124fmaps
6642 @cindex @code{target("avx5124fmaps")} function attribute, x86
6643 Enable/disable the generation of the AVX5124FMAPS instructions.
6646 @itemx no-avx5124vnniw
6647 @cindex @code{target("avx5124vnniw")} function attribute, x86
6648 Enable/disable the generation of the AVX5124VNNIW instructions.
6651 @itemx no-avx512bitalg
6652 @cindex @code{target("avx512bitalg")} function attribute, x86
6653 Enable/disable the generation of the AVX512BITALG instructions.
6657 @cindex @code{target("avx512bw")} function attribute, x86
6658 Enable/disable the generation of the AVX512BW instructions.
6662 @cindex @code{target("avx512cd")} function attribute, x86
6663 Enable/disable the generation of the AVX512CD instructions.
6667 @cindex @code{target("avx512dq")} function attribute, x86
6668 Enable/disable the generation of the AVX512DQ instructions.
6672 @cindex @code{target("avx512er")} function attribute, x86
6673 Enable/disable the generation of the AVX512ER instructions.
6677 @cindex @code{target("avx512f")} function attribute, x86
6678 Enable/disable the generation of the AVX512F instructions.
6681 @itemx no-avx512ifma
6682 @cindex @code{target("avx512ifma")} function attribute, x86
6683 Enable/disable the generation of the AVX512IFMA instructions.
6687 @cindex @code{target("avx512pf")} function attribute, x86
6688 Enable/disable the generation of the AVX512PF instructions.
6691 @itemx no-avx512vbmi
6692 @cindex @code{target("avx512vbmi")} function attribute, x86
6693 Enable/disable the generation of the AVX512VBMI instructions.
6696 @itemx no-avx512vbmi2
6697 @cindex @code{target("avx512vbmi2")} function attribute, x86
6698 Enable/disable the generation of the AVX512VBMI2 instructions.
6702 @cindex @code{target("avx512vl")} function attribute, x86
6703 Enable/disable the generation of the AVX512VL instructions.
6706 @itemx no-avx512vnni
6707 @cindex @code{target("avx512vnni")} function attribute, x86
6708 Enable/disable the generation of the AVX512VNNI instructions.
6710 @item avx512vpopcntdq
6711 @itemx no-avx512vpopcntdq
6712 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6713 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6717 @cindex @code{target("bmi")} function attribute, x86
6718 Enable/disable the generation of the BMI instructions.
6722 @cindex @code{target("bmi2")} function attribute, x86
6723 Enable/disable the generation of the BMI2 instructions.
6727 @cindex @code{target("cldemote")} function attribute, x86
6728 Enable/disable the generation of the CLDEMOTE instructions.
6731 @itemx no-clflushopt
6732 @cindex @code{target("clflushopt")} function attribute, x86
6733 Enable/disable the generation of the CLFLUSHOPT instructions.
6737 @cindex @code{target("clwb")} function attribute, x86
6738 Enable/disable the generation of the CLWB instructions.
6742 @cindex @code{target("clzero")} function attribute, x86
6743 Enable/disable the generation of the CLZERO instructions.
6747 @cindex @code{target("crc32")} function attribute, x86
6748 Enable/disable the generation of the CRC32 instructions.
6752 @cindex @code{target("cx16")} function attribute, x86
6753 Enable/disable the generation of the CMPXCHG16B instructions.
6756 @cindex @code{target("default")} function attribute, x86
6757 @xref{Function Multiversioning}, where it is used to specify the
6758 default function version.
6762 @cindex @code{target("f16c")} function attribute, x86
6763 Enable/disable the generation of the F16C instructions.
6767 @cindex @code{target("fma")} function attribute, x86
6768 Enable/disable the generation of the FMA instructions.
6772 @cindex @code{target("fma4")} function attribute, x86
6773 Enable/disable the generation of the FMA4 instructions.
6777 @cindex @code{target("fsgsbase")} function attribute, x86
6778 Enable/disable the generation of the FSGSBASE instructions.
6782 @cindex @code{target("fxsr")} function attribute, x86
6783 Enable/disable the generation of the FXSR instructions.
6787 @cindex @code{target("gfni")} function attribute, x86
6788 Enable/disable the generation of the GFNI instructions.
6792 @cindex @code{target("hle")} function attribute, x86
6793 Enable/disable the generation of the HLE instruction prefixes.
6797 @cindex @code{target("lwp")} function attribute, x86
6798 Enable/disable the generation of the LWP instructions.
6802 @cindex @code{target("lzcnt")} function attribute, x86
6803 Enable/disable the generation of the LZCNT instructions.
6807 @cindex @code{target("mmx")} function attribute, x86
6808 Enable/disable the generation of the MMX instructions.
6812 @cindex @code{target("movbe")} function attribute, x86
6813 Enable/disable the generation of the MOVBE instructions.
6817 @cindex @code{target("movdir64b")} function attribute, x86
6818 Enable/disable the generation of the MOVDIR64B instructions.
6822 @cindex @code{target("movdiri")} function attribute, x86
6823 Enable/disable the generation of the MOVDIRI instructions.
6827 @cindex @code{target("mwait")} function attribute, x86
6828 Enable/disable the generation of the MWAIT and MONITOR instructions.
6832 @cindex @code{target("mwaitx")} function attribute, x86
6833 Enable/disable the generation of the MWAITX instructions.
6837 @cindex @code{target("pclmul")} function attribute, x86
6838 Enable/disable the generation of the PCLMUL instructions.
6842 @cindex @code{target("pconfig")} function attribute, x86
6843 Enable/disable the generation of the PCONFIG instructions.
6847 @cindex @code{target("pku")} function attribute, x86
6848 Enable/disable the generation of the PKU instructions.
6852 @cindex @code{target("popcnt")} function attribute, x86
6853 Enable/disable the generation of the POPCNT instruction.
6856 @itemx no-prefetchwt1
6857 @cindex @code{target("prefetchwt1")} function attribute, x86
6858 Enable/disable the generation of the PREFETCHWT1 instructions.
6862 @cindex @code{target("prfchw")} function attribute, x86
6863 Enable/disable the generation of the PREFETCHW instruction.
6867 @cindex @code{target("ptwrite")} function attribute, x86
6868 Enable/disable the generation of the PTWRITE instructions.
6872 @cindex @code{target("rdpid")} function attribute, x86
6873 Enable/disable the generation of the RDPID instructions.
6877 @cindex @code{target("rdrnd")} function attribute, x86
6878 Enable/disable the generation of the RDRND instructions.
6882 @cindex @code{target("rdseed")} function attribute, x86
6883 Enable/disable the generation of the RDSEED instructions.
6887 @cindex @code{target("rtm")} function attribute, x86
6888 Enable/disable the generation of the RTM instructions.
6892 @cindex @code{target("sahf")} function attribute, x86
6893 Enable/disable the generation of the SAHF instructions.
6897 @cindex @code{target("sgx")} function attribute, x86
6898 Enable/disable the generation of the SGX instructions.
6902 @cindex @code{target("sha")} function attribute, x86
6903 Enable/disable the generation of the SHA instructions.
6907 @cindex @code{target("shstk")} function attribute, x86
6908 Enable/disable the shadow stack built-in functions from CET.
6912 @cindex @code{target("sse")} function attribute, x86
6913 Enable/disable the generation of the SSE instructions.
6917 @cindex @code{target("sse2")} function attribute, x86
6918 Enable/disable the generation of the SSE2 instructions.
6922 @cindex @code{target("sse3")} function attribute, x86
6923 Enable/disable the generation of the SSE3 instructions.
6927 @cindex @code{target("sse4")} function attribute, x86
6928 Enable/disable the generation of the SSE4 instructions (both SSE4.1
6933 @cindex @code{target("sse4.1")} function attribute, x86
6934 Enable/disable the generation of the SSE4.1 instructions.
6938 @cindex @code{target("sse4.2")} function attribute, x86
6939 Enable/disable the generation of the SSE4.2 instructions.
6943 @cindex @code{target("sse4a")} function attribute, x86
6944 Enable/disable the generation of the SSE4A instructions.
6948 @cindex @code{target("ssse3")} function attribute, x86
6949 Enable/disable the generation of the SSSE3 instructions.
6953 @cindex @code{target("tbm")} function attribute, x86
6954 Enable/disable the generation of the TBM instructions.
6958 @cindex @code{target("vaes")} function attribute, x86
6959 Enable/disable the generation of the VAES instructions.
6962 @itemx no-vpclmulqdq
6963 @cindex @code{target("vpclmulqdq")} function attribute, x86
6964 Enable/disable the generation of the VPCLMULQDQ instructions.
6968 @cindex @code{target("waitpkg")} function attribute, x86
6969 Enable/disable the generation of the WAITPKG instructions.
6973 @cindex @code{target("wbnoinvd")} function attribute, x86
6974 Enable/disable the generation of the WBNOINVD instructions.
6978 @cindex @code{target("xop")} function attribute, x86
6979 Enable/disable the generation of the XOP instructions.
6983 @cindex @code{target("xsave")} function attribute, x86
6984 Enable/disable the generation of the XSAVE instructions.
6988 @cindex @code{target("xsavec")} function attribute, x86
6989 Enable/disable the generation of the XSAVEC instructions.
6993 @cindex @code{target("xsaveopt")} function attribute, x86
6994 Enable/disable the generation of the XSAVEOPT instructions.
6998 @cindex @code{target("xsaves")} function attribute, x86
6999 Enable/disable the generation of the XSAVES instructions.
7003 @cindex @code{target("amx-tile")} function attribute, x86
7004 Enable/disable the generation of the AMX-TILE instructions.
7008 @cindex @code{target("amx-int8")} function attribute, x86
7009 Enable/disable the generation of the AMX-INT8 instructions.
7013 @cindex @code{target("amx-bf16")} function attribute, x86
7014 Enable/disable the generation of the AMX-BF16 instructions.
7018 @cindex @code{target("uintr")} function attribute, x86
7019 Enable/disable the generation of the UINTR instructions.
7023 @cindex @code{target("hreset")} function attribute, x86
7024 Enable/disable the generation of the HRESET instruction.
7028 @cindex @code{target("kl")} function attribute, x86
7029 Enable/disable the generation of the KEYLOCKER instructions.
7033 @cindex @code{target("widekl")} function attribute, x86
7034 Enable/disable the generation of the WIDEKL instructions.
7038 @cindex @code{target("avxvnni")} function attribute, x86
7039 Enable/disable the generation of the AVXVNNI instructions.
7043 @cindex @code{target("cld")} function attribute, x86
7044 Enable/disable the generation of the CLD before string moves.
7046 @item fancy-math-387
7047 @itemx no-fancy-math-387
7048 @cindex @code{target("fancy-math-387")} function attribute, x86
7049 Enable/disable the generation of the @code{sin}, @code{cos}, and
7050 @code{sqrt} instructions on the 387 floating-point unit.
7054 @cindex @code{target("ieee-fp")} function attribute, x86
7055 Enable/disable the generation of floating point that depends on IEEE arithmetic.
7057 @item inline-all-stringops
7058 @itemx no-inline-all-stringops
7059 @cindex @code{target("inline-all-stringops")} function attribute, x86
7060 Enable/disable inlining of string operations.
7062 @item inline-stringops-dynamically
7063 @itemx no-inline-stringops-dynamically
7064 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
7065 Enable/disable the generation of the inline code to do small string
7066 operations and calling the library routines for large operations.
7068 @item align-stringops
7069 @itemx no-align-stringops
7070 @cindex @code{target("align-stringops")} function attribute, x86
7071 Do/do not align destination of inlined string operations.
7075 @cindex @code{target("recip")} function attribute, x86
7076 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
7077 instructions followed an additional Newton-Raphson step instead of
7078 doing a floating-point division.
7080 @item general-regs-only
7081 @cindex @code{target("general-regs-only")} function attribute, x86
7082 Generate code which uses only the general registers.
7084 @item arch=@var{ARCH}
7085 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
7086 Specify the architecture to generate code for in compiling the function.
7088 @item tune=@var{TUNE}
7089 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
7090 Specify the architecture to tune for in compiling the function.
7092 @item fpmath=@var{FPMATH}
7093 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
7094 Specify which floating-point unit to use. You must specify the
7095 @code{target("fpmath=sse,387")} option as
7096 @code{target("fpmath=sse+387")} because the comma would separate
7099 @item prefer-vector-width=@var{OPT}
7100 @cindex @code{prefer-vector-width} function attribute, x86
7101 On x86 targets, the @code{prefer-vector-width} attribute informs the
7102 compiler to use @var{OPT}-bit vector width in instructions
7103 instead of the default on the selected platform.
7105 Valid @var{OPT} values are:
7109 No extra limitations applied to GCC other than defined by the selected platform.
7112 Prefer 128-bit vector width for instructions.
7115 Prefer 256-bit vector width for instructions.
7118 Prefer 512-bit vector width for instructions.
7121 On the x86, the inliner does not inline a
7122 function that has different target options than the caller, unless the
7123 callee has a subset of the target options of the caller. For example
7124 a function declared with @code{target("sse3")} can inline a function
7125 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
7128 @item indirect_branch("@var{choice}")
7129 @cindex @code{indirect_branch} function attribute, x86
7130 On x86 targets, the @code{indirect_branch} attribute causes the compiler
7131 to convert indirect call and jump with @var{choice}. @samp{keep}
7132 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
7133 call and jump to call and return thunk. @samp{thunk-inline} converts
7134 indirect call and jump to inlined call and return thunk.
7135 @samp{thunk-extern} converts indirect call and jump to external call
7136 and return thunk provided in a separate object file.
7138 @item function_return("@var{choice}")
7139 @cindex @code{function_return} function attribute, x86
7140 On x86 targets, the @code{function_return} attribute causes the compiler
7141 to convert function return with @var{choice}. @samp{keep} keeps function
7142 return unmodified. @samp{thunk} converts function return to call and
7143 return thunk. @samp{thunk-inline} converts function return to inlined
7144 call and return thunk. @samp{thunk-extern} converts function return to
7145 external call and return thunk provided in a separate object file.
7148 @cindex @code{nocf_check} function attribute
7149 The @code{nocf_check} attribute on a function is used to inform the
7150 compiler that the function's prologue should not be instrumented when
7151 compiled with the @option{-fcf-protection=branch} option. The
7152 compiler assumes that the function's address is a valid target for a
7153 control-flow transfer.
7155 The @code{nocf_check} attribute on a type of pointer to function is
7156 used to inform the compiler that a call through the pointer should
7157 not be instrumented when compiled with the
7158 @option{-fcf-protection=branch} option. The compiler assumes
7159 that the function's address from the pointer is a valid target for
7160 a control-flow transfer. A direct function call through a function
7161 name is assumed to be a safe call thus direct calls are not
7162 instrumented by the compiler.
7164 The @code{nocf_check} attribute is applied to an object's type.
7165 In case of assignment of a function address or a function pointer to
7166 another pointer, the attribute is not carried over from the right-hand
7167 object's type; the type of left-hand object stays unchanged. The
7168 compiler checks for @code{nocf_check} attribute mismatch and reports
7169 a warning in case of mismatch.
7173 int foo (void) __attribute__(nocf_check);
7174 void (*foo1)(void) __attribute__(nocf_check);
7177 /* foo's address is assumed to be valid. */
7181 /* This call site is not checked for control-flow
7185 /* A warning is issued about attribute mismatch. */
7188 /* This call site is still not checked. */
7191 /* This call site is checked. */
7194 /* A warning is issued about attribute mismatch. */
7197 /* This call site is still checked. */
7205 @cindex @code{cf_check} function attribute, x86
7207 The @code{cf_check} attribute on a function is used to inform the
7208 compiler that ENDBR instruction should be placed at the function
7209 entry when @option{-fcf-protection=branch} is enabled.
7211 @item indirect_return
7212 @cindex @code{indirect_return} function attribute, x86
7214 The @code{indirect_return} attribute can be applied to a function,
7215 as well as variable or type of function pointer to inform the
7216 compiler that the function may return via indirect branch.
7218 @item fentry_name("@var{name}")
7219 @cindex @code{fentry_name} function attribute, x86
7220 On x86 targets, the @code{fentry_name} attribute sets the function to
7221 call on function entry when function instrumentation is enabled
7222 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
7223 nop sequence is generated.
7225 @item fentry_section("@var{name}")
7226 @cindex @code{fentry_section} function attribute, x86
7227 On x86 targets, the @code{fentry_section} attribute sets the name
7228 of the section to record function entry instrumentation calls in when
7229 enabled with @option{-pg -mrecord-mcount}
7231 @item nodirect_extern_access
7232 @cindex @code{nodirect_extern_access} function attribute
7233 @opindex mno-direct-extern-access
7234 This attribute, attached to a global variable or function, is the
7235 counterpart to option @option{-mno-direct-extern-access}.
7239 @node Xstormy16 Function Attributes
7240 @subsection Xstormy16 Function Attributes
7242 These function attributes are supported by the Xstormy16 back end:
7246 @cindex @code{interrupt} function attribute, Xstormy16
7247 Use this attribute to indicate
7248 that the specified function is an interrupt handler. The compiler generates
7249 function entry and exit sequences suitable for use in an interrupt handler
7250 when this attribute is present.
7253 @node Variable Attributes
7254 @section Specifying Attributes of Variables
7255 @cindex attribute of variables
7256 @cindex variable attributes
7258 The keyword @code{__attribute__} allows you to specify special properties
7259 of variables, function parameters, or structure, union, and, in C++, class
7260 members. This @code{__attribute__} keyword is followed by an attribute
7261 specification enclosed in double parentheses. Some attributes are currently
7262 defined generically for variables. Other attributes are defined for
7263 variables on particular target systems. Other attributes are available
7264 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
7265 enumerators (@pxref{Enumerator Attributes}), statements
7266 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
7267 Other front ends might define more attributes
7268 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
7270 @xref{Attribute Syntax}, for details of the exact syntax for using
7274 * Common Variable Attributes::
7275 * ARC Variable Attributes::
7276 * AVR Variable Attributes::
7277 * Blackfin Variable Attributes::
7278 * H8/300 Variable Attributes::
7279 * IA-64 Variable Attributes::
7280 * M32R/D Variable Attributes::
7281 * MeP Variable Attributes::
7282 * Microsoft Windows Variable Attributes::
7283 * MSP430 Variable Attributes::
7284 * Nvidia PTX Variable Attributes::
7285 * PowerPC Variable Attributes::
7286 * RL78 Variable Attributes::
7287 * V850 Variable Attributes::
7288 * x86 Variable Attributes::
7289 * Xstormy16 Variable Attributes::
7292 @node Common Variable Attributes
7293 @subsection Common Variable Attributes
7295 The following attributes are supported on most targets.
7299 @item alias ("@var{target}")
7300 @cindex @code{alias} variable attribute
7301 The @code{alias} variable attribute causes the declaration to be emitted
7302 as an alias for another symbol known as an @dfn{alias target}. Except
7303 for top-level qualifiers the alias target must have the same type as
7304 the alias. For instance, the following
7308 extern int __attribute__ ((alias ("var_target"))) var_alias;
7312 defines @code{var_alias} to be an alias for the @code{var_target} variable.
7314 It is an error if the alias target is not defined in the same translation
7317 Note that in the absence of the attribute GCC assumes that distinct
7318 declarations with external linkage denote distinct objects. Using both
7319 the alias and the alias target to access the same object is undefined
7320 in a translation unit without a declaration of the alias with the attribute.
7322 This attribute requires assembler and object file support, and may not be
7323 available on all targets.
7325 @cindex @code{aligned} variable attribute
7327 @itemx aligned (@var{alignment})
7328 The @code{aligned} attribute specifies a minimum alignment for the variable
7329 or structure field, measured in bytes. When specified, @var{alignment} must
7330 be an integer constant power of 2. Specifying no @var{alignment} argument
7331 implies the maximum alignment for the target, which is often, but by no
7332 means always, 8 or 16 bytes.
7334 For example, the declaration:
7337 int x __attribute__ ((aligned (16))) = 0;
7341 causes the compiler to allocate the global variable @code{x} on a
7342 16-byte boundary. On a 68040, this could be used in conjunction with
7343 an @code{asm} expression to access the @code{move16} instruction which
7344 requires 16-byte aligned operands.
7346 You can also specify the alignment of structure fields. For example, to
7347 create a double-word aligned @code{int} pair, you could write:
7350 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
7354 This is an alternative to creating a union with a @code{double} member,
7355 which forces the union to be double-word aligned.
7357 As in the preceding examples, you can explicitly specify the alignment
7358 (in bytes) that you wish the compiler to use for a given variable or
7359 structure field. Alternatively, you can leave out the alignment factor
7360 and just ask the compiler to align a variable or field to the
7361 default alignment for the target architecture you are compiling for.
7362 The default alignment is sufficient for all scalar types, but may not be
7363 enough for all vector types on a target that supports vector operations.
7364 The default alignment is fixed for a particular target ABI.
7366 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
7367 which is the largest alignment ever used for any data type on the
7368 target machine you are compiling for. For example, you could write:
7371 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
7374 The compiler automatically sets the alignment for the declared
7375 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
7376 often make copy operations more efficient, because the compiler can
7377 use whatever instructions copy the biggest chunks of memory when
7378 performing copies to or from the variables or fields that you have
7379 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
7380 may change depending on command-line options.
7382 When used on a struct, or struct member, the @code{aligned} attribute can
7383 only increase the alignment; in order to decrease it, the @code{packed}
7384 attribute must be specified as well. When used as part of a typedef, the
7385 @code{aligned} attribute can both increase and decrease alignment, and
7386 specifying the @code{packed} attribute generates a warning.
7388 Note that the effectiveness of @code{aligned} attributes for static
7389 variables may be limited by inherent limitations in the system linker
7390 and/or object file format. On some systems, the linker is
7391 only able to arrange for variables to be aligned up to a certain maximum
7392 alignment. (For some linkers, the maximum supported alignment may
7393 be very very small.) If your linker is only able to align variables
7394 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
7395 in an @code{__attribute__} still only provides you with 8-byte
7396 alignment. See your linker documentation for further information.
7398 Stack variables are not affected by linker restrictions; GCC can properly
7399 align them on any target.
7401 The @code{aligned} attribute can also be used for functions
7402 (@pxref{Common Function Attributes}.)
7404 @cindex @code{warn_if_not_aligned} variable attribute
7405 @item warn_if_not_aligned (@var{alignment})
7406 This attribute specifies a threshold for the structure field, measured
7407 in bytes. If the structure field is aligned below the threshold, a
7408 warning will be issued. For example, the declaration:
7415 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
7420 causes the compiler to issue an warning on @code{struct foo}, like
7421 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
7422 The compiler also issues a warning, like @samp{warning: 'x' offset
7423 8 in 'struct foo' isn't aligned to 16}, when the structure field has
7424 the misaligned offset:
7427 struct __attribute__ ((aligned (16))) foo
7431 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
7435 This warning can be disabled by @option{-Wno-if-not-aligned}.
7436 The @code{warn_if_not_aligned} attribute can also be used for types
7437 (@pxref{Common Type Attributes}.)
7439 @item alloc_size (@var{position})
7440 @itemx alloc_size (@var{position-1}, @var{position-2})
7441 @cindex @code{alloc_size} variable attribute
7442 The @code{alloc_size} variable attribute may be applied to the declaration
7443 of a pointer to a function that returns a pointer and takes at least one
7444 argument of an integer type. It indicates that the returned pointer points
7445 to an object whose size is given by the function argument at @var{position},
7446 or by the product of the arguments at @var{position-1} and @var{position-2}.
7447 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
7448 sizes are diagnosed when detected. GCC uses this information to improve
7449 the results of @code{__builtin_object_size}.
7451 For instance, the following declarations
7454 typedef __attribute__ ((alloc_size (1, 2))) void*
7455 (*calloc_ptr) (size_t, size_t);
7456 typedef __attribute__ ((alloc_size (1))) void*
7457 (*malloc_ptr) (size_t);
7461 specify that @code{calloc_ptr} is a pointer of a function that, like
7462 the standard C function @code{calloc}, returns an object whose size
7463 is given by the product of arguments 1 and 2, and similarly, that
7464 @code{malloc_ptr}, like the standard C function @code{malloc},
7465 returns an object whose size is given by argument 1 to the function.
7467 @item cleanup (@var{cleanup_function})
7468 @cindex @code{cleanup} variable attribute
7469 The @code{cleanup} attribute runs a function when the variable goes
7470 out of scope. This attribute can only be applied to auto function
7471 scope variables; it may not be applied to parameters or variables
7472 with static storage duration. The function must take one parameter,
7473 a pointer to a type compatible with the variable. The return value
7474 of the function (if any) is ignored.
7476 If @option{-fexceptions} is enabled, then @var{cleanup_function}
7477 is run during the stack unwinding that happens during the
7478 processing of the exception. Note that the @code{cleanup} attribute
7479 does not allow the exception to be caught, only to perform an action.
7480 It is undefined what happens if @var{cleanup_function} does not
7485 @cindex @code{common} variable attribute
7486 @cindex @code{nocommon} variable attribute
7489 The @code{common} attribute requests GCC to place a variable in
7490 ``common'' storage. The @code{nocommon} attribute requests the
7491 opposite---to allocate space for it directly.
7493 These attributes override the default chosen by the
7494 @option{-fno-common} and @option{-fcommon} flags respectively.
7497 @itemx copy (@var{variable})
7498 @cindex @code{copy} variable attribute
7499 The @code{copy} attribute applies the set of attributes with which
7500 @var{variable} has been declared to the declaration of the variable
7501 to which the attribute is applied. The attribute is designed for
7502 libraries that define aliases that are expected to specify the same
7503 set of attributes as the aliased symbols. The @code{copy} attribute
7504 can be used with variables, functions or types. However, the kind
7505 of symbol to which the attribute is applied (either varible or
7506 function) must match the kind of symbol to which the argument refers.
7507 The @code{copy} attribute copies only syntactic and semantic attributes
7508 but not attributes that affect a symbol's linkage or visibility such as
7509 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7510 attribute is also not copied. @xref{Common Function Attributes}.
7511 @xref{Common Type Attributes}.
7514 @itemx deprecated (@var{msg})
7515 @cindex @code{deprecated} variable attribute
7516 The @code{deprecated} attribute results in a warning if the variable
7517 is used anywhere in the source file. This is useful when identifying
7518 variables that are expected to be removed in a future version of a
7519 program. The warning also includes the location of the declaration
7520 of the deprecated variable, to enable users to easily find further
7521 information about why the variable is deprecated, or what they should
7522 do instead. Note that the warning only occurs for uses:
7525 extern int old_var __attribute__ ((deprecated));
7527 int new_fn () @{ return old_var; @}
7531 results in a warning on line 3 but not line 2. The optional @var{msg}
7532 argument, which must be a string, is printed in the warning if
7535 The @code{deprecated} attribute can also be used for functions and
7536 types (@pxref{Common Function Attributes},
7537 @pxref{Common Type Attributes}).
7539 The message attached to the attribute is affected by the setting of
7540 the @option{-fmessage-length} option.
7543 @itemx unavailable (@var{msg})
7544 @cindex @code{unavailable} variable attribute
7545 The @code{unavailable} attribute indicates that the variable so marked
7546 is not available, if it is used anywhere in the source file. It behaves
7547 in the same manner as the @code{deprecated} attribute except that the
7548 compiler will emit an error rather than a warning.
7550 It is expected that items marked as @code{deprecated} will eventually be
7551 withdrawn from interfaces, and then become unavailable. This attribute
7552 allows for marking them appropriately.
7554 The @code{unavailable} attribute can also be used for functions and
7555 types (@pxref{Common Function Attributes},
7556 @pxref{Common Type Attributes}).
7558 @item mode (@var{mode})
7559 @cindex @code{mode} variable attribute
7560 This attribute specifies the data type for the declaration---whichever
7561 type corresponds to the mode @var{mode}. This in effect lets you
7562 request an integer or floating-point type according to its width.
7564 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
7565 for a list of the possible keywords for @var{mode}.
7566 You may also specify a mode of @code{byte} or @code{__byte__} to
7567 indicate the mode corresponding to a one-byte integer, @code{word} or
7568 @code{__word__} for the mode of a one-word integer, and @code{pointer}
7569 or @code{__pointer__} for the mode used to represent pointers.
7572 @cindex @code{nonstring} variable attribute
7573 The @code{nonstring} variable attribute specifies that an object or member
7574 declaration with type array of @code{char}, @code{signed char}, or
7575 @code{unsigned char}, or pointer to such a type is intended to store
7576 character arrays that do not necessarily contain a terminating @code{NUL}.
7577 This is useful in detecting uses of such arrays or pointers with functions
7578 that expect @code{NUL}-terminated strings, and to avoid warnings when such
7579 an array or pointer is used as an argument to a bounded string manipulation
7580 function such as @code{strncpy}. For example, without the attribute, GCC
7581 will issue a warning for the @code{strncpy} call below because it may
7582 truncate the copy without appending the terminating @code{NUL} character.
7583 Using the attribute makes it possible to suppress the warning. However,
7584 when the array is declared with the attribute the call to @code{strlen} is
7585 diagnosed because when the array doesn't contain a @code{NUL}-terminated
7586 string the call is undefined. To copy, compare, of search non-string
7587 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
7588 and other functions that operate on arrays of bytes. In addition,
7589 calling @code{strnlen} and @code{strndup} with such arrays is safe
7590 provided a suitable bound is specified, and not diagnosed.
7595 char name [32] __attribute__ ((nonstring));
7598 int f (struct Data *pd, const char *s)
7600 strncpy (pd->name, s, sizeof pd->name);
7602 return strlen (pd->name); // unsafe, gets a warning
7607 @cindex @code{packed} variable attribute
7608 The @code{packed} attribute specifies that a structure member should have
7609 the smallest possible alignment---one bit for a bit-field and one byte
7610 otherwise, unless a larger value is specified with the @code{aligned}
7611 attribute. The attribute does not apply to non-member objects.
7613 For example in the structure below, the member array @code{x} is packed
7614 so that it immediately follows @code{a} with no intervening padding:
7620 int x[2] __attribute__ ((packed));
7624 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
7625 @code{packed} attribute on bit-fields of type @code{char}. This has
7626 been fixed in GCC 4.4 but the change can lead to differences in the
7627 structure layout. See the documentation of
7628 @option{-Wpacked-bitfield-compat} for more information.
7630 @item section ("@var{section-name}")
7631 @cindex @code{section} variable attribute
7632 Normally, the compiler places the objects it generates in sections like
7633 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
7634 or you need certain particular variables to appear in special sections,
7635 for example to map to special hardware. The @code{section}
7636 attribute specifies that a variable (or function) lives in a particular
7637 section. For example, this small program uses several specific section names:
7640 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
7641 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
7642 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
7643 int init_data __attribute__ ((section ("INITDATA")));
7647 /* @r{Initialize stack pointer} */
7648 init_sp (stack + sizeof (stack));
7650 /* @r{Initialize initialized data} */
7651 memcpy (&init_data, &data, &edata - &data);
7653 /* @r{Turn on the serial ports} */
7660 Use the @code{section} attribute with
7661 @emph{global} variables and not @emph{local} variables,
7662 as shown in the example.
7664 You may use the @code{section} attribute with initialized or
7665 uninitialized global variables but the linker requires
7666 each object be defined once, with the exception that uninitialized
7667 variables tentatively go in the @code{common} (or @code{bss}) section
7668 and can be multiply ``defined''. Using the @code{section} attribute
7669 changes what section the variable goes into and may cause the
7670 linker to issue an error if an uninitialized variable has multiple
7671 definitions. You can force a variable to be initialized with the
7672 @option{-fno-common} flag or the @code{nocommon} attribute.
7674 Some file formats do not support arbitrary sections so the @code{section}
7675 attribute is not available on all platforms.
7676 If you need to map the entire contents of a module to a particular
7677 section, consider using the facilities of the linker instead.
7679 @item tls_model ("@var{tls_model}")
7680 @cindex @code{tls_model} variable attribute
7681 The @code{tls_model} attribute sets thread-local storage model
7682 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
7683 overriding @option{-ftls-model=} command-line switch on a per-variable
7685 The @var{tls_model} argument should be one of @code{global-dynamic},
7686 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
7688 Not all targets support this attribute.
7691 @cindex @code{unused} variable attribute
7692 This attribute, attached to a variable or structure field, means that
7693 the variable or field is meant to be possibly unused. GCC does not
7694 produce a warning for this variable or field.
7697 @cindex @code{used} variable attribute
7698 This attribute, attached to a variable with static storage, means that
7699 the variable must be emitted even if it appears that the variable is not
7702 When applied to a static data member of a C++ class template, the
7703 attribute also means that the member is instantiated if the
7704 class itself is instantiated.
7707 @cindex @code{retain} variable attribute
7708 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
7709 will save the variable from linker garbage collection. To support
7710 this behavior, variables that have not been placed in specific sections
7711 (e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
7712 will be placed in new, unique sections.
7714 This additional functionality requires Binutils version 2.36 or later.
7717 @cindex @code{uninitialized} variable attribute
7718 This attribute, attached to a variable with automatic storage, means that
7719 the variable should not be automatically initialized by the compiler when
7720 the option @code{-ftrivial-auto-var-init} presents.
7722 With the option @code{-ftrivial-auto-var-init}, all the automatic variables
7723 that do not have explicit initializers will be initialized by the compiler.
7724 These additional compiler initializations might incur run-time overhead,
7725 sometimes dramatically. This attribute can be used to mark some variables
7726 to be excluded from such automatical initialization in order to reduce runtime
7729 This attribute has no effect when the option @code{-ftrivial-auto-var-init}
7732 @item vector_size (@var{bytes})
7733 @cindex @code{vector_size} variable attribute
7734 This attribute specifies the vector size for the type of the declared
7735 variable, measured in bytes. The type to which it applies is known as
7736 the @dfn{base type}. The @var{bytes} argument must be a positive
7737 power-of-two multiple of the base type size. For example, the declaration:
7740 int foo __attribute__ ((vector_size (16)));
7744 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
7745 divided into @code{int} sized units. Assuming a 32-bit @code{int},
7746 @code{foo}'s type is a vector of four units of four bytes each, and
7747 the corresponding mode of @code{foo} is @code{V4SI}.
7748 @xref{Vector Extensions}, for details of manipulating vector variables.
7750 This attribute is only applicable to integral and floating scalars,
7751 although arrays, pointers, and function return values are allowed in
7752 conjunction with this construct.
7754 Aggregates with this attribute are invalid, even if they are of the same
7755 size as a corresponding scalar. For example, the declaration:
7758 struct S @{ int a; @};
7759 struct S __attribute__ ((vector_size (16))) foo;
7763 is invalid even if the size of the structure is the same as the size of
7766 @item visibility ("@var{visibility_type}")
7767 @cindex @code{visibility} variable attribute
7768 This attribute affects the linkage of the declaration to which it is attached.
7769 The @code{visibility} attribute is described in
7770 @ref{Common Function Attributes}.
7773 @cindex @code{weak} variable attribute
7774 The @code{weak} attribute is described in
7775 @ref{Common Function Attributes}.
7778 @cindex @code{noinit} variable attribute
7779 Any data with the @code{noinit} attribute will not be initialized by
7780 the C runtime startup code, or the program loader. Not initializing
7781 data in this way can reduce program startup times.
7783 This attribute is specific to ELF targets and relies on the linker
7784 script to place sections with the @code{.noinit} prefix in the right
7788 @cindex @code{persistent} variable attribute
7789 Any data with the @code{persistent} attribute will not be initialized by
7790 the C runtime startup code, but will be initialized by the program
7791 loader. This enables the value of the variable to @samp{persist}
7792 between processor resets.
7794 This attribute is specific to ELF targets and relies on the linker
7795 script to place the sections with the @code{.persistent} prefix in the
7796 right location. Specifically, some type of non-volatile, writeable
7799 @item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
7800 @cindex @code{objc_nullability} variable attribute
7801 This attribute applies to pointer variables only. It allows marking the
7802 pointer with one of four possible values describing the conditions under
7803 which the pointer might have a @code{nil} value. In most cases, the
7804 attribute is intended to be an internal representation for property and
7805 method nullability (specified by language keywords); it is not recommended
7808 When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
7809 known about the conditions in which the pointer might be @code{nil}. Making
7810 this state specific serves to avoid false positives in diagnostics.
7812 When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
7813 no meaning if it is @code{nil} and thus the compiler is free to emit
7814 diagnostics if it can be determined that the value will be @code{nil}.
7816 When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
7817 be @code{nil} and carry meaning as such.
7819 When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
7820 the context of property attribute lists) this describes the case in which a
7821 property setter may take the value @code{nil} (which perhaps causes the
7822 property to be reset in some manner to a default) but for which the property
7823 getter will never validly return @code{nil}.
7827 @node ARC Variable Attributes
7828 @subsection ARC Variable Attributes
7832 @cindex @code{aux} variable attribute, ARC
7833 The @code{aux} attribute is used to directly access the ARC's
7834 auxiliary register space from C. The auxilirary register number is
7835 given via attribute argument.
7839 @node AVR Variable Attributes
7840 @subsection AVR Variable Attributes
7844 @cindex @code{progmem} variable attribute, AVR
7845 The @code{progmem} attribute is used on the AVR to place read-only
7846 data in the non-volatile program memory (flash). The @code{progmem}
7847 attribute accomplishes this by putting respective variables into a
7848 section whose name starts with @code{.progmem}.
7850 This attribute works similar to the @code{section} attribute
7851 but adds additional checking.
7854 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers:
7855 @code{progmem} affects the location
7856 of the data but not how this data is accessed.
7857 In order to read data located with the @code{progmem} attribute
7858 (inline) assembler must be used.
7860 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
7861 #include <avr/pgmspace.h>
7863 /* Locate var in flash memory */
7864 const int var[2] PROGMEM = @{ 1, 2 @};
7866 int read_var (int i)
7868 /* Access var[] by accessor macro from avr/pgmspace.h */
7869 return (int) pgm_read_word (& var[i]);
7873 AVR is a Harvard architecture processor and data and read-only data
7874 normally resides in the data memory (RAM).
7876 See also the @ref{AVR Named Address Spaces} section for
7877 an alternate way to locate and access data in flash memory.
7879 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range:
7880 On such devices, there is no need for attribute @code{progmem} or
7881 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
7882 Just use standard C / C++. The compiler will generate @code{LD*}
7883 instructions. As flash memory is visible in the RAM address range,
7884 and the default linker script does @emph{not} locate @code{.rodata} in
7885 RAM, no special features are needed in order not to waste RAM for
7886 read-only data or to read from flash. You might even get slightly better
7888 avoiding @code{progmem} and @code{__flash}. This applies to devices from
7889 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
7892 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40:
7893 The compiler adds @code{0x4000}
7894 to the addresses of objects and declarations in @code{progmem} and locates
7895 the objects in flash memory, namely in section @code{.progmem.data}.
7896 The offset is needed because the flash memory is visible in the RAM
7897 address space starting at address @code{0x4000}.
7899 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
7900 no special functions or macros are needed.
7903 /* var is located in flash memory */
7904 extern const int var[2] __attribute__((progmem));
7906 int read_var (int i)
7912 Please notice that on these devices, there is no need for @code{progmem}
7918 @itemx io (@var{addr})
7919 @cindex @code{io} variable attribute, AVR
7920 Variables with the @code{io} attribute are used to address
7921 memory-mapped peripherals in the io address range.
7922 If an address is specified, the variable
7923 is assigned that address, and the value is interpreted as an
7924 address in the data address space.
7928 volatile int porta __attribute__((io (0x22)));
7931 The address specified in the address in the data address range.
7933 Otherwise, the variable it is not assigned an address, but the
7934 compiler will still use in/out instructions where applicable,
7935 assuming some other module assigns an address in the io address range.
7939 extern volatile int porta __attribute__((io));
7943 @itemx io_low (@var{addr})
7944 @cindex @code{io_low} variable attribute, AVR
7945 This is like the @code{io} attribute, but additionally it informs the
7946 compiler that the object lies in the lower half of the I/O area,
7947 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
7951 @itemx address (@var{addr})
7952 @cindex @code{address} variable attribute, AVR
7953 Variables with the @code{address} attribute are used to address
7954 memory-mapped peripherals that may lie outside the io address range.
7957 volatile int porta __attribute__((address (0x600)));
7961 @cindex @code{absdata} variable attribute, AVR
7962 Variables in static storage and with the @code{absdata} attribute can
7963 be accessed by the @code{LDS} and @code{STS} instructions which take
7968 This attribute is only supported for the reduced AVR Tiny core
7972 You must make sure that respective data is located in the
7973 address range @code{0x40}@dots{}@code{0xbf} accessible by
7974 @code{LDS} and @code{STS}. One way to achieve this as an
7975 appropriate linker description file.
7978 If the location does not fit the address range of @code{LDS}
7979 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
7982 @code{module.cc:(.text+0x1c): warning: internal error: out of range error}
7987 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
7991 @node Blackfin Variable Attributes
7992 @subsection Blackfin Variable Attributes
7994 Three attributes are currently defined for the Blackfin.
8000 @cindex @code{l1_data} variable attribute, Blackfin
8001 @cindex @code{l1_data_A} variable attribute, Blackfin
8002 @cindex @code{l1_data_B} variable attribute, Blackfin
8003 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
8004 Variables with @code{l1_data} attribute are put into the specific section
8005 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
8006 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
8007 attribute are put into the specific section named @code{.l1.data.B}.
8010 @cindex @code{l2} variable attribute, Blackfin
8011 Use this attribute on the Blackfin to place the variable into L2 SRAM.
8012 Variables with @code{l2} attribute are put into the specific section
8013 named @code{.l2.data}.
8016 @node H8/300 Variable Attributes
8017 @subsection H8/300 Variable Attributes
8019 These variable attributes are available for H8/300 targets:
8023 @cindex @code{eightbit_data} variable attribute, H8/300
8024 @cindex eight-bit data on the H8/300, H8/300H, and H8S
8025 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
8026 variable should be placed into the eight-bit data section.
8027 The compiler generates more efficient code for certain operations
8028 on data in the eight-bit data area. Note the eight-bit data area is limited to
8031 You must use GAS and GLD from GNU binutils version 2.7 or later for
8032 this attribute to work correctly.
8035 @cindex @code{tiny_data} variable attribute, H8/300
8036 @cindex tiny data section on the H8/300H and H8S
8037 Use this attribute on the H8/300H and H8S to indicate that the specified
8038 variable should be placed into the tiny data section.
8039 The compiler generates more efficient code for loads and stores
8040 on data in the tiny data section. Note the tiny data area is limited to
8041 slightly under 32KB of data.
8045 @node IA-64 Variable Attributes
8046 @subsection IA-64 Variable Attributes
8048 The IA-64 back end supports the following variable attribute:
8051 @item model (@var{model-name})
8052 @cindex @code{model} variable attribute, IA-64
8054 On IA-64, use this attribute to set the addressability of an object.
8055 At present, the only supported identifier for @var{model-name} is
8056 @code{small}, indicating addressability via ``small'' (22-bit)
8057 addresses (so that their addresses can be loaded with the @code{addl}
8058 instruction). Caveat: such addressing is by definition not position
8059 independent and hence this attribute must not be used for objects
8060 defined by shared libraries.
8064 @node M32R/D Variable Attributes
8065 @subsection M32R/D Variable Attributes
8067 One attribute is currently defined for the M32R/D@.
8070 @item model (@var{model-name})
8071 @cindex @code{model-name} variable attribute, M32R/D
8072 @cindex variable addressability on the M32R/D
8073 Use this attribute on the M32R/D to set the addressability of an object.
8074 The identifier @var{model-name} is one of @code{small}, @code{medium},
8075 or @code{large}, representing each of the code models.
8077 Small model objects live in the lower 16MB of memory (so that their
8078 addresses can be loaded with the @code{ld24} instruction).
8080 Medium and large model objects may live anywhere in the 32-bit address space
8081 (the compiler generates @code{seth/add3} instructions to load their
8085 @node MeP Variable Attributes
8086 @subsection MeP Variable Attributes
8088 The MeP target has a number of addressing modes and busses. The
8089 @code{near} space spans the standard memory space's first 16 megabytes
8090 (24 bits). The @code{far} space spans the entire 32-bit memory space.
8091 The @code{based} space is a 128-byte region in the memory space that
8092 is addressed relative to the @code{$tp} register. The @code{tiny}
8093 space is a 65536-byte region relative to the @code{$gp} register. In
8094 addition to these memory regions, the MeP target has a separate 16-bit
8095 control bus which is specified with @code{cb} attributes.
8100 @cindex @code{based} variable attribute, MeP
8101 Any variable with the @code{based} attribute is assigned to the
8102 @code{.based} section, and is accessed with relative to the
8103 @code{$tp} register.
8106 @cindex @code{tiny} variable attribute, MeP
8107 Likewise, the @code{tiny} attribute assigned variables to the
8108 @code{.tiny} section, relative to the @code{$gp} register.
8111 @cindex @code{near} variable attribute, MeP
8112 Variables with the @code{near} attribute are assumed to have addresses
8113 that fit in a 24-bit addressing mode. This is the default for large
8114 variables (@code{-mtiny=4} is the default) but this attribute can
8115 override @code{-mtiny=} for small variables, or override @code{-ml}.
8118 @cindex @code{far} variable attribute, MeP
8119 Variables with the @code{far} attribute are addressed using a full
8120 32-bit address. Since this covers the entire memory space, this
8121 allows modules to make no assumptions about where variables might be
8125 @cindex @code{io} variable attribute, MeP
8126 @itemx io (@var{addr})
8127 Variables with the @code{io} attribute are used to address
8128 memory-mapped peripherals. If an address is specified, the variable
8129 is assigned that address, else it is not assigned an address (it is
8130 assumed some other module assigns an address). Example:
8133 int timer_count __attribute__((io(0x123)));
8137 @itemx cb (@var{addr})
8138 @cindex @code{cb} variable attribute, MeP
8139 Variables with the @code{cb} attribute are used to access the control
8140 bus, using special instructions. @code{addr} indicates the control bus
8144 int cpu_clock __attribute__((cb(0x123)));
8149 @node Microsoft Windows Variable Attributes
8150 @subsection Microsoft Windows Variable Attributes
8152 You can use these attributes on Microsoft Windows targets.
8153 @ref{x86 Variable Attributes} for additional Windows compatibility
8154 attributes available on all x86 targets.
8159 @cindex @code{dllimport} variable attribute
8160 @cindex @code{dllexport} variable attribute
8161 The @code{dllimport} and @code{dllexport} attributes are described in
8162 @ref{Microsoft Windows Function Attributes}.
8165 @cindex @code{selectany} variable attribute
8166 The @code{selectany} attribute causes an initialized global variable to
8167 have link-once semantics. When multiple definitions of the variable are
8168 encountered by the linker, the first is selected and the remainder are
8169 discarded. Following usage by the Microsoft compiler, the linker is told
8170 @emph{not} to warn about size or content differences of the multiple
8173 Although the primary usage of this attribute is for POD types, the
8174 attribute can also be applied to global C++ objects that are initialized
8175 by a constructor. In this case, the static initialization and destruction
8176 code for the object is emitted in each translation defining the object,
8177 but the calls to the constructor and destructor are protected by a
8178 link-once guard variable.
8180 The @code{selectany} attribute is only available on Microsoft Windows
8181 targets. You can use @code{__declspec (selectany)} as a synonym for
8182 @code{__attribute__ ((selectany))} for compatibility with other
8186 @cindex @code{shared} variable attribute
8187 On Microsoft Windows, in addition to putting variable definitions in a named
8188 section, the section can also be shared among all running copies of an
8189 executable or DLL@. For example, this small program defines shared data
8190 by putting it in a named section @code{shared} and marking the section
8194 int foo __attribute__((section ("shared"), shared)) = 0;
8199 /* @r{Read and write foo. All running
8200 copies see the same value.} */
8206 You may only use the @code{shared} attribute along with @code{section}
8207 attribute with a fully-initialized global definition because of the way
8208 linkers work. See @code{section} attribute for more information.
8210 The @code{shared} attribute is only available on Microsoft Windows@.
8214 @node MSP430 Variable Attributes
8215 @subsection MSP430 Variable Attributes
8220 @cindex @code{upper} variable attribute, MSP430
8221 @cindex @code{either} variable attribute, MSP430
8222 These attributes are the same as the MSP430 function attributes of the
8223 same name (@pxref{MSP430 Function Attributes}).
8226 @cindex @code{lower} variable attribute, MSP430
8227 This option behaves mostly the same as the MSP430 function attribute of the
8228 same name (@pxref{MSP430 Function Attributes}), but it has some additional
8231 If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
8232 the @code{section} attribute is applied to a variable, the compiler will
8233 generate 430X instructions to handle it. This is because the compiler has
8234 to assume that the variable could get placed in the upper memory region
8235 (above address 0xFFFF). Marking the variable with the @code{lower} attribute
8236 informs the compiler that the variable will be placed in lower memory so it
8237 is safe to use 430 instructions to handle it.
8239 In the case of the @code{section} attribute, the section name given
8240 will be used, and the @code{.lower} prefix will not be added.
8244 @node Nvidia PTX Variable Attributes
8245 @subsection Nvidia PTX Variable Attributes
8247 These variable attributes are supported by the Nvidia PTX back end:
8251 @cindex @code{shared} attribute, Nvidia PTX
8252 Use this attribute to place a variable in the @code{.shared} memory space.
8253 This memory space is private to each cooperative thread array; only threads
8254 within one thread block refer to the same instance of the variable.
8255 The runtime does not initialize variables in this memory space.
8258 @node PowerPC Variable Attributes
8259 @subsection PowerPC Variable Attributes
8261 Three attributes currently are defined for PowerPC configurations:
8262 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8264 @cindex @code{ms_struct} variable attribute, PowerPC
8265 @cindex @code{gcc_struct} variable attribute, PowerPC
8266 For full documentation of the struct attributes please see the
8267 documentation in @ref{x86 Variable Attributes}.
8269 @cindex @code{altivec} variable attribute, PowerPC
8270 For documentation of @code{altivec} attribute please see the
8271 documentation in @ref{PowerPC Type Attributes}.
8273 @node RL78 Variable Attributes
8274 @subsection RL78 Variable Attributes
8276 @cindex @code{saddr} variable attribute, RL78
8277 The RL78 back end supports the @code{saddr} variable attribute. This
8278 specifies placement of the corresponding variable in the SADDR area,
8279 which can be accessed more efficiently than the default memory region.
8281 @node V850 Variable Attributes
8282 @subsection V850 Variable Attributes
8284 These variable attributes are supported by the V850 back end:
8289 @cindex @code{sda} variable attribute, V850
8290 Use this attribute to explicitly place a variable in the small data area,
8291 which can hold up to 64 kilobytes.
8294 @cindex @code{tda} variable attribute, V850
8295 Use this attribute to explicitly place a variable in the tiny data area,
8296 which can hold up to 256 bytes in total.
8299 @cindex @code{zda} variable attribute, V850
8300 Use this attribute to explicitly place a variable in the first 32 kilobytes
8304 @node x86 Variable Attributes
8305 @subsection x86 Variable Attributes
8307 Two attributes are currently defined for x86 configurations:
8308 @code{ms_struct} and @code{gcc_struct}.
8313 @cindex @code{ms_struct} variable attribute, x86
8314 @cindex @code{gcc_struct} variable attribute, x86
8316 If @code{packed} is used on a structure, or if bit-fields are used,
8317 it may be that the Microsoft ABI lays out the structure differently
8318 than the way GCC normally does. Particularly when moving packed
8319 data between functions compiled with GCC and the native Microsoft compiler
8320 (either via function call or as data in a file), it may be necessary to access
8323 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8324 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8325 command-line options, respectively;
8326 see @ref{x86 Options}, for details of how structure layout is affected.
8327 @xref{x86 Type Attributes}, for information about the corresponding
8328 attributes on types.
8332 @node Xstormy16 Variable Attributes
8333 @subsection Xstormy16 Variable Attributes
8335 One attribute is currently defined for xstormy16 configurations:
8340 @cindex @code{below100} variable attribute, Xstormy16
8342 If a variable has the @code{below100} attribute (@code{BELOW100} is
8343 allowed also), GCC places the variable in the first 0x100 bytes of
8344 memory and use special opcodes to access it. Such variables are
8345 placed in either the @code{.bss_below100} section or the
8346 @code{.data_below100} section.
8350 @node Type Attributes
8351 @section Specifying Attributes of Types
8352 @cindex attribute of types
8353 @cindex type attributes
8355 The keyword @code{__attribute__} allows you to specify various special
8356 properties of types. Some type attributes apply only to structure and
8357 union types, and in C++, also class types, while others can apply to
8358 any type defined via a @code{typedef} declaration. Unless otherwise
8359 specified, the same restrictions and effects apply to attributes regardless
8360 of whether a type is a trivial structure or a C++ class with user-defined
8361 constructors, destructors, or a copy assignment.
8363 Other attributes are defined for functions (@pxref{Function Attributes}),
8364 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
8365 Attributes}), statements (@pxref{Statement Attributes}), and for variables
8366 (@pxref{Variable Attributes}).
8368 The @code{__attribute__} keyword is followed by an attribute specification
8369 enclosed in double parentheses.
8371 You may specify type attributes in an enum, struct or union type
8372 declaration or definition by placing them immediately after the
8373 @code{struct}, @code{union} or @code{enum} keyword. You can also place
8374 them just past the closing curly brace of the definition, but this is less
8375 preferred because logically the type should be fully defined at
8378 You can also include type attributes in a @code{typedef} declaration.
8379 @xref{Attribute Syntax}, for details of the exact syntax for using
8383 * Common Type Attributes::
8384 * ARC Type Attributes::
8385 * ARM Type Attributes::
8386 * BPF Type Attributes::
8387 * MeP Type Attributes::
8388 * PowerPC Type Attributes::
8389 * x86 Type Attributes::
8392 @node Common Type Attributes
8393 @subsection Common Type Attributes
8395 The following type attributes are supported on most targets.
8398 @cindex @code{aligned} type attribute
8400 @itemx aligned (@var{alignment})
8401 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
8402 variables of the specified type. When specified, @var{alignment} must be
8403 a power of 2. Specifying no @var{alignment} argument implies the maximum
8404 alignment for the target, which is often, but by no means always, 8 or 16
8405 bytes. For example, the declarations:
8408 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
8409 typedef int more_aligned_int __attribute__ ((aligned (8)));
8413 force the compiler to ensure (as far as it can) that each variable whose
8414 type is @code{struct S} or @code{more_aligned_int} is allocated and
8415 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
8416 variables of type @code{struct S} aligned to 8-byte boundaries allows
8417 the compiler to use the @code{ldd} and @code{std} (doubleword load and
8418 store) instructions when copying one variable of type @code{struct S} to
8419 another, thus improving run-time efficiency.
8421 Note that the alignment of any given @code{struct} or @code{union} type
8422 is required by the ISO C standard to be at least a perfect multiple of
8423 the lowest common multiple of the alignments of all of the members of
8424 the @code{struct} or @code{union} in question. This means that you @emph{can}
8425 effectively adjust the alignment of a @code{struct} or @code{union}
8426 type by attaching an @code{aligned} attribute to any one of the members
8427 of such a type, but the notation illustrated in the example above is a
8428 more obvious, intuitive, and readable way to request the compiler to
8429 adjust the alignment of an entire @code{struct} or @code{union} type.
8431 As in the preceding example, you can explicitly specify the alignment
8432 (in bytes) that you wish the compiler to use for a given @code{struct}
8433 or @code{union} type. Alternatively, you can leave out the alignment factor
8434 and just ask the compiler to align a type to the maximum
8435 useful alignment for the target machine you are compiling for. For
8436 example, you could write:
8439 struct __attribute__ ((aligned)) S @{ short f[3]; @};
8442 Whenever you leave out the alignment factor in an @code{aligned}
8443 attribute specification, the compiler automatically sets the alignment
8444 for the type to the largest alignment that is ever used for any data
8445 type on the target machine you are compiling for. Doing this can often
8446 make copy operations more efficient, because the compiler can use
8447 whatever instructions copy the biggest chunks of memory when performing
8448 copies to or from the variables that have types that you have aligned
8451 In the example above, if the size of each @code{short} is 2 bytes, then
8452 the size of the entire @code{struct S} type is 6 bytes. The smallest
8453 power of two that is greater than or equal to that is 8, so the
8454 compiler sets the alignment for the entire @code{struct S} type to 8
8457 Note that although you can ask the compiler to select a time-efficient
8458 alignment for a given type and then declare only individual stand-alone
8459 objects of that type, the compiler's ability to select a time-efficient
8460 alignment is primarily useful only when you plan to create arrays of
8461 variables having the relevant (efficiently aligned) type. If you
8462 declare or use arrays of variables of an efficiently-aligned type, then
8463 it is likely that your program also does pointer arithmetic (or
8464 subscripting, which amounts to the same thing) on pointers to the
8465 relevant type, and the code that the compiler generates for these
8466 pointer arithmetic operations is often more efficient for
8467 efficiently-aligned types than for other types.
8469 Note that the effectiveness of @code{aligned} attributes may be limited
8470 by inherent limitations in your linker. On many systems, the linker is
8471 only able to arrange for variables to be aligned up to a certain maximum
8472 alignment. (For some linkers, the maximum supported alignment may
8473 be very very small.) If your linker is only able to align variables
8474 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
8475 in an @code{__attribute__} still only provides you with 8-byte
8476 alignment. See your linker documentation for further information.
8478 When used on a struct, or struct member, the @code{aligned} attribute can
8479 only increase the alignment; in order to decrease it, the @code{packed}
8480 attribute must be specified as well. When used as part of a typedef, the
8481 @code{aligned} attribute can both increase and decrease alignment, and
8482 specifying the @code{packed} attribute generates a warning.
8484 @cindex @code{warn_if_not_aligned} type attribute
8485 @item warn_if_not_aligned (@var{alignment})
8486 This attribute specifies a threshold for the structure field, measured
8487 in bytes. If the structure field is aligned below the threshold, a
8488 warning will be issued. For example, the declaration:
8491 typedef unsigned long long __u64
8492 __attribute__((aligned (4), warn_if_not_aligned (8)));
8503 causes the compiler to issue an warning on @code{struct foo}, like
8504 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
8505 It is used to define @code{struct foo} in such a way that
8506 @code{struct foo} has the same layout and the structure field @code{x}
8507 has the same alignment when @code{__u64} is aligned at either 4 or
8508 8 bytes. Align @code{struct foo} to 8 bytes:
8511 struct __attribute__ ((aligned (8))) foo
8520 silences the warning. The compiler also issues a warning, like
8521 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
8522 when the structure field has the misaligned offset:
8525 struct __attribute__ ((aligned (8))) foo
8534 This warning can be disabled by @option{-Wno-if-not-aligned}.
8536 @item alloc_size (@var{position})
8537 @itemx alloc_size (@var{position-1}, @var{position-2})
8538 @cindex @code{alloc_size} type attribute
8539 The @code{alloc_size} type attribute may be applied to the definition
8540 of a type of a function that returns a pointer and takes at least one
8541 argument of an integer type. It indicates that the returned pointer
8542 points to an object whose size is given by the function argument at
8543 @var{position-1}, or by the product of the arguments at @var{position-1}
8544 and @var{position-2}. Meaningful sizes are positive values less than
8545 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
8546 this information to improve the results of @code{__builtin_object_size}.
8548 For instance, the following declarations
8551 typedef __attribute__ ((alloc_size (1, 2))) void*
8552 calloc_type (size_t, size_t);
8553 typedef __attribute__ ((alloc_size (1))) void*
8554 malloc_type (size_t);
8558 specify that @code{calloc_type} is a type of a function that, like
8559 the standard C function @code{calloc}, returns an object whose size
8560 is given by the product of arguments 1 and 2, and that
8561 @code{malloc_type}, like the standard C function @code{malloc},
8562 returns an object whose size is given by argument 1 to the function.
8565 @itemx copy (@var{expression})
8566 @cindex @code{copy} type attribute
8567 The @code{copy} attribute applies the set of attributes with which
8568 the type of the @var{expression} has been declared to the declaration
8569 of the type to which the attribute is applied. The attribute is
8570 designed for libraries that define aliases that are expected to
8571 specify the same set of attributes as the aliased symbols.
8572 The @code{copy} attribute can be used with types, variables, or
8573 functions. However, the kind of symbol to which the attribute is
8574 applied (either varible or function) must match the kind of symbol
8575 to which the argument refers.
8576 The @code{copy} attribute copies only syntactic and semantic attributes
8577 but not attributes that affect a symbol's linkage or visibility such as
8578 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
8579 attribute is also not copied. @xref{Common Function Attributes}.
8580 @xref{Common Variable Attributes}.
8582 For example, suppose @code{struct A} below is defined in some third
8583 party library header to have the alignment requirement @code{N} and
8584 to force a warning whenever a variable of the type is not so aligned
8585 due to attribute @code{packed}. Specifying the @code{copy} attribute
8586 on the definition on the unrelated @code{struct B} has the effect of
8587 copying all relevant attributes from the type referenced by the pointer
8588 expression to @code{struct B}.
8591 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
8592 A @{ /* @r{@dots{}} */ @};
8593 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
8597 @itemx deprecated (@var{msg})
8598 @cindex @code{deprecated} type attribute
8599 The @code{deprecated} attribute results in a warning if the type
8600 is used anywhere in the source file. This is useful when identifying
8601 types that are expected to be removed in a future version of a program.
8602 If possible, the warning also includes the location of the declaration
8603 of the deprecated type, to enable users to easily find further
8604 information about why the type is deprecated, or what they should do
8605 instead. Note that the warnings only occur for uses and then only
8606 if the type is being applied to an identifier that itself is not being
8607 declared as deprecated.
8610 typedef int T1 __attribute__ ((deprecated));
8614 typedef T1 T3 __attribute__ ((deprecated));
8615 T3 z __attribute__ ((deprecated));
8619 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
8620 warning is issued for line 4 because T2 is not explicitly
8621 deprecated. Line 5 has no warning because T3 is explicitly
8622 deprecated. Similarly for line 6. The optional @var{msg}
8623 argument, which must be a string, is printed in the warning if
8624 present. Control characters in the string will be replaced with
8625 escape sequences, and if the @option{-fmessage-length} option is set
8626 to 0 (its default value) then any newline characters will be ignored.
8628 The @code{deprecated} attribute can also be used for functions and
8629 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8631 The message attached to the attribute is affected by the setting of
8632 the @option{-fmessage-length} option.
8635 @itemx unavailable (@var{msg})
8636 @cindex @code{unavailable} type attribute
8637 The @code{unavailable} attribute behaves in the same manner as the
8638 @code{deprecated} one, but emits an error rather than a warning. It is
8639 used to indicate that a (perhaps previously @code{deprecated}) type is
8642 The @code{unavailable} attribute can also be used for functions and
8643 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8645 @item designated_init
8646 @cindex @code{designated_init} type attribute
8647 This attribute may only be applied to structure types. It indicates
8648 that any initialization of an object of this type must use designated
8649 initializers rather than positional initializers. The intent of this
8650 attribute is to allow the programmer to indicate that a structure's
8651 layout may change, and that therefore relying on positional
8652 initialization will result in future breakage.
8654 GCC emits warnings based on this attribute by default; use
8655 @option{-Wno-designated-init} to suppress them.
8658 @cindex @code{may_alias} type attribute
8659 Accesses through pointers to types with this attribute are not subject
8660 to type-based alias analysis, but are instead assumed to be able to alias
8661 any other type of objects.
8662 In the context of section 6.5 paragraph 7 of the C99 standard,
8663 an lvalue expression
8664 dereferencing such a pointer is treated like having a character type.
8665 See @option{-fstrict-aliasing} for more information on aliasing issues.
8666 This extension exists to support some vector APIs, in which pointers to
8667 one vector type are permitted to alias pointers to a different vector type.
8669 Note that an object of a type with this attribute does not have any
8675 typedef short __attribute__ ((__may_alias__)) short_a;
8681 short_a *b = (short_a *) &a;
8685 if (a == 0x12345678)
8693 If you replaced @code{short_a} with @code{short} in the variable
8694 declaration, the above program would abort when compiled with
8695 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
8698 @item mode (@var{mode})
8699 @cindex @code{mode} type attribute
8700 This attribute specifies the data type for the declaration---whichever
8701 type corresponds to the mode @var{mode}. This in effect lets you
8702 request an integer or floating-point type according to its width.
8704 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
8705 for a list of the possible keywords for @var{mode}.
8706 You may also specify a mode of @code{byte} or @code{__byte__} to
8707 indicate the mode corresponding to a one-byte integer, @code{word} or
8708 @code{__word__} for the mode of a one-word integer, and @code{pointer}
8709 or @code{__pointer__} for the mode used to represent pointers.
8712 @cindex @code{packed} type attribute
8713 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
8714 type definition, specifies that each of its members (other than zero-width
8715 bit-fields) is placed to minimize the memory required. This is equivalent
8716 to specifying the @code{packed} attribute on each of the members.
8718 @opindex fshort-enums
8719 When attached to an @code{enum} definition, the @code{packed} attribute
8720 indicates that the smallest integral type should be used.
8721 Specifying the @option{-fshort-enums} flag on the command line
8722 is equivalent to specifying the @code{packed}
8723 attribute on all @code{enum} definitions.
8725 In the following example @code{struct my_packed_struct}'s members are
8726 packed closely together, but the internal layout of its @code{s} member
8727 is not packed---to do that, @code{struct my_unpacked_struct} needs to
8731 struct my_unpacked_struct
8737 struct __attribute__ ((__packed__)) my_packed_struct
8741 struct my_unpacked_struct s;
8745 You may only specify the @code{packed} attribute on the definition
8746 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
8747 not on a @code{typedef} that does not also define the enumerated type,
8748 structure, union, or class.
8750 @item scalar_storage_order ("@var{endianness}")
8751 @cindex @code{scalar_storage_order} type attribute
8752 When attached to a @code{union} or a @code{struct}, this attribute sets
8753 the storage order, aka endianness, of the scalar fields of the type, as
8754 well as the array fields whose component is scalar. The supported
8755 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
8756 has no effects on fields which are themselves a @code{union}, a @code{struct}
8757 or an array whose component is a @code{union} or a @code{struct}, and it is
8758 possible for these fields to have a different scalar storage order than the
8761 Note that neither pointer nor vector fields are considered scalar fields in
8762 this context, so the attribute has no effects on these fields.
8764 This attribute is supported only for targets that use a uniform default
8765 scalar storage order (fortunately, most of them), i.e.@: targets that store
8766 the scalars either all in big-endian or all in little-endian.
8768 Additional restrictions are enforced for types with the reverse scalar
8769 storage order with regard to the scalar storage order of the target:
8772 @item Taking the address of a scalar field of a @code{union} or a
8773 @code{struct} with reverse scalar storage order is not permitted and yields
8775 @item Taking the address of an array field, whose component is scalar, of
8776 a @code{union} or a @code{struct} with reverse scalar storage order is
8777 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
8779 @item Taking the address of a @code{union} or a @code{struct} with reverse
8780 scalar storage order is permitted.
8783 These restrictions exist because the storage order attribute is lost when
8784 the address of a scalar or the address of an array with scalar component is
8785 taken, so storing indirectly through this address generally does not work.
8786 The second case is nevertheless allowed to be able to perform a block copy
8787 from or to the array.
8789 Moreover, the use of type punning or aliasing to toggle the storage order
8790 is not supported; that is to say, if a given scalar object can be accessed
8791 through distinct types that assign a different storage order to it, then the
8792 behavior is undefined.
8794 @item transparent_union
8795 @cindex @code{transparent_union} type attribute
8797 This attribute, attached to a @code{union} type definition, indicates
8798 that any function parameter having that union type causes calls to that
8799 function to be treated in a special way.
8801 First, the argument corresponding to a transparent union type can be of
8802 any type in the union; no cast is required. Also, if the union contains
8803 a pointer type, the corresponding argument can be a null pointer
8804 constant or a void pointer expression; and if the union contains a void
8805 pointer type, the corresponding argument can be any pointer expression.
8806 If the union member type is a pointer, qualifiers like @code{const} on
8807 the referenced type must be respected, just as with normal pointer
8810 Second, the argument is passed to the function using the calling
8811 conventions of the first member of the transparent union, not the calling
8812 conventions of the union itself. All members of the union must have the
8813 same machine representation; this is necessary for this argument passing
8816 Transparent unions are designed for library functions that have multiple
8817 interfaces for compatibility reasons. For example, suppose the
8818 @code{wait} function must accept either a value of type @code{int *} to
8819 comply with POSIX, or a value of type @code{union wait *} to comply with
8820 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
8821 @code{wait} would accept both kinds of arguments, but it would also
8822 accept any other pointer type and this would make argument type checking
8823 less useful. Instead, @code{<sys/wait.h>} might define the interface
8827 typedef union __attribute__ ((__transparent_union__))
8831 @} wait_status_ptr_t;
8833 pid_t wait (wait_status_ptr_t);
8837 This interface allows either @code{int *} or @code{union wait *}
8838 arguments to be passed, using the @code{int *} calling convention.
8839 The program can call @code{wait} with arguments of either type:
8842 int w1 () @{ int w; return wait (&w); @}
8843 int w2 () @{ union wait w; return wait (&w); @}
8847 With this interface, @code{wait}'s implementation might look like this:
8850 pid_t wait (wait_status_ptr_t p)
8852 return waitpid (-1, p.__ip, 0);
8857 @cindex @code{unused} type attribute
8858 When attached to a type (including a @code{union} or a @code{struct}),
8859 this attribute means that variables of that type are meant to appear
8860 possibly unused. GCC does not produce a warning for any variables of
8861 that type, even if the variable appears to do nothing. This is often
8862 the case with lock or thread classes, which are usually defined and then
8863 not referenced, but contain constructors and destructors that have
8864 nontrivial bookkeeping functions.
8866 @item vector_size (@var{bytes})
8867 @cindex @code{vector_size} type attribute
8868 This attribute specifies the vector size for the type, measured in bytes.
8869 The type to which it applies is known as the @dfn{base type}. The @var{bytes}
8870 argument must be a positive power-of-two multiple of the base type size. For
8871 example, the following declarations:
8874 typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
8875 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
8876 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
8880 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
8881 sized units. With @code{int} having a size of 4 bytes, the type defines
8882 a vector of eight units, four bytes each. The mode of variables of type
8883 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
8884 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
8885 an array of three such vectors. @xref{Vector Extensions}, for details of
8886 manipulating objects of vector types.
8888 This attribute is only applicable to integral and floating scalar types.
8889 In function declarations the attribute applies to the function return
8892 For example, the following:
8894 __attribute__ ((vector_size (16))) float get_flt_vec16 (void);
8896 declares @code{get_flt_vec16} to be a function returning a 16-byte vector
8897 with the base type @code{float}.
8900 @cindex @code{visibility} type attribute
8901 In C++, attribute visibility (@pxref{Function Attributes}) can also be
8902 applied to class, struct, union and enum types. Unlike other type
8903 attributes, the attribute must appear between the initial keyword and
8904 the name of the type; it cannot appear after the body of the type.
8906 Note that the type visibility is applied to vague linkage entities
8907 associated with the class (vtable, typeinfo node, etc.). In
8908 particular, if a class is thrown as an exception in one shared object
8909 and caught in another, the class must have default visibility.
8910 Otherwise the two shared objects are unable to use the same
8911 typeinfo node and exception handling will break.
8913 @item objc_root_class @r{(Objective-C and Objective-C++ only)}
8914 @cindex @code{objc_root_class} type attribute
8915 This attribute marks a class as being a root class, and thus allows
8916 the compiler to elide any warnings about a missing superclass and to
8917 make additional checks for mandatory methods as needed.
8921 To specify multiple attributes, separate them by commas within the
8922 double parentheses: for example, @samp{__attribute__ ((aligned (16),
8925 @node ARC Type Attributes
8926 @subsection ARC Type Attributes
8928 @cindex @code{uncached} type attribute, ARC
8929 Declaring objects with @code{uncached} allows you to exclude
8930 data-cache participation in load and store operations on those objects
8931 without involving the additional semantic implications of
8932 @code{volatile}. The @code{.di} instruction suffix is used for all
8933 loads and stores of data declared @code{uncached}.
8935 @node ARM Type Attributes
8936 @subsection ARM Type Attributes
8938 @cindex @code{notshared} type attribute, ARM
8939 On those ARM targets that support @code{dllimport} (such as Symbian
8940 OS), you can use the @code{notshared} attribute to indicate that the
8941 virtual table and other similar data for a class should not be
8942 exported from a DLL@. For example:
8945 class __declspec(notshared) C @{
8947 __declspec(dllimport) C();
8951 __declspec(dllexport)
8956 In this code, @code{C::C} is exported from the current DLL, but the
8957 virtual table for @code{C} is not exported. (You can use
8958 @code{__attribute__} instead of @code{__declspec} if you prefer, but
8959 most Symbian OS code uses @code{__declspec}.)
8961 @node BPF Type Attributes
8962 @subsection BPF Type Attributes
8964 @cindex @code{preserve_access_index} type attribute, BPF
8965 BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a
8966 @code{struct} or @code{union} type definition, indicates that CO-RE
8967 relocation information should be generated for any access to a variable
8968 of that type. The behavior is equivalent to the programmer manually
8969 wrapping every such access with @code{__builtin_preserve_access_index}.
8972 @node MeP Type Attributes
8973 @subsection MeP Type Attributes
8975 @cindex @code{based} type attribute, MeP
8976 @cindex @code{tiny} type attribute, MeP
8977 @cindex @code{near} type attribute, MeP
8978 @cindex @code{far} type attribute, MeP
8979 Many of the MeP variable attributes may be applied to types as well.
8980 Specifically, the @code{based}, @code{tiny}, @code{near}, and
8981 @code{far} attributes may be applied to either. The @code{io} and
8982 @code{cb} attributes may not be applied to types.
8984 @node PowerPC Type Attributes
8985 @subsection PowerPC Type Attributes
8987 Three attributes currently are defined for PowerPC configurations:
8988 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8990 @cindex @code{ms_struct} type attribute, PowerPC
8991 @cindex @code{gcc_struct} type attribute, PowerPC
8992 For full documentation of the @code{ms_struct} and @code{gcc_struct}
8993 attributes please see the documentation in @ref{x86 Type Attributes}.
8995 @cindex @code{altivec} type attribute, PowerPC
8996 The @code{altivec} attribute allows one to declare AltiVec vector data
8997 types supported by the AltiVec Programming Interface Manual. The
8998 attribute requires an argument to specify one of three vector types:
8999 @code{vector__}, @code{pixel__} (always followed by unsigned short),
9000 and @code{bool__} (always followed by unsigned).
9003 __attribute__((altivec(vector__)))
9004 __attribute__((altivec(pixel__))) unsigned short
9005 __attribute__((altivec(bool__))) unsigned
9008 These attributes mainly are intended to support the @code{__vector},
9009 @code{__pixel}, and @code{__bool} AltiVec keywords.
9011 @node x86 Type Attributes
9012 @subsection x86 Type Attributes
9014 Two attributes are currently defined for x86 configurations:
9015 @code{ms_struct} and @code{gcc_struct}.
9021 @cindex @code{ms_struct} type attribute, x86
9022 @cindex @code{gcc_struct} type attribute, x86
9024 If @code{packed} is used on a structure, or if bit-fields are used
9025 it may be that the Microsoft ABI packs them differently
9026 than GCC normally packs them. Particularly when moving packed
9027 data between functions compiled with GCC and the native Microsoft compiler
9028 (either via function call or as data in a file), it may be necessary to access
9031 The @code{ms_struct} and @code{gcc_struct} attributes correspond
9032 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
9033 command-line options, respectively;
9034 see @ref{x86 Options}, for details of how structure layout is affected.
9035 @xref{x86 Variable Attributes}, for information about the corresponding
9036 attributes on variables.
9040 @node Label Attributes
9041 @section Label Attributes
9042 @cindex Label Attributes
9044 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
9045 details of the exact syntax for using attributes. Other attributes are
9046 available for functions (@pxref{Function Attributes}), variables
9047 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
9048 statements (@pxref{Statement Attributes}), and for types
9049 (@pxref{Type Attributes}). A label attribute followed
9050 by a declaration appertains to the label and not the declaration.
9052 This example uses the @code{cold} label attribute to indicate the
9053 @code{ErrorHandling} branch is unlikely to be taken and that the
9054 @code{ErrorHandling} label is unused:
9058 asm goto ("some asm" : : : : NoError);
9060 /* This branch (the fall-through from the asm) is less commonly used */
9062 __attribute__((cold, unused)); /* Semi-colon is required here */
9067 printf("no error\n");
9073 @cindex @code{unused} label attribute
9074 This feature is intended for program-generated code that may contain
9075 unused labels, but which is compiled with @option{-Wall}. It is
9076 not normally appropriate to use in it human-written code, though it
9077 could be useful in cases where the code that jumps to the label is
9078 contained within an @code{#ifdef} conditional.
9081 @cindex @code{hot} label attribute
9082 The @code{hot} attribute on a label is used to inform the compiler that
9083 the path following the label is more likely than paths that are not so
9084 annotated. This attribute is used in cases where @code{__builtin_expect}
9085 cannot be used, for instance with computed goto or @code{asm goto}.
9088 @cindex @code{cold} label attribute
9089 The @code{cold} attribute on labels is used to inform the compiler that
9090 the path following the label is unlikely to be executed. This attribute
9091 is used in cases where @code{__builtin_expect} cannot be used, for instance
9092 with computed goto or @code{asm goto}.
9096 @node Enumerator Attributes
9097 @section Enumerator Attributes
9098 @cindex Enumerator Attributes
9100 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
9101 details of the exact syntax for using attributes. Other attributes are
9102 available for functions (@pxref{Function Attributes}), variables
9103 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
9104 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
9106 This example uses the @code{deprecated} enumerator attribute to indicate the
9107 @code{oldval} enumerator is deprecated:
9111 oldval __attribute__((deprecated)),
9124 @cindex @code{deprecated} enumerator attribute
9125 The @code{deprecated} attribute results in a warning if the enumerator
9126 is used anywhere in the source file. This is useful when identifying
9127 enumerators that are expected to be removed in a future version of a
9128 program. The warning also includes the location of the declaration
9129 of the deprecated enumerator, to enable users to easily find further
9130 information about why the enumerator is deprecated, or what they should
9131 do instead. Note that the warnings only occurs for uses.
9134 @cindex @code{unavailable} enumerator attribute
9135 The @code{unavailable} attribute results in an error if the enumerator
9136 is used anywhere in the source file. In other respects it behaves in the
9137 same manner as the @code{deprecated} attribute.
9141 @node Statement Attributes
9142 @section Statement Attributes
9143 @cindex Statement Attributes
9145 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
9146 for details of the exact syntax for using attributes. Other attributes are
9147 available for functions (@pxref{Function Attributes}), variables
9148 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
9149 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
9151 This example uses the @code{fallthrough} statement attribute to indicate that
9152 the @option{-Wimplicit-fallthrough} warning should not be emitted:
9159 __attribute__((fallthrough));
9167 @cindex @code{fallthrough} statement attribute
9168 The @code{fallthrough} attribute with a null statement serves as a
9169 fallthrough statement. It hints to the compiler that a statement
9170 that falls through to another case label, or user-defined label
9171 in a switch statement is intentional and thus the
9172 @option{-Wimplicit-fallthrough} warning must not trigger. The
9173 fallthrough attribute may appear at most once in each attribute
9174 list, and may not be mixed with other attributes. It can only
9175 be used in a switch statement (the compiler will issue an error
9176 otherwise), after a preceding statement and before a logically
9177 succeeding case label, or user-defined label.
9181 @node Attribute Syntax
9182 @section Attribute Syntax
9183 @cindex attribute syntax
9185 This section describes the syntax with which @code{__attribute__} may be
9186 used, and the constructs to which attribute specifiers bind, for the C
9187 language. Some details may vary for C++ and Objective-C@. Because of
9188 infelicities in the grammar for attributes, some forms described here
9189 may not be successfully parsed in all cases.
9191 There are some problems with the semantics of attributes in C++. For
9192 example, there are no manglings for attributes, although they may affect
9193 code generation, so problems may arise when attributed types are used in
9194 conjunction with templates or overloading. Similarly, @code{typeid}
9195 does not distinguish between types with different attributes. Support
9196 for attributes in C++ may be restricted in future to attributes on
9197 declarations only, but not on nested declarators.
9199 @xref{Function Attributes}, for details of the semantics of attributes
9200 applying to functions. @xref{Variable Attributes}, for details of the
9201 semantics of attributes applying to variables. @xref{Type Attributes},
9202 for details of the semantics of attributes applying to structure, union
9203 and enumerated types.
9204 @xref{Label Attributes}, for details of the semantics of attributes
9206 @xref{Enumerator Attributes}, for details of the semantics of attributes
9207 applying to enumerators.
9208 @xref{Statement Attributes}, for details of the semantics of attributes
9209 applying to statements.
9211 An @dfn{attribute specifier} is of the form
9212 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
9213 is a possibly empty comma-separated sequence of @dfn{attributes}, where
9214 each attribute is one of the following:
9218 Empty. Empty attributes are ignored.
9222 (which may be an identifier such as @code{unused}, or a reserved
9223 word such as @code{const}).
9226 An attribute name followed by a parenthesized list of
9227 parameters for the attribute.
9228 These parameters take one of the following forms:
9232 An identifier. For example, @code{mode} attributes use this form.
9235 An identifier followed by a comma and a non-empty comma-separated list
9236 of expressions. For example, @code{format} attributes use this form.
9239 A possibly empty comma-separated list of expressions. For example,
9240 @code{format_arg} attributes use this form with the list being a single
9241 integer constant expression, and @code{alias} attributes use this form
9242 with the list being a single string constant.
9246 An @dfn{attribute specifier list} is a sequence of one or more attribute
9247 specifiers, not separated by any other tokens.
9249 You may optionally specify attribute names with @samp{__}
9250 preceding and following the name.
9251 This allows you to use them in header files without
9252 being concerned about a possible macro of the same name. For example,
9253 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
9256 @subsubheading Label Attributes
9258 In GNU C, an attribute specifier list may appear after the colon following a
9259 label, other than a @code{case} or @code{default} label. GNU C++ only permits
9260 attributes on labels if the attribute specifier is immediately
9261 followed by a semicolon (i.e., the label applies to an empty
9262 statement). If the semicolon is missing, C++ label attributes are
9263 ambiguous, as it is permissible for a declaration, which could begin
9264 with an attribute list, to be labelled in C++. Declarations cannot be
9265 labelled in C90 or C99, so the ambiguity does not arise there.
9267 @subsubheading Enumerator Attributes
9269 In GNU C, an attribute specifier list may appear as part of an enumerator.
9270 The attribute goes after the enumeration constant, before @code{=}, if
9271 present. The optional attribute in the enumerator appertains to the
9272 enumeration constant. It is not possible to place the attribute after
9273 the constant expression, if present.
9275 @subsubheading Statement Attributes
9276 In GNU C, an attribute specifier list may appear as part of a null
9277 statement. The attribute goes before the semicolon.
9279 @subsubheading Type Attributes
9281 An attribute specifier list may appear as part of a @code{struct},
9282 @code{union} or @code{enum} specifier. It may go either immediately
9283 after the @code{struct}, @code{union} or @code{enum} keyword, or after
9284 the closing brace. The former syntax is preferred.
9285 Where attribute specifiers follow the closing brace, they are considered
9286 to relate to the structure, union or enumerated type defined, not to any
9287 enclosing declaration the type specifier appears in, and the type
9288 defined is not complete until after the attribute specifiers.
9289 @c Otherwise, there would be the following problems: a shift/reduce
9290 @c conflict between attributes binding the struct/union/enum and
9291 @c binding to the list of specifiers/qualifiers; and "aligned"
9292 @c attributes could use sizeof for the structure, but the size could be
9293 @c changed later by "packed" attributes.
9296 @subsubheading All other attributes
9298 Otherwise, an attribute specifier appears as part of a declaration,
9299 counting declarations of unnamed parameters and type names, and relates
9300 to that declaration (which may be nested in another declaration, for
9301 example in the case of a parameter declaration), or to a particular declarator
9302 within a declaration. Where an
9303 attribute specifier is applied to a parameter declared as a function or
9304 an array, it should apply to the function or array rather than the
9305 pointer to which the parameter is implicitly converted, but this is not
9306 yet correctly implemented.
9308 Any list of specifiers and qualifiers at the start of a declaration may
9309 contain attribute specifiers, whether or not such a list may in that
9310 context contain storage class specifiers. (Some attributes, however,
9311 are essentially in the nature of storage class specifiers, and only make
9312 sense where storage class specifiers may be used; for example,
9313 @code{section}.) There is one necessary limitation to this syntax: the
9314 first old-style parameter declaration in a function definition cannot
9315 begin with an attribute specifier, because such an attribute applies to
9316 the function instead by syntax described below (which, however, is not
9317 yet implemented in this case). In some other cases, attribute
9318 specifiers are permitted by this grammar but not yet supported by the
9319 compiler. All attribute specifiers in this place relate to the
9320 declaration as a whole. In the obsolescent usage where a type of
9321 @code{int} is implied by the absence of type specifiers, such a list of
9322 specifiers and qualifiers may be an attribute specifier list with no
9323 other specifiers or qualifiers.
9325 At present, the first parameter in a function prototype must have some
9326 type specifier that is not an attribute specifier; this resolves an
9327 ambiguity in the interpretation of @code{void f(int
9328 (__attribute__((foo)) x))}, but is subject to change. At present, if
9329 the parentheses of a function declarator contain only attributes then
9330 those attributes are ignored, rather than yielding an error or warning
9331 or implying a single parameter of type int, but this is subject to
9334 An attribute specifier list may appear immediately before a declarator
9335 (other than the first) in a comma-separated list of declarators in a
9336 declaration of more than one identifier using a single list of
9337 specifiers and qualifiers. Such attribute specifiers apply
9338 only to the identifier before whose declarator they appear. For
9342 __attribute__((noreturn)) void d0 (void),
9343 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
9348 the @code{noreturn} attribute applies to all the functions
9349 declared; the @code{format} attribute only applies to @code{d1}.
9351 An attribute specifier list may appear immediately before the comma,
9352 @code{=} or semicolon terminating the declaration of an identifier other
9353 than a function definition. Such attribute specifiers apply
9354 to the declared object or function. Where an
9355 assembler name for an object or function is specified (@pxref{Asm
9356 Labels}), the attribute must follow the @code{asm}
9359 An attribute specifier list may, in future, be permitted to appear after
9360 the declarator in a function definition (before any old-style parameter
9361 declarations or the function body).
9363 Attribute specifiers may be mixed with type qualifiers appearing inside
9364 the @code{[]} of a parameter array declarator, in the C99 construct by
9365 which such qualifiers are applied to the pointer to which the array is
9366 implicitly converted. Such attribute specifiers apply to the pointer,
9367 not to the array, but at present this is not implemented and they are
9370 An attribute specifier list may appear at the start of a nested
9371 declarator. At present, there are some limitations in this usage: the
9372 attributes correctly apply to the declarator, but for most individual
9373 attributes the semantics this implies are not implemented.
9374 When attribute specifiers follow the @code{*} of a pointer
9375 declarator, they may be mixed with any type qualifiers present.
9376 The following describes the formal semantics of this syntax. It makes the
9377 most sense if you are familiar with the formal specification of
9378 declarators in the ISO C standard.
9380 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
9381 D1}, where @code{T} contains declaration specifiers that specify a type
9382 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
9383 contains an identifier @var{ident}. The type specified for @var{ident}
9384 for derived declarators whose type does not include an attribute
9385 specifier is as in the ISO C standard.
9387 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
9388 and the declaration @code{T D} specifies the type
9389 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
9390 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
9391 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
9393 If @code{D1} has the form @code{*
9394 @var{type-qualifier-and-attribute-specifier-list} D}, and the
9395 declaration @code{T D} specifies the type
9396 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
9397 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
9398 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
9404 void (__attribute__((noreturn)) ****f) (void);
9408 specifies the type ``pointer to pointer to pointer to pointer to
9409 non-returning function returning @code{void}''. As another example,
9412 char *__attribute__((aligned(8))) *f;
9416 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
9417 Note again that this does not work with most attributes; for example,
9418 the usage of @samp{aligned} and @samp{noreturn} attributes given above
9419 is not yet supported.
9421 For compatibility with existing code written for compiler versions that
9422 did not implement attributes on nested declarators, some laxity is
9423 allowed in the placing of attributes. If an attribute that only applies
9424 to types is applied to a declaration, it is treated as applying to
9425 the type of that declaration. If an attribute that only applies to
9426 declarations is applied to the type of a declaration, it is treated
9427 as applying to that declaration; and, for compatibility with code
9428 placing the attributes immediately before the identifier declared, such
9429 an attribute applied to a function return type is treated as
9430 applying to the function type, and such an attribute applied to an array
9431 element type is treated as applying to the array type. If an
9432 attribute that only applies to function types is applied to a
9433 pointer-to-function type, it is treated as applying to the pointer
9434 target type; if such an attribute is applied to a function return type
9435 that is not a pointer-to-function type, it is treated as applying
9436 to the function type.
9438 @node Function Prototypes
9439 @section Prototypes and Old-Style Function Definitions
9440 @cindex function prototype declarations
9441 @cindex old-style function definitions
9442 @cindex promotion of formal parameters
9444 GNU C extends ISO C to allow a function prototype to override a later
9445 old-style non-prototype definition. Consider the following example:
9448 /* @r{Use prototypes unless the compiler is old-fashioned.} */
9455 /* @r{Prototype function declaration.} */
9456 int isroot P((uid_t));
9458 /* @r{Old-style function definition.} */
9460 isroot (x) /* @r{??? lossage here ???} */
9467 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
9468 not allow this example, because subword arguments in old-style
9469 non-prototype definitions are promoted. Therefore in this example the
9470 function definition's argument is really an @code{int}, which does not
9471 match the prototype argument type of @code{short}.
9473 This restriction of ISO C makes it hard to write code that is portable
9474 to traditional C compilers, because the programmer does not know
9475 whether the @code{uid_t} type is @code{short}, @code{int}, or
9476 @code{long}. Therefore, in cases like these GNU C allows a prototype
9477 to override a later old-style definition. More precisely, in GNU C, a
9478 function prototype argument type overrides the argument type specified
9479 by a later old-style definition if the former type is the same as the
9480 latter type before promotion. Thus in GNU C the above example is
9481 equivalent to the following:
9494 GNU C++ does not support old-style function definitions, so this
9495 extension is irrelevant.
9498 @section C++ Style Comments
9500 @cindex C++ comments
9501 @cindex comments, C++ style
9503 In GNU C, you may use C++ style comments, which start with @samp{//} and
9504 continue until the end of the line. Many other C implementations allow
9505 such comments, and they are included in the 1999 C standard. However,
9506 C++ style comments are not recognized if you specify an @option{-std}
9507 option specifying a version of ISO C before C99, or @option{-ansi}
9508 (equivalent to @option{-std=c90}).
9511 @section Dollar Signs in Identifier Names
9513 @cindex dollar signs in identifier names
9514 @cindex identifier names, dollar signs in
9516 In GNU C, you may normally use dollar signs in identifier names.
9517 This is because many traditional C implementations allow such identifiers.
9518 However, dollar signs in identifiers are not supported on a few target
9519 machines, typically because the target assembler does not allow them.
9521 @node Character Escapes
9522 @section The Character @key{ESC} in Constants
9524 You can use the sequence @samp{\e} in a string or character constant to
9525 stand for the ASCII character @key{ESC}.
9528 @section Determining the Alignment of Functions, Types or Variables
9530 @cindex type alignment
9531 @cindex variable alignment
9533 The keyword @code{__alignof__} determines the alignment requirement of
9534 a function, object, or a type, or the minimum alignment usually required
9535 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
9537 For example, if the target machine requires a @code{double} value to be
9538 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
9539 This is true on many RISC machines. On more traditional machine
9540 designs, @code{__alignof__ (double)} is 4 or even 2.
9542 Some machines never actually require alignment; they allow references to any
9543 data type even at an odd address. For these machines, @code{__alignof__}
9544 reports the smallest alignment that GCC gives the data type, usually as
9545 mandated by the target ABI.
9547 If the operand of @code{__alignof__} is an lvalue rather than a type,
9548 its value is the required alignment for its type, taking into account
9549 any minimum alignment specified by attribute @code{aligned}
9550 (@pxref{Common Variable Attributes}). For example, after this
9554 struct foo @{ int x; char y; @} foo1;
9558 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
9559 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
9560 It is an error to ask for the alignment of an incomplete type other
9563 If the operand of the @code{__alignof__} expression is a function,
9564 the expression evaluates to the alignment of the function which may
9565 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
9568 @section An Inline Function is As Fast As a Macro
9569 @cindex inline functions
9570 @cindex integrating function code
9572 @cindex macros, inline alternative
9574 By declaring a function inline, you can direct GCC to make
9575 calls to that function faster. One way GCC can achieve this is to
9576 integrate that function's code into the code for its callers. This
9577 makes execution faster by eliminating the function-call overhead; in
9578 addition, if any of the actual argument values are constant, their
9579 known values may permit simplifications at compile time so that not
9580 all of the inline function's code needs to be included. The effect on
9581 code size is less predictable; object code may be larger or smaller
9582 with function inlining, depending on the particular case. You can
9583 also direct GCC to try to integrate all ``simple enough'' functions
9584 into their callers with the option @option{-finline-functions}.
9586 GCC implements three different semantics of declaring a function
9587 inline. One is available with @option{-std=gnu89} or
9588 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
9589 on all inline declarations, another when
9591 @option{-std=gnu99} or an option for a later C version is used
9592 (without @option{-fgnu89-inline}), and the third
9593 is used when compiling C++.
9595 To declare a function inline, use the @code{inline} keyword in its
9596 declaration, like this:
9606 If you are writing a header file to be included in ISO C90 programs, write
9607 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
9609 The three types of inlining behave similarly in two important cases:
9610 when the @code{inline} keyword is used on a @code{static} function,
9611 like the example above, and when a function is first declared without
9612 using the @code{inline} keyword and then is defined with
9613 @code{inline}, like this:
9616 extern int inc (int *a);
9624 In both of these common cases, the program behaves the same as if you
9625 had not used the @code{inline} keyword, except for its speed.
9627 @cindex inline functions, omission of
9628 @opindex fkeep-inline-functions
9629 When a function is both inline and @code{static}, if all calls to the
9630 function are integrated into the caller, and the function's address is
9631 never used, then the function's own assembler code is never referenced.
9632 In this case, GCC does not actually output assembler code for the
9633 function, unless you specify the option @option{-fkeep-inline-functions}.
9634 If there is a nonintegrated call, then the function is compiled to
9635 assembler code as usual. The function must also be compiled as usual if
9636 the program refers to its address, because that cannot be inlined.
9639 Note that certain usages in a function definition can make it unsuitable
9640 for inline substitution. Among these usages are: variadic functions,
9641 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
9642 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
9643 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
9644 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
9645 function marked @code{inline} could not be substituted, and gives the
9646 reason for the failure.
9648 @cindex automatic @code{inline} for C++ member fns
9649 @cindex @code{inline} automatic for C++ member fns
9650 @cindex member fns, automatically @code{inline}
9651 @cindex C++ member fns, automatically @code{inline}
9652 @opindex fno-default-inline
9653 As required by ISO C++, GCC considers member functions defined within
9654 the body of a class to be marked inline even if they are
9655 not explicitly declared with the @code{inline} keyword. You can
9656 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
9657 Options,,Options Controlling C++ Dialect}.
9659 GCC does not inline any functions when not optimizing unless you specify
9660 the @samp{always_inline} attribute for the function, like this:
9663 /* @r{Prototype.} */
9664 inline void foo (const char) __attribute__((always_inline));
9667 The remainder of this section is specific to GNU C90 inlining.
9669 @cindex non-static inline function
9670 When an inline function is not @code{static}, then the compiler must assume
9671 that there may be calls from other source files; since a global symbol can
9672 be defined only once in any program, the function must not be defined in
9673 the other source files, so the calls therein cannot be integrated.
9674 Therefore, a non-@code{static} inline function is always compiled on its
9675 own in the usual fashion.
9677 If you specify both @code{inline} and @code{extern} in the function
9678 definition, then the definition is used only for inlining. In no case
9679 is the function compiled on its own, not even if you refer to its
9680 address explicitly. Such an address becomes an external reference, as
9681 if you had only declared the function, and had not defined it.
9683 This combination of @code{inline} and @code{extern} has almost the
9684 effect of a macro. The way to use it is to put a function definition in
9685 a header file with these keywords, and put another copy of the
9686 definition (lacking @code{inline} and @code{extern}) in a library file.
9687 The definition in the header file causes most calls to the function
9688 to be inlined. If any uses of the function remain, they refer to
9689 the single copy in the library.
9692 @section When is a Volatile Object Accessed?
9693 @cindex accessing volatiles
9694 @cindex volatile read
9695 @cindex volatile write
9696 @cindex volatile access
9698 C has the concept of volatile objects. These are normally accessed by
9699 pointers and used for accessing hardware or inter-thread
9700 communication. The standard encourages compilers to refrain from
9701 optimizations concerning accesses to volatile objects, but leaves it
9702 implementation defined as to what constitutes a volatile access. The
9703 minimum requirement is that at a sequence point all previous accesses
9704 to volatile objects have stabilized and no subsequent accesses have
9705 occurred. Thus an implementation is free to reorder and combine
9706 volatile accesses that occur between sequence points, but cannot do
9707 so for accesses across a sequence point. The use of volatile does
9708 not allow you to violate the restriction on updating objects multiple
9709 times between two sequence points.
9711 Accesses to non-volatile objects are not ordered with respect to
9712 volatile accesses. You cannot use a volatile object as a memory
9713 barrier to order a sequence of writes to non-volatile memory. For
9717 int *ptr = @var{something};
9719 *ptr = @var{something};
9724 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
9725 that the write to @var{*ptr} occurs by the time the update
9726 of @var{vobj} happens. If you need this guarantee, you must use
9727 a stronger memory barrier such as:
9730 int *ptr = @var{something};
9732 *ptr = @var{something};
9733 asm volatile ("" : : : "memory");
9737 A scalar volatile object is read when it is accessed in a void context:
9740 volatile int *src = @var{somevalue};
9744 Such expressions are rvalues, and GCC implements this as a
9745 read of the volatile object being pointed to.
9747 Assignments are also expressions and have an rvalue. However when
9748 assigning to a scalar volatile, the volatile object is not reread,
9749 regardless of whether the assignment expression's rvalue is used or
9750 not. If the assignment's rvalue is used, the value is that assigned
9751 to the volatile object. For instance, there is no read of @var{vobj}
9752 in all the following cases:
9757 vobj = @var{something};
9758 obj = vobj = @var{something};
9759 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
9760 obj = (@var{something}, vobj = @var{anotherthing});
9763 If you need to read the volatile object after an assignment has
9764 occurred, you must use a separate expression with an intervening
9767 As bit-fields are not individually addressable, volatile bit-fields may
9768 be implicitly read when written to, or when adjacent bit-fields are
9769 accessed. Bit-field operations may be optimized such that adjacent
9770 bit-fields are only partially accessed, if they straddle a storage unit
9771 boundary. For these reasons it is unwise to use volatile bit-fields to
9774 @node Using Assembly Language with C
9775 @section How to Use Inline Assembly Language in C Code
9776 @cindex @code{asm} keyword
9777 @cindex assembly language in C
9778 @cindex inline assembly language
9779 @cindex mixing assembly language and C
9781 The @code{asm} keyword allows you to embed assembler instructions
9782 within C code. GCC provides two forms of inline @code{asm}
9783 statements. A @dfn{basic @code{asm}} statement is one with no
9784 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
9785 statement (@pxref{Extended Asm}) includes one or more operands.
9786 The extended form is preferred for mixing C and assembly language
9787 within a function, but to include assembly language at
9788 top level you must use basic @code{asm}.
9790 You can also use the @code{asm} keyword to override the assembler name
9791 for a C symbol, or to place a C variable in a specific register.
9794 * Basic Asm:: Inline assembler without operands.
9795 * Extended Asm:: Inline assembler with operands.
9796 * Constraints:: Constraints for @code{asm} operands
9797 * Asm Labels:: Specifying the assembler name to use for a C symbol.
9798 * Explicit Register Variables:: Defining variables residing in specified
9800 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
9804 @subsection Basic Asm --- Assembler Instructions Without Operands
9805 @cindex basic @code{asm}
9806 @cindex assembly language in C, basic
9808 A basic @code{asm} statement has the following syntax:
9811 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
9814 For the C language, the @code{asm} keyword is a GNU extension.
9815 When writing C code that can be compiled with @option{-ansi} and the
9816 @option{-std} options that select C dialects without GNU extensions, use
9817 @code{__asm__} instead of @code{asm} (@pxref{Alternate Keywords}). For
9818 the C++ language, @code{asm} is a standard keyword, but @code{__asm__}
9819 can be used for code compiled with @option{-fno-asm}.
9821 @subsubheading Qualifiers
9824 The optional @code{volatile} qualifier has no effect.
9825 All basic @code{asm} blocks are implicitly volatile.
9828 If you use the @code{inline} qualifier, then for inlining purposes the size
9829 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
9833 @subsubheading Parameters
9836 @item AssemblerInstructions
9837 This is a literal string that specifies the assembler code. The string can
9838 contain any instructions recognized by the assembler, including directives.
9839 GCC does not parse the assembler instructions themselves and
9840 does not know what they mean or even whether they are valid assembler input.
9842 You may place multiple assembler instructions together in a single @code{asm}
9843 string, separated by the characters normally used in assembly code for the
9844 system. A combination that works in most places is a newline to break the
9845 line, plus a tab character (written as @samp{\n\t}).
9846 Some assemblers allow semicolons as a line separator. However,
9847 note that some assembler dialects use semicolons to start a comment.
9850 @subsubheading Remarks
9851 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
9852 smaller, safer, and more efficient code, and in most cases it is a
9853 better solution than basic @code{asm}. However, there are two
9854 situations where only basic @code{asm} can be used:
9858 Extended @code{asm} statements have to be inside a C
9859 function, so to write inline assembly language at file scope (``top-level''),
9860 outside of C functions, you must use basic @code{asm}.
9861 You can use this technique to emit assembler directives,
9862 define assembly language macros that can be invoked elsewhere in the file,
9863 or write entire functions in assembly language.
9864 Basic @code{asm} statements outside of functions may not use any
9869 with the @code{naked} attribute also require basic @code{asm}
9870 (@pxref{Function Attributes}).
9873 Safely accessing C data and calling functions from basic @code{asm} is more
9874 complex than it may appear. To access C data, it is better to use extended
9877 Do not expect a sequence of @code{asm} statements to remain perfectly
9878 consecutive after compilation. If certain instructions need to remain
9879 consecutive in the output, put them in a single multi-instruction @code{asm}
9880 statement. Note that GCC's optimizers can move @code{asm} statements
9881 relative to other code, including across jumps.
9883 @code{asm} statements may not perform jumps into other @code{asm} statements.
9884 GCC does not know about these jumps, and therefore cannot take
9885 account of them when deciding how to optimize. Jumps from @code{asm} to C
9886 labels are only supported in extended @code{asm}.
9888 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9889 assembly code when optimizing. This can lead to unexpected duplicate
9890 symbol errors during compilation if your assembly code defines symbols or
9893 @strong{Warning:} The C standards do not specify semantics for @code{asm},
9894 making it a potential source of incompatibilities between compilers. These
9895 incompatibilities may not produce compiler warnings/errors.
9897 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
9898 means there is no way to communicate to the compiler what is happening
9899 inside them. GCC has no visibility of symbols in the @code{asm} and may
9900 discard them as unreferenced. It also does not know about side effects of
9901 the assembler code, such as modifications to memory or registers. Unlike
9902 some compilers, GCC assumes that no changes to general purpose registers
9903 occur. This assumption may change in a future release.
9905 To avoid complications from future changes to the semantics and the
9906 compatibility issues between compilers, consider replacing basic @code{asm}
9907 with extended @code{asm}. See
9908 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
9909 from basic asm to extended asm} for information about how to perform this
9912 The compiler copies the assembler instructions in a basic @code{asm}
9913 verbatim to the assembly language output file, without
9914 processing dialects or any of the @samp{%} operators that are available with
9915 extended @code{asm}. This results in minor differences between basic
9916 @code{asm} strings and extended @code{asm} templates. For example, to refer to
9917 registers you might use @samp{%eax} in basic @code{asm} and
9918 @samp{%%eax} in extended @code{asm}.
9920 On targets such as x86 that support multiple assembler dialects,
9921 all basic @code{asm} blocks use the assembler dialect specified by the
9922 @option{-masm} command-line option (@pxref{x86 Options}).
9923 Basic @code{asm} provides no
9924 mechanism to provide different assembler strings for different dialects.
9926 For basic @code{asm} with non-empty assembler string GCC assumes
9927 the assembler block does not change any general purpose registers,
9928 but it may read or write any globally accessible variable.
9930 Here is an example of basic @code{asm} for i386:
9933 /* Note that this code will not compile with -masm=intel */
9934 #define DebugBreak() asm("int $3")
9938 @subsection Extended Asm - Assembler Instructions with C Expression Operands
9939 @cindex extended @code{asm}
9940 @cindex assembly language in C, extended
9942 With extended @code{asm} you can read and write C variables from
9943 assembler and perform jumps from assembler code to C labels.
9944 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
9945 the operand parameters after the assembler template:
9948 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9949 : @var{OutputOperands}
9950 @r{[} : @var{InputOperands}
9951 @r{[} : @var{Clobbers} @r{]} @r{]})
9953 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9954 : @var{OutputOperands}
9955 : @var{InputOperands}
9959 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
9962 The @code{asm} keyword is a GNU extension.
9963 When writing code that can be compiled with @option{-ansi} and the
9964 various @option{-std} options, use @code{__asm__} instead of
9965 @code{asm} (@pxref{Alternate Keywords}).
9967 @subsubheading Qualifiers
9971 The typical use of extended @code{asm} statements is to manipulate input
9972 values to produce output values. However, your @code{asm} statements may
9973 also produce side effects. If so, you may need to use the @code{volatile}
9974 qualifier to disable certain optimizations. @xref{Volatile}.
9977 If you use the @code{inline} qualifier, then for inlining purposes the size
9978 of the @code{asm} statement is taken as the smallest size possible
9979 (@pxref{Size of an asm}).
9982 This qualifier informs the compiler that the @code{asm} statement may
9983 perform a jump to one of the labels listed in the @var{GotoLabels}.
9987 @subsubheading Parameters
9989 @item AssemblerTemplate
9990 This is a literal string that is the template for the assembler code. It is a
9991 combination of fixed text and tokens that refer to the input, output,
9992 and goto parameters. @xref{AssemblerTemplate}.
9994 @item OutputOperands
9995 A comma-separated list of the C variables modified by the instructions in the
9996 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
9999 A comma-separated list of C expressions read by the instructions in the
10000 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
10003 A comma-separated list of registers or other values changed by the
10004 @var{AssemblerTemplate}, beyond those listed as outputs.
10005 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
10008 When you are using the @code{goto} form of @code{asm}, this section contains
10009 the list of all C labels to which the code in the
10010 @var{AssemblerTemplate} may jump.
10013 @code{asm} statements may not perform jumps into other @code{asm} statements,
10014 only to the listed @var{GotoLabels}.
10015 GCC's optimizers do not know about other jumps; therefore they cannot take
10016 account of them when deciding how to optimize.
10019 The total number of input + output + goto operands is limited to 30.
10021 @subsubheading Remarks
10022 The @code{asm} statement allows you to include assembly instructions directly
10023 within C code. This may help you to maximize performance in time-sensitive
10024 code or to access assembly instructions that are not readily available to C
10027 Note that extended @code{asm} statements must be inside a function. Only
10028 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
10029 Functions declared with the @code{naked} attribute also require basic
10030 @code{asm} (@pxref{Function Attributes}).
10032 While the uses of @code{asm} are many and varied, it may help to think of an
10033 @code{asm} statement as a series of low-level instructions that convert input
10034 parameters to output parameters. So a simple (if not particularly useful)
10035 example for i386 using @code{asm} might look like this:
10041 asm ("mov %1, %0\n\t"
10046 printf("%d\n", dst);
10049 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
10052 @subsubsection Volatile
10053 @cindex volatile @code{asm}
10054 @cindex @code{asm} volatile
10056 GCC's optimizers sometimes discard @code{asm} statements if they determine
10057 there is no need for the output variables. Also, the optimizers may move
10058 code out of loops if they believe that the code will always return the same
10059 result (i.e.@: none of its input values change between calls). Using the
10060 @code{volatile} qualifier disables these optimizations. @code{asm} statements
10061 that have no output operands and @code{asm goto} statements,
10062 are implicitly volatile.
10064 This i386 code demonstrates a case that does not use (or require) the
10065 @code{volatile} qualifier. If it is performing assertion checking, this code
10066 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
10067 unreferenced by any code. As a result, the optimizers can discard the
10068 @code{asm} statement, which in turn removes the need for the entire
10069 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
10070 isn't needed you allow the optimizers to produce the most efficient code
10074 void DoCheck(uint32_t dwSomeValue)
10078 // Assumes dwSomeValue is not zero.
10081 : "r" (dwSomeValue)
10088 The next example shows a case where the optimizers can recognize that the input
10089 (@code{dwSomeValue}) never changes during the execution of the function and can
10090 therefore move the @code{asm} outside the loop to produce more efficient code.
10091 Again, using the @code{volatile} qualifier disables this type of optimization.
10094 void do_print(uint32_t dwSomeValue)
10098 for (uint32_t x=0; x < 5; x++)
10100 // Assumes dwSomeValue is not zero.
10103 : "r" (dwSomeValue)
10106 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
10111 The following example demonstrates a case where you need to use the
10112 @code{volatile} qualifier.
10113 It uses the x86 @code{rdtsc} instruction, which reads
10114 the computer's time-stamp counter. Without the @code{volatile} qualifier,
10115 the optimizers might assume that the @code{asm} block will always return the
10116 same value and therefore optimize away the second call.
10121 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
10122 "shl $32, %%rdx\n\t" // Shift the upper bits left.
10123 "or %%rdx, %0" // 'Or' in the lower bits.
10128 printf("msr: %llx\n", msr);
10130 // Do other work...
10132 // Reprint the timestamp
10133 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
10134 "shl $32, %%rdx\n\t" // Shift the upper bits left.
10135 "or %%rdx, %0" // 'Or' in the lower bits.
10140 printf("msr: %llx\n", msr);
10143 GCC's optimizers do not treat this code like the non-volatile code in the
10144 earlier examples. They do not move it out of loops or omit it on the
10145 assumption that the result from a previous call is still valid.
10147 Note that the compiler can move even @code{volatile asm} instructions relative
10148 to other code, including across jump instructions. For example, on many
10149 targets there is a system register that controls the rounding mode of
10150 floating-point operations. Setting it with a @code{volatile asm} statement,
10151 as in the following PowerPC example, does not work reliably.
10154 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
10158 The compiler may move the addition back before the @code{volatile asm}
10159 statement. To make it work as expected, add an artificial dependency to
10160 the @code{asm} by referencing a variable in the subsequent code, for
10164 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
10168 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
10169 assembly code when optimizing. This can lead to unexpected duplicate symbol
10170 errors during compilation if your @code{asm} code defines symbols or labels.
10172 (@pxref{AssemblerTemplate}) may help resolve this problem.
10174 @anchor{AssemblerTemplate}
10175 @subsubsection Assembler Template
10176 @cindex @code{asm} assembler template
10178 An assembler template is a literal string containing assembler instructions.
10179 The compiler replaces tokens in the template that refer
10180 to inputs, outputs, and goto labels,
10181 and then outputs the resulting string to the assembler. The
10182 string can contain any instructions recognized by the assembler, including
10183 directives. GCC does not parse the assembler instructions
10184 themselves and does not know what they mean or even whether they are valid
10185 assembler input. However, it does count the statements
10186 (@pxref{Size of an asm}).
10188 You may place multiple assembler instructions together in a single @code{asm}
10189 string, separated by the characters normally used in assembly code for the
10190 system. A combination that works in most places is a newline to break the
10191 line, plus a tab character to move to the instruction field (written as
10193 Some assemblers allow semicolons as a line separator. However, note
10194 that some assembler dialects use semicolons to start a comment.
10196 Do not expect a sequence of @code{asm} statements to remain perfectly
10197 consecutive after compilation, even when you are using the @code{volatile}
10198 qualifier. If certain instructions need to remain consecutive in the output,
10199 put them in a single multi-instruction @code{asm} statement.
10201 Accessing data from C programs without using input/output operands (such as
10202 by using global symbols directly from the assembler template) may not work as
10203 expected. Similarly, calling functions directly from an assembler template
10204 requires a detailed understanding of the target assembler and ABI.
10206 Since GCC does not parse the assembler template,
10207 it has no visibility of any
10208 symbols it references. This may result in GCC discarding those symbols as
10209 unreferenced unless they are also listed as input, output, or goto operands.
10211 @subsubheading Special format strings
10213 In addition to the tokens described by the input, output, and goto operands,
10214 these tokens have special meanings in the assembler template:
10218 Outputs a single @samp{%} into the assembler code.
10221 Outputs a number that is unique to each instance of the @code{asm}
10222 statement in the entire compilation. This option is useful when creating local
10223 labels and referring to them multiple times in a single template that
10224 generates multiple assembler instructions.
10229 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
10230 into the assembler code. When unescaped, these characters have special
10231 meaning to indicate multiple assembler dialects, as described below.
10234 @subsubheading Multiple assembler dialects in @code{asm} templates
10236 On targets such as x86, GCC supports multiple assembler dialects.
10237 The @option{-masm} option controls which dialect GCC uses as its
10238 default for inline assembler. The target-specific documentation for the
10239 @option{-masm} option contains the list of supported dialects, as well as the
10240 default dialect if the option is not specified. This information may be
10241 important to understand, since assembler code that works correctly when
10242 compiled using one dialect will likely fail if compiled using another.
10243 @xref{x86 Options}.
10245 If your code needs to support multiple assembler dialects (for example, if
10246 you are writing public headers that need to support a variety of compilation
10247 options), use constructs of this form:
10250 @{ dialect0 | dialect1 | dialect2... @}
10253 This construct outputs @code{dialect0}
10254 when using dialect #0 to compile the code,
10255 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
10256 braces than the number of dialects the compiler supports, the construct
10259 For example, if an x86 compiler supports two dialects
10260 (@samp{att}, @samp{intel}), an
10261 assembler template such as this:
10264 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
10268 is equivalent to one of
10271 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
10272 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
10275 Using that same compiler, this code:
10278 "xchg@{l@}\t@{%%@}ebx, %1"
10282 corresponds to either
10285 "xchgl\t%%ebx, %1" @r{/* att dialect */}
10286 "xchg\tebx, %1" @r{/* intel dialect */}
10289 There is no support for nesting dialect alternatives.
10291 @anchor{OutputOperands}
10292 @subsubsection Output Operands
10293 @cindex @code{asm} output operands
10295 An @code{asm} statement has zero or more output operands indicating the names
10296 of C variables modified by the assembler code.
10298 In this i386 example, @code{old} (referred to in the template string as
10299 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
10300 (@code{%2}) is an input:
10305 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
10306 "sbb %0,%0" // Use the CF to calculate old.
10307 : "=r" (old), "+rm" (*Base)
10314 Operands are separated by commas. Each operand has this format:
10317 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
10321 @item asmSymbolicName
10322 Specifies a symbolic name for the operand.
10323 Reference the name in the assembler template
10324 by enclosing it in square brackets
10325 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10326 that contains the definition. Any valid C variable name is acceptable,
10327 including names already defined in the surrounding code. No two operands
10328 within the same @code{asm} statement can use the same symbolic name.
10330 When not using an @var{asmSymbolicName}, use the (zero-based) position
10332 in the list of operands in the assembler template. For example if there are
10333 three output operands, use @samp{%0} in the template to refer to the first,
10334 @samp{%1} for the second, and @samp{%2} for the third.
10337 A string constant specifying constraints on the placement of the operand;
10338 @xref{Constraints}, for details.
10340 Output constraints must begin with either @samp{=} (a variable overwriting an
10341 existing value) or @samp{+} (when reading and writing). When using
10342 @samp{=}, do not assume the location contains the existing value
10343 on entry to the @code{asm}, except
10344 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
10346 After the prefix, there must be one or more additional constraints
10347 (@pxref{Constraints}) that describe where the value resides. Common
10348 constraints include @samp{r} for register and @samp{m} for memory.
10349 When you list more than one possible location (for example, @code{"=rm"}),
10350 the compiler chooses the most efficient one based on the current context.
10351 If you list as many alternates as the @code{asm} statement allows, you permit
10352 the optimizers to produce the best possible code.
10353 If you must use a specific register, but your Machine Constraints do not
10354 provide sufficient control to select the specific register you want,
10355 local register variables may provide a solution (@pxref{Local Register
10358 @item cvariablename
10359 Specifies a C lvalue expression to hold the output, typically a variable name.
10360 The enclosing parentheses are a required part of the syntax.
10364 When the compiler selects the registers to use to
10365 represent the output operands, it does not use any of the clobbered registers
10366 (@pxref{Clobbers and Scratch Registers}).
10368 Output operand expressions must be lvalues. The compiler cannot check whether
10369 the operands have data types that are reasonable for the instruction being
10370 executed. For output expressions that are not directly addressable (for
10371 example a bit-field), the constraint must allow a register. In that case, GCC
10372 uses the register as the output of the @code{asm}, and then stores that
10373 register into the output.
10375 Operands using the @samp{+} constraint modifier count as two operands
10376 (that is, both as input and output) towards the total maximum of 30 operands
10377 per @code{asm} statement.
10379 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
10380 operands that must not overlap an input. Otherwise,
10381 GCC may allocate the output operand in the same register as an unrelated
10382 input operand, on the assumption that the assembler code consumes its
10383 inputs before producing outputs. This assumption may be false if the assembler
10384 code actually consists of more than one instruction.
10386 The same problem can occur if one output parameter (@var{a}) allows a register
10387 constraint and another output parameter (@var{b}) allows a memory constraint.
10388 The code generated by GCC to access the memory address in @var{b} can contain
10389 registers which @emph{might} be shared by @var{a}, and GCC considers those
10390 registers to be inputs to the asm. As above, GCC assumes that such input
10391 registers are consumed before any outputs are written. This assumption may
10392 result in incorrect behavior if the @code{asm} statement writes to @var{a}
10394 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
10395 ensures that modifying @var{a} does not affect the address referenced by
10396 @var{b}. Otherwise, the location of @var{b}
10397 is undefined if @var{a} is modified before using @var{b}.
10399 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10400 instead of simply @samp{%2}). Typically these qualifiers are hardware
10401 dependent. The list of supported modifiers for x86 is found at
10402 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10404 If the C code that follows the @code{asm} makes no use of any of the output
10405 operands, use @code{volatile} for the @code{asm} statement to prevent the
10406 optimizers from discarding the @code{asm} statement as unneeded
10407 (see @ref{Volatile}).
10409 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
10410 references the first output operand as @code{%0} (were there a second, it
10411 would be @code{%1}, etc). The number of the first input operand is one greater
10412 than that of the last output operand. In this i386 example, that makes
10413 @code{Mask} referenced as @code{%1}:
10416 uint32_t Mask = 1234;
10425 That code overwrites the variable @code{Index} (@samp{=}),
10426 placing the value in a register (@samp{r}).
10427 Using the generic @samp{r} constraint instead of a constraint for a specific
10428 register allows the compiler to pick the register to use, which can result
10429 in more efficient code. This may not be possible if an assembler instruction
10430 requires a specific register.
10432 The following i386 example uses the @var{asmSymbolicName} syntax.
10434 same result as the code above, but some may consider it more readable or more
10435 maintainable since reordering index numbers is not necessary when adding or
10436 removing operands. The names @code{aIndex} and @code{aMask}
10437 are only used in this example to emphasize which
10438 names get used where.
10439 It is acceptable to reuse the names @code{Index} and @code{Mask}.
10442 uint32_t Mask = 1234;
10445 asm ("bsfl %[aMask], %[aIndex]"
10446 : [aIndex] "=r" (Index)
10447 : [aMask] "r" (Mask)
10451 Here are some more examples of output operands.
10458 asm ("mov %[e], %[d]"
10463 Here, @code{d} may either be in a register or in memory. Since the compiler
10464 might already have the current value of the @code{uint32_t} location
10465 pointed to by @code{e}
10466 in a register, you can enable it to choose the best location
10467 for @code{d} by specifying both constraints.
10469 @anchor{FlagOutputOperands}
10470 @subsubsection Flag Output Operands
10471 @cindex @code{asm} flag output operands
10473 Some targets have a special register that holds the ``flags'' for the
10474 result of an operation or comparison. Normally, the contents of that
10475 register are either unmodifed by the asm, or the @code{asm} statement is
10476 considered to clobber the contents.
10478 On some targets, a special form of output operand exists by which
10479 conditions in the flags register may be outputs of the asm. The set of
10480 conditions supported are target specific, but the general rule is that
10481 the output variable must be a scalar integer, and the value is boolean.
10482 When supported, the target defines the preprocessor symbol
10483 @code{__GCC_ASM_FLAG_OUTPUTS__}.
10485 Because of the special nature of the flag output operands, the constraint
10486 may not include alternatives.
10488 Most often, the target has only one flags register, and thus is an implied
10489 operand of many instructions. In this case, the operand should not be
10490 referenced within the assembler template via @code{%0} etc, as there's
10491 no corresponding text in the assembly language.
10496 The flag output constraints for the ARM family are of the form
10497 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
10498 conditions defined in the ARM ARM for @code{ConditionHolds}.
10502 Z flag set, or equal
10504 Z flag clear or not equal
10507 C flag set or unsigned greater than equal
10510 C flag clear or unsigned less than
10512 N flag set or ``minus''
10514 N flag clear or ``plus''
10516 V flag set or signed overflow
10520 unsigned greater than
10522 unsigned less than equal
10524 signed greater than equal
10528 signed greater than
10530 signed less than equal
10533 The flag output constraints are not supported in thumb1 mode.
10536 The flag output constraints for the x86 family are of the form
10537 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
10538 conditions defined in the ISA manual for @code{j@var{cc}} or
10539 @code{set@var{cc}}.
10543 ``above'' or unsigned greater than
10545 ``above or equal'' or unsigned greater than or equal
10547 ``below'' or unsigned less than
10549 ``below or equal'' or unsigned less than or equal
10554 ``equal'' or zero flag set
10556 signed greater than
10558 signed greater than or equal
10562 signed less than or equal
10583 ``not'' @var{flag}, or inverted versions of those above
10588 @anchor{InputOperands}
10589 @subsubsection Input Operands
10590 @cindex @code{asm} input operands
10591 @cindex @code{asm} expressions
10593 Input operands make values from C variables and expressions available to the
10596 Operands are separated by commas. Each operand has this format:
10599 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
10603 @item asmSymbolicName
10604 Specifies a symbolic name for the operand.
10605 Reference the name in the assembler template
10606 by enclosing it in square brackets
10607 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10608 that contains the definition. Any valid C variable name is acceptable,
10609 including names already defined in the surrounding code. No two operands
10610 within the same @code{asm} statement can use the same symbolic name.
10612 When not using an @var{asmSymbolicName}, use the (zero-based) position
10614 in the list of operands in the assembler template. For example if there are
10615 two output operands and three inputs,
10616 use @samp{%2} in the template to refer to the first input operand,
10617 @samp{%3} for the second, and @samp{%4} for the third.
10620 A string constant specifying constraints on the placement of the operand;
10621 @xref{Constraints}, for details.
10623 Input constraint strings may not begin with either @samp{=} or @samp{+}.
10624 When you list more than one possible location (for example, @samp{"irm"}),
10625 the compiler chooses the most efficient one based on the current context.
10626 If you must use a specific register, but your Machine Constraints do not
10627 provide sufficient control to select the specific register you want,
10628 local register variables may provide a solution (@pxref{Local Register
10631 Input constraints can also be digits (for example, @code{"0"}). This indicates
10632 that the specified input must be in the same place as the output constraint
10633 at the (zero-based) index in the output constraint list.
10634 When using @var{asmSymbolicName} syntax for the output operands,
10635 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
10638 This is the C variable or expression being passed to the @code{asm} statement
10639 as input. The enclosing parentheses are a required part of the syntax.
10643 When the compiler selects the registers to use to represent the input
10644 operands, it does not use any of the clobbered registers
10645 (@pxref{Clobbers and Scratch Registers}).
10647 If there are no output operands but there are input operands, place two
10648 consecutive colons where the output operands would go:
10651 __asm__ ("some instructions"
10652 : /* No outputs. */
10653 : "r" (Offset / 8));
10656 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
10657 (except for inputs tied to outputs). The compiler assumes that on exit from
10658 the @code{asm} statement these operands contain the same values as they
10659 had before executing the statement.
10660 It is @emph{not} possible to use clobbers
10661 to inform the compiler that the values in these inputs are changing. One
10662 common work-around is to tie the changing input variable to an output variable
10663 that never gets used. Note, however, that if the code that follows the
10664 @code{asm} statement makes no use of any of the output operands, the GCC
10665 optimizers may discard the @code{asm} statement as unneeded
10666 (see @ref{Volatile}).
10668 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10669 instead of simply @samp{%2}). Typically these qualifiers are hardware
10670 dependent. The list of supported modifiers for x86 is found at
10671 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10673 In this example using the fictitious @code{combine} instruction, the
10674 constraint @code{"0"} for input operand 1 says that it must occupy the same
10675 location as output operand 0. Only input operands may use numbers in
10676 constraints, and they must each refer to an output operand. Only a number (or
10677 the symbolic assembler name) in the constraint can guarantee that one operand
10678 is in the same place as another. The mere fact that @code{foo} is the value of
10679 both operands is not enough to guarantee that they are in the same place in
10680 the generated assembler code.
10683 asm ("combine %2, %0"
10685 : "0" (foo), "g" (bar));
10688 Here is an example using symbolic names.
10691 asm ("cmoveq %1, %2, %[result]"
10692 : [result] "=r"(result)
10693 : "r" (test), "r" (new), "[result]" (old));
10696 @anchor{Clobbers and Scratch Registers}
10697 @subsubsection Clobbers and Scratch Registers
10698 @cindex @code{asm} clobbers
10699 @cindex @code{asm} scratch registers
10701 While the compiler is aware of changes to entries listed in the output
10702 operands, the inline @code{asm} code may modify more than just the outputs. For
10703 example, calculations may require additional registers, or the processor may
10704 overwrite a register as a side effect of a particular assembler instruction.
10705 In order to inform the compiler of these changes, list them in the clobber
10706 list. Clobber list items are either register names or the special clobbers
10707 (listed below). Each clobber list item is a string constant
10708 enclosed in double quotes and separated by commas.
10710 Clobber descriptions may not in any way overlap with an input or output
10711 operand. For example, you may not have an operand describing a register class
10712 with one member when listing that register in the clobber list. Variables
10713 declared to live in specific registers (@pxref{Explicit Register
10714 Variables}) and used
10715 as @code{asm} input or output operands must have no part mentioned in the
10716 clobber description. In particular, there is no way to specify that input
10717 operands get modified without also specifying them as output operands.
10719 When the compiler selects which registers to use to represent input and output
10720 operands, it does not use any of the clobbered registers. As a result,
10721 clobbered registers are available for any use in the assembler code.
10723 Another restriction is that the clobber list should not contain the
10724 stack pointer register. This is because the compiler requires the
10725 value of the stack pointer to be the same after an @code{asm}
10726 statement as it was on entry to the statement. However, previous
10727 versions of GCC did not enforce this rule and allowed the stack
10728 pointer to appear in the list, with unclear semantics. This behavior
10729 is deprecated and listing the stack pointer may become an error in
10730 future versions of GCC@.
10732 Here is a realistic example for the VAX showing the use of clobbered
10736 asm volatile ("movc3 %0, %1, %2"
10737 : /* No outputs. */
10738 : "g" (from), "g" (to), "g" (count)
10739 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
10742 Also, there are two special clobber arguments:
10746 The @code{"cc"} clobber indicates that the assembler code modifies the flags
10747 register. On some machines, GCC represents the condition codes as a specific
10748 hardware register; @code{"cc"} serves to name this register.
10749 On other machines, condition code handling is different,
10750 and specifying @code{"cc"} has no effect. But
10751 it is valid no matter what the target.
10754 The @code{"memory"} clobber tells the compiler that the assembly code
10756 reads or writes to items other than those listed in the input and output
10757 operands (for example, accessing the memory pointed to by one of the input
10758 parameters). To ensure memory contains correct values, GCC may need to flush
10759 specific register values to memory before executing the @code{asm}. Further,
10760 the compiler does not assume that any values read from memory before an
10761 @code{asm} remain unchanged after that @code{asm}; it reloads them as
10763 Using the @code{"memory"} clobber effectively forms a read/write
10764 memory barrier for the compiler.
10766 Note that this clobber does not prevent the @emph{processor} from doing
10767 speculative reads past the @code{asm} statement. To prevent that, you need
10768 processor-specific fence instructions.
10772 Flushing registers to memory has performance implications and may be
10773 an issue for time-sensitive code. You can provide better information
10774 to GCC to avoid this, as shown in the following examples. At a
10775 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
10776 need to be flushed.
10778 Here is a fictitious sum of squares instruction, that takes two
10779 pointers to floating point values in memory and produces a floating
10780 point register output.
10781 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
10782 parameters, once to specify memory accessed, and once to specify a
10783 base register used by the @code{asm}. You won't normally be wasting a
10784 register by doing this as GCC can use the same register for both
10785 purposes. However, it would be foolish to use both @code{%1} and
10786 @code{%3} for @code{x} in this @code{asm} and expect them to be the
10787 same. In fact, @code{%3} may well not be a register. It might be a
10788 symbolic memory reference to the object pointed to by @code{x}.
10791 asm ("sumsq %0, %1, %2"
10793 : "r" (x), "r" (y), "m" (*x), "m" (*y));
10796 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
10797 Notice that the @code{x}, @code{y} and @code{z} pointer registers
10798 must be specified as input/output because the @code{asm} modifies
10802 asm ("vecmul %0, %1, %2"
10803 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
10804 : "m" (*x), "m" (*y));
10807 An x86 example where the string memory argument is of unknown length.
10811 : "=c" (count), "+D" (p)
10812 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
10815 If you know the above will only be reading a ten byte array then you
10816 could instead use a memory input like:
10817 @code{"m" (*(const char (*)[10]) p)}.
10819 Here is an example of a PowerPC vector scale implemented in assembly,
10820 complete with vector and condition code clobbers, and some initialized
10821 offset registers that are unchanged by the @code{asm}.
10825 dscal (size_t n, double *x, double alpha)
10827 asm ("/* lots of asm here */"
10828 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
10829 : "d" (alpha), "b" (32), "b" (48), "b" (64),
10830 "b" (80), "b" (96), "b" (112)
10832 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
10833 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
10837 Rather than allocating fixed registers via clobbers to provide scratch
10838 registers for an @code{asm} statement, an alternative is to define a
10839 variable and make it an early-clobber output as with @code{a2} and
10840 @code{a3} in the example below. This gives the compiler register
10841 allocator more freedom. You can also define a variable and make it an
10842 output tied to an input as with @code{a0} and @code{a1}, tied
10843 respectively to @code{ap} and @code{lda}. Of course, with tied
10844 outputs your @code{asm} can't use the input value after modifying the
10845 output register since they are one and the same register. What's
10846 more, if you omit the early-clobber on the output, it is possible that
10847 GCC might allocate the same register to another of the inputs if GCC
10848 could prove they had the same value on entry to the @code{asm}. This
10849 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
10850 might conceivably be known to have the value 16 and without an
10851 early-clobber share the same register as @code{%11}. On the other
10852 hand, @code{ap} can't be the same as any of the other inputs, so an
10853 early-clobber on @code{a0} is not needed. It is also not desirable in
10854 this case. An early-clobber on @code{a0} would cause GCC to allocate
10855 a separate register for the @code{"m" (*(const double (*)[]) ap)}
10856 input. Note that tying an input to an output is the way to set up an
10857 initialized temporary register modified by an @code{asm} statement.
10858 An input not tied to an output is assumed by GCC to be unchanged, for
10859 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
10860 use that register in following code if the value 16 happened to be
10861 needed. You can even use a normal @code{asm} output for a scratch if
10862 all inputs that might share the same register are consumed before the
10863 scratch is used. The VSX registers clobbered by the @code{asm}
10864 statement could have used this technique except for GCC's limit on the
10865 number of @code{asm} parameters.
10869 dgemv_kernel_4x4 (long n, const double *ap, long lda,
10870 const double *x, double *y, double alpha)
10879 /* lots of asm here */
10880 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
10881 "#a0=%3 a1=%4 a2=%5 a3=%6"
10883 "+m" (*(double (*)[n]) y),
10891 "m" (*(const double (*)[n]) x),
10892 "m" (*(const double (*)[]) ap),
10900 "vs32","vs33","vs34","vs35","vs36","vs37",
10901 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
10906 @anchor{GotoLabels}
10907 @subsubsection Goto Labels
10908 @cindex @code{asm} goto labels
10910 @code{asm goto} allows assembly code to jump to one or more C labels. The
10911 @var{GotoLabels} section in an @code{asm goto} statement contains
10913 list of all C labels to which the assembler code may jump. GCC assumes that
10914 @code{asm} execution falls through to the next statement (if this is not the
10915 case, consider using the @code{__builtin_unreachable} intrinsic after the
10916 @code{asm} statement). Optimization of @code{asm goto} may be improved by
10917 using the @code{hot} and @code{cold} label attributes (@pxref{Label
10920 If the assembler code does modify anything, use the @code{"memory"} clobber
10922 optimizers to flush all register values to memory and reload them if
10923 necessary after the @code{asm} statement.
10925 Also note that an @code{asm goto} statement is always implicitly
10926 considered volatile.
10928 Be careful when you set output operands inside @code{asm goto} only on
10929 some possible control flow paths. If you don't set up the output on
10930 given path and never use it on this path, it is okay. Otherwise, you
10931 should use @samp{+} constraint modifier meaning that the operand is
10932 input and output one. With this modifier you will have the correct
10933 values on all possible paths from the @code{asm goto}.
10935 To reference a label in the assembler template, prefix it with
10936 @samp{%l} (lowercase @samp{L}) followed by its (zero-based) position
10937 in @var{GotoLabels} plus the number of input and output operands.
10938 Output operand with constraint modifier @samp{+} is counted as two
10939 operands because it is considered as one output and one input operand.
10940 For example, if the @code{asm} has three inputs, one output operand
10941 with constraint modifier @samp{+} and one output operand with
10942 constraint modifier @samp{=} and references two labels, refer to the
10943 first label as @samp{%l6} and the second as @samp{%l7}).
10945 Alternately, you can reference labels using the actual C label name
10946 enclosed in brackets. For example, to reference a label named
10947 @code{carry}, you can use @samp{%l[carry]}. The label must still be
10948 listed in the @var{GotoLabels} section when using this approach. It
10949 is better to use the named references for labels as in this case you
10950 can avoid counting input and output operands and special treatment of
10951 output operands with constraint modifier @samp{+}.
10953 Here is an example of @code{asm goto} for i386:
10959 : /* No outputs. */
10960 : "r" (p1), "r" (p2)
10970 The following example shows an @code{asm goto} that uses a memory clobber.
10976 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
10977 : /* No outputs. */
10987 The following example shows an @code{asm goto} that uses an output.
10992 asm goto ("dec %0; jb %l[stop]"
11003 The following artificial example shows an @code{asm goto} that sets
11004 up an output only on one path inside the @code{asm goto}. Usage of
11005 constraint modifier @code{=} instead of @code{+} would be wrong as
11006 @code{factor} is used on all paths from the @code{asm goto}.
11012 asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0"
11018 return inp * factor; /* return 2 * inp or 0 if inp < 10 */
11022 @anchor{x86Operandmodifiers}
11023 @subsubsection x86 Operand Modifiers
11025 References to input, output, and goto operands in the assembler template
11026 of extended @code{asm} statements can use
11027 modifiers to affect the way the operands are formatted in
11028 the code output to the assembler. For example, the
11029 following code uses the @samp{h} and @samp{b} modifiers for x86:
11033 asm volatile ("xchg %h0, %b0" : "+a" (num) );
11037 These modifiers generate this assembler code:
11043 The rest of this discussion uses the following code for illustrative purposes.
11052 asm volatile goto ("some assembler instructions here"
11053 : /* No outputs. */
11054 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
11055 : /* No clobbers. */
11060 With no modifiers, this is what the output from the operands would be
11061 for the @samp{att} and @samp{intel} dialects of assembler:
11063 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
11064 @headitem Operand @tab @samp{att} @tab @samp{intel}
11073 @tab @code{OFFSET FLAT:.L3}
11085 The table below shows the list of supported modifiers and their effects.
11087 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
11088 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
11090 @tab Print an absolute memory reference.
11095 @tab Print the QImode name of the register.
11100 @tab print the opcode suffix of b.
11105 @tab Require a constant operand and print the constant expression with no punctuation.
11110 @tab print duplicated register operand for AVX instruction.
11112 @tab @code{%xmm0, %xmm0}
11113 @tab @code{xmm0, xmm0}
11115 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
11116 Otherwise mode is unspecified (VOIDmode).
11121 @tab Print the V16SFmode name of the register.
11126 @tab Print the QImode name for a ``high'' register.
11131 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
11132 high 8 bytes of SSE values. For a memref in (%rax), it generates
11134 @tab @code{8(%rax)}
11137 @tab Print the SImode name of the register.
11142 @tab Print the label name with no punctuation.
11147 @tab print the opcode suffix of l.
11157 @tab Print raw symbol name (without syntax-specific prefixes).
11162 @tab If used for a function, print the PLT suffix and generate PIC code.
11163 For example, emit @code{foo@@PLT} instead of 'foo' for the function
11164 foo(). If used for a constant, drop all syntax-specific prefixes and
11165 issue the bare constant. See @code{p} above.
11167 @tab Print the DImode name of the register.
11172 @tab print the opcode suffix of q.
11177 @tab print embedded rounding and sae.
11179 @tab @code{@{rn-sae@}, }
11180 @tab @code{, @{rn-sae@}}
11182 @tab print only sae.
11184 @tab @code{@{sae@}, }
11185 @tab @code{, @{sae@}}
11187 @tab print a shift double count, followed by the assemblers argument
11188 delimiterprint the opcode suffix of s.
11193 @tab print the opcode suffix of s.
11198 @tab print the V8SFmode name of the register.
11203 @tab print the opcode suffix of t.
11208 @tab print naked full integer register name without %.
11213 @tab Print the HImode name of the register.
11218 @tab print the opcode suffix of w.
11223 @tab print the V4SFmode name of the register.
11228 @tab print "st(0)" instead of "st" as a register.
11233 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
11238 @tab Like @code{z}, with special suffixes for x87 instructions.
11242 @anchor{x86floatingpointasmoperands}
11243 @subsubsection x86 Floating-Point @code{asm} Operands
11245 On x86 targets, there are several rules on the usage of stack-like registers
11246 in the operands of an @code{asm}. These rules apply only to the operands
11247 that are stack-like registers:
11251 Given a set of input registers that die in an @code{asm}, it is
11252 necessary to know which are implicitly popped by the @code{asm}, and
11253 which must be explicitly popped by GCC@.
11255 An input register that is implicitly popped by the @code{asm} must be
11256 explicitly clobbered, unless it is constrained to match an
11260 For any input register that is implicitly popped by an @code{asm}, it is
11261 necessary to know how to adjust the stack to compensate for the pop.
11262 If any non-popped input is closer to the top of the reg-stack than
11263 the implicitly popped register, it would not be possible to know what the
11264 stack looked like---it's not clear how the rest of the stack ``slides
11267 All implicitly popped input registers must be closer to the top of
11268 the reg-stack than any input that is not implicitly popped.
11270 It is possible that if an input dies in an @code{asm}, the compiler might
11271 use the input register for an output reload. Consider this example:
11274 asm ("foo" : "=t" (a) : "f" (b));
11278 This code says that input @code{b} is not popped by the @code{asm}, and that
11279 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
11280 deeper after the @code{asm} than it was before. But, it is possible that
11281 reload may think that it can use the same register for both the input and
11284 To prevent this from happening,
11285 if any input operand uses the @samp{f} constraint, all output register
11286 constraints must use the @samp{&} early-clobber modifier.
11288 The example above is correctly written as:
11291 asm ("foo" : "=&t" (a) : "f" (b));
11295 Some operands need to be in particular places on the stack. All
11296 output operands fall in this category---GCC has no other way to
11297 know which registers the outputs appear in unless you indicate
11298 this in the constraints.
11300 Output operands must specifically indicate which register an output
11301 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
11302 constraints must select a class with a single register.
11305 Output operands may not be ``inserted'' between existing stack registers.
11306 Since no 387 opcode uses a read/write operand, all output operands
11307 are dead before the @code{asm}, and are pushed by the @code{asm}.
11308 It makes no sense to push anywhere but the top of the reg-stack.
11310 Output operands must start at the top of the reg-stack: output
11311 operands may not ``skip'' a register.
11314 Some @code{asm} statements may need extra stack space for internal
11315 calculations. This can be guaranteed by clobbering stack registers
11316 unrelated to the inputs and outputs.
11321 takes one input, which is internally popped, and produces two outputs.
11324 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
11328 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
11329 and replaces them with one output. The @code{st(1)} clobber is necessary
11330 for the compiler to know that @code{fyl2xp1} pops both inputs.
11333 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
11336 @anchor{msp430Operandmodifiers}
11337 @subsubsection MSP430 Operand Modifiers
11339 The list below describes the supported modifiers and their effects for MSP430.
11341 @multitable @columnfractions .10 .90
11342 @headitem Modifier @tab Description
11343 @item @code{A} @tab Select low 16-bits of the constant/register/memory operand.
11344 @item @code{B} @tab Select high 16-bits of the constant/register/memory
11346 @item @code{C} @tab Select bits 32-47 of the constant/register/memory operand.
11347 @item @code{D} @tab Select bits 48-63 of the constant/register/memory operand.
11348 @item @code{H} @tab Equivalent to @code{B} (for backwards compatibility).
11349 @item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant
11351 @item @code{J} @tab Print an integer without a @code{#} prefix.
11352 @item @code{L} @tab Equivalent to @code{A} (for backwards compatibility).
11353 @item @code{O} @tab Offset of the current frame from the top of the stack.
11354 @item @code{Q} @tab Use the @code{A} instruction postfix.
11355 @item @code{R} @tab Inverse of condition code, for unsigned comparisons.
11356 @item @code{W} @tab Subtract 16 from the constant value.
11357 @item @code{X} @tab Use the @code{X} instruction postfix.
11358 @item @code{Y} @tab Subtract 4 from the constant value.
11359 @item @code{Z} @tab Subtract 1 from the constant value.
11360 @item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the
11361 instruction, depending on the mode.
11362 @item @code{d} @tab Offset 1 byte of a memory reference or constant value.
11363 @item @code{e} @tab Offset 3 bytes of a memory reference or constant value.
11364 @item @code{f} @tab Offset 5 bytes of a memory reference or constant value.
11365 @item @code{g} @tab Offset 7 bytes of a memory reference or constant value.
11366 @item @code{p} @tab Print the value of 2, raised to the power of the given
11367 constant. Used to select the specified bit position.
11368 @item @code{r} @tab Inverse of condition code, for signed comparisons.
11369 @item @code{x} @tab Equivialent to @code{X}, but only for pointers.
11377 @subsection Controlling Names Used in Assembler Code
11378 @cindex assembler names for identifiers
11379 @cindex names used in assembler code
11380 @cindex identifiers, names in assembler code
11382 You can specify the name to be used in the assembler code for a C
11383 function or variable by writing the @code{asm} (or @code{__asm__})
11384 keyword after the declarator.
11385 It is up to you to make sure that the assembler names you choose do not
11386 conflict with any other assembler symbols, or reference registers.
11388 @subsubheading Assembler names for data:
11390 This sample shows how to specify the assembler name for data:
11393 int foo asm ("myfoo") = 2;
11397 This specifies that the name to be used for the variable @code{foo} in
11398 the assembler code should be @samp{myfoo} rather than the usual
11401 On systems where an underscore is normally prepended to the name of a C
11402 variable, this feature allows you to define names for the
11403 linker that do not start with an underscore.
11405 GCC does not support using this feature with a non-static local variable
11406 since such variables do not have assembler names. If you are
11407 trying to put the variable in a particular register, see
11408 @ref{Explicit Register Variables}.
11410 @subsubheading Assembler names for functions:
11412 To specify the assembler name for functions, write a declaration for the
11413 function before its definition and put @code{asm} there, like this:
11416 int func (int x, int y) asm ("MYFUNC");
11418 int func (int x, int y)
11424 This specifies that the name to be used for the function @code{func} in
11425 the assembler code should be @code{MYFUNC}.
11427 @node Explicit Register Variables
11428 @subsection Variables in Specified Registers
11429 @anchor{Explicit Reg Vars}
11430 @cindex explicit register variables
11431 @cindex variables in specified registers
11432 @cindex specified registers
11434 GNU C allows you to associate specific hardware registers with C
11435 variables. In almost all cases, allowing the compiler to assign
11436 registers produces the best code. However under certain unusual
11437 circumstances, more precise control over the variable storage is
11440 Both global and local variables can be associated with a register. The
11441 consequences of performing this association are very different between
11442 the two, as explained in the sections below.
11445 * Global Register Variables:: Variables declared at global scope.
11446 * Local Register Variables:: Variables declared within a function.
11449 @node Global Register Variables
11450 @subsubsection Defining Global Register Variables
11451 @anchor{Global Reg Vars}
11452 @cindex global register variables
11453 @cindex registers, global variables in
11454 @cindex registers, global allocation
11456 You can define a global register variable and associate it with a specified
11457 register like this:
11460 register int *foo asm ("r12");
11464 Here @code{r12} is the name of the register that should be used. Note that
11465 this is the same syntax used for defining local register variables, but for
11466 a global variable the declaration appears outside a function. The
11467 @code{register} keyword is required, and cannot be combined with
11468 @code{static}. The register name must be a valid register name for the
11471 Do not use type qualifiers such as @code{const} and @code{volatile}, as
11472 the outcome may be contrary to expectations. In particular, using the
11473 @code{volatile} qualifier does not fully prevent the compiler from
11474 optimizing accesses to the register.
11476 Registers are a scarce resource on most systems and allowing the
11477 compiler to manage their usage usually results in the best code. However,
11478 under special circumstances it can make sense to reserve some globally.
11479 For example this may be useful in programs such as programming language
11480 interpreters that have a couple of global variables that are accessed
11483 After defining a global register variable, for the current compilation
11487 @item If the register is a call-saved register, call ABI is affected:
11488 the register will not be restored in function epilogue sequences after
11489 the variable has been assigned. Therefore, functions cannot safely
11490 return to callers that assume standard ABI.
11491 @item Conversely, if the register is a call-clobbered register, making
11492 calls to functions that use standard ABI may lose contents of the variable.
11493 Such calls may be created by the compiler even if none are evident in
11494 the original program, for example when libgcc functions are used to
11495 make up for unavailable instructions.
11496 @item Accesses to the variable may be optimized as usual and the register
11497 remains available for allocation and use in any computations, provided that
11498 observable values of the variable are not affected.
11499 @item If the variable is referenced in inline assembly, the type of access
11500 must be provided to the compiler via constraints (@pxref{Constraints}).
11501 Accesses from basic asms are not supported.
11504 Note that these points @emph{only} apply to code that is compiled with the
11505 definition. The behavior of code that is merely linked in (for example
11506 code from libraries) is not affected.
11508 If you want to recompile source files that do not actually use your global
11509 register variable so they do not use the specified register for any other
11510 purpose, you need not actually add the global register declaration to
11511 their source code. It suffices to specify the compiler option
11512 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
11515 @subsubheading Declaring the variable
11517 Global register variables cannot have initial values, because an
11518 executable file has no means to supply initial contents for a register.
11520 When selecting a register, choose one that is normally saved and
11521 restored by function calls on your machine. This ensures that code
11522 which is unaware of this reservation (such as library routines) will
11523 restore it before returning.
11525 On machines with register windows, be sure to choose a global
11526 register that is not affected magically by the function call mechanism.
11528 @subsubheading Using the variable
11530 @cindex @code{qsort}, and global register variables
11531 When calling routines that are not aware of the reservation, be
11532 cautious if those routines call back into code which uses them. As an
11533 example, if you call the system library version of @code{qsort}, it may
11534 clobber your registers during execution, but (if you have selected
11535 appropriate registers) it will restore them before returning. However
11536 it will @emph{not} restore them before calling @code{qsort}'s comparison
11537 function. As a result, global values will not reliably be available to
11538 the comparison function unless the @code{qsort} function itself is rebuilt.
11540 Similarly, it is not safe to access the global register variables from signal
11541 handlers or from more than one thread of control. Unless you recompile
11542 them specially for the task at hand, the system library routines may
11543 temporarily use the register for other things. Furthermore, since the register
11544 is not reserved exclusively for the variable, accessing it from handlers of
11545 asynchronous signals may observe unrelated temporary values residing in the
11548 @cindex register variable after @code{longjmp}
11549 @cindex global register after @code{longjmp}
11550 @cindex value after @code{longjmp}
11553 On most machines, @code{longjmp} restores to each global register
11554 variable the value it had at the time of the @code{setjmp}. On some
11555 machines, however, @code{longjmp} does not change the value of global
11556 register variables. To be portable, the function that called @code{setjmp}
11557 should make other arrangements to save the values of the global register
11558 variables, and to restore them in a @code{longjmp}. This way, the same
11559 thing happens regardless of what @code{longjmp} does.
11561 @node Local Register Variables
11562 @subsubsection Specifying Registers for Local Variables
11563 @anchor{Local Reg Vars}
11564 @cindex local variables, specifying registers
11565 @cindex specifying registers for local variables
11566 @cindex registers for local variables
11568 You can define a local register variable and associate it with a specified
11569 register like this:
11572 register int *foo asm ("r12");
11576 Here @code{r12} is the name of the register that should be used. Note
11577 that this is the same syntax used for defining global register variables,
11578 but for a local variable the declaration appears within a function. The
11579 @code{register} keyword is required, and cannot be combined with
11580 @code{static}. The register name must be a valid register name for the
11583 Do not use type qualifiers such as @code{const} and @code{volatile}, as
11584 the outcome may be contrary to expectations. In particular, when the
11585 @code{const} qualifier is used, the compiler may substitute the
11586 variable with its initializer in @code{asm} statements, which may cause
11587 the corresponding operand to appear in a different register.
11589 As with global register variables, it is recommended that you choose
11590 a register that is normally saved and restored by function calls on your
11591 machine, so that calls to library routines will not clobber it.
11593 The only supported use for this feature is to specify registers
11594 for input and output operands when calling Extended @code{asm}
11595 (@pxref{Extended Asm}). This may be necessary if the constraints for a
11596 particular machine don't provide sufficient control to select the desired
11597 register. To force an operand into a register, create a local variable
11598 and specify the register name after the variable's declaration. Then use
11599 the local variable for the @code{asm} operand and specify any constraint
11600 letter that matches the register:
11603 register int *p1 asm ("r0") = @dots{};
11604 register int *p2 asm ("r1") = @dots{};
11605 register int *result asm ("r0");
11606 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
11609 @emph{Warning:} In the above example, be aware that a register (for example
11610 @code{r0}) can be call-clobbered by subsequent code, including function
11611 calls and library calls for arithmetic operators on other variables (for
11612 example the initialization of @code{p2}). In this case, use temporary
11613 variables for expressions between the register assignments:
11617 register int *p1 asm ("r0") = @dots{};
11618 register int *p2 asm ("r1") = t1;
11619 register int *result asm ("r0");
11620 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
11623 Defining a register variable does not reserve the register. Other than
11624 when invoking the Extended @code{asm}, the contents of the specified
11625 register are not guaranteed. For this reason, the following uses
11626 are explicitly @emph{not} supported. If they appear to work, it is only
11627 happenstance, and may stop working as intended due to (seemingly)
11628 unrelated changes in surrounding code, or even minor changes in the
11629 optimization of a future version of gcc:
11632 @item Passing parameters to or from Basic @code{asm}
11633 @item Passing parameters to or from Extended @code{asm} without using input
11634 or output operands.
11635 @item Passing parameters to or from routines written in assembler (or
11636 other languages) using non-standard calling conventions.
11639 Some developers use Local Register Variables in an attempt to improve
11640 gcc's allocation of registers, especially in large functions. In this
11641 case the register name is essentially a hint to the register allocator.
11642 While in some instances this can generate better code, improvements are
11643 subject to the whims of the allocator/optimizers. Since there are no
11644 guarantees that your improvements won't be lost, this usage of Local
11645 Register Variables is discouraged.
11647 On the MIPS platform, there is related use for local register variables
11648 with slightly different characteristics (@pxref{MIPS Coprocessors,,
11649 Defining coprocessor specifics for MIPS targets, gccint,
11650 GNU Compiler Collection (GCC) Internals}).
11652 @node Size of an asm
11653 @subsection Size of an @code{asm}
11655 Some targets require that GCC track the size of each instruction used
11656 in order to generate correct code. Because the final length of the
11657 code produced by an @code{asm} statement is only known by the
11658 assembler, GCC must make an estimate as to how big it will be. It
11659 does this by counting the number of instructions in the pattern of the
11660 @code{asm} and multiplying that by the length of the longest
11661 instruction supported by that processor. (When working out the number
11662 of instructions, it assumes that any occurrence of a newline or of
11663 whatever statement separator character is supported by the assembler ---
11664 typically @samp{;} --- indicates the end of an instruction.)
11666 Normally, GCC's estimate is adequate to ensure that correct
11667 code is generated, but it is possible to confuse the compiler if you use
11668 pseudo instructions or assembler macros that expand into multiple real
11669 instructions, or if you use assembler directives that expand to more
11670 space in the object file than is needed for a single instruction.
11671 If this happens then the assembler may produce a diagnostic saying that
11672 a label is unreachable.
11674 @cindex @code{asm inline}
11675 This size is also used for inlining decisions. If you use @code{asm inline}
11676 instead of just @code{asm}, then for inlining purposes the size of the asm
11677 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
11679 @node Alternate Keywords
11680 @section Alternate Keywords
11681 @cindex alternate keywords
11682 @cindex keywords, alternate
11684 @option{-ansi} and the various @option{-std} options disable certain
11685 keywords. This causes trouble when you want to use GNU C extensions, or
11686 a general-purpose header file that should be usable by all programs,
11687 including ISO C programs. The keywords @code{asm}, @code{typeof} and
11688 @code{inline} are not available in programs compiled with
11689 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
11690 program compiled with @option{-std=c99} or a later standard). The
11692 @code{restrict} is only available when @option{-std=gnu99} (which will
11693 eventually be the default) or @option{-std=c99} (or the equivalent
11694 @option{-std=iso9899:1999}), or an option for a later standard
11697 The way to solve these problems is to put @samp{__} at the beginning and
11698 end of each problematical keyword. For example, use @code{__asm__}
11699 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
11701 Other C compilers won't accept these alternative keywords; if you want to
11702 compile with another compiler, you can define the alternate keywords as
11703 macros to replace them with the customary keywords. It looks like this:
11707 #define __asm__ asm
11711 @findex __extension__
11713 @option{-pedantic} and other options cause warnings for many GNU C extensions.
11715 prevent such warnings within one expression by writing
11716 @code{__extension__} before the expression. @code{__extension__} has no
11717 effect aside from this.
11719 @node Incomplete Enums
11720 @section Incomplete @code{enum} Types
11722 You can define an @code{enum} tag without specifying its possible values.
11723 This results in an incomplete type, much like what you get if you write
11724 @code{struct foo} without describing the elements. A later declaration
11725 that does specify the possible values completes the type.
11727 You cannot allocate variables or storage using the type while it is
11728 incomplete. However, you can work with pointers to that type.
11730 This extension may not be very useful, but it makes the handling of
11731 @code{enum} more consistent with the way @code{struct} and @code{union}
11734 This extension is not supported by GNU C++.
11736 @node Function Names
11737 @section Function Names as Strings
11738 @cindex @code{__func__} identifier
11739 @cindex @code{__FUNCTION__} identifier
11740 @cindex @code{__PRETTY_FUNCTION__} identifier
11742 GCC provides three magic constants that hold the name of the current
11743 function as a string. In C++11 and later modes, all three are treated
11744 as constant expressions and can be used in @code{constexpr} constexts.
11745 The first of these constants is @code{__func__}, which is part of
11748 The identifier @code{__func__} is implicitly declared by the translator
11749 as if, immediately following the opening brace of each function
11750 definition, the declaration
11753 static const char __func__[] = "function-name";
11757 appeared, where function-name is the name of the lexically-enclosing
11758 function. This name is the unadorned name of the function. As an
11759 extension, at file (or, in C++, namespace scope), @code{__func__}
11760 evaluates to the empty string.
11762 @code{__FUNCTION__} is another name for @code{__func__}, provided for
11763 backward compatibility with old versions of GCC.
11765 In C, @code{__PRETTY_FUNCTION__} is yet another name for
11766 @code{__func__}, except that at file scope (or, in C++, namespace scope),
11767 it evaluates to the string @code{"top level"}. In addition, in C++,
11768 @code{__PRETTY_FUNCTION__} contains the signature of the function as
11769 well as its bare name. For example, this program:
11772 extern "C" int printf (const char *, ...);
11778 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
11779 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
11797 __PRETTY_FUNCTION__ = void a::sub(int)
11800 These identifiers are variables, not preprocessor macros, and may not
11801 be used to initialize @code{char} arrays or be concatenated with string
11804 @node Return Address
11805 @section Getting the Return or Frame Address of a Function
11807 These functions may be used to get information about the callers of a
11810 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
11811 This function returns the return address of the current function, or of
11812 one of its callers. The @var{level} argument is number of frames to
11813 scan up the call stack. A value of @code{0} yields the return address
11814 of the current function, a value of @code{1} yields the return address
11815 of the caller of the current function, and so forth. When inlining
11816 the expected behavior is that the function returns the address of
11817 the function that is returned to. To work around this behavior use
11818 the @code{noinline} function attribute.
11820 The @var{level} argument must be a constant integer.
11822 On some machines it may be impossible to determine the return address of
11823 any function other than the current one; in such cases, or when the top
11824 of the stack has been reached, this function returns an unspecified
11825 value. In addition, @code{__builtin_frame_address} may be used
11826 to determine if the top of the stack has been reached.
11828 Additional post-processing of the returned value may be needed, see
11829 @code{__builtin_extract_return_addr}.
11831 The stored representation of the return address in memory may be different
11832 from the address returned by @code{__builtin_return_address}. For example,
11833 on AArch64 the stored address may be mangled with return address signing
11834 whereas the address returned by @code{__builtin_return_address} is not.
11836 Calling this function with a nonzero argument can have unpredictable
11837 effects, including crashing the calling program. As a result, calls
11838 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11839 option is in effect. Such calls should only be made in debugging
11842 On targets where code addresses are representable as @code{void *},
11844 void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
11846 gives the code address where the current function would return. For example,
11847 such an address may be used with @code{dladdr} or other interfaces that work
11848 with code addresses.
11851 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
11852 The address as returned by @code{__builtin_return_address} may have to be fed
11853 through this function to get the actual encoded address. For example, on the
11854 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
11855 platforms an offset has to be added for the true next instruction to be
11858 If no fixup is needed, this function simply passes through @var{addr}.
11861 @deftypefn {Built-in Function} {void *} __builtin_frob_return_addr (void *@var{addr})
11862 This function does the reverse of @code{__builtin_extract_return_addr}.
11865 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
11866 This function is similar to @code{__builtin_return_address}, but it
11867 returns the address of the function frame rather than the return address
11868 of the function. Calling @code{__builtin_frame_address} with a value of
11869 @code{0} yields the frame address of the current function, a value of
11870 @code{1} yields the frame address of the caller of the current function,
11873 The frame is the area on the stack that holds local variables and saved
11874 registers. The frame address is normally the address of the first word
11875 pushed on to the stack by the function. However, the exact definition
11876 depends upon the processor and the calling convention. If the processor
11877 has a dedicated frame pointer register, and the function has a frame,
11878 then @code{__builtin_frame_address} returns the value of the frame
11881 On some machines it may be impossible to determine the frame address of
11882 any function other than the current one; in such cases, or when the top
11883 of the stack has been reached, this function returns @code{0} if
11884 the first frame pointer is properly initialized by the startup code.
11886 Calling this function with a nonzero argument can have unpredictable
11887 effects, including crashing the calling program. As a result, calls
11888 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11889 option is in effect. Such calls should only be made in debugging
11893 @node Vector Extensions
11894 @section Using Vector Instructions through Built-in Functions
11896 On some targets, the instruction set contains SIMD vector instructions which
11897 operate on multiple values contained in one large register at the same time.
11898 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
11901 The first step in using these extensions is to provide the necessary data
11902 types. This should be done using an appropriate @code{typedef}:
11905 typedef int v4si __attribute__ ((vector_size (16)));
11909 The @code{int} type specifies the @dfn{base type}, while the attribute specifies
11910 the vector size for the variable, measured in bytes. For example, the
11911 declaration above causes the compiler to set the mode for the @code{v4si}
11912 type to be 16 bytes wide and divided into @code{int} sized units. For
11913 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
11914 corresponding mode of @code{foo} is @acronym{V4SI}.
11916 The @code{vector_size} attribute is only applicable to integral and
11917 floating scalars, although arrays, pointers, and function return values
11918 are allowed in conjunction with this construct. Only sizes that are
11919 positive power-of-two multiples of the base type size are currently allowed.
11921 All the basic integer types can be used as base types, both as signed
11922 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
11923 @code{long long}. In addition, @code{float} and @code{double} can be
11924 used to build floating-point vector types.
11926 Specifying a combination that is not valid for the current architecture
11927 causes GCC to synthesize the instructions using a narrower mode.
11928 For example, if you specify a variable of type @code{V4SI} and your
11929 architecture does not allow for this specific SIMD type, GCC
11930 produces code that uses 4 @code{SIs}.
11932 The types defined in this manner can be used with a subset of normal C
11933 operations. Currently, GCC allows using the following operators
11934 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
11936 The operations behave like C++ @code{valarrays}. Addition is defined as
11937 the addition of the corresponding elements of the operands. For
11938 example, in the code below, each of the 4 elements in @var{a} is
11939 added to the corresponding 4 elements in @var{b} and the resulting
11940 vector is stored in @var{c}.
11943 typedef int v4si __attribute__ ((vector_size (16)));
11950 Subtraction, multiplication, division, and the logical operations
11951 operate in a similar manner. Likewise, the result of using the unary
11952 minus or complement operators on a vector type is a vector whose
11953 elements are the negative or complemented values of the corresponding
11954 elements in the operand.
11956 It is possible to use shifting operators @code{<<}, @code{>>} on
11957 integer-type vectors. The operation is defined as following: @code{@{a0,
11958 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
11959 @dots{}, an >> bn@}}@. Vector operands must have the same number of
11962 For convenience, it is allowed to use a binary vector operation
11963 where one operand is a scalar. In that case the compiler transforms
11964 the scalar operand into a vector where each element is the scalar from
11965 the operation. The transformation happens only if the scalar could be
11966 safely converted to the vector-element type.
11967 Consider the following code.
11970 typedef int v4si __attribute__ ((vector_size (16)));
11975 a = b + 1; /* a = b + @{1,1,1,1@}; */
11976 a = 2 * b; /* a = @{2,2,2,2@} * b; */
11978 a = l + a; /* Error, cannot convert long to int. */
11981 Vectors can be subscripted as if the vector were an array with
11982 the same number of elements and base type. Out of bound accesses
11983 invoke undefined behavior at run time. Warnings for out of bound
11984 accesses for vector subscription can be enabled with
11985 @option{-Warray-bounds}.
11987 Vector comparison is supported with standard comparison
11988 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
11989 vector expressions of integer-type or real-type. Comparison between
11990 integer-type vectors and real-type vectors are not supported. The
11991 result of the comparison is a vector of the same width and number of
11992 elements as the comparison operands with a signed integral element
11995 Vectors are compared element-wise producing 0 when comparison is false
11996 and -1 (constant of the appropriate type where all bits are set)
11997 otherwise. Consider the following example.
12000 typedef int v4si __attribute__ ((vector_size (16)));
12002 v4si a = @{1,2,3,4@};
12003 v4si b = @{3,2,1,4@};
12006 c = a > b; /* The result would be @{0, 0,-1, 0@} */
12007 c = a == b; /* The result would be @{0,-1, 0,-1@} */
12010 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
12011 @code{b} and @code{c} are vectors of the same type and @code{a} is an
12012 integer vector with the same number of elements of the same size as @code{b}
12013 and @code{c}, computes all three arguments and creates a vector
12014 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
12015 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
12016 As in the case of binary operations, this syntax is also accepted when
12017 one of @code{b} or @code{c} is a scalar that is then transformed into a
12018 vector. If both @code{b} and @code{c} are scalars and the type of
12019 @code{true?b:c} has the same size as the element type of @code{a}, then
12020 @code{b} and @code{c} are converted to a vector type whose elements have
12021 this type and with the same number of elements as @code{a}.
12023 In C++, the logic operators @code{!, &&, ||} are available for vectors.
12024 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
12025 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
12026 For mixed operations between a scalar @code{s} and a vector @code{v},
12027 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
12028 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
12030 @findex __builtin_shuffle
12031 Vector shuffling is available using functions
12032 @code{__builtin_shuffle (vec, mask)} and
12033 @code{__builtin_shuffle (vec0, vec1, mask)}.
12034 Both functions construct a permutation of elements from one or two
12035 vectors and return a vector of the same type as the input vector(s).
12036 The @var{mask} is an integral vector with the same width (@var{W})
12037 and element count (@var{N}) as the output vector.
12039 The elements of the input vectors are numbered in memory ordering of
12040 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
12041 elements of @var{mask} are considered modulo @var{N} in the single-operand
12042 case and modulo @math{2*@var{N}} in the two-operand case.
12044 Consider the following example,
12047 typedef int v4si __attribute__ ((vector_size (16)));
12049 v4si a = @{1,2,3,4@};
12050 v4si b = @{5,6,7,8@};
12051 v4si mask1 = @{0,1,1,3@};
12052 v4si mask2 = @{0,4,2,5@};
12055 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
12056 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
12059 Note that @code{__builtin_shuffle} is intentionally semantically
12060 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
12062 You can declare variables and use them in function calls and returns, as
12063 well as in assignments and some casts. You can specify a vector type as
12064 a return type for a function. Vector types can also be used as function
12065 arguments. It is possible to cast from one vector type to another,
12066 provided they are of the same size (in fact, you can also cast vectors
12067 to and from other datatypes of the same size).
12069 You cannot operate between vectors of different lengths or different
12070 signedness without a cast.
12072 @findex __builtin_shufflevector
12073 Vector shuffling is available using the
12074 @code{__builtin_shufflevector (vec1, vec2, index...)}
12075 function. @var{vec1} and @var{vec2} must be expressions with
12076 vector type with a compatible element type. The result of
12077 @code{__builtin_shufflevector} is a vector with the same element type
12078 as @var{vec1} and @var{vec2} but that has an element count equal to
12079 the number of indices specified.
12081 The @var{index} arguments are a list of integers that specify the
12082 elements indices of the first two vectors that should be extracted and
12083 returned in a new vector. These element indices are numbered sequentially
12084 starting with the first vector, continuing into the second vector.
12085 An index of -1 can be used to indicate that the corresponding element in
12086 the returned vector is a don't care and can be freely chosen to optimized
12087 the generated code sequence performing the shuffle operation.
12089 Consider the following example,
12091 typedef int v4si __attribute__ ((vector_size (16)));
12092 typedef int v8si __attribute__ ((vector_size (32)));
12094 v8si a = @{1,-2,3,-4,5,-6,7,-8@};
12095 v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */
12096 v4si c = @{-2,-4,-6,-8@};
12097 v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */
12100 @findex __builtin_convertvector
12101 Vector conversion is available using the
12102 @code{__builtin_convertvector (vec, vectype)}
12103 function. @var{vec} must be an expression with integral or floating
12104 vector type and @var{vectype} an integral or floating vector type with the
12105 same number of elements. The result has @var{vectype} type and value of
12106 a C cast of every element of @var{vec} to the element type of @var{vectype}.
12108 Consider the following example,
12110 typedef int v4si __attribute__ ((vector_size (16)));
12111 typedef float v4sf __attribute__ ((vector_size (16)));
12112 typedef double v4df __attribute__ ((vector_size (32)));
12113 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
12115 v4si a = @{1,-2,3,-4@};
12116 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
12117 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
12118 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
12120 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
12121 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
12122 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
12123 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
12124 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
12127 @cindex vector types, using with x86 intrinsics
12128 Sometimes it is desirable to write code using a mix of generic vector
12129 operations (for clarity) and machine-specific vector intrinsics (to
12130 access vector instructions that are not exposed via generic built-ins).
12131 On x86, intrinsic functions for integer vectors typically use the same
12132 vector type @code{__m128i} irrespective of how they interpret the vector,
12133 making it necessary to cast their arguments and return values from/to
12134 other vector types. In C, you can make use of a @code{union} type:
12135 @c In C++ such type punning via a union is not allowed by the language
12137 #include <immintrin.h>
12139 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
12140 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
12150 for variables that can be used with both built-in operators and x86
12154 v128 x, y = @{ 0 @};
12155 memcpy (&x, ptr, sizeof x);
12157 x.mm = _mm_adds_epu8 (x.mm, y.mm);
12160 /* Instead of a variable, a compound literal may be used to pass the
12161 return value of an intrinsic call to a function expecting the union: */
12163 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
12164 @c This could be done implicitly with __attribute__((transparent_union)),
12165 @c but GCC does not accept it for unions of vector types (PR 88955).
12169 @section Support for @code{offsetof}
12170 @findex __builtin_offsetof
12172 GCC implements for both C and C++ a syntactic extension to implement
12173 the @code{offsetof} macro.
12177 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
12179 offsetof_member_designator:
12181 | offsetof_member_designator "." @code{identifier}
12182 | offsetof_member_designator "[" @code{expr} "]"
12185 This extension is sufficient such that
12188 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
12192 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
12193 may be dependent. In either case, @var{member} may consist of a single
12194 identifier, or a sequence of member accesses and array references.
12196 @node __sync Builtins
12197 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
12199 The following built-in functions
12200 are intended to be compatible with those described
12201 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
12202 section 7.4. As such, they depart from normal GCC practice by not using
12203 the @samp{__builtin_} prefix and also by being overloaded so that they
12204 work on multiple types.
12206 The definition given in the Intel documentation allows only for the use of
12207 the types @code{int}, @code{long}, @code{long long} or their unsigned
12208 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
12209 size other than the C type @code{_Bool} or the C++ type @code{bool}.
12210 Operations on pointer arguments are performed as if the operands were
12211 of the @code{uintptr_t} type. That is, they are not scaled by the size
12212 of the type to which the pointer points.
12214 These functions are implemented in terms of the @samp{__atomic}
12215 builtins (@pxref{__atomic Builtins}). They should not be used for new
12216 code which should use the @samp{__atomic} builtins instead.
12218 Not all operations are supported by all target processors. If a particular
12219 operation cannot be implemented on the target processor, a warning is
12220 generated and a call to an external function is generated. The external
12221 function carries the same name as the built-in version,
12222 with an additional suffix
12223 @samp{_@var{n}} where @var{n} is the size of the data type.
12225 @c ??? Should we have a mechanism to suppress this warning? This is almost
12226 @c useful for implementing the operation under the control of an external
12229 In most cases, these built-in functions are considered a @dfn{full barrier}.
12231 no memory operand is moved across the operation, either forward or
12232 backward. Further, instructions are issued as necessary to prevent the
12233 processor from speculating loads across the operation and from queuing stores
12234 after the operation.
12236 All of the routines are described in the Intel documentation to take
12237 ``an optional list of variables protected by the memory barrier''. It's
12238 not clear what is meant by that; it could mean that @emph{only} the
12239 listed variables are protected, or it could mean a list of additional
12240 variables to be protected. The list is ignored by GCC which treats it as
12241 empty. GCC interprets an empty list as meaning that all globally
12242 accessible variables should be protected.
12245 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
12246 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
12247 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
12248 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
12249 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
12250 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
12251 @findex __sync_fetch_and_add
12252 @findex __sync_fetch_and_sub
12253 @findex __sync_fetch_and_or
12254 @findex __sync_fetch_and_and
12255 @findex __sync_fetch_and_xor
12256 @findex __sync_fetch_and_nand
12257 These built-in functions perform the operation suggested by the name, and
12258 returns the value that had previously been in memory. That is, operations
12259 on integer operands have the following semantics. Operations on pointer
12260 arguments are performed as if the operands were of the @code{uintptr_t}
12261 type. That is, they are not scaled by the size of the type to which
12262 the pointer points.
12265 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
12266 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
12269 The object pointed to by the first argument must be of integer or pointer
12270 type. It must not be a boolean type.
12272 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
12273 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
12275 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
12276 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
12277 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
12278 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
12279 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
12280 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
12281 @findex __sync_add_and_fetch
12282 @findex __sync_sub_and_fetch
12283 @findex __sync_or_and_fetch
12284 @findex __sync_and_and_fetch
12285 @findex __sync_xor_and_fetch
12286 @findex __sync_nand_and_fetch
12287 These built-in functions perform the operation suggested by the name, and
12288 return the new value. That is, operations on integer operands have
12289 the following semantics. Operations on pointer operands are performed as
12290 if the operand's type were @code{uintptr_t}.
12293 @{ *ptr @var{op}= value; return *ptr; @}
12294 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
12297 The same constraints on arguments apply as for the corresponding
12298 @code{__sync_op_and_fetch} built-in functions.
12300 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
12301 as @code{*ptr = ~(*ptr & value)} instead of
12302 @code{*ptr = ~*ptr & value}.
12304 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
12305 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
12306 @findex __sync_bool_compare_and_swap
12307 @findex __sync_val_compare_and_swap
12308 These built-in functions perform an atomic compare and swap.
12309 That is, if the current
12310 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
12313 The ``bool'' version returns @code{true} if the comparison is successful and
12314 @var{newval} is written. The ``val'' version returns the contents
12315 of @code{*@var{ptr}} before the operation.
12317 @item __sync_synchronize (...)
12318 @findex __sync_synchronize
12319 This built-in function issues a full memory barrier.
12321 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
12322 @findex __sync_lock_test_and_set
12323 This built-in function, as described by Intel, is not a traditional test-and-set
12324 operation, but rather an atomic exchange operation. It writes @var{value}
12325 into @code{*@var{ptr}}, and returns the previous contents of
12328 Many targets have only minimal support for such locks, and do not support
12329 a full exchange operation. In this case, a target may support reduced
12330 functionality here by which the @emph{only} valid value to store is the
12331 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
12332 is implementation defined.
12334 This built-in function is not a full barrier,
12335 but rather an @dfn{acquire barrier}.
12336 This means that references after the operation cannot move to (or be
12337 speculated to) before the operation, but previous memory stores may not
12338 be globally visible yet, and previous memory loads may not yet be
12341 @item void __sync_lock_release (@var{type} *ptr, ...)
12342 @findex __sync_lock_release
12343 This built-in function releases the lock acquired by
12344 @code{__sync_lock_test_and_set}.
12345 Normally this means writing the constant 0 to @code{*@var{ptr}}.
12347 This built-in function is not a full barrier,
12348 but rather a @dfn{release barrier}.
12349 This means that all previous memory stores are globally visible, and all
12350 previous memory loads have been satisfied, but following memory reads
12351 are not prevented from being speculated to before the barrier.
12354 @node __atomic Builtins
12355 @section Built-in Functions for Memory Model Aware Atomic Operations
12357 The following built-in functions approximately match the requirements
12358 for the C++11 memory model. They are all
12359 identified by being prefixed with @samp{__atomic} and most are
12360 overloaded so that they work with multiple types.
12362 These functions are intended to replace the legacy @samp{__sync}
12363 builtins. The main difference is that the memory order that is requested
12364 is a parameter to the functions. New code should always use the
12365 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
12367 Note that the @samp{__atomic} builtins assume that programs will
12368 conform to the C++11 memory model. In particular, they assume
12369 that programs are free of data races. See the C++11 standard for
12370 detailed requirements.
12372 The @samp{__atomic} builtins can be used with any integral scalar or
12373 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
12374 types are also allowed if @samp{__int128} (@pxref{__int128}) is
12375 supported by the architecture.
12377 The four non-arithmetic functions (load, store, exchange, and
12378 compare_exchange) all have a generic version as well. This generic
12379 version works on any data type. It uses the lock-free built-in function
12380 if the specific data type size makes that possible; otherwise, an
12381 external call is left to be resolved at run time. This external call is
12382 the same format with the addition of a @samp{size_t} parameter inserted
12383 as the first parameter indicating the size of the object being pointed to.
12384 All objects must be the same size.
12386 There are 6 different memory orders that can be specified. These map
12387 to the C++11 memory orders with the same names, see the C++11 standard
12388 or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
12389 on atomic synchronization} for detailed definitions. Individual
12390 targets may also support additional memory orders for use on specific
12391 architectures. Refer to the target documentation for details of
12394 An atomic operation can both constrain code motion and
12395 be mapped to hardware instructions for synchronization between threads
12396 (e.g., a fence). To which extent this happens is controlled by the
12397 memory orders, which are listed here in approximately ascending order of
12398 strength. The description of each memory order is only meant to roughly
12399 illustrate the effects and is not a specification; see the C++11
12400 memory model for precise semantics.
12403 @item __ATOMIC_RELAXED
12404 Implies no inter-thread ordering constraints.
12405 @item __ATOMIC_CONSUME
12406 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
12407 memory order because of a deficiency in C++11's semantics for
12408 @code{memory_order_consume}.
12409 @item __ATOMIC_ACQUIRE
12410 Creates an inter-thread happens-before constraint from the release (or
12411 stronger) semantic store to this acquire load. Can prevent hoisting
12412 of code to before the operation.
12413 @item __ATOMIC_RELEASE
12414 Creates an inter-thread happens-before constraint to acquire (or stronger)
12415 semantic loads that read from this release store. Can prevent sinking
12416 of code to after the operation.
12417 @item __ATOMIC_ACQ_REL
12418 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
12419 @code{__ATOMIC_RELEASE}.
12420 @item __ATOMIC_SEQ_CST
12421 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
12424 Note that in the C++11 memory model, @emph{fences} (e.g.,
12425 @samp{__atomic_thread_fence}) take effect in combination with other
12426 atomic operations on specific memory locations (e.g., atomic loads);
12427 operations on specific memory locations do not necessarily affect other
12428 operations in the same way.
12430 Target architectures are encouraged to provide their own patterns for
12431 each of the atomic built-in functions. If no target is provided, the original
12432 non-memory model set of @samp{__sync} atomic built-in functions are
12433 used, along with any required synchronization fences surrounding it in
12434 order to achieve the proper behavior. Execution in this case is subject
12435 to the same restrictions as those built-in functions.
12437 If there is no pattern or mechanism to provide a lock-free instruction
12438 sequence, a call is made to an external routine with the same parameters
12439 to be resolved at run time.
12441 When implementing patterns for these built-in functions, the memory order
12442 parameter can be ignored as long as the pattern implements the most
12443 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
12444 orders execute correctly with this memory order but they may not execute as
12445 efficiently as they could with a more appropriate implementation of the
12446 relaxed requirements.
12448 Note that the C++11 standard allows for the memory order parameter to be
12449 determined at run time rather than at compile time. These built-in
12450 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
12451 than invoke a runtime library call or inline a switch statement. This is
12452 standard compliant, safe, and the simplest approach for now.
12454 The memory order parameter is a signed int, but only the lower 16 bits are
12455 reserved for the memory order. The remainder of the signed int is reserved
12456 for target use and should be 0. Use of the predefined atomic values
12457 ensures proper usage.
12459 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
12460 This built-in function implements an atomic load operation. It returns the
12461 contents of @code{*@var{ptr}}.
12463 The valid memory order variants are
12464 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
12465 and @code{__ATOMIC_CONSUME}.
12469 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
12470 This is the generic version of an atomic load. It returns the
12471 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
12475 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
12476 This built-in function implements an atomic store operation. It writes
12477 @code{@var{val}} into @code{*@var{ptr}}.
12479 The valid memory order variants are
12480 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
12484 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
12485 This is the generic version of an atomic store. It stores the value
12486 of @code{*@var{val}} into @code{*@var{ptr}}.
12490 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
12491 This built-in function implements an atomic exchange operation. It writes
12492 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
12495 All memory order variants are valid.
12499 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
12500 This is the generic version of an atomic exchange. It stores the
12501 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
12502 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
12506 @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)
12507 This built-in function implements an atomic compare and exchange operation.
12508 This compares the contents of @code{*@var{ptr}} with the contents of
12509 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
12510 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
12511 equal, the operation is a @emph{read} and the current contents of
12512 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
12513 for weak compare_exchange, which may fail spuriously, and @code{false} for
12514 the strong variation, which never fails spuriously. Many targets
12515 only offer the strong variation and ignore the parameter. When in doubt, use
12516 the strong variation.
12518 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
12519 and memory is affected according to the
12520 memory order specified by @var{success_memorder}. There are no
12521 restrictions on what memory order can be used here.
12523 Otherwise, @code{false} is returned and memory is affected according
12524 to @var{failure_memorder}. This memory order cannot be
12525 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
12526 stronger order than that specified by @var{success_memorder}.
12530 @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)
12531 This built-in function implements the generic version of
12532 @code{__atomic_compare_exchange}. The function is virtually identical to
12533 @code{__atomic_compare_exchange_n}, except the desired value is also a
12538 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
12539 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
12540 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
12541 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
12542 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
12543 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
12544 These built-in functions perform the operation suggested by the name, and
12545 return the result of the operation. Operations on pointer arguments are
12546 performed as if the operands were of the @code{uintptr_t} type. That is,
12547 they are not scaled by the size of the type to which the pointer points.
12550 @{ *ptr @var{op}= val; return *ptr; @}
12551 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
12554 The object pointed to by the first argument must be of integer or pointer
12555 type. It must not be a boolean type. All memory orders are valid.
12559 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
12560 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
12561 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
12562 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
12563 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
12564 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
12565 These built-in functions perform the operation suggested by the name, and
12566 return the value that had previously been in @code{*@var{ptr}}. Operations
12567 on pointer arguments are performed as if the operands were of
12568 the @code{uintptr_t} type. That is, they are not scaled by the size of
12569 the type to which the pointer points.
12572 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
12573 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
12576 The same constraints on arguments apply as for the corresponding
12577 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
12581 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
12583 This built-in function performs an atomic test-and-set operation on
12584 the byte at @code{*@var{ptr}}. The byte is set to some implementation
12585 defined nonzero ``set'' value and the return value is @code{true} if and only
12586 if the previous contents were ``set''.
12587 It should be only used for operands of type @code{bool} or @code{char}. For
12588 other types only part of the value may be set.
12590 All memory orders are valid.
12594 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
12596 This built-in function performs an atomic clear operation on
12597 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
12598 It should be only used for operands of type @code{bool} or @code{char} and
12599 in conjunction with @code{__atomic_test_and_set}.
12600 For other types it may only clear partially. If the type is not @code{bool}
12601 prefer using @code{__atomic_store}.
12603 The valid memory order variants are
12604 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
12605 @code{__ATOMIC_RELEASE}.
12609 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
12611 This built-in function acts as a synchronization fence between threads
12612 based on the specified memory order.
12614 All memory orders are valid.
12618 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
12620 This built-in function acts as a synchronization fence between a thread
12621 and signal handlers based in the same thread.
12623 All memory orders are valid.
12627 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
12629 This built-in function returns @code{true} if objects of @var{size} bytes always
12630 generate lock-free atomic instructions for the target architecture.
12631 @var{size} must resolve to a compile-time constant and the result also
12632 resolves to a compile-time constant.
12634 @var{ptr} is an optional pointer to the object that may be used to determine
12635 alignment. A value of 0 indicates typical alignment should be used. The
12636 compiler may also ignore this parameter.
12639 if (__atomic_always_lock_free (sizeof (long long), 0))
12644 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
12646 This built-in function returns @code{true} if objects of @var{size} bytes always
12647 generate lock-free atomic instructions for the target architecture. If
12648 the built-in function is not known to be lock-free, a call is made to a
12649 runtime routine named @code{__atomic_is_lock_free}.
12651 @var{ptr} is an optional pointer to the object that may be used to determine
12652 alignment. A value of 0 indicates typical alignment should be used. The
12653 compiler may also ignore this parameter.
12656 @node Integer Overflow Builtins
12657 @section Built-in Functions to Perform Arithmetic with Overflow Checking
12659 The following built-in functions allow performing simple arithmetic operations
12660 together with checking whether the operations overflowed.
12662 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12663 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
12664 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
12665 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
12666 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
12667 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12668 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12670 These built-in functions promote the first two operands into infinite precision signed
12671 type and perform addition on those promoted operands. The result is then
12672 cast to the type the third pointer argument points to and stored there.
12673 If the stored result is equal to the infinite precision result, the built-in
12674 functions return @code{false}, otherwise they return @code{true}. As the addition is
12675 performed in infinite signed precision, these built-in functions have fully defined
12676 behavior for all argument values.
12678 The first built-in function allows arbitrary integral types for operands and
12679 the result type must be pointer to some integral type other than enumerated or
12680 boolean type, the rest of the built-in functions have explicit integer types.
12682 The compiler will attempt to use hardware instructions to implement
12683 these built-in functions where possible, like conditional jump on overflow
12684 after addition, conditional jump on carry etc.
12688 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12689 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
12690 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
12691 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
12692 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
12693 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12694 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12696 These built-in functions are similar to the add overflow checking built-in
12697 functions above, except they perform subtraction, subtract the second argument
12698 from the first one, instead of addition.
12702 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12703 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
12704 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
12705 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
12706 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
12707 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12708 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12710 These built-in functions are similar to the add overflow checking built-in
12711 functions above, except they perform multiplication, instead of addition.
12715 The following built-in functions allow checking if simple arithmetic operation
12718 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12719 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12720 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12722 These built-in functions are similar to @code{__builtin_add_overflow},
12723 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
12724 they don't store the result of the arithmetic operation anywhere and the
12725 last argument is not a pointer, but some expression with integral type other
12726 than enumerated or boolean type.
12728 The built-in functions promote the first two operands into infinite precision signed type
12729 and perform addition on those promoted operands. The result is then
12730 cast to the type of the third argument. If the cast result is equal to the infinite
12731 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
12732 The value of the third argument is ignored, just the side effects in the third argument
12733 are evaluated, and no integral argument promotions are performed on the last argument.
12734 If the third argument is a bit-field, the type used for the result cast has the
12735 precision and signedness of the given bit-field, rather than precision and signedness
12736 of the underlying type.
12738 For example, the following macro can be used to portably check, at
12739 compile-time, whether or not adding two constant integers will overflow,
12740 and perform the addition only when it is known to be safe and not to trigger
12741 a @option{-Woverflow} warning.
12744 #define INT_ADD_OVERFLOW_P(a, b) \
12745 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
12748 A = INT_MAX, B = 3,
12749 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
12750 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
12754 The compiler will attempt to use hardware instructions to implement
12755 these built-in functions where possible, like conditional jump on overflow
12756 after addition, conditional jump on carry etc.
12760 @node x86 specific memory model extensions for transactional memory
12761 @section x86-Specific Memory Model Extensions for Transactional Memory
12763 The x86 architecture supports additional memory ordering flags
12764 to mark critical sections for hardware lock elision.
12765 These must be specified in addition to an existing memory order to
12769 @item __ATOMIC_HLE_ACQUIRE
12770 Start lock elision on a lock variable.
12771 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
12772 @item __ATOMIC_HLE_RELEASE
12773 End lock elision on a lock variable.
12774 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
12777 When a lock acquire fails, it is required for good performance to abort
12778 the transaction quickly. This can be done with a @code{_mm_pause}.
12781 #include <immintrin.h> // For _mm_pause
12785 /* Acquire lock with lock elision */
12786 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
12787 _mm_pause(); /* Abort failed transaction */
12789 /* Free lock with lock elision */
12790 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
12793 @node Object Size Checking
12794 @section Object Size Checking Built-in Functions
12795 @findex __builtin_object_size
12796 @findex __builtin_dynamic_object_size
12797 @findex __builtin___memcpy_chk
12798 @findex __builtin___mempcpy_chk
12799 @findex __builtin___memmove_chk
12800 @findex __builtin___memset_chk
12801 @findex __builtin___strcpy_chk
12802 @findex __builtin___stpcpy_chk
12803 @findex __builtin___strncpy_chk
12804 @findex __builtin___strcat_chk
12805 @findex __builtin___strncat_chk
12806 @findex __builtin___sprintf_chk
12807 @findex __builtin___snprintf_chk
12808 @findex __builtin___vsprintf_chk
12809 @findex __builtin___vsnprintf_chk
12810 @findex __builtin___printf_chk
12811 @findex __builtin___vprintf_chk
12812 @findex __builtin___fprintf_chk
12813 @findex __builtin___vfprintf_chk
12815 GCC implements a limited buffer overflow protection mechanism that can
12816 prevent some buffer overflow attacks by determining the sizes of objects
12817 into which data is about to be written and preventing the writes when
12818 the size isn't sufficient. The built-in functions described below yield
12819 the best results when used together and when optimization is enabled.
12820 For example, to detect object sizes across function boundaries or to
12821 follow pointer assignments through non-trivial control flow they rely
12822 on various optimization passes enabled with @option{-O2}. However, to
12823 a limited extent, they can be used without optimization as well.
12825 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
12826 is a built-in construct that returns a constant number of bytes from
12827 @var{ptr} to the end of the object @var{ptr} pointer points to
12828 (if known at compile time). To determine the sizes of dynamically allocated
12829 objects the function relies on the allocation functions called to obtain
12830 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
12831 Function Attributes}). @code{__builtin_object_size} never evaluates
12832 its arguments for side effects. If there are any side effects in them, it
12833 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12834 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
12835 point to and all of them are known at compile time, the returned number
12836 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
12837 0 and minimum if nonzero. If it is not possible to determine which objects
12838 @var{ptr} points to at compile time, @code{__builtin_object_size} should
12839 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12840 for @var{type} 2 or 3.
12842 @var{type} is an integer constant from 0 to 3. If the least significant
12843 bit is clear, objects are whole variables, if it is set, a closest
12844 surrounding subobject is considered the object a pointer points to.
12845 The second bit determines if maximum or minimum of remaining bytes
12849 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
12850 char *p = &var.buf1[1], *q = &var.b;
12852 /* Here the object p points to is var. */
12853 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
12854 /* The subobject p points to is var.buf1. */
12855 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
12856 /* The object q points to is var. */
12857 assert (__builtin_object_size (q, 0)
12858 == (char *) (&var + 1) - (char *) &var.b);
12859 /* The subobject q points to is var.b. */
12860 assert (__builtin_object_size (q, 1) == sizeof (var.b));
12864 @deftypefn {Built-in Function} {size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})
12865 is similar to @code{__builtin_object_size} in that it returns a number of bytes
12866 from @var{ptr} to the end of the object @var{ptr} pointer points to, except
12867 that the size returned may not be a constant. This results in successful
12868 evaluation of object size estimates in a wider range of use cases and can be
12869 more precise than @code{__builtin_object_size}, but it incurs a performance
12870 penalty since it may add a runtime overhead on size computation. Semantics of
12871 @var{type} as well as return values in case it is not possible to determine
12872 which objects @var{ptr} points to at compile time are the same as in the case
12873 of @code{__builtin_object_size}.
12876 There are built-in functions added for many common string operation
12877 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
12878 built-in is provided. This built-in has an additional last argument,
12879 which is the number of bytes remaining in the object the @var{dest}
12880 argument points to or @code{(size_t) -1} if the size is not known.
12882 The built-in functions are optimized into the normal string functions
12883 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
12884 it is known at compile time that the destination object will not
12885 be overflowed. If the compiler can determine at compile time that the
12886 object will always be overflowed, it issues a warning.
12888 The intended use can be e.g.@:
12892 #define bos0(dest) __builtin_object_size (dest, 0)
12893 #define memcpy(dest, src, n) \
12894 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
12898 /* It is unknown what object p points to, so this is optimized
12899 into plain memcpy - no checking is possible. */
12900 memcpy (p, "abcde", n);
12901 /* Destination is known and length too. It is known at compile
12902 time there will be no overflow. */
12903 memcpy (&buf[5], "abcde", 5);
12904 /* Destination is known, but the length is not known at compile time.
12905 This will result in __memcpy_chk call that can check for overflow
12907 memcpy (&buf[5], "abcde", n);
12908 /* Destination is known and it is known at compile time there will
12909 be overflow. There will be a warning and __memcpy_chk call that
12910 will abort the program at run time. */
12911 memcpy (&buf[6], "abcde", 5);
12914 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
12915 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
12916 @code{strcat} and @code{strncat}.
12918 There are also checking built-in functions for formatted output functions.
12920 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
12921 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12922 const char *fmt, ...);
12923 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
12925 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12926 const char *fmt, va_list ap);
12929 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
12930 etc.@: functions and can contain implementation specific flags on what
12931 additional security measures the checking function might take, such as
12932 handling @code{%n} differently.
12934 The @var{os} argument is the object size @var{s} points to, like in the
12935 other built-in functions. There is a small difference in the behavior
12936 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
12937 optimized into the non-checking functions only if @var{flag} is 0, otherwise
12938 the checking function is called with @var{os} argument set to
12939 @code{(size_t) -1}.
12941 In addition to this, there are checking built-in functions
12942 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
12943 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
12944 These have just one additional argument, @var{flag}, right before
12945 format string @var{fmt}. If the compiler is able to optimize them to
12946 @code{fputc} etc.@: functions, it does, otherwise the checking function
12947 is called and the @var{flag} argument passed to it.
12949 @node Other Builtins
12950 @section Other Built-in Functions Provided by GCC
12951 @cindex built-in functions
12952 @findex __builtin_alloca
12953 @findex __builtin_alloca_with_align
12954 @findex __builtin_alloca_with_align_and_max
12955 @findex __builtin_call_with_static_chain
12956 @findex __builtin_extend_pointer
12957 @findex __builtin_fpclassify
12958 @findex __builtin_has_attribute
12959 @findex __builtin_isfinite
12960 @findex __builtin_isnormal
12961 @findex __builtin_isgreater
12962 @findex __builtin_isgreaterequal
12963 @findex __builtin_isinf_sign
12964 @findex __builtin_isless
12965 @findex __builtin_islessequal
12966 @findex __builtin_islessgreater
12967 @findex __builtin_isunordered
12968 @findex __builtin_object_size
12969 @findex __builtin_powi
12970 @findex __builtin_powif
12971 @findex __builtin_powil
12972 @findex __builtin_speculation_safe_value
13133 @findex fprintf_unlocked
13135 @findex fputs_unlocked
13244 @findex nexttowardf
13245 @findex nexttowardl
13253 @findex printf_unlocked
13284 @findex signbitd128
13285 @findex significand
13286 @findex significandf
13287 @findex significandl
13315 @findex strncasecmp
13359 GCC provides a large number of built-in functions other than the ones
13360 mentioned above. Some of these are for internal use in the processing
13361 of exceptions or variable-length argument lists and are not
13362 documented here because they may change from time to time; we do not
13363 recommend general use of these functions.
13365 The remaining functions are provided for optimization purposes.
13367 With the exception of built-ins that have library equivalents such as
13368 the standard C library functions discussed below, or that expand to
13369 library calls, GCC built-in functions are always expanded inline and
13370 thus do not have corresponding entry points and their address cannot
13371 be obtained. Attempting to use them in an expression other than
13372 a function call results in a compile-time error.
13374 @opindex fno-builtin
13375 GCC includes built-in versions of many of the functions in the standard
13376 C library. These functions come in two forms: one whose names start with
13377 the @code{__builtin_} prefix, and the other without. Both forms have the
13378 same type (including prototype), the same address (when their address is
13379 taken), and the same meaning as the C library functions even if you specify
13380 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
13381 functions are only optimized in certain cases; if they are not optimized in
13382 a particular case, a call to the library function is emitted.
13386 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
13387 @option{-std=c99} or @option{-std=c11}), the functions
13388 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
13389 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
13390 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
13391 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
13392 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
13393 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
13394 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
13395 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
13396 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
13397 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
13398 @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl},
13399 @code{scalbf}, @code{scalbl}, @code{scalb},
13400 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
13401 @code{signbitd64}, @code{signbitd128}, @code{significandf},
13402 @code{significandl}, @code{significand}, @code{sincosf},
13403 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
13404 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
13405 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
13406 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
13408 may be handled as built-in functions.
13409 All these functions have corresponding versions
13410 prefixed with @code{__builtin_}, which may be used even in strict C90
13413 The ISO C99 functions
13414 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
13415 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
13416 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
13417 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
13418 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
13419 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
13420 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
13421 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
13422 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
13423 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
13424 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
13425 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
13426 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
13427 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
13428 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
13429 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
13430 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
13431 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
13432 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
13433 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
13434 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
13435 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
13436 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
13437 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
13438 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
13439 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
13440 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
13441 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
13442 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
13443 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
13444 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
13445 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
13446 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
13447 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
13448 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
13449 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
13450 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
13451 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
13452 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
13453 are handled as built-in functions
13454 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
13456 There are also built-in versions of the ISO C99 functions
13457 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
13458 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
13459 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
13460 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
13461 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
13462 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
13463 @code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf},
13464 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
13465 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
13466 that are recognized in any mode since ISO C90 reserves these names for
13467 the purpose to which ISO C99 puts them. All these functions have
13468 corresponding versions prefixed with @code{__builtin_}.
13470 There are also built-in functions @code{__builtin_fabsf@var{n}},
13471 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
13472 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
13473 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
13474 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
13475 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
13477 There are also GNU extension functions @code{clog10}, @code{clog10f} and
13478 @code{clog10l} which names are reserved by ISO C99 for future use.
13479 All these functions have versions prefixed with @code{__builtin_}.
13481 The ISO C94 functions
13482 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
13483 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
13484 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
13486 are handled as built-in functions
13487 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
13489 The ISO C90 functions
13490 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
13491 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
13492 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
13493 @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf},
13494 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
13495 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
13496 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
13497 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
13498 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
13499 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
13500 @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin},
13501 @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
13502 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
13503 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
13504 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
13505 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
13506 are all recognized as built-in functions unless
13507 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
13508 is specified for an individual function). All of these functions have
13509 corresponding versions prefixed with @code{__builtin_}.
13511 GCC provides built-in versions of the ISO C99 floating-point comparison
13512 macros that avoid raising exceptions for unordered operands. They have
13513 the same names as the standard macros ( @code{isgreater},
13514 @code{isgreaterequal}, @code{isless}, @code{islessequal},
13515 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
13516 prefixed. We intend for a library implementor to be able to simply
13517 @code{#define} each standard macro to its built-in equivalent.
13518 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
13519 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
13520 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
13521 built-in functions appear both with and without the @code{__builtin_} prefix.
13523 GCC provides built-in versions of the ISO C99 floating-point rounding and
13524 exceptions handling functions @code{fegetround}, @code{feclearexcept} and
13525 @code{feraiseexcept}. They may not be available for all targets, and because
13526 they need close interaction with libc internal values, they may not be available
13527 for all target libcs, but in all cases they will gracefully fallback to libc
13528 calls. These built-in functions appear both with and without the
13529 @code{__builtin_} prefix.
13531 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
13532 The @code{__builtin_alloca} function must be called at block scope.
13533 The function allocates an object @var{size} bytes large on the stack
13534 of the calling function. The object is aligned on the default stack
13535 alignment boundary for the target determined by the
13536 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
13537 function returns a pointer to the first byte of the allocated object.
13538 The lifetime of the allocated object ends just before the calling
13539 function returns to its caller. This is so even when
13540 @code{__builtin_alloca} is called within a nested block.
13542 For example, the following function allocates eight objects of @code{n}
13543 bytes each on the stack, storing a pointer to each in consecutive elements
13544 of the array @code{a}. It then passes the array to function @code{g}
13545 which can safely use the storage pointed to by each of the array elements.
13548 void f (unsigned n)
13551 for (int i = 0; i != 8; ++i)
13552 a [i] = __builtin_alloca (n);
13554 g (a, n); // @r{safe}
13558 Since the @code{__builtin_alloca} function doesn't validate its argument
13559 it is the responsibility of its caller to make sure the argument doesn't
13560 cause it to exceed the stack size limit.
13561 The @code{__builtin_alloca} function is provided to make it possible to
13562 allocate on the stack arrays of bytes with an upper bound that may be
13563 computed at run time. Since C99 Variable Length Arrays offer
13564 similar functionality under a portable, more convenient, and safer
13565 interface they are recommended instead, in both C99 and C++ programs
13566 where GCC provides them as an extension.
13567 @xref{Variable Length}, for details.
13571 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
13572 The @code{__builtin_alloca_with_align} function must be called at block
13573 scope. The function allocates an object @var{size} bytes large on
13574 the stack of the calling function. The allocated object is aligned on
13575 the boundary specified by the argument @var{alignment} whose unit is given
13576 in bits (not bytes). The @var{size} argument must be positive and not
13577 exceed the stack size limit. The @var{alignment} argument must be a constant
13578 integer expression that evaluates to a power of 2 greater than or equal to
13579 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
13580 with other values are rejected with an error indicating the valid bounds.
13581 The function returns a pointer to the first byte of the allocated object.
13582 The lifetime of the allocated object ends at the end of the block in which
13583 the function was called. The allocated storage is released no later than
13584 just before the calling function returns to its caller, but may be released
13585 at the end of the block in which the function was called.
13587 For example, in the following function the call to @code{g} is unsafe
13588 because when @code{overalign} is non-zero, the space allocated by
13589 @code{__builtin_alloca_with_align} may have been released at the end
13590 of the @code{if} statement in which it was called.
13593 void f (unsigned n, bool overalign)
13597 p = __builtin_alloca_with_align (n, 64 /* bits */);
13599 p = __builtin_alloc (n);
13601 g (p, n); // @r{unsafe}
13605 Since the @code{__builtin_alloca_with_align} function doesn't validate its
13606 @var{size} argument it is the responsibility of its caller to make sure
13607 the argument doesn't cause it to exceed the stack size limit.
13608 The @code{__builtin_alloca_with_align} function is provided to make
13609 it possible to allocate on the stack overaligned arrays of bytes with
13610 an upper bound that may be computed at run time. Since C99
13611 Variable Length Arrays offer the same functionality under
13612 a portable, more convenient, and safer interface they are recommended
13613 instead, in both C99 and C++ programs where GCC provides them as
13614 an extension. @xref{Variable Length}, for details.
13618 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
13619 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
13620 specifying an upper bound for @var{size} in case its value cannot be computed
13621 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
13622 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
13623 expression, it has no effect on code generation and no attempt is made to
13624 check its compatibility with @var{size}.
13628 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
13629 The @code{__builtin_has_attribute} function evaluates to an integer constant
13630 expression equal to @code{true} if the symbol or type referenced by
13631 the @var{type-or-expression} argument has been declared with
13632 the @var{attribute} referenced by the second argument. For
13633 an @var{type-or-expression} argument that does not reference a symbol,
13634 since attributes do not apply to expressions the built-in consider
13635 the type of the argument. Neither argument is evaluated.
13636 The @var{type-or-expression} argument is subject to the same
13637 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
13638 @var{attribute} argument is an attribute name optionally followed by
13639 a comma-separated list of arguments enclosed in parentheses. Both forms
13640 of attribute names---with and without double leading and trailing
13641 underscores---are recognized. @xref{Attribute Syntax}, for details.
13642 When no attribute arguments are specified for an attribute that expects
13643 one or more arguments the function returns @code{true} if
13644 @var{type-or-expression} has been declared with the attribute regardless
13645 of the attribute argument values. Arguments provided for an attribute
13646 that expects some are validated and matched up to the provided number.
13647 The function returns @code{true} if all provided arguments match. For
13648 example, the first call to the function below evaluates to @code{true}
13649 because @code{x} is declared with the @code{aligned} attribute but
13650 the second call evaluates to @code{false} because @code{x} is declared
13651 @code{aligned (8)} and not @code{aligned (4)}.
13654 __attribute__ ((aligned (8))) int x;
13655 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
13656 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
13659 Due to a limitation the @code{__builtin_has_attribute} function returns
13660 @code{false} for the @code{mode} attribute even if the type or variable
13661 referenced by the @var{type-or-expression} argument was declared with one.
13662 The function is also not supported with labels, and in C with enumerators.
13664 Note that unlike the @code{__has_attribute} preprocessor operator which
13665 is suitable for use in @code{#if} preprocessing directives
13666 @code{__builtin_has_attribute} is an intrinsic function that is not
13667 recognized in such contexts.
13671 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
13673 This built-in function can be used to help mitigate against unsafe
13674 speculative execution. @var{type} may be any integral type or any
13679 If the CPU is not speculatively executing the code, then @var{val}
13682 If the CPU is executing speculatively then either:
13685 The function may cause execution to pause until it is known that the
13686 code is no-longer being executed speculatively (in which case
13687 @var{val} can be returned, as above); or
13689 The function may use target-dependent speculation tracking state to cause
13690 @var{failval} to be returned when it is known that speculative
13691 execution has incorrectly predicted a conditional branch operation.
13695 The second argument, @var{failval}, is optional and defaults to zero
13698 GCC defines the preprocessor macro
13699 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
13700 updated to support this builtin.
13702 The built-in function can be used where a variable appears to be used in a
13703 safe way, but the CPU, due to speculative execution may temporarily ignore
13704 the bounds checks. Consider, for example, the following function:
13708 int f (unsigned untrusted_index)
13710 if (untrusted_index < 500)
13711 return array[untrusted_index];
13716 If the function is called repeatedly with @code{untrusted_index} less
13717 than the limit of 500, then a branch predictor will learn that the
13718 block of code that returns a value stored in @code{array} will be
13719 executed. If the function is subsequently called with an
13720 out-of-range value it will still try to execute that block of code
13721 first until the CPU determines that the prediction was incorrect
13722 (the CPU will unwind any incorrect operations at that point).
13723 However, depending on how the result of the function is used, it might be
13724 possible to leave traces in the cache that can reveal what was stored
13725 at the out-of-bounds location. The built-in function can be used to
13726 provide some protection against leaking data in this way by changing
13731 int f (unsigned untrusted_index)
13733 if (untrusted_index < 500)
13734 return array[__builtin_speculation_safe_value (untrusted_index)];
13739 The built-in function will either cause execution to stall until the
13740 conditional branch has been fully resolved, or it may permit
13741 speculative execution to continue, but using 0 instead of
13742 @code{untrusted_value} if that exceeds the limit.
13744 If accessing any memory location is potentially unsafe when speculative
13745 execution is incorrect, then the code can be rewritten as
13749 int f (unsigned untrusted_index)
13751 if (untrusted_index < 500)
13752 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
13757 which will cause a @code{NULL} pointer to be used for the unsafe case.
13761 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
13763 You can use the built-in function @code{__builtin_types_compatible_p} to
13764 determine whether two types are the same.
13766 This built-in function returns 1 if the unqualified versions of the
13767 types @var{type1} and @var{type2} (which are types, not expressions) are
13768 compatible, 0 otherwise. The result of this built-in function can be
13769 used in integer constant expressions.
13771 This built-in function ignores top level qualifiers (e.g., @code{const},
13772 @code{volatile}). For example, @code{int} is equivalent to @code{const
13775 The type @code{int[]} and @code{int[5]} are compatible. On the other
13776 hand, @code{int} and @code{char *} are not compatible, even if the size
13777 of their types, on the particular architecture are the same. Also, the
13778 amount of pointer indirection is taken into account when determining
13779 similarity. Consequently, @code{short *} is not similar to
13780 @code{short **}. Furthermore, two types that are typedefed are
13781 considered compatible if their underlying types are compatible.
13783 An @code{enum} type is not considered to be compatible with another
13784 @code{enum} type even if both are compatible with the same integer
13785 type; this is what the C standard specifies.
13786 For example, @code{enum @{foo, bar@}} is not similar to
13787 @code{enum @{hot, dog@}}.
13789 You typically use this function in code whose execution varies
13790 depending on the arguments' types. For example:
13795 typeof (x) tmp = (x); \
13796 if (__builtin_types_compatible_p (typeof (x), long double)) \
13797 tmp = foo_long_double (tmp); \
13798 else if (__builtin_types_compatible_p (typeof (x), double)) \
13799 tmp = foo_double (tmp); \
13800 else if (__builtin_types_compatible_p (typeof (x), float)) \
13801 tmp = foo_float (tmp); \
13808 @emph{Note:} This construct is only available for C@.
13812 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
13814 The @var{call_exp} expression must be a function call, and the
13815 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
13816 is passed to the function call in the target's static chain location.
13817 The result of builtin is the result of the function call.
13819 @emph{Note:} This builtin is only available for C@.
13820 This builtin can be used to call Go closures from C.
13824 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
13826 You can use the built-in function @code{__builtin_choose_expr} to
13827 evaluate code depending on the value of a constant expression. This
13828 built-in function returns @var{exp1} if @var{const_exp}, which is an
13829 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
13831 This built-in function is analogous to the @samp{? :} operator in C,
13832 except that the expression returned has its type unaltered by promotion
13833 rules. Also, the built-in function does not evaluate the expression
13834 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
13835 @var{exp2} is not evaluated even if it has side effects.
13837 This built-in function can return an lvalue if the chosen argument is an
13840 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
13841 type. Similarly, if @var{exp2} is returned, its return type is the same
13848 __builtin_choose_expr ( \
13849 __builtin_types_compatible_p (typeof (x), double), \
13851 __builtin_choose_expr ( \
13852 __builtin_types_compatible_p (typeof (x), float), \
13854 /* @r{The void expression results in a compile-time error} \
13855 @r{when assigning the result to something.} */ \
13859 @emph{Note:} This construct is only available for C@. Furthermore, the
13860 unused expression (@var{exp1} or @var{exp2} depending on the value of
13861 @var{const_exp}) may still generate syntax errors. This may change in
13866 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
13868 The built-in function @code{__builtin_tgmath}, available only for C
13869 and Objective-C, calls a function determined according to the rules of
13870 @code{<tgmath.h>} macros. It is intended to be used in
13871 implementations of that header, so that expansions of macros from that
13872 header only expand each of their arguments once, to avoid problems
13873 when calls to such macros are nested inside the arguments of other
13874 calls to such macros; in addition, it results in better diagnostics
13875 for invalid calls to @code{<tgmath.h>} macros than implementations
13876 using other GNU C language features. For example, the @code{pow}
13877 type-generic macro might be defined as:
13880 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
13881 cpowf, cpow, cpowl, a, b)
13884 The arguments to @code{__builtin_tgmath} are at least two pointers to
13885 functions, followed by the arguments to the type-generic macro (which
13886 will be passed as arguments to the selected function). All the
13887 pointers to functions must be pointers to prototyped functions, none
13888 of which may have variable arguments, and all of which must have the
13889 same number of parameters; the number of parameters of the first
13890 function determines how many arguments to @code{__builtin_tgmath} are
13891 interpreted as function pointers, and how many as the arguments to the
13894 The types of the specified functions must all be different, but
13895 related to each other in the same way as a set of functions that may
13896 be selected between by a macro in @code{<tgmath.h>}. This means that
13897 the functions are parameterized by a floating-point type @var{t},
13898 different for each such function. The function return types may all
13899 be the same type, or they may be @var{t} for each function, or they
13900 may be the real type corresponding to @var{t} for each function (if
13901 some of the types @var{t} are complex). Likewise, for each parameter
13902 position, the type of the parameter in that position may always be the
13903 same type, or may be @var{t} for each function (this case must apply
13904 for at least one parameter position), or may be the real type
13905 corresponding to @var{t} for each function.
13907 The standard rules for @code{<tgmath.h>} macros are used to find a
13908 common type @var{u} from the types of the arguments for parameters
13909 whose types vary between the functions; complex integer types (a GNU
13910 extension) are treated like @code{_Complex double} for this purpose
13911 (or @code{_Complex _Float64} if all the function return types are the
13912 same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
13913 If the function return types vary, or are all the same integer type,
13914 the function called is the one for which @var{t} is @var{u}, and it is
13915 an error if there is no such function. If the function return types
13916 are all the same floating-point type, the type-generic macro is taken
13917 to be one of those from TS 18661 that rounds the result to a narrower
13918 type; if there is a function for which @var{t} is @var{u}, it is
13919 called, and otherwise the first function, if any, for which @var{t}
13920 has at least the range and precision of @var{u} is called, and it is
13921 an error if there is no such function.
13925 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
13926 You can use the built-in function @code{__builtin_constant_p} to
13927 determine if a value is known to be constant at compile time and hence
13928 that GCC can perform constant-folding on expressions involving that
13929 value. The argument of the function is the value to test. The function
13930 returns the integer 1 if the argument is known to be a compile-time
13931 constant and 0 if it is not known to be a compile-time constant. A
13932 return of 0 does not indicate that the value is @emph{not} a constant,
13933 but merely that GCC cannot prove it is a constant with the specified
13934 value of the @option{-O} option.
13936 You typically use this function in an embedded application where
13937 memory is a critical resource. If you have some complex calculation,
13938 you may want it to be folded if it involves constants, but need to call
13939 a function if it does not. For example:
13942 #define Scale_Value(X) \
13943 (__builtin_constant_p (X) \
13944 ? ((X) * SCALE + OFFSET) : Scale (X))
13947 You may use this built-in function in either a macro or an inline
13948 function. However, if you use it in an inlined function and pass an
13949 argument of the function as the argument to the built-in, GCC
13950 never returns 1 when you call the inline function with a string constant
13951 or compound literal (@pxref{Compound Literals}) and does not return 1
13952 when you pass a constant numeric value to the inline function unless you
13953 specify the @option{-O} option.
13955 You may also use @code{__builtin_constant_p} in initializers for static
13956 data. For instance, you can write
13959 static const int table[] = @{
13960 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
13966 This is an acceptable initializer even if @var{EXPRESSION} is not a
13967 constant expression, including the case where
13968 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
13969 folded to a constant but @var{EXPRESSION} contains operands that are
13970 not otherwise permitted in a static initializer (for example,
13971 @code{0 && foo ()}). GCC must be more conservative about evaluating the
13972 built-in in this case, because it has no opportunity to perform
13976 @deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void)
13977 The @code{__builtin_is_constant_evaluated} function is available only
13978 in C++. The built-in is intended to be used by implementations of
13979 the @code{std::is_constant_evaluated} C++ function. Programs should make
13980 use of the latter function rather than invoking the built-in directly.
13982 The main use case of the built-in is to determine whether a @code{constexpr}
13983 function is being called in a @code{constexpr} context. A call to
13984 the function evaluates to a core constant expression with the value
13985 @code{true} if and only if it occurs within the evaluation of an expression
13986 or conversion that is manifestly constant-evaluated as defined in the C++
13987 standard. Manifestly constant-evaluated contexts include constant-expressions,
13988 the conditions of @code{constexpr if} statements, constraint-expressions, and
13989 initializers of variables usable in constant expressions. For more details
13990 refer to the latest revision of the C++ standard.
13993 @deftypefn {Built-in Function} void __builtin_clear_padding (@var{ptr})
13994 The built-in function @code{__builtin_clear_padding} function clears
13995 padding bits inside of the object representation of object pointed by
13996 @var{ptr}, which has to be a pointer. The value representation of the
13997 object is not affected. The type of the object is assumed to be the type
13998 the pointer points to. Inside of a union, the only cleared bits are
13999 bits that are padding bits for all the union members.
14001 This built-in-function is useful if the padding bits of an object might
14002 have intederminate values and the object representation needs to be
14003 bitwise compared to some other object, for example for atomic operations.
14005 For C++, @var{ptr} argument type should be pointer to trivially-copyable
14006 type, unless the argument is address of a variable or parameter, because
14007 otherwise it isn't known if the type isn't just a base class whose padding
14008 bits are reused or laid out differently in a derived class.
14011 @deftypefn {Built-in Function} @var{type} __builtin_bit_cast (@var{type}, @var{arg})
14012 The @code{__builtin_bit_cast} function is available only
14013 in C++. The built-in is intended to be used by implementations of
14014 the @code{std::bit_cast} C++ template function. Programs should make
14015 use of the latter function rather than invoking the built-in directly.
14017 This built-in function allows reinterpreting the bits of the @var{arg}
14018 argument as if it had type @var{type}. @var{type} and the type of the
14019 @var{arg} argument need to be trivially copyable types with the same size.
14020 When manifestly constant-evaluated, it performs extra diagnostics required
14021 for @code{std::bit_cast} and returns a constant expression if @var{arg}
14022 is a constant expression. For more details
14023 refer to the latest revision of the C++ standard.
14026 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
14027 @opindex fprofile-arcs
14028 You may use @code{__builtin_expect} to provide the compiler with
14029 branch prediction information. In general, you should prefer to
14030 use actual profile feedback for this (@option{-fprofile-arcs}), as
14031 programmers are notoriously bad at predicting how their programs
14032 actually perform. However, there are applications in which this
14033 data is hard to collect.
14035 The return value is the value of @var{exp}, which should be an integral
14036 expression. The semantics of the built-in are that it is expected that
14037 @var{exp} == @var{c}. For example:
14040 if (__builtin_expect (x, 0))
14045 indicates that we do not expect to call @code{foo}, since
14046 we expect @code{x} to be zero. Since you are limited to integral
14047 expressions for @var{exp}, you should use constructions such as
14050 if (__builtin_expect (ptr != NULL, 1))
14055 when testing pointer or floating-point values.
14057 For the purposes of branch prediction optimizations, the probability that
14058 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
14059 @code{builtin-expect-probability} parameter, which defaults to 90%.
14061 You can also use @code{__builtin_expect_with_probability} to explicitly
14062 assign a probability value to individual expressions. If the built-in
14063 is used in a loop construct, the provided probability will influence
14064 the expected number of iterations made by loop optimizations.
14067 @deftypefn {Built-in Function} long __builtin_expect_with_probability
14068 (long @var{exp}, long @var{c}, double @var{probability})
14070 This function has the same semantics as @code{__builtin_expect},
14071 but the caller provides the expected probability that @var{exp} == @var{c}.
14072 The last argument, @var{probability}, is a floating-point value in the
14073 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
14074 constant floating-point expression.
14077 @deftypefn {Built-in Function} void __builtin_trap (void)
14078 This function causes the program to exit abnormally. GCC implements
14079 this function by using a target-dependent mechanism (such as
14080 intentionally executing an illegal instruction) or by calling
14081 @code{abort}. The mechanism used may vary from release to release so
14082 you should not rely on any particular implementation.
14085 @deftypefn {Built-in Function} void __builtin_unreachable (void)
14086 If control flow reaches the point of the @code{__builtin_unreachable},
14087 the program is undefined. It is useful in situations where the
14088 compiler cannot deduce the unreachability of the code.
14090 One such case is immediately following an @code{asm} statement that
14091 either never terminates, or one that transfers control elsewhere
14092 and never returns. In this example, without the
14093 @code{__builtin_unreachable}, GCC issues a warning that control
14094 reaches the end of a non-void function. It also generates code
14095 to return after the @code{asm}.
14098 int f (int c, int v)
14106 asm("jmp error_handler");
14107 __builtin_unreachable ();
14113 Because the @code{asm} statement unconditionally transfers control out
14114 of the function, control never reaches the end of the function
14115 body. The @code{__builtin_unreachable} is in fact unreachable and
14116 communicates this fact to the compiler.
14118 Another use for @code{__builtin_unreachable} is following a call a
14119 function that never returns but that is not declared
14120 @code{__attribute__((noreturn))}, as in this example:
14123 void function_that_never_returns (void);
14133 function_that_never_returns ();
14134 __builtin_unreachable ();
14141 @deftypefn {Built-in Function} @var{type} __builtin_assoc_barrier (@var{type} @var{expr})
14142 This built-in inhibits re-association of the floating-point expression
14143 @var{expr} with expressions consuming the return value of the built-in. The
14144 expression @var{expr} itself can be reordered, and the whole expression
14145 @var{expr} can be reordered with operands after the barrier. The barrier is
14146 only relevant when @code{-fassociative-math} is active, since otherwise
14147 floating-point is not treated as associative.
14150 float x0 = a + b - b;
14151 float x1 = __builtin_assoc_barrier(a + b) - b;
14155 means that, with @code{-fassociative-math}, @code{x0} can be optimized to
14156 @code{x0 = a} but @code{x1} cannot.
14159 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
14160 This function returns its first argument, and allows the compiler
14161 to assume that the returned pointer is at least @var{align} bytes
14162 aligned. This built-in can have either two or three arguments,
14163 if it has three, the third argument should have integer type, and
14164 if it is nonzero means misalignment offset. For example:
14167 void *x = __builtin_assume_aligned (arg, 16);
14171 means that the compiler can assume @code{x}, set to @code{arg}, is at least
14172 16-byte aligned, while:
14175 void *x = __builtin_assume_aligned (arg, 32, 8);
14179 means that the compiler can assume for @code{x}, set to @code{arg}, that
14180 @code{(char *) x - 8} is 32-byte aligned.
14183 @deftypefn {Built-in Function} int __builtin_LINE ()
14184 This function is the equivalent of the preprocessor @code{__LINE__}
14185 macro and returns a constant integer expression that evaluates to
14186 the line number of the invocation of the built-in. When used as a C++
14187 default argument for a function @var{F}, it returns the line number
14188 of the call to @var{F}.
14191 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
14192 This function is the equivalent of the @code{__FUNCTION__} symbol
14193 and returns an address constant pointing to the name of the function
14194 from which the built-in was invoked, or the empty string if
14195 the invocation is not at function scope. When used as a C++ default
14196 argument for a function @var{F}, it returns the name of @var{F}'s
14197 caller or the empty string if the call was not made at function
14201 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
14202 This function is the equivalent of the preprocessor @code{__FILE__}
14203 macro and returns an address constant pointing to the file name
14204 containing the invocation of the built-in, or the empty string if
14205 the invocation is not at function scope. When used as a C++ default
14206 argument for a function @var{F}, it returns the file name of the call
14207 to @var{F} or the empty string if the call was not made at function
14210 For example, in the following, each call to function @code{foo} will
14211 print a line similar to @code{"file.c:123: foo: message"} with the name
14212 of the file and the line number of the @code{printf} call, the name of
14213 the function @code{foo}, followed by the word @code{message}.
14217 function (const char *func = __builtin_FUNCTION ())
14224 printf ("%s:%i: %s: message\n", file (), line (), function ());
14230 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
14231 This function is used to flush the processor's instruction cache for
14232 the region of memory between @var{begin} inclusive and @var{end}
14233 exclusive. Some targets require that the instruction cache be
14234 flushed, after modifying memory containing code, in order to obtain
14235 deterministic behavior.
14237 If the target does not require instruction cache flushes,
14238 @code{__builtin___clear_cache} has no effect. Otherwise either
14239 instructions are emitted in-line to clear the instruction cache or a
14240 call to the @code{__clear_cache} function in libgcc is made.
14243 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
14244 This function is used to minimize cache-miss latency by moving data into
14245 a cache before it is accessed.
14246 You can insert calls to @code{__builtin_prefetch} into code for which
14247 you know addresses of data in memory that is likely to be accessed soon.
14248 If the target supports them, data prefetch instructions are generated.
14249 If the prefetch is done early enough before the access then the data will
14250 be in the cache by the time it is accessed.
14252 The value of @var{addr} is the address of the memory to prefetch.
14253 There are two optional arguments, @var{rw} and @var{locality}.
14254 The value of @var{rw} is a compile-time constant one or zero; one
14255 means that the prefetch is preparing for a write to the memory address
14256 and zero, the default, means that the prefetch is preparing for a read.
14257 The value @var{locality} must be a compile-time constant integer between
14258 zero and three. A value of zero means that the data has no temporal
14259 locality, so it need not be left in the cache after the access. A value
14260 of three means that the data has a high degree of temporal locality and
14261 should be left in all levels of cache possible. Values of one and two
14262 mean, respectively, a low or moderate degree of temporal locality. The
14266 for (i = 0; i < n; i++)
14268 a[i] = a[i] + b[i];
14269 __builtin_prefetch (&a[i+j], 1, 1);
14270 __builtin_prefetch (&b[i+j], 0, 1);
14275 Data prefetch does not generate faults if @var{addr} is invalid, but
14276 the address expression itself must be valid. For example, a prefetch
14277 of @code{p->next} does not fault if @code{p->next} is not a valid
14278 address, but evaluation faults if @code{p} is not a valid address.
14280 If the target does not support data prefetch, the address expression
14281 is evaluated if it includes side effects but no other code is generated
14282 and GCC does not issue a warning.
14285 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
14286 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size
14287 Checking}, for a detailed description of the function.
14290 @deftypefn {Built-in Function} double __builtin_huge_val (void)
14291 Returns a positive infinity, if supported by the floating-point format,
14292 else @code{DBL_MAX}. This function is suitable for implementing the
14293 ISO C macro @code{HUGE_VAL}.
14296 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
14297 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
14300 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
14301 Similar to @code{__builtin_huge_val}, except the return
14302 type is @code{long double}.
14305 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
14306 Similar to @code{__builtin_huge_val}, except the return type is
14307 @code{_Float@var{n}}.
14310 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
14311 Similar to @code{__builtin_huge_val}, except the return type is
14312 @code{_Float@var{n}x}.
14315 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
14316 This built-in implements the C99 fpclassify functionality. The first
14317 five int arguments should be the target library's notion of the
14318 possible FP classes and are used for return values. They must be
14319 constant values and they must appear in this order: @code{FP_NAN},
14320 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
14321 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
14322 to classify. GCC treats the last argument as type-generic, which
14323 means it does not do default promotion from float to double.
14326 @deftypefn {Built-in Function} double __builtin_inf (void)
14327 Similar to @code{__builtin_huge_val}, except a warning is generated
14328 if the target floating-point format does not support infinities.
14331 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
14332 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
14335 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
14336 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
14339 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
14340 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
14343 @deftypefn {Built-in Function} float __builtin_inff (void)
14344 Similar to @code{__builtin_inf}, except the return type is @code{float}.
14345 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
14348 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
14349 Similar to @code{__builtin_inf}, except the return
14350 type is @code{long double}.
14353 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
14354 Similar to @code{__builtin_inf}, except the return
14355 type is @code{_Float@var{n}}.
14358 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
14359 Similar to @code{__builtin_inf}, except the return
14360 type is @code{_Float@var{n}x}.
14363 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
14364 Similar to @code{isinf}, except the return value is -1 for
14365 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
14366 Note while the parameter list is an
14367 ellipsis, this function only accepts exactly one floating-point
14368 argument. GCC treats this parameter as type-generic, which means it
14369 does not do default promotion from float to double.
14372 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
14373 This is an implementation of the ISO C99 function @code{nan}.
14375 Since ISO C99 defines this function in terms of @code{strtod}, which we
14376 do not implement, a description of the parsing is in order. The string
14377 is parsed as by @code{strtol}; that is, the base is recognized by
14378 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
14379 in the significand such that the least significant bit of the number
14380 is at the least significant bit of the significand. The number is
14381 truncated to fit the significand field provided. The significand is
14382 forced to be a quiet NaN@.
14384 This function, if given a string literal all of which would have been
14385 consumed by @code{strtol}, is evaluated early enough that it is considered a
14386 compile-time constant.
14389 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
14390 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
14393 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
14394 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
14397 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
14398 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
14401 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
14402 Similar to @code{__builtin_nan}, except the return type is @code{float}.
14405 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
14406 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
14409 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
14410 Similar to @code{__builtin_nan}, except the return type is
14411 @code{_Float@var{n}}.
14414 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
14415 Similar to @code{__builtin_nan}, except the return type is
14416 @code{_Float@var{n}x}.
14419 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
14420 Similar to @code{__builtin_nan}, except the significand is forced
14421 to be a signaling NaN@. The @code{nans} function is proposed by
14422 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
14425 @deftypefn {Built-in Function} _Decimal32 __builtin_nansd32 (const char *str)
14426 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}.
14429 @deftypefn {Built-in Function} _Decimal64 __builtin_nansd64 (const char *str)
14430 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}.
14433 @deftypefn {Built-in Function} _Decimal128 __builtin_nansd128 (const char *str)
14434 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}.
14437 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
14438 Similar to @code{__builtin_nans}, except the return type is @code{float}.
14441 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
14442 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
14445 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
14446 Similar to @code{__builtin_nans}, except the return type is
14447 @code{_Float@var{n}}.
14450 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
14451 Similar to @code{__builtin_nans}, except the return type is
14452 @code{_Float@var{n}x}.
14455 @deftypefn {Built-in Function} int __builtin_ffs (int x)
14456 Returns one plus the index of the least significant 1-bit of @var{x}, or
14457 if @var{x} is zero, returns zero.
14460 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
14461 Returns the number of leading 0-bits in @var{x}, starting at the most
14462 significant bit position. If @var{x} is 0, the result is undefined.
14465 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
14466 Returns the number of trailing 0-bits in @var{x}, starting at the least
14467 significant bit position. If @var{x} is 0, the result is undefined.
14470 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
14471 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
14472 number of bits following the most significant bit that are identical
14473 to it. There are no special cases for 0 or other values.
14476 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
14477 Returns the number of 1-bits in @var{x}.
14480 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
14481 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
14485 @deftypefn {Built-in Function} int __builtin_ffsl (long)
14486 Similar to @code{__builtin_ffs}, except the argument type is
14490 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
14491 Similar to @code{__builtin_clz}, except the argument type is
14492 @code{unsigned long}.
14495 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
14496 Similar to @code{__builtin_ctz}, except the argument type is
14497 @code{unsigned long}.
14500 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
14501 Similar to @code{__builtin_clrsb}, except the argument type is
14505 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
14506 Similar to @code{__builtin_popcount}, except the argument type is
14507 @code{unsigned long}.
14510 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
14511 Similar to @code{__builtin_parity}, except the argument type is
14512 @code{unsigned long}.
14515 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
14516 Similar to @code{__builtin_ffs}, except the argument type is
14520 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
14521 Similar to @code{__builtin_clz}, except the argument type is
14522 @code{unsigned long long}.
14525 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
14526 Similar to @code{__builtin_ctz}, except the argument type is
14527 @code{unsigned long long}.
14530 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
14531 Similar to @code{__builtin_clrsb}, except the argument type is
14535 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
14536 Similar to @code{__builtin_popcount}, except the argument type is
14537 @code{unsigned long long}.
14540 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
14541 Similar to @code{__builtin_parity}, except the argument type is
14542 @code{unsigned long long}.
14545 @deftypefn {Built-in Function} double __builtin_powi (double, int)
14546 Returns the first argument raised to the power of the second. Unlike the
14547 @code{pow} function no guarantees about precision and rounding are made.
14550 @deftypefn {Built-in Function} float __builtin_powif (float, int)
14551 Similar to @code{__builtin_powi}, except the argument and return types
14555 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
14556 Similar to @code{__builtin_powi}, except the argument and return types
14557 are @code{long double}.
14560 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
14561 Returns @var{x} with the order of the bytes reversed; for example,
14562 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
14566 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
14567 Similar to @code{__builtin_bswap16}, except the argument and return types
14571 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
14572 Similar to @code{__builtin_bswap32}, except the argument and return types
14576 @deftypefn {Built-in Function} uint128_t __builtin_bswap128 (uint128_t x)
14577 Similar to @code{__builtin_bswap64}, except the argument and return types
14578 are 128-bit. Only supported on targets when 128-bit types are supported.
14582 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
14583 On targets where the user visible pointer size is smaller than the size
14584 of an actual hardware address this function returns the extended user
14585 pointer. Targets where this is true included ILP32 mode on x86_64 or
14586 Aarch64. This function is mainly useful when writing inline assembly
14590 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
14591 Returns the openacc gang, worker or vector id depending on whether @var{x} is
14595 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
14596 Returns the openacc gang, worker or vector size depending on whether @var{x} is
14600 @node Target Builtins
14601 @section Built-in Functions Specific to Particular Target Machines
14603 On some target machines, GCC supports many built-in functions specific
14604 to those machines. Generally these generate calls to specific machine
14605 instructions, but allow the compiler to schedule those calls.
14608 * AArch64 Built-in Functions::
14609 * Alpha Built-in Functions::
14610 * Altera Nios II Built-in Functions::
14611 * ARC Built-in Functions::
14612 * ARC SIMD Built-in Functions::
14613 * ARM iWMMXt Built-in Functions::
14614 * ARM C Language Extensions (ACLE)::
14615 * ARM Floating Point Status and Control Intrinsics::
14616 * ARM ARMv8-M Security Extensions::
14617 * AVR Built-in Functions::
14618 * Blackfin Built-in Functions::
14619 * BPF Built-in Functions::
14620 * FR-V Built-in Functions::
14621 * MIPS DSP Built-in Functions::
14622 * MIPS Paired-Single Support::
14623 * MIPS Loongson Built-in Functions::
14624 * MIPS SIMD Architecture (MSA) Support::
14625 * Other MIPS Built-in Functions::
14626 * MSP430 Built-in Functions::
14627 * NDS32 Built-in Functions::
14628 * picoChip Built-in Functions::
14629 * Basic PowerPC Built-in Functions::
14630 * PowerPC AltiVec/VSX Built-in Functions::
14631 * PowerPC Hardware Transactional Memory Built-in Functions::
14632 * PowerPC Atomic Memory Operation Functions::
14633 * PowerPC Matrix-Multiply Assist Built-in Functions::
14634 * PRU Built-in Functions::
14635 * RISC-V Built-in Functions::
14636 * RX Built-in Functions::
14637 * S/390 System z Built-in Functions::
14638 * SH Built-in Functions::
14639 * SPARC VIS Built-in Functions::
14640 * TI C6X Built-in Functions::
14641 * x86 Built-in Functions::
14642 * x86 transactional memory intrinsics::
14643 * x86 control-flow protection intrinsics::
14646 @node AArch64 Built-in Functions
14647 @subsection AArch64 Built-in Functions
14649 These built-in functions are available for the AArch64 family of
14652 unsigned int __builtin_aarch64_get_fpcr ();
14653 void __builtin_aarch64_set_fpcr (unsigned int);
14654 unsigned int __builtin_aarch64_get_fpsr ();
14655 void __builtin_aarch64_set_fpsr (unsigned int);
14657 unsigned long long __builtin_aarch64_get_fpcr64 ();
14658 void __builtin_aarch64_set_fpcr64 (unsigned long long);
14659 unsigned long long __builtin_aarch64_get_fpsr64 ();
14660 void __builtin_aarch64_set_fpsr64 (unsigned long long);
14663 @node Alpha Built-in Functions
14664 @subsection Alpha Built-in Functions
14666 These built-in functions are available for the Alpha family of
14667 processors, depending on the command-line switches used.
14669 The following built-in functions are always available. They
14670 all generate the machine instruction that is part of the name.
14673 long __builtin_alpha_implver (void);
14674 long __builtin_alpha_rpcc (void);
14675 long __builtin_alpha_amask (long);
14676 long __builtin_alpha_cmpbge (long, long);
14677 long __builtin_alpha_extbl (long, long);
14678 long __builtin_alpha_extwl (long, long);
14679 long __builtin_alpha_extll (long, long);
14680 long __builtin_alpha_extql (long, long);
14681 long __builtin_alpha_extwh (long, long);
14682 long __builtin_alpha_extlh (long, long);
14683 long __builtin_alpha_extqh (long, long);
14684 long __builtin_alpha_insbl (long, long);
14685 long __builtin_alpha_inswl (long, long);
14686 long __builtin_alpha_insll (long, long);
14687 long __builtin_alpha_insql (long, long);
14688 long __builtin_alpha_inswh (long, long);
14689 long __builtin_alpha_inslh (long, long);
14690 long __builtin_alpha_insqh (long, long);
14691 long __builtin_alpha_mskbl (long, long);
14692 long __builtin_alpha_mskwl (long, long);
14693 long __builtin_alpha_mskll (long, long);
14694 long __builtin_alpha_mskql (long, long);
14695 long __builtin_alpha_mskwh (long, long);
14696 long __builtin_alpha_msklh (long, long);
14697 long __builtin_alpha_mskqh (long, long);
14698 long __builtin_alpha_umulh (long, long);
14699 long __builtin_alpha_zap (long, long);
14700 long __builtin_alpha_zapnot (long, long);
14703 The following built-in functions are always with @option{-mmax}
14704 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
14705 later. They all generate the machine instruction that is part
14709 long __builtin_alpha_pklb (long);
14710 long __builtin_alpha_pkwb (long);
14711 long __builtin_alpha_unpkbl (long);
14712 long __builtin_alpha_unpkbw (long);
14713 long __builtin_alpha_minub8 (long, long);
14714 long __builtin_alpha_minsb8 (long, long);
14715 long __builtin_alpha_minuw4 (long, long);
14716 long __builtin_alpha_minsw4 (long, long);
14717 long __builtin_alpha_maxub8 (long, long);
14718 long __builtin_alpha_maxsb8 (long, long);
14719 long __builtin_alpha_maxuw4 (long, long);
14720 long __builtin_alpha_maxsw4 (long, long);
14721 long __builtin_alpha_perr (long, long);
14724 The following built-in functions are always with @option{-mcix}
14725 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
14726 later. They all generate the machine instruction that is part
14730 long __builtin_alpha_cttz (long);
14731 long __builtin_alpha_ctlz (long);
14732 long __builtin_alpha_ctpop (long);
14735 The following built-in functions are available on systems that use the OSF/1
14736 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
14737 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
14738 @code{rdval} and @code{wrval}.
14741 void *__builtin_thread_pointer (void);
14742 void __builtin_set_thread_pointer (void *);
14745 @node Altera Nios II Built-in Functions
14746 @subsection Altera Nios II Built-in Functions
14748 These built-in functions are available for the Altera Nios II
14749 family of processors.
14751 The following built-in functions are always available. They
14752 all generate the machine instruction that is part of the name.
14755 int __builtin_ldbio (volatile const void *);
14756 int __builtin_ldbuio (volatile const void *);
14757 int __builtin_ldhio (volatile const void *);
14758 int __builtin_ldhuio (volatile const void *);
14759 int __builtin_ldwio (volatile const void *);
14760 void __builtin_stbio (volatile void *, int);
14761 void __builtin_sthio (volatile void *, int);
14762 void __builtin_stwio (volatile void *, int);
14763 void __builtin_sync (void);
14764 int __builtin_rdctl (int);
14765 int __builtin_rdprs (int, int);
14766 void __builtin_wrctl (int, int);
14767 void __builtin_flushd (volatile void *);
14768 void __builtin_flushda (volatile void *);
14769 int __builtin_wrpie (int);
14770 void __builtin_eni (int);
14771 int __builtin_ldex (volatile const void *);
14772 int __builtin_stex (volatile void *, int);
14773 int __builtin_ldsex (volatile const void *);
14774 int __builtin_stsex (volatile void *, int);
14777 The following built-in functions are always available. They
14778 all generate a Nios II Custom Instruction. The name of the
14779 function represents the types that the function takes and
14780 returns. The letter before the @code{n} is the return type
14781 or void if absent. The @code{n} represents the first parameter
14782 to all the custom instructions, the custom instruction number.
14783 The two letters after the @code{n} represent the up to two
14784 parameters to the function.
14786 The letters represent the following data types:
14789 @code{void} for return type and no parameter for parameter types.
14792 @code{int} for return type and parameter type
14795 @code{float} for return type and parameter type
14798 @code{void *} for return type and parameter type
14802 And the function names are:
14804 void __builtin_custom_n (void);
14805 void __builtin_custom_ni (int);
14806 void __builtin_custom_nf (float);
14807 void __builtin_custom_np (void *);
14808 void __builtin_custom_nii (int, int);
14809 void __builtin_custom_nif (int, float);
14810 void __builtin_custom_nip (int, void *);
14811 void __builtin_custom_nfi (float, int);
14812 void __builtin_custom_nff (float, float);
14813 void __builtin_custom_nfp (float, void *);
14814 void __builtin_custom_npi (void *, int);
14815 void __builtin_custom_npf (void *, float);
14816 void __builtin_custom_npp (void *, void *);
14817 int __builtin_custom_in (void);
14818 int __builtin_custom_ini (int);
14819 int __builtin_custom_inf (float);
14820 int __builtin_custom_inp (void *);
14821 int __builtin_custom_inii (int, int);
14822 int __builtin_custom_inif (int, float);
14823 int __builtin_custom_inip (int, void *);
14824 int __builtin_custom_infi (float, int);
14825 int __builtin_custom_inff (float, float);
14826 int __builtin_custom_infp (float, void *);
14827 int __builtin_custom_inpi (void *, int);
14828 int __builtin_custom_inpf (void *, float);
14829 int __builtin_custom_inpp (void *, void *);
14830 float __builtin_custom_fn (void);
14831 float __builtin_custom_fni (int);
14832 float __builtin_custom_fnf (float);
14833 float __builtin_custom_fnp (void *);
14834 float __builtin_custom_fnii (int, int);
14835 float __builtin_custom_fnif (int, float);
14836 float __builtin_custom_fnip (int, void *);
14837 float __builtin_custom_fnfi (float, int);
14838 float __builtin_custom_fnff (float, float);
14839 float __builtin_custom_fnfp (float, void *);
14840 float __builtin_custom_fnpi (void *, int);
14841 float __builtin_custom_fnpf (void *, float);
14842 float __builtin_custom_fnpp (void *, void *);
14843 void * __builtin_custom_pn (void);
14844 void * __builtin_custom_pni (int);
14845 void * __builtin_custom_pnf (float);
14846 void * __builtin_custom_pnp (void *);
14847 void * __builtin_custom_pnii (int, int);
14848 void * __builtin_custom_pnif (int, float);
14849 void * __builtin_custom_pnip (int, void *);
14850 void * __builtin_custom_pnfi (float, int);
14851 void * __builtin_custom_pnff (float, float);
14852 void * __builtin_custom_pnfp (float, void *);
14853 void * __builtin_custom_pnpi (void *, int);
14854 void * __builtin_custom_pnpf (void *, float);
14855 void * __builtin_custom_pnpp (void *, void *);
14858 @node ARC Built-in Functions
14859 @subsection ARC Built-in Functions
14861 The following built-in functions are provided for ARC targets. The
14862 built-ins generate the corresponding assembly instructions. In the
14863 examples given below, the generated code often requires an operand or
14864 result to be in a register. Where necessary further code will be
14865 generated to ensure this is true, but for brevity this is not
14866 described in each case.
14868 @emph{Note:} Using a built-in to generate an instruction not supported
14869 by a target may cause problems. At present the compiler is not
14870 guaranteed to detect such misuse, and as a result an internal compiler
14871 error may be generated.
14873 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
14874 Return 1 if @var{val} is known to have the byte alignment given
14875 by @var{alignval}, otherwise return 0.
14876 Note that this is different from
14878 __alignof__(*(char *)@var{val}) >= alignval
14880 because __alignof__ sees only the type of the dereference, whereas
14881 __builtin_arc_align uses alignment information from the pointer
14882 as well as from the pointed-to type.
14883 The information available will depend on optimization level.
14886 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
14893 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
14894 The operand is the number of a register to be read. Generates:
14896 mov @var{dest}, r@var{regno}
14898 where the value in @var{dest} will be the result returned from the
14902 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
14903 The first operand is the number of a register to be written, the
14904 second operand is a compile time constant to write into that
14905 register. Generates:
14907 mov r@var{regno}, @var{val}
14911 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
14912 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
14915 divaw @var{dest}, @var{a}, @var{b}
14917 where the value in @var{dest} will be the result returned from the
14921 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
14928 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
14929 The operand, @var{auxv}, is the address of an auxiliary register and
14930 must be a compile time constant. Generates:
14932 lr @var{dest}, [@var{auxr}]
14934 Where the value in @var{dest} will be the result returned from the
14938 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
14939 Only available with @option{-mmul64}. Generates:
14941 mul64 @var{a}, @var{b}
14945 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
14946 Only available with @option{-mmul64}. Generates:
14948 mulu64 @var{a}, @var{b}
14952 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
14959 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
14960 Only valid if the @samp{norm} instruction is available through the
14961 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14964 norm @var{dest}, @var{src}
14966 Where the value in @var{dest} will be the result returned from the
14970 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
14971 Only valid if the @samp{normw} instruction is available through the
14972 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14975 normw @var{dest}, @var{src}
14977 Where the value in @var{dest} will be the result returned from the
14981 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
14988 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
14995 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{val}, unsigned int @var{auxr})
14996 The first argument, @var{val}, is a compile time constant to be
14997 written to the register, the second argument, @var{auxr}, is the
14998 address of an auxiliary register. Generates:
15000 sr @var{val}, [@var{auxr}]
15004 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
15005 Only valid with @option{-mswap}. Generates:
15007 swap @var{dest}, @var{src}
15009 Where the value in @var{dest} will be the result returned from the
15013 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
15020 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
15021 Only available with @option{-mcpu=ARC700}. Generates:
15027 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
15028 Only available with @option{-mcpu=ARC700}. Generates:
15034 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
15035 Only available with @option{-mcpu=ARC700}. Generates:
15041 The instructions generated by the following builtins are not
15042 considered as candidates for scheduling. They are not moved around by
15043 the compiler during scheduling, and thus can be expected to appear
15044 where they are put in the C code:
15046 __builtin_arc_brk()
15047 __builtin_arc_core_read()
15048 __builtin_arc_core_write()
15049 __builtin_arc_flag()
15051 __builtin_arc_sleep()
15053 __builtin_arc_swi()
15056 @node ARC SIMD Built-in Functions
15057 @subsection ARC SIMD Built-in Functions
15059 SIMD builtins provided by the compiler can be used to generate the
15060 vector instructions. This section describes the available builtins
15061 and their usage in programs. With the @option{-msimd} option, the
15062 compiler provides 128-bit vector types, which can be specified using
15063 the @code{vector_size} attribute. The header file @file{arc-simd.h}
15064 can be included to use the following predefined types:
15066 typedef int __v4si __attribute__((vector_size(16)));
15067 typedef short __v8hi __attribute__((vector_size(16)));
15070 These types can be used to define 128-bit variables. The built-in
15071 functions listed in the following section can be used on these
15072 variables to generate the vector operations.
15074 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
15075 @file{arc-simd.h} also provides equivalent macros called
15076 @code{_@var{someinsn}} that can be used for programming ease and
15077 improved readability. The following macros for DMA control are also
15080 #define _setup_dma_in_channel_reg _vdiwr
15081 #define _setup_dma_out_channel_reg _vdowr
15084 The following is a complete list of all the SIMD built-ins provided
15085 for ARC, grouped by calling signature.
15087 The following take two @code{__v8hi} arguments and return a
15088 @code{__v8hi} result:
15090 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi);
15091 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi);
15092 __v8hi __builtin_arc_vand (__v8hi, __v8hi);
15093 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi);
15094 __v8hi __builtin_arc_vavb (__v8hi, __v8hi);
15095 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi);
15096 __v8hi __builtin_arc_vbic (__v8hi, __v8hi);
15097 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi);
15098 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi);
15099 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi);
15100 __v8hi __builtin_arc_veqw (__v8hi, __v8hi);
15101 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi);
15102 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi);
15103 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi);
15104 __v8hi __builtin_arc_vlew (__v8hi, __v8hi);
15105 __v8hi __builtin_arc_vltw (__v8hi, __v8hi);
15106 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi);
15107 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi);
15108 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi);
15109 __v8hi __builtin_arc_vminw (__v8hi, __v8hi);
15110 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi);
15111 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi);
15112 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi);
15113 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi);
15114 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi);
15115 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi);
15116 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi);
15117 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi);
15118 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi);
15119 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi);
15120 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi);
15121 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi);
15122 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi);
15123 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi);
15124 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi);
15125 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi);
15126 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi);
15127 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi);
15128 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi);
15129 __v8hi __builtin_arc_vnew (__v8hi, __v8hi);
15130 __v8hi __builtin_arc_vor (__v8hi, __v8hi);
15131 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi);
15132 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi);
15133 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi);
15134 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi);
15135 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi);
15136 __v8hi __builtin_arc_vxor (__v8hi, __v8hi);
15137 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi);
15140 The following take one @code{__v8hi} and one @code{int} argument and return a
15141 @code{__v8hi} result:
15144 __v8hi __builtin_arc_vbaddw (__v8hi, int);
15145 __v8hi __builtin_arc_vbmaxw (__v8hi, int);
15146 __v8hi __builtin_arc_vbminw (__v8hi, int);
15147 __v8hi __builtin_arc_vbmulaw (__v8hi, int);
15148 __v8hi __builtin_arc_vbmulfw (__v8hi, int);
15149 __v8hi __builtin_arc_vbmulw (__v8hi, int);
15150 __v8hi __builtin_arc_vbrsubw (__v8hi, int);
15151 __v8hi __builtin_arc_vbsubw (__v8hi, int);
15154 The following take one @code{__v8hi} argument and one @code{int} argument which
15155 must be a 3-bit compile time constant indicating a register number
15156 I0-I7. They return a @code{__v8hi} result.
15158 __v8hi __builtin_arc_vasrw (__v8hi, const int);
15159 __v8hi __builtin_arc_vsr8 (__v8hi, const int);
15160 __v8hi __builtin_arc_vsr8aw (__v8hi, const int);
15163 The following take one @code{__v8hi} argument and one @code{int}
15164 argument which must be a 6-bit compile time constant. They return a
15165 @code{__v8hi} result.
15167 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int);
15168 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int);
15169 __v8hi __builtin_arc_vasrrwi (__v8hi, const int);
15170 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int);
15171 __v8hi __builtin_arc_vasrwi (__v8hi, const int);
15172 __v8hi __builtin_arc_vsr8awi (__v8hi, const int);
15173 __v8hi __builtin_arc_vsr8i (__v8hi, const int);
15176 The following take one @code{__v8hi} argument and one @code{int} argument which
15177 must be a 8-bit compile time constant. They return a @code{__v8hi}
15180 __v8hi __builtin_arc_vd6tapf (__v8hi, const int);
15181 __v8hi __builtin_arc_vmvaw (__v8hi, const int);
15182 __v8hi __builtin_arc_vmvw (__v8hi, const int);
15183 __v8hi __builtin_arc_vmvzw (__v8hi, const int);
15186 The following take two @code{int} arguments, the second of which which
15187 must be a 8-bit compile time constant. They return a @code{__v8hi}
15190 __v8hi __builtin_arc_vmovaw (int, const int);
15191 __v8hi __builtin_arc_vmovw (int, const int);
15192 __v8hi __builtin_arc_vmovzw (int, const int);
15195 The following take a single @code{__v8hi} argument and return a
15196 @code{__v8hi} result:
15198 __v8hi __builtin_arc_vabsaw (__v8hi);
15199 __v8hi __builtin_arc_vabsw (__v8hi);
15200 __v8hi __builtin_arc_vaddsuw (__v8hi);
15201 __v8hi __builtin_arc_vexch1 (__v8hi);
15202 __v8hi __builtin_arc_vexch2 (__v8hi);
15203 __v8hi __builtin_arc_vexch4 (__v8hi);
15204 __v8hi __builtin_arc_vsignw (__v8hi);
15205 __v8hi __builtin_arc_vupbaw (__v8hi);
15206 __v8hi __builtin_arc_vupbw (__v8hi);
15207 __v8hi __builtin_arc_vupsbaw (__v8hi);
15208 __v8hi __builtin_arc_vupsbw (__v8hi);
15211 The following take two @code{int} arguments and return no result:
15213 void __builtin_arc_vdirun (int, int);
15214 void __builtin_arc_vdorun (int, int);
15217 The following take two @code{int} arguments and return no result. The
15218 first argument must a 3-bit compile time constant indicating one of
15219 the DR0-DR7 DMA setup channels:
15221 void __builtin_arc_vdiwr (const int, int);
15222 void __builtin_arc_vdowr (const int, int);
15225 The following take an @code{int} argument and return no result:
15227 void __builtin_arc_vendrec (int);
15228 void __builtin_arc_vrec (int);
15229 void __builtin_arc_vrecrun (int);
15230 void __builtin_arc_vrun (int);
15233 The following take a @code{__v8hi} argument and two @code{int}
15234 arguments and return a @code{__v8hi} result. The second argument must
15235 be a 3-bit compile time constants, indicating one the registers I0-I7,
15236 and the third argument must be an 8-bit compile time constant.
15238 @emph{Note:} Although the equivalent hardware instructions do not take
15239 an SIMD register as an operand, these builtins overwrite the relevant
15240 bits of the @code{__v8hi} register provided as the first argument with
15241 the value loaded from the @code{[Ib, u8]} location in the SDM.
15244 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int);
15245 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int);
15246 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int);
15247 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int);
15250 The following take two @code{int} arguments and return a @code{__v8hi}
15251 result. The first argument must be a 3-bit compile time constants,
15252 indicating one the registers I0-I7, and the second argument must be an
15253 8-bit compile time constant.
15256 __v8hi __builtin_arc_vld128 (const int, const int);
15257 __v8hi __builtin_arc_vld64w (const int, const int);
15260 The following take a @code{__v8hi} argument and two @code{int}
15261 arguments and return no result. The second argument must be a 3-bit
15262 compile time constants, indicating one the registers I0-I7, and the
15263 third argument must be an 8-bit compile time constant.
15266 void __builtin_arc_vst128 (__v8hi, const int, const int);
15267 void __builtin_arc_vst64 (__v8hi, const int, const int);
15270 The following take a @code{__v8hi} argument and three @code{int}
15271 arguments and return no result. The second argument must be a 3-bit
15272 compile-time constant, identifying the 16-bit sub-register to be
15273 stored, the third argument must be a 3-bit compile time constants,
15274 indicating one the registers I0-I7, and the fourth argument must be an
15275 8-bit compile time constant.
15278 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int);
15279 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int);
15282 @node ARM iWMMXt Built-in Functions
15283 @subsection ARM iWMMXt Built-in Functions
15285 These built-in functions are available for the ARM family of
15286 processors when the @option{-mcpu=iwmmxt} switch is used:
15289 typedef int v2si __attribute__ ((vector_size (8)));
15290 typedef short v4hi __attribute__ ((vector_size (8)));
15291 typedef char v8qi __attribute__ ((vector_size (8)));
15293 int __builtin_arm_getwcgr0 (void);
15294 void __builtin_arm_setwcgr0 (int);
15295 int __builtin_arm_getwcgr1 (void);
15296 void __builtin_arm_setwcgr1 (int);
15297 int __builtin_arm_getwcgr2 (void);
15298 void __builtin_arm_setwcgr2 (int);
15299 int __builtin_arm_getwcgr3 (void);
15300 void __builtin_arm_setwcgr3 (int);
15301 int __builtin_arm_textrmsb (v8qi, int);
15302 int __builtin_arm_textrmsh (v4hi, int);
15303 int __builtin_arm_textrmsw (v2si, int);
15304 int __builtin_arm_textrmub (v8qi, int);
15305 int __builtin_arm_textrmuh (v4hi, int);
15306 int __builtin_arm_textrmuw (v2si, int);
15307 v8qi __builtin_arm_tinsrb (v8qi, int, int);
15308 v4hi __builtin_arm_tinsrh (v4hi, int, int);
15309 v2si __builtin_arm_tinsrw (v2si, int, int);
15310 long long __builtin_arm_tmia (long long, int, int);
15311 long long __builtin_arm_tmiabb (long long, int, int);
15312 long long __builtin_arm_tmiabt (long long, int, int);
15313 long long __builtin_arm_tmiaph (long long, int, int);
15314 long long __builtin_arm_tmiatb (long long, int, int);
15315 long long __builtin_arm_tmiatt (long long, int, int);
15316 int __builtin_arm_tmovmskb (v8qi);
15317 int __builtin_arm_tmovmskh (v4hi);
15318 int __builtin_arm_tmovmskw (v2si);
15319 long long __builtin_arm_waccb (v8qi);
15320 long long __builtin_arm_wacch (v4hi);
15321 long long __builtin_arm_waccw (v2si);
15322 v8qi __builtin_arm_waddb (v8qi, v8qi);
15323 v8qi __builtin_arm_waddbss (v8qi, v8qi);
15324 v8qi __builtin_arm_waddbus (v8qi, v8qi);
15325 v4hi __builtin_arm_waddh (v4hi, v4hi);
15326 v4hi __builtin_arm_waddhss (v4hi, v4hi);
15327 v4hi __builtin_arm_waddhus (v4hi, v4hi);
15328 v2si __builtin_arm_waddw (v2si, v2si);
15329 v2si __builtin_arm_waddwss (v2si, v2si);
15330 v2si __builtin_arm_waddwus (v2si, v2si);
15331 v8qi __builtin_arm_walign (v8qi, v8qi, int);
15332 long long __builtin_arm_wand(long long, long long);
15333 long long __builtin_arm_wandn (long long, long long);
15334 v8qi __builtin_arm_wavg2b (v8qi, v8qi);
15335 v8qi __builtin_arm_wavg2br (v8qi, v8qi);
15336 v4hi __builtin_arm_wavg2h (v4hi, v4hi);
15337 v4hi __builtin_arm_wavg2hr (v4hi, v4hi);
15338 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi);
15339 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi);
15340 v2si __builtin_arm_wcmpeqw (v2si, v2si);
15341 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi);
15342 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi);
15343 v2si __builtin_arm_wcmpgtsw (v2si, v2si);
15344 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi);
15345 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi);
15346 v2si __builtin_arm_wcmpgtuw (v2si, v2si);
15347 long long __builtin_arm_wmacs (long long, v4hi, v4hi);
15348 long long __builtin_arm_wmacsz (v4hi, v4hi);
15349 long long __builtin_arm_wmacu (long long, v4hi, v4hi);
15350 long long __builtin_arm_wmacuz (v4hi, v4hi);
15351 v4hi __builtin_arm_wmadds (v4hi, v4hi);
15352 v4hi __builtin_arm_wmaddu (v4hi, v4hi);
15353 v8qi __builtin_arm_wmaxsb (v8qi, v8qi);
15354 v4hi __builtin_arm_wmaxsh (v4hi, v4hi);
15355 v2si __builtin_arm_wmaxsw (v2si, v2si);
15356 v8qi __builtin_arm_wmaxub (v8qi, v8qi);
15357 v4hi __builtin_arm_wmaxuh (v4hi, v4hi);
15358 v2si __builtin_arm_wmaxuw (v2si, v2si);
15359 v8qi __builtin_arm_wminsb (v8qi, v8qi);
15360 v4hi __builtin_arm_wminsh (v4hi, v4hi);
15361 v2si __builtin_arm_wminsw (v2si, v2si);
15362 v8qi __builtin_arm_wminub (v8qi, v8qi);
15363 v4hi __builtin_arm_wminuh (v4hi, v4hi);
15364 v2si __builtin_arm_wminuw (v2si, v2si);
15365 v4hi __builtin_arm_wmulsm (v4hi, v4hi);
15366 v4hi __builtin_arm_wmulul (v4hi, v4hi);
15367 v4hi __builtin_arm_wmulum (v4hi, v4hi);
15368 long long __builtin_arm_wor (long long, long long);
15369 v2si __builtin_arm_wpackdss (long long, long long);
15370 v2si __builtin_arm_wpackdus (long long, long long);
15371 v8qi __builtin_arm_wpackhss (v4hi, v4hi);
15372 v8qi __builtin_arm_wpackhus (v4hi, v4hi);
15373 v4hi __builtin_arm_wpackwss (v2si, v2si);
15374 v4hi __builtin_arm_wpackwus (v2si, v2si);
15375 long long __builtin_arm_wrord (long long, long long);
15376 long long __builtin_arm_wrordi (long long, int);
15377 v4hi __builtin_arm_wrorh (v4hi, long long);
15378 v4hi __builtin_arm_wrorhi (v4hi, int);
15379 v2si __builtin_arm_wrorw (v2si, long long);
15380 v2si __builtin_arm_wrorwi (v2si, int);
15381 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi);
15382 v2si __builtin_arm_wsadbz (v8qi, v8qi);
15383 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi);
15384 v2si __builtin_arm_wsadhz (v4hi, v4hi);
15385 v4hi __builtin_arm_wshufh (v4hi, int);
15386 long long __builtin_arm_wslld (long long, long long);
15387 long long __builtin_arm_wslldi (long long, int);
15388 v4hi __builtin_arm_wsllh (v4hi, long long);
15389 v4hi __builtin_arm_wsllhi (v4hi, int);
15390 v2si __builtin_arm_wsllw (v2si, long long);
15391 v2si __builtin_arm_wsllwi (v2si, int);
15392 long long __builtin_arm_wsrad (long long, long long);
15393 long long __builtin_arm_wsradi (long long, int);
15394 v4hi __builtin_arm_wsrah (v4hi, long long);
15395 v4hi __builtin_arm_wsrahi (v4hi, int);
15396 v2si __builtin_arm_wsraw (v2si, long long);
15397 v2si __builtin_arm_wsrawi (v2si, int);
15398 long long __builtin_arm_wsrld (long long, long long);
15399 long long __builtin_arm_wsrldi (long long, int);
15400 v4hi __builtin_arm_wsrlh (v4hi, long long);
15401 v4hi __builtin_arm_wsrlhi (v4hi, int);
15402 v2si __builtin_arm_wsrlw (v2si, long long);
15403 v2si __builtin_arm_wsrlwi (v2si, int);
15404 v8qi __builtin_arm_wsubb (v8qi, v8qi);
15405 v8qi __builtin_arm_wsubbss (v8qi, v8qi);
15406 v8qi __builtin_arm_wsubbus (v8qi, v8qi);
15407 v4hi __builtin_arm_wsubh (v4hi, v4hi);
15408 v4hi __builtin_arm_wsubhss (v4hi, v4hi);
15409 v4hi __builtin_arm_wsubhus (v4hi, v4hi);
15410 v2si __builtin_arm_wsubw (v2si, v2si);
15411 v2si __builtin_arm_wsubwss (v2si, v2si);
15412 v2si __builtin_arm_wsubwus (v2si, v2si);
15413 v4hi __builtin_arm_wunpckehsb (v8qi);
15414 v2si __builtin_arm_wunpckehsh (v4hi);
15415 long long __builtin_arm_wunpckehsw (v2si);
15416 v4hi __builtin_arm_wunpckehub (v8qi);
15417 v2si __builtin_arm_wunpckehuh (v4hi);
15418 long long __builtin_arm_wunpckehuw (v2si);
15419 v4hi __builtin_arm_wunpckelsb (v8qi);
15420 v2si __builtin_arm_wunpckelsh (v4hi);
15421 long long __builtin_arm_wunpckelsw (v2si);
15422 v4hi __builtin_arm_wunpckelub (v8qi);
15423 v2si __builtin_arm_wunpckeluh (v4hi);
15424 long long __builtin_arm_wunpckeluw (v2si);
15425 v8qi __builtin_arm_wunpckihb (v8qi, v8qi);
15426 v4hi __builtin_arm_wunpckihh (v4hi, v4hi);
15427 v2si __builtin_arm_wunpckihw (v2si, v2si);
15428 v8qi __builtin_arm_wunpckilb (v8qi, v8qi);
15429 v4hi __builtin_arm_wunpckilh (v4hi, v4hi);
15430 v2si __builtin_arm_wunpckilw (v2si, v2si);
15431 long long __builtin_arm_wxor (long long, long long);
15432 long long __builtin_arm_wzero ();
15436 @node ARM C Language Extensions (ACLE)
15437 @subsection ARM C Language Extensions (ACLE)
15439 GCC implements extensions for C as described in the ARM C Language
15440 Extensions (ACLE) specification, which can be found at
15441 @uref{https://developer.arm.com/documentation/ihi0053/latest/}.
15443 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
15444 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
15445 intrinsics can be found at
15446 @uref{https://developer.arm.com/documentation/ihi0073/latest/}.
15447 The built-in intrinsics for the Advanced SIMD extension are available when
15450 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
15451 back ends support CRC32 intrinsics and the ARM back end supports the
15452 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
15453 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
15454 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
15457 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
15458 availability of extensions.
15460 @node ARM Floating Point Status and Control Intrinsics
15461 @subsection ARM Floating Point Status and Control Intrinsics
15463 These built-in functions are available for the ARM family of
15464 processors with floating-point unit.
15467 unsigned int __builtin_arm_get_fpscr ();
15468 void __builtin_arm_set_fpscr (unsigned int);
15471 @node ARM ARMv8-M Security Extensions
15472 @subsection ARM ARMv8-M Security Extensions
15474 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
15475 Security Extensions: Requirements on Development Tools Engineering
15476 Specification, which can be found at
15477 @uref{https://developer.arm.com/documentation/ecm0359818/latest/}.
15479 As part of the Security Extensions GCC implements two new function attributes:
15480 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
15482 As part of the Security Extensions GCC implements the intrinsics below. FPTR
15483 is used here to mean any function pointer type.
15486 cmse_address_info_t cmse_TT (void *);
15487 cmse_address_info_t cmse_TT_fptr (FPTR);
15488 cmse_address_info_t cmse_TTT (void *);
15489 cmse_address_info_t cmse_TTT_fptr (FPTR);
15490 cmse_address_info_t cmse_TTA (void *);
15491 cmse_address_info_t cmse_TTA_fptr (FPTR);
15492 cmse_address_info_t cmse_TTAT (void *);
15493 cmse_address_info_t cmse_TTAT_fptr (FPTR);
15494 void * cmse_check_address_range (void *, size_t, int);
15495 typeof(p) cmse_nsfptr_create (FPTR p);
15496 intptr_t cmse_is_nsfptr (FPTR);
15497 int cmse_nonsecure_caller (void);
15500 @node AVR Built-in Functions
15501 @subsection AVR Built-in Functions
15503 For each built-in function for AVR, there is an equally named,
15504 uppercase built-in macro defined. That way users can easily query if
15505 or if not a specific built-in is implemented or not. For example, if
15506 @code{__builtin_avr_nop} is available the macro
15507 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
15511 @item void __builtin_avr_nop (void)
15512 @itemx void __builtin_avr_sei (void)
15513 @itemx void __builtin_avr_cli (void)
15514 @itemx void __builtin_avr_sleep (void)
15515 @itemx void __builtin_avr_wdr (void)
15516 @itemx unsigned char __builtin_avr_swap (unsigned char)
15517 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
15518 @itemx int __builtin_avr_fmuls (char, char)
15519 @itemx int __builtin_avr_fmulsu (char, unsigned char)
15520 These built-in functions map to the respective machine
15521 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
15522 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
15523 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
15524 as library call if no hardware multiplier is available.
15526 @item void __builtin_avr_delay_cycles (unsigned long ticks)
15527 Delay execution for @var{ticks} cycles. Note that this
15528 built-in does not take into account the effect of interrupts that
15529 might increase delay time. @var{ticks} must be a compile-time
15530 integer constant; delays with a variable number of cycles are not supported.
15532 @item char __builtin_avr_flash_segment (const __memx void*)
15533 This built-in takes a byte address to the 24-bit
15534 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
15535 the number of the flash segment (the 64 KiB chunk) where the address
15536 points to. Counting starts at @code{0}.
15537 If the address does not point to flash memory, return @code{-1}.
15539 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
15540 Insert bits from @var{bits} into @var{val} and return the resulting
15541 value. The nibbles of @var{map} determine how the insertion is
15542 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
15544 @item If @var{X} is @code{0xf},
15545 then the @var{n}-th bit of @var{val} is returned unaltered.
15547 @item If X is in the range 0@dots{}7,
15548 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
15550 @item If X is in the range 8@dots{}@code{0xe},
15551 then the @var{n}-th result bit is undefined.
15555 One typical use case for this built-in is adjusting input and
15556 output values to non-contiguous port layouts. Some examples:
15559 // same as val, bits is unused
15560 __builtin_avr_insert_bits (0xffffffff, bits, val);
15564 // same as bits, val is unused
15565 __builtin_avr_insert_bits (0x76543210, bits, val);
15569 // same as rotating bits by 4
15570 __builtin_avr_insert_bits (0x32107654, bits, 0);
15574 // high nibble of result is the high nibble of val
15575 // low nibble of result is the low nibble of bits
15576 __builtin_avr_insert_bits (0xffff3210, bits, val);
15580 // reverse the bit order of bits
15581 __builtin_avr_insert_bits (0x01234567, bits, 0);
15584 @item void __builtin_avr_nops (unsigned count)
15585 Insert @var{count} @code{NOP} instructions.
15586 The number of instructions must be a compile-time integer constant.
15591 There are many more AVR-specific built-in functions that are used to
15592 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
15593 section 7.18a.6. You don't need to use these built-ins directly.
15594 Instead, use the declarations as supplied by the @code{stdfix.h} header
15598 #include <stdfix.h>
15600 // Re-interpret the bit representation of unsigned 16-bit
15601 // integer @var{uval} as Q-format 0.16 value.
15602 unsigned fract get_bits (uint_ur_t uval)
15604 return urbits (uval);
15608 @node Blackfin Built-in Functions
15609 @subsection Blackfin Built-in Functions
15611 Currently, there are two Blackfin-specific built-in functions. These are
15612 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
15613 using inline assembly; by using these built-in functions the compiler can
15614 automatically add workarounds for hardware errata involving these
15615 instructions. These functions are named as follows:
15618 void __builtin_bfin_csync (void);
15619 void __builtin_bfin_ssync (void);
15622 @node BPF Built-in Functions
15623 @subsection BPF Built-in Functions
15625 The following built-in functions are available for eBPF targets.
15627 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset})
15628 Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15631 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset})
15632 Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15635 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset})
15636 Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15639 @deftypefn {Built-in Function} void * __builtin_preserve_access_index (@var{expr})
15640 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).
15643 @node FR-V Built-in Functions
15644 @subsection FR-V Built-in Functions
15646 GCC provides many FR-V-specific built-in functions. In general,
15647 these functions are intended to be compatible with those described
15648 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
15649 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
15650 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
15651 pointer rather than by value.
15653 Most of the functions are named after specific FR-V instructions.
15654 Such functions are said to be ``directly mapped'' and are summarized
15655 here in tabular form.
15659 * Directly-mapped Integer Functions::
15660 * Directly-mapped Media Functions::
15661 * Raw read/write Functions::
15662 * Other Built-in Functions::
15665 @node Argument Types
15666 @subsubsection Argument Types
15668 The arguments to the built-in functions can be divided into three groups:
15669 register numbers, compile-time constants and run-time values. In order
15670 to make this classification clear at a glance, the arguments and return
15671 values are given the following pseudo types:
15673 @multitable @columnfractions .20 .30 .15 .35
15674 @headitem Pseudo type @tab Real C type @tab Constant? @tab Description
15675 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
15676 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
15677 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
15678 @item @code{uw2} @tab @code{unsigned long long} @tab No
15679 @tab an unsigned doubleword
15680 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
15681 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
15682 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
15683 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
15686 These pseudo types are not defined by GCC, they are simply a notational
15687 convenience used in this manual.
15689 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
15690 and @code{sw2} are evaluated at run time. They correspond to
15691 register operands in the underlying FR-V instructions.
15693 @code{const} arguments represent immediate operands in the underlying
15694 FR-V instructions. They must be compile-time constants.
15696 @code{acc} arguments are evaluated at compile time and specify the number
15697 of an accumulator register. For example, an @code{acc} argument of 2
15698 selects the ACC2 register.
15700 @code{iacc} arguments are similar to @code{acc} arguments but specify the
15701 number of an IACC register. See @pxref{Other Built-in Functions}
15704 @node Directly-mapped Integer Functions
15705 @subsubsection Directly-Mapped Integer Functions
15707 The functions listed below map directly to FR-V I-type instructions.
15709 @multitable @columnfractions .45 .32 .23
15710 @headitem Function prototype @tab Example usage @tab Assembly output
15711 @item @code{sw1 __ADDSS (sw1, sw1)}
15712 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
15713 @tab @code{ADDSS @var{a},@var{b},@var{c}}
15714 @item @code{sw1 __SCAN (sw1, sw1)}
15715 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
15716 @tab @code{SCAN @var{a},@var{b},@var{c}}
15717 @item @code{sw1 __SCUTSS (sw1)}
15718 @tab @code{@var{b} = __SCUTSS (@var{a})}
15719 @tab @code{SCUTSS @var{a},@var{b}}
15720 @item @code{sw1 __SLASS (sw1, sw1)}
15721 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
15722 @tab @code{SLASS @var{a},@var{b},@var{c}}
15723 @item @code{void __SMASS (sw1, sw1)}
15724 @tab @code{__SMASS (@var{a}, @var{b})}
15725 @tab @code{SMASS @var{a},@var{b}}
15726 @item @code{void __SMSSS (sw1, sw1)}
15727 @tab @code{__SMSSS (@var{a}, @var{b})}
15728 @tab @code{SMSSS @var{a},@var{b}}
15729 @item @code{void __SMU (sw1, sw1)}
15730 @tab @code{__SMU (@var{a}, @var{b})}
15731 @tab @code{SMU @var{a},@var{b}}
15732 @item @code{sw2 __SMUL (sw1, sw1)}
15733 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
15734 @tab @code{SMUL @var{a},@var{b},@var{c}}
15735 @item @code{sw1 __SUBSS (sw1, sw1)}
15736 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
15737 @tab @code{SUBSS @var{a},@var{b},@var{c}}
15738 @item @code{uw2 __UMUL (uw1, uw1)}
15739 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
15740 @tab @code{UMUL @var{a},@var{b},@var{c}}
15743 @node Directly-mapped Media Functions
15744 @subsubsection Directly-Mapped Media Functions
15746 The functions listed below map directly to FR-V M-type instructions.
15748 @multitable @columnfractions .45 .32 .23
15749 @headitem Function prototype @tab Example usage @tab Assembly output
15750 @item @code{uw1 __MABSHS (sw1)}
15751 @tab @code{@var{b} = __MABSHS (@var{a})}
15752 @tab @code{MABSHS @var{a},@var{b}}
15753 @item @code{void __MADDACCS (acc, acc)}
15754 @tab @code{__MADDACCS (@var{b}, @var{a})}
15755 @tab @code{MADDACCS @var{a},@var{b}}
15756 @item @code{sw1 __MADDHSS (sw1, sw1)}
15757 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
15758 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
15759 @item @code{uw1 __MADDHUS (uw1, uw1)}
15760 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
15761 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
15762 @item @code{uw1 __MAND (uw1, uw1)}
15763 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
15764 @tab @code{MAND @var{a},@var{b},@var{c}}
15765 @item @code{void __MASACCS (acc, acc)}
15766 @tab @code{__MASACCS (@var{b}, @var{a})}
15767 @tab @code{MASACCS @var{a},@var{b}}
15768 @item @code{uw1 __MAVEH (uw1, uw1)}
15769 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
15770 @tab @code{MAVEH @var{a},@var{b},@var{c}}
15771 @item @code{uw2 __MBTOH (uw1)}
15772 @tab @code{@var{b} = __MBTOH (@var{a})}
15773 @tab @code{MBTOH @var{a},@var{b}}
15774 @item @code{void __MBTOHE (uw1 *, uw1)}
15775 @tab @code{__MBTOHE (&@var{b}, @var{a})}
15776 @tab @code{MBTOHE @var{a},@var{b}}
15777 @item @code{void __MCLRACC (acc)}
15778 @tab @code{__MCLRACC (@var{a})}
15779 @tab @code{MCLRACC @var{a}}
15780 @item @code{void __MCLRACCA (void)}
15781 @tab @code{__MCLRACCA ()}
15782 @tab @code{MCLRACCA}
15783 @item @code{uw1 __Mcop1 (uw1, uw1)}
15784 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
15785 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
15786 @item @code{uw1 __Mcop2 (uw1, uw1)}
15787 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
15788 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
15789 @item @code{uw1 __MCPLHI (uw2, const)}
15790 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
15791 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
15792 @item @code{uw1 __MCPLI (uw2, const)}
15793 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
15794 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
15795 @item @code{void __MCPXIS (acc, sw1, sw1)}
15796 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
15797 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
15798 @item @code{void __MCPXIU (acc, uw1, uw1)}
15799 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
15800 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
15801 @item @code{void __MCPXRS (acc, sw1, sw1)}
15802 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
15803 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
15804 @item @code{void __MCPXRU (acc, uw1, uw1)}
15805 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
15806 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
15807 @item @code{uw1 __MCUT (acc, uw1)}
15808 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
15809 @tab @code{MCUT @var{a},@var{b},@var{c}}
15810 @item @code{uw1 __MCUTSS (acc, sw1)}
15811 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
15812 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
15813 @item @code{void __MDADDACCS (acc, acc)}
15814 @tab @code{__MDADDACCS (@var{b}, @var{a})}
15815 @tab @code{MDADDACCS @var{a},@var{b}}
15816 @item @code{void __MDASACCS (acc, acc)}
15817 @tab @code{__MDASACCS (@var{b}, @var{a})}
15818 @tab @code{MDASACCS @var{a},@var{b}}
15819 @item @code{uw2 __MDCUTSSI (acc, const)}
15820 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
15821 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
15822 @item @code{uw2 __MDPACKH (uw2, uw2)}
15823 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
15824 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
15825 @item @code{uw2 __MDROTLI (uw2, const)}
15826 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
15827 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
15828 @item @code{void __MDSUBACCS (acc, acc)}
15829 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
15830 @tab @code{MDSUBACCS @var{a},@var{b}}
15831 @item @code{void __MDUNPACKH (uw1 *, uw2)}
15832 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
15833 @tab @code{MDUNPACKH @var{a},@var{b}}
15834 @item @code{uw2 __MEXPDHD (uw1, const)}
15835 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
15836 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
15837 @item @code{uw1 __MEXPDHW (uw1, const)}
15838 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
15839 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
15840 @item @code{uw1 __MHDSETH (uw1, const)}
15841 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
15842 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
15843 @item @code{sw1 __MHDSETS (const)}
15844 @tab @code{@var{b} = __MHDSETS (@var{a})}
15845 @tab @code{MHDSETS #@var{a},@var{b}}
15846 @item @code{uw1 __MHSETHIH (uw1, const)}
15847 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
15848 @tab @code{MHSETHIH #@var{a},@var{b}}
15849 @item @code{sw1 __MHSETHIS (sw1, const)}
15850 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
15851 @tab @code{MHSETHIS #@var{a},@var{b}}
15852 @item @code{uw1 __MHSETLOH (uw1, const)}
15853 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
15854 @tab @code{MHSETLOH #@var{a},@var{b}}
15855 @item @code{sw1 __MHSETLOS (sw1, const)}
15856 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
15857 @tab @code{MHSETLOS #@var{a},@var{b}}
15858 @item @code{uw1 __MHTOB (uw2)}
15859 @tab @code{@var{b} = __MHTOB (@var{a})}
15860 @tab @code{MHTOB @var{a},@var{b}}
15861 @item @code{void __MMACHS (acc, sw1, sw1)}
15862 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
15863 @tab @code{MMACHS @var{a},@var{b},@var{c}}
15864 @item @code{void __MMACHU (acc, uw1, uw1)}
15865 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
15866 @tab @code{MMACHU @var{a},@var{b},@var{c}}
15867 @item @code{void __MMRDHS (acc, sw1, sw1)}
15868 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
15869 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
15870 @item @code{void __MMRDHU (acc, uw1, uw1)}
15871 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
15872 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
15873 @item @code{void __MMULHS (acc, sw1, sw1)}
15874 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
15875 @tab @code{MMULHS @var{a},@var{b},@var{c}}
15876 @item @code{void __MMULHU (acc, uw1, uw1)}
15877 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
15878 @tab @code{MMULHU @var{a},@var{b},@var{c}}
15879 @item @code{void __MMULXHS (acc, sw1, sw1)}
15880 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
15881 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
15882 @item @code{void __MMULXHU (acc, uw1, uw1)}
15883 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
15884 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
15885 @item @code{uw1 __MNOT (uw1)}
15886 @tab @code{@var{b} = __MNOT (@var{a})}
15887 @tab @code{MNOT @var{a},@var{b}}
15888 @item @code{uw1 __MOR (uw1, uw1)}
15889 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
15890 @tab @code{MOR @var{a},@var{b},@var{c}}
15891 @item @code{uw1 __MPACKH (uh, uh)}
15892 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
15893 @tab @code{MPACKH @var{a},@var{b},@var{c}}
15894 @item @code{sw2 __MQADDHSS (sw2, sw2)}
15895 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
15896 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
15897 @item @code{uw2 __MQADDHUS (uw2, uw2)}
15898 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
15899 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
15900 @item @code{void __MQCPXIS (acc, sw2, sw2)}
15901 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
15902 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
15903 @item @code{void __MQCPXIU (acc, uw2, uw2)}
15904 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
15905 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
15906 @item @code{void __MQCPXRS (acc, sw2, sw2)}
15907 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
15908 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
15909 @item @code{void __MQCPXRU (acc, uw2, uw2)}
15910 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
15911 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
15912 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
15913 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
15914 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
15915 @item @code{sw2 __MQLMTHS (sw2, sw2)}
15916 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
15917 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
15918 @item @code{void __MQMACHS (acc, sw2, sw2)}
15919 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
15920 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
15921 @item @code{void __MQMACHU (acc, uw2, uw2)}
15922 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
15923 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
15924 @item @code{void __MQMACXHS (acc, sw2, sw2)}
15925 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
15926 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
15927 @item @code{void __MQMULHS (acc, sw2, sw2)}
15928 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
15929 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
15930 @item @code{void __MQMULHU (acc, uw2, uw2)}
15931 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
15932 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
15933 @item @code{void __MQMULXHS (acc, sw2, sw2)}
15934 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
15935 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
15936 @item @code{void __MQMULXHU (acc, uw2, uw2)}
15937 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
15938 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
15939 @item @code{sw2 __MQSATHS (sw2, sw2)}
15940 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
15941 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
15942 @item @code{uw2 __MQSLLHI (uw2, int)}
15943 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
15944 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
15945 @item @code{sw2 __MQSRAHI (sw2, int)}
15946 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
15947 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
15948 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
15949 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
15950 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
15951 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
15952 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
15953 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
15954 @item @code{void __MQXMACHS (acc, sw2, sw2)}
15955 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
15956 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
15957 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
15958 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
15959 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
15960 @item @code{uw1 __MRDACC (acc)}
15961 @tab @code{@var{b} = __MRDACC (@var{a})}
15962 @tab @code{MRDACC @var{a},@var{b}}
15963 @item @code{uw1 __MRDACCG (acc)}
15964 @tab @code{@var{b} = __MRDACCG (@var{a})}
15965 @tab @code{MRDACCG @var{a},@var{b}}
15966 @item @code{uw1 __MROTLI (uw1, const)}
15967 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
15968 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
15969 @item @code{uw1 __MROTRI (uw1, const)}
15970 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
15971 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
15972 @item @code{sw1 __MSATHS (sw1, sw1)}
15973 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
15974 @tab @code{MSATHS @var{a},@var{b},@var{c}}
15975 @item @code{uw1 __MSATHU (uw1, uw1)}
15976 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
15977 @tab @code{MSATHU @var{a},@var{b},@var{c}}
15978 @item @code{uw1 __MSLLHI (uw1, const)}
15979 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
15980 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
15981 @item @code{sw1 __MSRAHI (sw1, const)}
15982 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
15983 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
15984 @item @code{uw1 __MSRLHI (uw1, const)}
15985 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
15986 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
15987 @item @code{void __MSUBACCS (acc, acc)}
15988 @tab @code{__MSUBACCS (@var{b}, @var{a})}
15989 @tab @code{MSUBACCS @var{a},@var{b}}
15990 @item @code{sw1 __MSUBHSS (sw1, sw1)}
15991 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
15992 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
15993 @item @code{uw1 __MSUBHUS (uw1, uw1)}
15994 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
15995 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
15996 @item @code{void __MTRAP (void)}
15997 @tab @code{__MTRAP ()}
15999 @item @code{uw2 __MUNPACKH (uw1)}
16000 @tab @code{@var{b} = __MUNPACKH (@var{a})}
16001 @tab @code{MUNPACKH @var{a},@var{b}}
16002 @item @code{uw1 __MWCUT (uw2, uw1)}
16003 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
16004 @tab @code{MWCUT @var{a},@var{b},@var{c}}
16005 @item @code{void __MWTACC (acc, uw1)}
16006 @tab @code{__MWTACC (@var{b}, @var{a})}
16007 @tab @code{MWTACC @var{a},@var{b}}
16008 @item @code{void __MWTACCG (acc, uw1)}
16009 @tab @code{__MWTACCG (@var{b}, @var{a})}
16010 @tab @code{MWTACCG @var{a},@var{b}}
16011 @item @code{uw1 __MXOR (uw1, uw1)}
16012 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
16013 @tab @code{MXOR @var{a},@var{b},@var{c}}
16016 @node Raw read/write Functions
16017 @subsubsection Raw Read/Write Functions
16019 This sections describes built-in functions related to read and write
16020 instructions to access memory. These functions generate
16021 @code{membar} instructions to flush the I/O load and stores where
16022 appropriate, as described in Fujitsu's manual described above.
16026 @item unsigned char __builtin_read8 (void *@var{data})
16027 @item unsigned short __builtin_read16 (void *@var{data})
16028 @item unsigned long __builtin_read32 (void *@var{data})
16029 @item unsigned long long __builtin_read64 (void *@var{data})
16031 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
16032 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
16033 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
16034 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
16037 @node Other Built-in Functions
16038 @subsubsection Other Built-in Functions
16040 This section describes built-in functions that are not named after
16041 a specific FR-V instruction.
16044 @item sw2 __IACCreadll (iacc @var{reg})
16045 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
16046 for future expansion and must be 0.
16048 @item sw1 __IACCreadl (iacc @var{reg})
16049 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
16050 Other values of @var{reg} are rejected as invalid.
16052 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
16053 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
16054 is reserved for future expansion and must be 0.
16056 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
16057 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
16058 is 1. Other values of @var{reg} are rejected as invalid.
16060 @item void __data_prefetch0 (const void *@var{x})
16061 Use the @code{dcpl} instruction to load the contents of address @var{x}
16062 into the data cache.
16064 @item void __data_prefetch (const void *@var{x})
16065 Use the @code{nldub} instruction to load the contents of address @var{x}
16066 into the data cache. The instruction is issued in slot I1@.
16069 @node MIPS DSP Built-in Functions
16070 @subsection MIPS DSP Built-in Functions
16072 The MIPS DSP Application-Specific Extension (ASE) includes new
16073 instructions that are designed to improve the performance of DSP and
16074 media applications. It provides instructions that operate on packed
16075 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
16077 GCC supports MIPS DSP operations using both the generic
16078 vector extensions (@pxref{Vector Extensions}) and a collection of
16079 MIPS-specific built-in functions. Both kinds of support are
16080 enabled by the @option{-mdsp} command-line option.
16082 Revision 2 of the ASE was introduced in the second half of 2006.
16083 This revision adds extra instructions to the original ASE, but is
16084 otherwise backwards-compatible with it. You can select revision 2
16085 using the command-line option @option{-mdspr2}; this option implies
16088 The SCOUNT and POS bits of the DSP control register are global. The
16089 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
16090 POS bits. During optimization, the compiler does not delete these
16091 instructions and it does not delete calls to functions containing
16092 these instructions.
16094 At present, GCC only provides support for operations on 32-bit
16095 vectors. The vector type associated with 8-bit integer data is
16096 usually called @code{v4i8}, the vector type associated with Q7
16097 is usually called @code{v4q7}, the vector type associated with 16-bit
16098 integer data is usually called @code{v2i16}, and the vector type
16099 associated with Q15 is usually called @code{v2q15}. They can be
16100 defined in C as follows:
16103 typedef signed char v4i8 __attribute__ ((vector_size(4)));
16104 typedef signed char v4q7 __attribute__ ((vector_size(4)));
16105 typedef short v2i16 __attribute__ ((vector_size(4)));
16106 typedef short v2q15 __attribute__ ((vector_size(4)));
16109 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
16110 initialized in the same way as aggregates. For example:
16113 v4i8 a = @{1, 2, 3, 4@};
16115 b = (v4i8) @{5, 6, 7, 8@};
16117 v2q15 c = @{0x0fcb, 0x3a75@};
16119 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
16122 @emph{Note:} The CPU's endianness determines the order in which values
16123 are packed. On little-endian targets, the first value is the least
16124 significant and the last value is the most significant. The opposite
16125 order applies to big-endian targets. For example, the code above
16126 sets the lowest byte of @code{a} to @code{1} on little-endian targets
16127 and @code{4} on big-endian targets.
16129 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
16130 representation. As shown in this example, the integer representation
16131 of a Q7 value can be obtained by multiplying the fractional value by
16132 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
16133 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
16136 The table below lists the @code{v4i8} and @code{v2q15} operations for which
16137 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
16138 and @code{c} and @code{d} are @code{v2q15} values.
16140 @multitable @columnfractions .50 .50
16141 @headitem C code @tab MIPS instruction
16142 @item @code{a + b} @tab @code{addu.qb}
16143 @item @code{c + d} @tab @code{addq.ph}
16144 @item @code{a - b} @tab @code{subu.qb}
16145 @item @code{c - d} @tab @code{subq.ph}
16148 The table below lists the @code{v2i16} operation for which
16149 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
16150 @code{v2i16} values.
16152 @multitable @columnfractions .50 .50
16153 @headitem C code @tab MIPS instruction
16154 @item @code{e * f} @tab @code{mul.ph}
16157 It is easier to describe the DSP built-in functions if we first define
16158 the following types:
16163 typedef unsigned int ui32;
16164 typedef long long a64;
16167 @code{q31} and @code{i32} are actually the same as @code{int}, but we
16168 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
16169 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
16170 @code{long long}, but we use @code{a64} to indicate values that are
16171 placed in one of the four DSP accumulators (@code{$ac0},
16172 @code{$ac1}, @code{$ac2} or @code{$ac3}).
16174 Also, some built-in functions prefer or require immediate numbers as
16175 parameters, because the corresponding DSP instructions accept both immediate
16176 numbers and register operands, or accept immediate numbers only. The
16177 immediate parameters are listed as follows.
16185 imm0_255: 0 to 255.
16186 imm_n32_31: -32 to 31.
16187 imm_n512_511: -512 to 511.
16190 The following built-in functions map directly to a particular MIPS DSP
16191 instruction. Please refer to the architecture specification
16192 for details on what each instruction does.
16195 v2q15 __builtin_mips_addq_ph (v2q15, v2q15);
16196 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15);
16197 q31 __builtin_mips_addq_s_w (q31, q31);
16198 v4i8 __builtin_mips_addu_qb (v4i8, v4i8);
16199 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8);
16200 v2q15 __builtin_mips_subq_ph (v2q15, v2q15);
16201 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15);
16202 q31 __builtin_mips_subq_s_w (q31, q31);
16203 v4i8 __builtin_mips_subu_qb (v4i8, v4i8);
16204 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8);
16205 i32 __builtin_mips_addsc (i32, i32);
16206 i32 __builtin_mips_addwc (i32, i32);
16207 i32 __builtin_mips_modsub (i32, i32);
16208 i32 __builtin_mips_raddu_w_qb (v4i8);
16209 v2q15 __builtin_mips_absq_s_ph (v2q15);
16210 q31 __builtin_mips_absq_s_w (q31);
16211 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15);
16212 v2q15 __builtin_mips_precrq_ph_w (q31, q31);
16213 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31);
16214 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15);
16215 q31 __builtin_mips_preceq_w_phl (v2q15);
16216 q31 __builtin_mips_preceq_w_phr (v2q15);
16217 v2q15 __builtin_mips_precequ_ph_qbl (v4i8);
16218 v2q15 __builtin_mips_precequ_ph_qbr (v4i8);
16219 v2q15 __builtin_mips_precequ_ph_qbla (v4i8);
16220 v2q15 __builtin_mips_precequ_ph_qbra (v4i8);
16221 v2q15 __builtin_mips_preceu_ph_qbl (v4i8);
16222 v2q15 __builtin_mips_preceu_ph_qbr (v4i8);
16223 v2q15 __builtin_mips_preceu_ph_qbla (v4i8);
16224 v2q15 __builtin_mips_preceu_ph_qbra (v4i8);
16225 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7);
16226 v4i8 __builtin_mips_shll_qb (v4i8, i32);
16227 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15);
16228 v2q15 __builtin_mips_shll_ph (v2q15, i32);
16229 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15);
16230 v2q15 __builtin_mips_shll_s_ph (v2q15, i32);
16231 q31 __builtin_mips_shll_s_w (q31, imm0_31);
16232 q31 __builtin_mips_shll_s_w (q31, i32);
16233 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7);
16234 v4i8 __builtin_mips_shrl_qb (v4i8, i32);
16235 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15);
16236 v2q15 __builtin_mips_shra_ph (v2q15, i32);
16237 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15);
16238 v2q15 __builtin_mips_shra_r_ph (v2q15, i32);
16239 q31 __builtin_mips_shra_r_w (q31, imm0_31);
16240 q31 __builtin_mips_shra_r_w (q31, i32);
16241 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15);
16242 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15);
16243 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15);
16244 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15);
16245 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15);
16246 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8);
16247 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8);
16248 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8);
16249 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8);
16250 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15);
16251 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31);
16252 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15);
16253 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31);
16254 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15);
16255 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15);
16256 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15);
16257 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15);
16258 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15);
16259 i32 __builtin_mips_bitrev (i32);
16260 i32 __builtin_mips_insv (i32, i32);
16261 v4i8 __builtin_mips_repl_qb (imm0_255);
16262 v4i8 __builtin_mips_repl_qb (i32);
16263 v2q15 __builtin_mips_repl_ph (imm_n512_511);
16264 v2q15 __builtin_mips_repl_ph (i32);
16265 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8);
16266 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8);
16267 void __builtin_mips_cmpu_le_qb (v4i8, v4i8);
16268 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8);
16269 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8);
16270 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8);
16271 void __builtin_mips_cmp_eq_ph (v2q15, v2q15);
16272 void __builtin_mips_cmp_lt_ph (v2q15, v2q15);
16273 void __builtin_mips_cmp_le_ph (v2q15, v2q15);
16274 v4i8 __builtin_mips_pick_qb (v4i8, v4i8);
16275 v2q15 __builtin_mips_pick_ph (v2q15, v2q15);
16276 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15);
16277 i32 __builtin_mips_extr_w (a64, imm0_31);
16278 i32 __builtin_mips_extr_w (a64, i32);
16279 i32 __builtin_mips_extr_r_w (a64, imm0_31);
16280 i32 __builtin_mips_extr_s_h (a64, i32);
16281 i32 __builtin_mips_extr_rs_w (a64, imm0_31);
16282 i32 __builtin_mips_extr_rs_w (a64, i32);
16283 i32 __builtin_mips_extr_s_h (a64, imm0_31);
16284 i32 __builtin_mips_extr_r_w (a64, i32);
16285 i32 __builtin_mips_extp (a64, imm0_31);
16286 i32 __builtin_mips_extp (a64, i32);
16287 i32 __builtin_mips_extpdp (a64, imm0_31);
16288 i32 __builtin_mips_extpdp (a64, i32);
16289 a64 __builtin_mips_shilo (a64, imm_n32_31);
16290 a64 __builtin_mips_shilo (a64, i32);
16291 a64 __builtin_mips_mthlip (a64, i32);
16292 void __builtin_mips_wrdsp (i32, imm0_63);
16293 i32 __builtin_mips_rddsp (imm0_63);
16294 i32 __builtin_mips_lbux (void *, i32);
16295 i32 __builtin_mips_lhx (void *, i32);
16296 i32 __builtin_mips_lwx (void *, i32);
16297 a64 __builtin_mips_ldx (void *, i32); /* MIPS64 only */
16298 i32 __builtin_mips_bposge32 (void);
16299 a64 __builtin_mips_madd (a64, i32, i32);
16300 a64 __builtin_mips_maddu (a64, ui32, ui32);
16301 a64 __builtin_mips_msub (a64, i32, i32);
16302 a64 __builtin_mips_msubu (a64, ui32, ui32);
16303 a64 __builtin_mips_mult (i32, i32);
16304 a64 __builtin_mips_multu (ui32, ui32);
16307 The following built-in functions map directly to a particular MIPS DSP REV 2
16308 instruction. Please refer to the architecture specification
16309 for details on what each instruction does.
16312 v4q7 __builtin_mips_absq_s_qb (v4q7);
16313 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
16314 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
16315 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
16316 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
16317 i32 __builtin_mips_append (i32, i32, imm0_31);
16318 i32 __builtin_mips_balign (i32, i32, imm0_3);
16319 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
16320 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
16321 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
16322 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
16323 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
16324 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
16325 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
16326 q31 __builtin_mips_mulq_rs_w (q31, q31);
16327 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
16328 q31 __builtin_mips_mulq_s_w (q31, q31);
16329 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
16330 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
16331 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
16332 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
16333 i32 __builtin_mips_prepend (i32, i32, imm0_31);
16334 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
16335 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
16336 v4i8 __builtin_mips_shra_qb (v4i8, i32);
16337 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
16338 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
16339 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
16340 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
16341 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
16342 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
16343 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
16344 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
16345 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
16346 q31 __builtin_mips_addqh_w (q31, q31);
16347 q31 __builtin_mips_addqh_r_w (q31, q31);
16348 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
16349 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
16350 q31 __builtin_mips_subqh_w (q31, q31);
16351 q31 __builtin_mips_subqh_r_w (q31, q31);
16352 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
16353 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
16354 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
16355 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
16356 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
16357 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
16361 @node MIPS Paired-Single Support
16362 @subsection MIPS Paired-Single Support
16364 The MIPS64 architecture includes a number of instructions that
16365 operate on pairs of single-precision floating-point values.
16366 Each pair is packed into a 64-bit floating-point register,
16367 with one element being designated the ``upper half'' and
16368 the other being designated the ``lower half''.
16370 GCC supports paired-single operations using both the generic
16371 vector extensions (@pxref{Vector Extensions}) and a collection of
16372 MIPS-specific built-in functions. Both kinds of support are
16373 enabled by the @option{-mpaired-single} command-line option.
16375 The vector type associated with paired-single values is usually
16376 called @code{v2sf}. It can be defined in C as follows:
16379 typedef float v2sf __attribute__ ((vector_size (8)));
16382 @code{v2sf} values are initialized in the same way as aggregates.
16386 v2sf a = @{1.5, 9.1@};
16389 b = (v2sf) @{e, f@};
16392 @emph{Note:} The CPU's endianness determines which value is stored in
16393 the upper half of a register and which value is stored in the lower half.
16394 On little-endian targets, the first value is the lower one and the second
16395 value is the upper one. The opposite order applies to big-endian targets.
16396 For example, the code above sets the lower half of @code{a} to
16397 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
16399 @node MIPS Loongson Built-in Functions
16400 @subsection MIPS Loongson Built-in Functions
16402 GCC provides intrinsics to access the SIMD instructions provided by the
16403 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
16404 available after inclusion of the @code{loongson.h} header file,
16405 operate on the following 64-bit vector types:
16408 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
16409 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
16410 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
16411 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
16412 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
16413 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
16416 The intrinsics provided are listed below; each is named after the
16417 machine instruction to which it corresponds, with suffixes added as
16418 appropriate to distinguish intrinsics that expand to the same machine
16419 instruction yet have different argument types. Refer to the architecture
16420 documentation for a description of the functionality of each
16424 int16x4_t packsswh (int32x2_t s, int32x2_t t);
16425 int8x8_t packsshb (int16x4_t s, int16x4_t t);
16426 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
16427 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
16428 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
16429 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
16430 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
16431 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
16432 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
16433 uint64_t paddd_u (uint64_t s, uint64_t t);
16434 int64_t paddd_s (int64_t s, int64_t t);
16435 int16x4_t paddsh (int16x4_t s, int16x4_t t);
16436 int8x8_t paddsb (int8x8_t s, int8x8_t t);
16437 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
16438 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
16439 uint64_t pandn_ud (uint64_t s, uint64_t t);
16440 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
16441 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
16442 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
16443 int64_t pandn_sd (int64_t s, int64_t t);
16444 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
16445 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
16446 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
16447 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
16448 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
16449 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
16450 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
16451 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
16452 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
16453 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
16454 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
16455 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
16456 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
16457 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
16458 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
16459 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
16460 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
16461 uint16x4_t pextrh_u (uint16x4_t s, int field);
16462 int16x4_t pextrh_s (int16x4_t s, int field);
16463 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
16464 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
16465 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
16466 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
16467 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
16468 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
16469 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
16470 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
16471 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
16472 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
16473 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
16474 int16x4_t pminsh (int16x4_t s, int16x4_t t);
16475 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
16476 uint8x8_t pmovmskb_u (uint8x8_t s);
16477 int8x8_t pmovmskb_s (int8x8_t s);
16478 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
16479 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
16480 int16x4_t pmullh (int16x4_t s, int16x4_t t);
16481 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
16482 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
16483 uint16x4_t biadd (uint8x8_t s);
16484 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
16485 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
16486 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
16487 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
16488 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
16489 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
16490 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
16491 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
16492 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
16493 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
16494 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
16495 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
16496 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
16497 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
16498 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
16499 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
16500 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
16501 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
16502 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
16503 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
16504 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
16505 uint64_t psubd_u (uint64_t s, uint64_t t);
16506 int64_t psubd_s (int64_t s, int64_t t);
16507 int16x4_t psubsh (int16x4_t s, int16x4_t t);
16508 int8x8_t psubsb (int8x8_t s, int8x8_t t);
16509 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
16510 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
16511 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
16512 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
16513 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
16514 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
16515 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
16516 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
16517 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
16518 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
16519 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
16520 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
16521 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
16522 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
16526 * Paired-Single Arithmetic::
16527 * Paired-Single Built-in Functions::
16528 * MIPS-3D Built-in Functions::
16531 @node Paired-Single Arithmetic
16532 @subsubsection Paired-Single Arithmetic
16534 The table below lists the @code{v2sf} operations for which hardware
16535 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
16536 values and @code{x} is an integral value.
16538 @multitable @columnfractions .50 .50
16539 @headitem C code @tab MIPS instruction
16540 @item @code{a + b} @tab @code{add.ps}
16541 @item @code{a - b} @tab @code{sub.ps}
16542 @item @code{-a} @tab @code{neg.ps}
16543 @item @code{a * b} @tab @code{mul.ps}
16544 @item @code{a * b + c} @tab @code{madd.ps}
16545 @item @code{a * b - c} @tab @code{msub.ps}
16546 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
16547 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
16548 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
16551 Note that the multiply-accumulate instructions can be disabled
16552 using the command-line option @code{-mno-fused-madd}.
16554 @node Paired-Single Built-in Functions
16555 @subsubsection Paired-Single Built-in Functions
16557 The following paired-single functions map directly to a particular
16558 MIPS instruction. Please refer to the architecture specification
16559 for details on what each instruction does.
16562 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
16563 Pair lower lower (@code{pll.ps}).
16565 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
16566 Pair upper lower (@code{pul.ps}).
16568 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
16569 Pair lower upper (@code{plu.ps}).
16571 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
16572 Pair upper upper (@code{puu.ps}).
16574 @item v2sf __builtin_mips_cvt_ps_s (float, float)
16575 Convert pair to paired single (@code{cvt.ps.s}).
16577 @item float __builtin_mips_cvt_s_pl (v2sf)
16578 Convert pair lower to single (@code{cvt.s.pl}).
16580 @item float __builtin_mips_cvt_s_pu (v2sf)
16581 Convert pair upper to single (@code{cvt.s.pu}).
16583 @item v2sf __builtin_mips_abs_ps (v2sf)
16584 Absolute value (@code{abs.ps}).
16586 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
16587 Align variable (@code{alnv.ps}).
16589 @emph{Note:} The value of the third parameter must be 0 or 4
16590 modulo 8, otherwise the result is unpredictable. Please read the
16591 instruction description for details.
16594 The following multi-instruction functions are also available.
16595 In each case, @var{cond} can be any of the 16 floating-point conditions:
16596 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16597 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
16598 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16601 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16602 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16603 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
16604 @code{movt.ps}/@code{movf.ps}).
16606 The @code{movt} functions return the value @var{x} computed by:
16609 c.@var{cond}.ps @var{cc},@var{a},@var{b}
16610 mov.ps @var{x},@var{c}
16611 movt.ps @var{x},@var{d},@var{cc}
16614 The @code{movf} functions are similar but use @code{movf.ps} instead
16617 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16618 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16619 Comparison of two paired-single values (@code{c.@var{cond}.ps},
16620 @code{bc1t}/@code{bc1f}).
16622 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16623 and return either the upper or lower half of the result. For example:
16627 if (__builtin_mips_upper_c_eq_ps (a, b))
16628 upper_halves_are_equal ();
16630 upper_halves_are_unequal ();
16632 if (__builtin_mips_lower_c_eq_ps (a, b))
16633 lower_halves_are_equal ();
16635 lower_halves_are_unequal ();
16639 @node MIPS-3D Built-in Functions
16640 @subsubsection MIPS-3D Built-in Functions
16642 The MIPS-3D Application-Specific Extension (ASE) includes additional
16643 paired-single instructions that are designed to improve the performance
16644 of 3D graphics operations. Support for these instructions is controlled
16645 by the @option{-mips3d} command-line option.
16647 The functions listed below map directly to a particular MIPS-3D
16648 instruction. Please refer to the architecture specification for
16649 more details on what each instruction does.
16652 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
16653 Reduction add (@code{addr.ps}).
16655 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
16656 Reduction multiply (@code{mulr.ps}).
16658 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
16659 Convert paired single to paired word (@code{cvt.pw.ps}).
16661 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
16662 Convert paired word to paired single (@code{cvt.ps.pw}).
16664 @item float __builtin_mips_recip1_s (float)
16665 @itemx double __builtin_mips_recip1_d (double)
16666 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
16667 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
16669 @item float __builtin_mips_recip2_s (float, float)
16670 @itemx double __builtin_mips_recip2_d (double, double)
16671 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
16672 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
16674 @item float __builtin_mips_rsqrt1_s (float)
16675 @itemx double __builtin_mips_rsqrt1_d (double)
16676 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
16677 Reduced-precision reciprocal square root (sequence step 1)
16678 (@code{rsqrt1.@var{fmt}}).
16680 @item float __builtin_mips_rsqrt2_s (float, float)
16681 @itemx double __builtin_mips_rsqrt2_d (double, double)
16682 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
16683 Reduced-precision reciprocal square root (sequence step 2)
16684 (@code{rsqrt2.@var{fmt}}).
16687 The following multi-instruction functions are also available.
16688 In each case, @var{cond} can be any of the 16 floating-point conditions:
16689 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16690 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
16691 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16694 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
16695 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
16696 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
16697 @code{bc1t}/@code{bc1f}).
16699 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
16700 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
16705 if (__builtin_mips_cabs_eq_s (a, b))
16711 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16712 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16713 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
16714 @code{bc1t}/@code{bc1f}).
16716 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
16717 and return either the upper or lower half of the result. For example:
16721 if (__builtin_mips_upper_cabs_eq_ps (a, b))
16722 upper_halves_are_equal ();
16724 upper_halves_are_unequal ();
16726 if (__builtin_mips_lower_cabs_eq_ps (a, b))
16727 lower_halves_are_equal ();
16729 lower_halves_are_unequal ();
16732 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16733 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16734 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
16735 @code{movt.ps}/@code{movf.ps}).
16737 The @code{movt} functions return the value @var{x} computed by:
16740 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
16741 mov.ps @var{x},@var{c}
16742 movt.ps @var{x},@var{d},@var{cc}
16745 The @code{movf} functions are similar but use @code{movf.ps} instead
16748 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16749 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16750 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16751 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16752 Comparison of two paired-single values
16753 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16754 @code{bc1any2t}/@code{bc1any2f}).
16756 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16757 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
16758 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
16763 if (__builtin_mips_any_c_eq_ps (a, b))
16768 if (__builtin_mips_all_c_eq_ps (a, b))
16774 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16775 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16776 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16777 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16778 Comparison of four paired-single values
16779 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16780 @code{bc1any4t}/@code{bc1any4f}).
16782 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
16783 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
16784 The @code{any} forms return @code{true} if any of the four results are @code{true}
16785 and the @code{all} forms return @code{true} if all four results are @code{true}.
16790 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
16795 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
16802 @node MIPS SIMD Architecture (MSA) Support
16803 @subsection MIPS SIMD Architecture (MSA) Support
16806 * MIPS SIMD Architecture Built-in Functions::
16809 GCC provides intrinsics to access the SIMD instructions provided by the
16810 MSA MIPS SIMD Architecture. The interface is made available by including
16811 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
16812 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
16815 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
16816 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
16817 data elements. The following vectors typedefs are included in @code{msa.h}:
16819 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
16820 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
16821 @item @code{v8i16}, a vector of eight signed 16-bit integers;
16822 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
16823 @item @code{v4i32}, a vector of four signed 32-bit integers;
16824 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
16825 @item @code{v2i64}, a vector of two signed 64-bit integers;
16826 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
16827 @item @code{v4f32}, a vector of four 32-bit floats;
16828 @item @code{v2f64}, a vector of two 64-bit doubles.
16831 Instructions and corresponding built-ins may have additional restrictions and/or
16832 input/output values manipulated:
16834 @item @code{imm0_1}, an integer literal in range 0 to 1;
16835 @item @code{imm0_3}, an integer literal in range 0 to 3;
16836 @item @code{imm0_7}, an integer literal in range 0 to 7;
16837 @item @code{imm0_15}, an integer literal in range 0 to 15;
16838 @item @code{imm0_31}, an integer literal in range 0 to 31;
16839 @item @code{imm0_63}, an integer literal in range 0 to 63;
16840 @item @code{imm0_255}, an integer literal in range 0 to 255;
16841 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
16842 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
16843 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
16844 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
16845 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
16846 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
16847 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
16848 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
16849 @item @code{imm1_4}, an integer literal in range 1 to 4;
16850 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
16856 #if __LONG_MAX__ == __LONG_LONG_MAX__
16859 typedef long long i64;
16862 typedef unsigned int u32;
16863 #if __LONG_MAX__ == __LONG_LONG_MAX__
16864 typedef unsigned long u64;
16866 typedef unsigned long long u64;
16869 typedef double f64;
16874 @node MIPS SIMD Architecture Built-in Functions
16875 @subsubsection MIPS SIMD Architecture Built-in Functions
16877 The intrinsics provided are listed below; each is named after the
16878 machine instruction.
16881 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
16882 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
16883 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
16884 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
16886 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
16887 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
16888 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
16889 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
16891 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
16892 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
16893 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
16894 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
16896 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
16897 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
16898 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
16899 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
16901 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
16902 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
16903 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
16904 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
16906 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
16907 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
16908 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
16909 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
16911 v16u8 __builtin_msa_and_v (v16u8, v16u8);
16913 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
16915 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
16916 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
16917 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
16918 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
16920 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
16921 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
16922 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
16923 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
16925 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
16926 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
16927 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
16928 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
16930 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
16931 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
16932 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
16933 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
16935 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
16936 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
16937 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
16938 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
16940 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
16941 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
16942 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
16943 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
16945 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
16946 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
16947 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
16948 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
16950 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
16951 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
16952 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
16953 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
16955 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
16956 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
16957 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
16958 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
16960 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
16961 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
16962 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
16963 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
16965 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
16966 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
16967 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
16968 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
16970 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
16971 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
16972 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
16973 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
16975 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
16977 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
16979 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
16981 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
16983 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
16984 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
16985 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
16986 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
16988 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
16989 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
16990 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
16991 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
16993 i32 __builtin_msa_bnz_b (v16u8);
16994 i32 __builtin_msa_bnz_h (v8u16);
16995 i32 __builtin_msa_bnz_w (v4u32);
16996 i32 __builtin_msa_bnz_d (v2u64);
16998 i32 __builtin_msa_bnz_v (v16u8);
17000 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
17002 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
17004 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
17005 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
17006 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
17007 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
17009 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
17010 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
17011 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
17012 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
17014 i32 __builtin_msa_bz_b (v16u8);
17015 i32 __builtin_msa_bz_h (v8u16);
17016 i32 __builtin_msa_bz_w (v4u32);
17017 i32 __builtin_msa_bz_d (v2u64);
17019 i32 __builtin_msa_bz_v (v16u8);
17021 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
17022 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
17023 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
17024 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
17026 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
17027 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
17028 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
17029 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
17031 i32 __builtin_msa_cfcmsa (imm0_31);
17033 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
17034 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
17035 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
17036 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
17038 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
17039 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
17040 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
17041 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
17043 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
17044 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
17045 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
17046 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
17048 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
17049 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
17050 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
17051 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
17053 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
17054 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
17055 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
17056 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
17058 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
17059 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
17060 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
17061 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
17063 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
17064 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
17065 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
17066 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
17068 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
17069 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
17070 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
17071 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
17073 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
17074 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
17075 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
17076 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
17078 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
17079 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
17080 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
17081 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
17083 void __builtin_msa_ctcmsa (imm0_31, i32);
17085 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
17086 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
17087 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
17088 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
17090 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
17091 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
17092 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
17093 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
17095 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
17096 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
17097 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
17099 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
17100 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
17101 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
17103 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
17104 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
17105 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
17107 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
17108 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
17109 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
17111 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
17112 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
17113 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
17115 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
17116 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
17117 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
17119 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
17120 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
17122 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
17123 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
17125 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
17126 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
17128 v4i32 __builtin_msa_fclass_w (v4f32);
17129 v2i64 __builtin_msa_fclass_d (v2f64);
17131 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
17132 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
17134 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
17135 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
17137 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
17138 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
17140 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
17141 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
17143 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
17144 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
17146 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
17147 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
17149 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
17150 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
17152 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
17153 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
17155 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
17156 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
17158 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
17159 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
17161 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
17162 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
17164 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
17165 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
17167 v4f32 __builtin_msa_fexupl_w (v8i16);
17168 v2f64 __builtin_msa_fexupl_d (v4f32);
17170 v4f32 __builtin_msa_fexupr_w (v8i16);
17171 v2f64 __builtin_msa_fexupr_d (v4f32);
17173 v4f32 __builtin_msa_ffint_s_w (v4i32);
17174 v2f64 __builtin_msa_ffint_s_d (v2i64);
17176 v4f32 __builtin_msa_ffint_u_w (v4u32);
17177 v2f64 __builtin_msa_ffint_u_d (v2u64);
17179 v4f32 __builtin_msa_ffql_w (v8i16);
17180 v2f64 __builtin_msa_ffql_d (v4i32);
17182 v4f32 __builtin_msa_ffqr_w (v8i16);
17183 v2f64 __builtin_msa_ffqr_d (v4i32);
17185 v16i8 __builtin_msa_fill_b (i32);
17186 v8i16 __builtin_msa_fill_h (i32);
17187 v4i32 __builtin_msa_fill_w (i32);
17188 v2i64 __builtin_msa_fill_d (i64);
17190 v4f32 __builtin_msa_flog2_w (v4f32);
17191 v2f64 __builtin_msa_flog2_d (v2f64);
17193 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
17194 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
17196 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
17197 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
17199 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
17200 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
17202 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
17203 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
17205 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
17206 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
17208 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
17209 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
17211 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
17212 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
17214 v4f32 __builtin_msa_frint_w (v4f32);
17215 v2f64 __builtin_msa_frint_d (v2f64);
17217 v4f32 __builtin_msa_frcp_w (v4f32);
17218 v2f64 __builtin_msa_frcp_d (v2f64);
17220 v4f32 __builtin_msa_frsqrt_w (v4f32);
17221 v2f64 __builtin_msa_frsqrt_d (v2f64);
17223 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
17224 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
17226 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
17227 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
17229 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
17230 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
17232 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
17233 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
17235 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
17236 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
17238 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
17239 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
17241 v4f32 __builtin_msa_fsqrt_w (v4f32);
17242 v2f64 __builtin_msa_fsqrt_d (v2f64);
17244 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
17245 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
17247 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
17248 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
17250 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
17251 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
17253 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
17254 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
17256 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
17257 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
17259 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
17260 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
17262 v4i32 __builtin_msa_ftint_s_w (v4f32);
17263 v2i64 __builtin_msa_ftint_s_d (v2f64);
17265 v4u32 __builtin_msa_ftint_u_w (v4f32);
17266 v2u64 __builtin_msa_ftint_u_d (v2f64);
17268 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
17269 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
17271 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
17272 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
17274 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
17275 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
17277 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
17278 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
17279 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
17281 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
17282 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
17283 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
17285 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
17286 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
17287 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
17289 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
17290 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
17291 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
17293 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
17294 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
17295 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
17296 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
17298 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
17299 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
17300 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
17301 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
17303 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
17304 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
17305 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
17306 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
17308 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
17309 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
17310 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
17311 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
17313 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
17314 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
17315 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
17316 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
17318 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
17319 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
17320 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
17321 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
17323 v16i8 __builtin_msa_ld_b (const void *, imm_n512_511);
17324 v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022);
17325 v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044);
17326 v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088);
17328 v16i8 __builtin_msa_ldi_b (imm_n512_511);
17329 v8i16 __builtin_msa_ldi_h (imm_n512_511);
17330 v4i32 __builtin_msa_ldi_w (imm_n512_511);
17331 v2i64 __builtin_msa_ldi_d (imm_n512_511);
17333 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
17334 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
17336 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
17337 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
17339 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
17340 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
17341 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
17342 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
17344 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
17345 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
17346 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
17347 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
17349 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
17350 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
17351 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
17352 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
17354 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
17355 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
17356 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
17357 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
17359 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
17360 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
17361 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
17362 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
17364 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
17365 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
17366 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
17367 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
17369 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
17370 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
17371 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
17372 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
17374 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
17375 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
17376 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
17377 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
17379 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
17380 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
17381 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
17382 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
17384 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
17385 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
17386 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
17387 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
17389 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
17390 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
17391 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
17392 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
17394 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
17395 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
17396 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
17397 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
17399 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
17400 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
17401 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
17402 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
17404 v16i8 __builtin_msa_move_v (v16i8);
17406 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
17407 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
17409 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
17410 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
17412 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
17413 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
17414 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
17415 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
17417 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
17418 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
17420 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
17421 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
17423 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
17424 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
17425 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
17426 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
17428 v16i8 __builtin_msa_nloc_b (v16i8);
17429 v8i16 __builtin_msa_nloc_h (v8i16);
17430 v4i32 __builtin_msa_nloc_w (v4i32);
17431 v2i64 __builtin_msa_nloc_d (v2i64);
17433 v16i8 __builtin_msa_nlzc_b (v16i8);
17434 v8i16 __builtin_msa_nlzc_h (v8i16);
17435 v4i32 __builtin_msa_nlzc_w (v4i32);
17436 v2i64 __builtin_msa_nlzc_d (v2i64);
17438 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
17440 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
17442 v16u8 __builtin_msa_or_v (v16u8, v16u8);
17444 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
17446 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
17447 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
17448 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
17449 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
17451 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
17452 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
17453 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
17454 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
17456 v16i8 __builtin_msa_pcnt_b (v16i8);
17457 v8i16 __builtin_msa_pcnt_h (v8i16);
17458 v4i32 __builtin_msa_pcnt_w (v4i32);
17459 v2i64 __builtin_msa_pcnt_d (v2i64);
17461 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
17462 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
17463 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
17464 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
17466 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
17467 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
17468 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
17469 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
17471 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
17472 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
17473 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
17475 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
17476 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
17477 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
17478 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
17480 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
17481 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
17482 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
17483 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
17485 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
17486 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
17487 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
17488 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
17490 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
17491 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
17492 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
17493 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
17495 v16i8 __builtin_msa_splat_b (v16i8, i32);
17496 v8i16 __builtin_msa_splat_h (v8i16, i32);
17497 v4i32 __builtin_msa_splat_w (v4i32, i32);
17498 v2i64 __builtin_msa_splat_d (v2i64, i32);
17500 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
17501 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
17502 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
17503 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
17505 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
17506 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
17507 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
17508 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
17510 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
17511 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
17512 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
17513 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
17515 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
17516 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
17517 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
17518 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
17520 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
17521 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
17522 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
17523 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
17525 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
17526 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
17527 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
17528 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
17530 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
17531 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
17532 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
17533 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
17535 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
17536 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
17537 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
17538 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
17540 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
17541 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
17542 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
17543 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
17545 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
17546 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
17547 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
17548 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
17550 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
17551 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
17552 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
17553 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
17555 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
17556 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
17557 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
17558 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
17560 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
17561 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
17562 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
17563 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
17565 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
17566 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
17567 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
17568 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
17570 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
17571 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
17572 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
17573 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
17575 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
17576 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
17577 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
17578 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
17580 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
17581 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
17582 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
17583 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
17585 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
17587 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
17590 @node Other MIPS Built-in Functions
17591 @subsection Other MIPS Built-in Functions
17593 GCC provides other MIPS-specific built-in functions:
17596 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
17597 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
17598 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
17599 when this function is available.
17601 @item unsigned int __builtin_mips_get_fcsr (void)
17602 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
17603 Get and set the contents of the floating-point control and status register
17604 (FPU control register 31). These functions are only available in hard-float
17605 code but can be called in both MIPS16 and non-MIPS16 contexts.
17607 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
17608 register except the condition codes, which GCC assumes are preserved.
17611 @node MSP430 Built-in Functions
17612 @subsection MSP430 Built-in Functions
17614 GCC provides a couple of special builtin functions to aid in the
17615 writing of interrupt handlers in C.
17618 @item __bic_SR_register_on_exit (int @var{mask})
17619 This clears the indicated bits in the saved copy of the status register
17620 currently residing on the stack. This only works inside interrupt
17621 handlers and the changes to the status register will only take affect
17622 once the handler returns.
17624 @item __bis_SR_register_on_exit (int @var{mask})
17625 This sets the indicated bits in the saved copy of the status register
17626 currently residing on the stack. This only works inside interrupt
17627 handlers and the changes to the status register will only take affect
17628 once the handler returns.
17630 @item __delay_cycles (long long @var{cycles})
17631 This inserts an instruction sequence that takes exactly @var{cycles}
17632 cycles (between 0 and about 17E9) to complete. The inserted sequence
17633 may use jumps, loops, or no-ops, and does not interfere with any other
17634 instructions. Note that @var{cycles} must be a compile-time constant
17635 integer - that is, you must pass a number, not a variable that may be
17636 optimized to a constant later. The number of cycles delayed by this
17640 @node NDS32 Built-in Functions
17641 @subsection NDS32 Built-in Functions
17643 These built-in functions are available for the NDS32 target:
17645 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
17646 Insert an ISYNC instruction into the instruction stream where
17647 @var{addr} is an instruction address for serialization.
17650 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
17651 Insert an ISB instruction into the instruction stream.
17654 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
17655 Return the content of a system register which is mapped by @var{sr}.
17658 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
17659 Return the content of a user space register which is mapped by @var{usr}.
17662 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
17663 Move the @var{value} to a system register which is mapped by @var{sr}.
17666 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
17667 Move the @var{value} to a user space register which is mapped by @var{usr}.
17670 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
17671 Enable global interrupt.
17674 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
17675 Disable global interrupt.
17678 @node picoChip Built-in Functions
17679 @subsection picoChip Built-in Functions
17681 GCC provides an interface to selected machine instructions from the
17682 picoChip instruction set.
17685 @item int __builtin_sbc (int @var{value})
17686 Sign bit count. Return the number of consecutive bits in @var{value}
17687 that have the same value as the sign bit. The result is the number of
17688 leading sign bits minus one, giving the number of redundant sign bits in
17691 @item int __builtin_byteswap (int @var{value})
17692 Byte swap. Return the result of swapping the upper and lower bytes of
17695 @item int __builtin_brev (int @var{value})
17696 Bit reversal. Return the result of reversing the bits in
17697 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
17700 @item int __builtin_adds (int @var{x}, int @var{y})
17701 Saturating addition. Return the result of adding @var{x} and @var{y},
17702 storing the value 32767 if the result overflows.
17704 @item int __builtin_subs (int @var{x}, int @var{y})
17705 Saturating subtraction. Return the result of subtracting @var{y} from
17706 @var{x}, storing the value @minus{}32768 if the result overflows.
17708 @item void __builtin_halt (void)
17709 Halt. The processor stops execution. This built-in is useful for
17710 implementing assertions.
17714 @node Basic PowerPC Built-in Functions
17715 @subsection Basic PowerPC Built-in Functions
17718 * Basic PowerPC Built-in Functions Available on all Configurations::
17719 * Basic PowerPC Built-in Functions Available on ISA 2.05::
17720 * Basic PowerPC Built-in Functions Available on ISA 2.06::
17721 * Basic PowerPC Built-in Functions Available on ISA 2.07::
17722 * Basic PowerPC Built-in Functions Available on ISA 3.0::
17723 * Basic PowerPC Built-in Functions Available on ISA 3.1::
17726 This section describes PowerPC built-in functions that do not require
17727 the inclusion of any special header files to declare prototypes or
17728 provide macro definitions. The sections that follow describe
17729 additional PowerPC built-in functions.
17731 @node Basic PowerPC Built-in Functions Available on all Configurations
17732 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
17734 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
17735 This function is a @code{nop} on the PowerPC platform and is included solely
17736 to maintain API compatibility with the x86 builtins.
17739 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
17740 This function returns a value of @code{1} if the run-time CPU is of type
17741 @var{cpuname} and returns @code{0} otherwise
17743 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
17744 which exports the hardware capability bits. GCC defines the macro
17745 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
17746 built-in function is fully supported.
17748 If GCC was configured to use a GLIBC before 2.23, the built-in
17749 function @code{__builtin_cpu_is} always returns a 0 and the compiler
17752 The following CPU names can be detected:
17756 IBM POWER10 Server CPU.
17758 IBM POWER9 Server CPU.
17760 IBM POWER8 Server CPU.
17762 IBM POWER7 Server CPU.
17764 IBM POWER6 Server CPU (RAW mode).
17766 IBM POWER6 Server CPU (Architected mode).
17768 IBM POWER5+ Server CPU.
17770 IBM POWER5 Server CPU.
17772 IBM 970 Server CPU (ie, Apple G5).
17774 IBM POWER4 Server CPU.
17776 IBM A2 64-bit Embedded CPU
17778 IBM PowerPC 476FP 32-bit Embedded CPU.
17780 IBM PowerPC 464 32-bit Embedded CPU.
17782 PowerPC 440 32-bit Embedded CPU.
17784 PowerPC 405 32-bit Embedded CPU.
17786 IBM PowerPC Cell Broadband Engine Architecture CPU.
17789 Here is an example:
17791 #ifdef __BUILTIN_CPU_SUPPORTS__
17792 if (__builtin_cpu_is ("power8"))
17794 do_power8 (); // POWER8 specific implementation.
17799 do_generic (); // Generic implementation.
17804 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
17805 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
17806 feature @var{feature} and returns @code{0} otherwise.
17808 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
17809 newer which exports the hardware capability bits. GCC defines the
17810 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
17811 @code{__builtin_cpu_supports} built-in function is fully supported.
17813 If GCC was configured to use a GLIBC before 2.23, the built-in
17814 function @code{__builtin_cpu_supports} always returns a 0 and the
17815 compiler issues a warning.
17817 The following features can be
17822 4xx CPU has a Multiply Accumulator.
17824 CPU has a SIMD/Vector Unit.
17826 CPU supports ISA 2.05 (eg, POWER6)
17828 CPU supports ISA 2.06 (eg, POWER7)
17830 CPU supports ISA 2.07 (eg, POWER8)
17832 CPU supports ISA 3.0 (eg, POWER9)
17834 CPU supports ISA 3.1 (eg, POWER10)
17836 CPU supports the set of compatible performance monitoring events.
17838 CPU supports the Embedded ISA category.
17840 CPU has a CELL broadband engine.
17842 CPU supports the @code{darn} (deliver a random number) instruction.
17844 CPU has a decimal floating point unit.
17846 CPU supports the data stream control register.
17848 CPU supports event base branching.
17850 CPU has a SPE double precision floating point unit.
17852 CPU has a SPE single precision floating point unit.
17854 CPU has a floating point unit.
17856 CPU has hardware transaction memory instructions.
17858 Kernel aborts hardware transactions when a syscall is made.
17859 @item htm-no-suspend
17860 CPU supports hardware transaction memory but does not support the
17861 @code{tsuspend.} instruction.
17863 CPU supports icache snooping capabilities.
17865 CPU supports 128-bit IEEE binary floating point instructions.
17867 CPU supports the integer select instruction.
17869 CPU supports the matrix-multiply assist instructions.
17871 CPU has a memory management unit.
17873 CPU does not have a timebase (eg, 601 and 403gx).
17875 CPU supports the PA Semi 6T CORE ISA.
17877 CPU supports ISA 2.00 (eg, POWER4)
17879 CPU supports ISA 2.02 (eg, POWER5)
17881 CPU supports ISA 2.03 (eg, POWER5+)
17883 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
17885 CPU supports 32-bit mode execution.
17887 CPU supports the old POWER ISA (eg, 601)
17889 CPU supports 64-bit mode execution.
17891 CPU supports a little-endian mode that uses address swizzling.
17893 Kernel supports system call vectored.
17895 CPU support simultaneous multi-threading.
17897 CPU has a signal processing extension unit.
17899 CPU supports the target address register.
17901 CPU supports true little-endian mode.
17903 CPU has unified I/D cache.
17905 CPU supports the vector cryptography instructions.
17907 CPU supports the vector-scalar extension.
17910 Here is an example:
17912 #ifdef __BUILTIN_CPU_SUPPORTS__
17913 if (__builtin_cpu_supports ("fpu"))
17915 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
17920 dst = __fadd (src1, src2); // Software FP addition function.
17925 The following built-in functions are also available on all PowerPC
17928 uint64_t __builtin_ppc_get_timebase ();
17929 unsigned long __builtin_ppc_mftb ();
17930 double __builtin_unpack_ibm128 (__ibm128, int);
17931 __ibm128 __builtin_pack_ibm128 (double, double);
17932 double __builtin_mffs (void);
17933 void __builtin_mtfsf (const int, double);
17934 void __builtin_mtfsb0 (const int);
17935 void __builtin_mtfsb1 (const int);
17936 void __builtin_set_fpscr_rn (int);
17939 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
17940 functions generate instructions to read the Time Base Register. The
17941 @code{__builtin_ppc_get_timebase} function may generate multiple
17942 instructions and always returns the 64 bits of the Time Base Register.
17943 The @code{__builtin_ppc_mftb} function always generates one instruction and
17944 returns the Time Base Register value as an unsigned long, throwing away
17945 the most significant word on 32-bit environments. The @code{__builtin_mffs}
17946 return the value of the FPSCR register. Note, ISA 3.0 supports the
17947 @code{__builtin_mffsl()} which permits software to read the control and
17948 non-sticky status bits in the FSPCR without the higher latency associated with
17949 accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant
17950 8-bit integer field mask and a double precision floating point argument
17951 and generates the @code{mtfsf} (extended mnemonic) instruction to write new
17952 values to selected fields of the FPSCR. The
17953 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
17954 as an argument. The valid bit range is between 0 and 31. The builtins map to
17955 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
17956 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
17957 changing the specified bit to a zero or one respectively. The
17958 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
17959 point rounding mode bits. The argument is a 2-bit value. The argument can
17960 either be a @code{const int} or stored in a variable. The builtin uses
17962 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
17963 the current rounding mode bits out and OR's in the new value.
17965 @node Basic PowerPC Built-in Functions Available on ISA 2.05
17966 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
17968 The basic built-in functions described in this section are
17969 available on the PowerPC family of processors starting with ISA 2.05
17970 or later. Unless specific options are explicitly disabled on the
17971 command line, specifying option @option{-mcpu=power6} has the effect of
17972 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
17973 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
17974 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
17975 @option{-mrecip-precision} options. Specify the
17976 @option{-maltivec} option explicitly in
17977 combination with the above options if desired.
17979 The following functions require option @option{-mcmpb}.
17981 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
17982 unsigned int __builtin_cmpb (unsigned int, unsigned int);
17985 The @code{__builtin_cmpb} function
17986 performs a byte-wise compare on the contents of its two arguments,
17987 returning the result of the byte-wise comparison as the returned
17988 value. For each byte comparison, the corresponding byte of the return
17989 value holds 0xff if the input bytes are equal and 0 if the input bytes
17990 are not equal. If either of the arguments to this built-in function
17991 is wider than 32 bits, the function call expands into the form that
17992 expects @code{unsigned long long int} arguments
17993 which is only available on 64-bit targets.
17995 The following built-in functions are available
17996 when hardware decimal floating point
17997 (@option{-mhard-dfp}) is available:
17999 void __builtin_set_fpscr_drn(int);
18000 _Decimal64 __builtin_ddedpd (int, _Decimal64);
18001 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
18002 _Decimal64 __builtin_denbcd (int, _Decimal64);
18003 _Decimal128 __builtin_denbcdq (int, _Decimal128);
18004 _Decimal64 __builtin_diex (long long, _Decimal64);
18005 _Decimal128 _builtin_diexq (long long, _Decimal128);
18006 _Decimal64 __builtin_dscli (_Decimal64, int);
18007 _Decimal128 __builtin_dscliq (_Decimal128, int);
18008 _Decimal64 __builtin_dscri (_Decimal64, int);
18009 _Decimal128 __builtin_dscriq (_Decimal128, int);
18010 long long __builtin_dxex (_Decimal64);
18011 long long __builtin_dxexq (_Decimal128);
18012 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
18013 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
18015 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
18016 floating point rounding mode bits. The argument is a 3-bit value. The
18017 argument can either be a @code{const int} or the value can be stored in
18019 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
18020 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
18021 mode bits out and OR's in the new value.
18025 The following functions require @option{-mhard-float},
18026 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
18029 double __builtin_recipdiv (double, double);
18030 float __builtin_recipdivf (float, float);
18031 double __builtin_rsqrt (double);
18032 float __builtin_rsqrtf (float);
18035 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
18036 @code{__builtin_rsqrtf} functions generate multiple instructions to
18037 implement the reciprocal sqrt functionality using reciprocal sqrt
18038 estimate instructions.
18040 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
18041 functions generate multiple instructions to implement division using
18042 the reciprocal estimate instructions.
18044 The following functions require @option{-mhard-float} and
18045 @option{-mmultiple} options.
18047 The @code{__builtin_unpack_longdouble} function takes a
18048 @code{long double} argument and a compile time constant of 0 or 1. If
18049 the constant is 0, the first @code{double} within the
18050 @code{long double} is returned, otherwise the second @code{double}
18051 is returned. The @code{__builtin_unpack_longdouble} function is only
18052 available if @code{long double} uses the IBM extended double
18055 The @code{__builtin_pack_longdouble} function takes two @code{double}
18056 arguments and returns a @code{long double} value that combines the two
18057 arguments. The @code{__builtin_pack_longdouble} function is only
18058 available if @code{long double} uses the IBM extended double
18061 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
18062 argument and a compile time constant of 0 or 1. If the constant is 0,
18063 the first @code{double} within the @code{__ibm128} is returned,
18064 otherwise the second @code{double} is returned.
18066 The @code{__builtin_pack_ibm128} function takes two @code{double}
18067 arguments and returns a @code{__ibm128} value that combines the two
18070 Additional built-in functions are available for the 64-bit PowerPC
18071 family of processors, for efficient use of 128-bit floating point
18072 (@code{__float128}) values.
18074 @node Basic PowerPC Built-in Functions Available on ISA 2.06
18075 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
18077 The basic built-in functions described in this section are
18078 available on the PowerPC family of processors starting with ISA 2.05
18079 or later. Unless specific options are explicitly disabled on the
18080 command line, specifying option @option{-mcpu=power7} has the effect of
18081 enabling all the same options as for @option{-mcpu=power6} in
18082 addition to the @option{-maltivec}, @option{-mpopcntd}, and
18083 @option{-mvsx} options.
18085 The following basic built-in functions require @option{-mpopcntd}:
18087 unsigned int __builtin_addg6s (unsigned int, unsigned int);
18088 long long __builtin_bpermd (long long, long long);
18089 unsigned int __builtin_cbcdtd (unsigned int);
18090 unsigned int __builtin_cdtbcd (unsigned int);
18091 long long __builtin_divde (long long, long long);
18092 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
18093 int __builtin_divwe (int, int);
18094 unsigned int __builtin_divweu (unsigned int, unsigned int);
18095 vector __int128 __builtin_pack_vector_int128 (long long, long long);
18096 void __builtin_rs6000_speculation_barrier (void);
18097 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
18100 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
18101 require a 64-bit environment.
18103 The following basic built-in functions, which are also supported on
18104 x86 targets, require @option{-mfloat128}.
18106 __float128 __builtin_fabsq (__float128);
18107 __float128 __builtin_copysignq (__float128, __float128);
18108 __float128 __builtin_infq (void);
18109 __float128 __builtin_huge_valq (void);
18110 __float128 __builtin_nanq (void);
18111 __float128 __builtin_nansq (void);
18113 __float128 __builtin_sqrtf128 (__float128);
18114 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
18117 @node Basic PowerPC Built-in Functions Available on ISA 2.07
18118 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
18120 The basic built-in functions described in this section are
18121 available on the PowerPC family of processors starting with ISA 2.07
18122 or later. Unless specific options are explicitly disabled on the
18123 command line, specifying option @option{-mcpu=power8} has the effect of
18124 enabling all the same options as for @option{-mcpu=power7} in
18125 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
18126 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
18127 @option{-mquad-memory-atomic} options.
18129 This section intentionally empty.
18131 @node Basic PowerPC Built-in Functions Available on ISA 3.0
18132 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
18134 The basic built-in functions described in this section are
18135 available on the PowerPC family of processors starting with ISA 3.0
18136 or later. Unless specific options are explicitly disabled on the
18137 command line, specifying option @option{-mcpu=power9} has the effect of
18138 enabling all the same options as for @option{-mcpu=power8} in
18139 addition to the @option{-misel} option.
18141 The following built-in functions are available on Linux 64-bit systems
18142 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
18145 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
18146 Perform a 128-bit IEEE floating point add using round to odd as the
18148 @findex __builtin_addf128_round_to_odd
18150 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
18151 Perform a 128-bit IEEE floating point subtract using round to odd as
18153 @findex __builtin_subf128_round_to_odd
18155 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
18156 Perform a 128-bit IEEE floating point multiply using round to odd as
18158 @findex __builtin_mulf128_round_to_odd
18160 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
18161 Perform a 128-bit IEEE floating point divide using round to odd as
18163 @findex __builtin_divf128_round_to_odd
18165 @item __float128 __builtin_sqrtf128_round_to_odd (__float128)
18166 Perform a 128-bit IEEE floating point square root using round to odd
18167 as the rounding mode.
18168 @findex __builtin_sqrtf128_round_to_odd
18170 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
18171 Perform a 128-bit IEEE floating point fused multiply and add operation
18172 using round to odd as the rounding mode.
18173 @findex __builtin_fmaf128_round_to_odd
18175 @item double __builtin_truncf128_round_to_odd (__float128)
18176 Convert a 128-bit IEEE floating point value to @code{double} using
18177 round to odd as the rounding mode.
18178 @findex __builtin_truncf128_round_to_odd
18181 The following additional built-in functions are also available for the
18182 PowerPC family of processors, starting with ISA 3.0 or later:
18184 long long __builtin_darn (void);
18185 long long __builtin_darn_raw (void);
18186 int __builtin_darn_32 (void);
18189 The @code{__builtin_darn} and @code{__builtin_darn_raw}
18190 functions require a
18191 64-bit environment supporting ISA 3.0 or later.
18192 The @code{__builtin_darn} function provides a 64-bit conditioned
18193 random number. The @code{__builtin_darn_raw} function provides a
18194 64-bit raw random number. The @code{__builtin_darn_32} function
18195 provides a 32-bit conditioned random number.
18197 The following additional built-in functions are also available for the
18198 PowerPC family of processors, starting with ISA 3.0 or later:
18201 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
18202 int __builtin_byte_in_range (unsigned char u, unsigned int range);
18203 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
18205 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
18206 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
18207 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
18208 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
18210 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
18211 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
18212 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
18213 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
18215 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
18216 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
18217 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
18218 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
18220 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
18221 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
18222 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
18223 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
18225 double __builtin_mffsl(void);
18228 The @code{__builtin_byte_in_set} function requires a
18229 64-bit environment supporting ISA 3.0 or later. This function returns
18230 a non-zero value if and only if its @code{u} argument exactly equals one of
18231 the eight bytes contained within its 64-bit @code{set} argument.
18233 The @code{__builtin_byte_in_range} and
18234 @code{__builtin_byte_in_either_range} require an environment
18235 supporting ISA 3.0 or later. For these two functions, the
18236 @code{range} argument is encoded as 4 bytes, organized as
18237 @code{hi_1:lo_1:hi_2:lo_2}.
18238 The @code{__builtin_byte_in_range} function returns a
18239 non-zero value if and only if its @code{u} argument is within the
18240 range bounded between @code{lo_2} and @code{hi_2} inclusive.
18241 The @code{__builtin_byte_in_either_range} function returns non-zero if
18242 and only if its @code{u} argument is within either the range bounded
18243 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
18244 between @code{lo_2} and @code{hi_2} inclusive.
18246 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
18247 if and only if the number of signficant digits of its @code{value} argument
18248 is less than its @code{comparison} argument. The
18249 @code{__builtin_dfp_dtstsfi_lt_dd} and
18250 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
18251 require that the type of the @code{value} argument be
18252 @code{__Decimal64} and @code{__Decimal128} respectively.
18254 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
18255 if and only if the number of signficant digits of its @code{value} argument
18256 is greater than its @code{comparison} argument. The
18257 @code{__builtin_dfp_dtstsfi_gt_dd} and
18258 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
18259 require that the type of the @code{value} argument be
18260 @code{__Decimal64} and @code{__Decimal128} respectively.
18262 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
18263 if and only if the number of signficant digits of its @code{value} argument
18264 equals its @code{comparison} argument. The
18265 @code{__builtin_dfp_dtstsfi_eq_dd} and
18266 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
18267 require that the type of the @code{value} argument be
18268 @code{__Decimal64} and @code{__Decimal128} respectively.
18270 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
18271 if and only if its @code{value} argument has an undefined number of
18272 significant digits, such as when @code{value} is an encoding of @code{NaN}.
18273 The @code{__builtin_dfp_dtstsfi_ov_dd} and
18274 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
18275 require that the type of the @code{value} argument be
18276 @code{__Decimal64} and @code{__Decimal128} respectively.
18278 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
18279 the FPSCR. The instruction is a lower latency version of the @code{mffs}
18280 instruction. If the @code{mffsl} instruction is not available, then the
18281 builtin uses the older @code{mffs} instruction to read the FPSCR.
18283 @node Basic PowerPC Built-in Functions Available on ISA 3.1
18284 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1
18286 The basic built-in functions described in this section are
18287 available on the PowerPC family of processors starting with ISA 3.1.
18288 Unless specific options are explicitly disabled on the
18289 command line, specifying option @option{-mcpu=power10} has the effect of
18290 enabling all the same options as for @option{-mcpu=power9}.
18292 The following built-in functions are available on Linux 64-bit systems
18293 that use a future architecture instruction set (@option{-mcpu=power10}):
18296 @exdent unsigned long long
18297 @exdent __builtin_cfuged (unsigned long long, unsigned long long)
18299 Perform a 64-bit centrifuge operation, as if implemented by the
18300 @code{cfuged} instruction.
18301 @findex __builtin_cfuged
18304 @exdent unsigned long long
18305 @exdent __builtin_cntlzdm (unsigned long long, unsigned long long)
18307 Perform a 64-bit count leading zeros operation under mask, as if
18308 implemented by the @code{cntlzdm} instruction.
18309 @findex __builtin_cntlzdm
18312 @exdent unsigned long long
18313 @exdent __builtin_cnttzdm (unsigned long long, unsigned long long)
18315 Perform a 64-bit count trailing zeros operation under mask, as if
18316 implemented by the @code{cnttzdm} instruction.
18317 @findex __builtin_cnttzdm
18320 @exdent unsigned long long
18321 @exdent __builtin_pdepd (unsigned long long, unsigned long long)
18323 Perform a 64-bit parallel bits deposit operation, as if implemented by the
18324 @code{pdepd} instruction.
18325 @findex __builtin_pdepd
18328 @exdent unsigned long long
18329 @exdent __builtin_pextd (unsigned long long, unsigned long long)
18331 Perform a 64-bit parallel bits extract operation, as if implemented by the
18332 @code{pextd} instruction.
18333 @findex __builtin_pextd
18336 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed char *)
18338 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed short *)
18340 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed int *)
18342 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed long long *)
18344 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned char *)
18346 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned short *)
18348 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned int *)
18350 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned long long *)
18353 Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1
18354 @code{lxvrbx}, @code{lxvrhx}, @code{lxvrwx}, and @code{lxvrdx} instructions.
18355 @findex vsx_xl_sext
18356 @findex vsx_xl_zext
18359 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed char *)
18361 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed short *)
18363 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed int *)
18365 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed long long *)
18367 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *)
18369 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *)
18371 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *)
18373 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *)
18376 Truncate and store the rightmost element of a vector, as if implemented by the
18377 ISA 3.1 @code{stxvrbx}, @code{stxvrhx}, @code{stxvrwx}, and @code{stxvrdx}
18379 @findex vec_xst_trunc
18381 @node PowerPC AltiVec/VSX Built-in Functions
18382 @subsection PowerPC AltiVec/VSX Built-in Functions
18384 GCC provides an interface for the PowerPC family of processors to access
18385 the AltiVec operations described in Motorola's AltiVec Programming
18386 Interface Manual. The interface is made available by including
18387 @code{<altivec.h>} and using @option{-maltivec} and
18388 @option{-mabi=altivec}. The interface supports the following vector
18392 vector unsigned char
18396 vector unsigned short
18397 vector signed short
18401 vector unsigned int
18407 GCC's implementation of the high-level language interface available from
18408 C and C++ code differs from Motorola's documentation in several ways.
18413 A vector constant is a list of constant expressions within curly braces.
18416 A vector initializer requires no cast if the vector constant is of the
18417 same type as the variable it is initializing.
18420 If @code{signed} or @code{unsigned} is omitted, the signedness of the
18421 vector type is the default signedness of the base type. The default
18422 varies depending on the operating system, so a portable program should
18423 always specify the signedness.
18426 Compiling with @option{-maltivec} adds keywords @code{__vector},
18427 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
18428 @code{bool}. When compiling ISO C, the context-sensitive substitution
18429 of the keywords @code{vector}, @code{pixel} and @code{bool} is
18430 disabled. To use them, you must include @code{<altivec.h>} instead.
18433 GCC allows using a @code{typedef} name as the type specifier for a
18434 vector type, but only under the following circumstances:
18439 When using @code{__vector} instead of @code{vector}; for example,
18442 typedef signed short int16;
18443 __vector int16 data;
18447 When using @code{vector} in keyword-and-predefine mode; for example,
18450 typedef signed short int16;
18454 Note that keyword-and-predefine mode is enabled by disabling GNU
18455 extensions (e.g., by using @code{-std=c11}) and including
18456 @code{<altivec.h>}.
18460 For C, overloaded functions are implemented with macros so the following
18464 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
18468 Since @code{vec_add} is a macro, the vector constant in the example
18469 is treated as four separate arguments. Wrap the entire argument in
18470 parentheses for this to work.
18473 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
18474 Internally, GCC uses built-in functions to achieve the functionality in
18475 the aforementioned header file, but they are not supported and are
18476 subject to change without notice.
18478 GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR),
18479 which may be found at
18480 @uref{https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference}.
18481 Chapter 4 of this document fully documents the vector API interfaces
18483 provided by compliant compilers. Programmers should preferentially use
18484 the interfaces described therein. However, historically GCC has provided
18485 additional interfaces for access to vector instructions. These are
18486 briefly described below. Where the PVIPR provides a portable interface,
18487 other functions in GCC that provide the same capabilities should be
18488 considered deprecated.
18490 The PVIPR documents the following overloaded functions:
18492 @multitable @columnfractions 0.33 0.33 0.33
18494 @item @code{vec_abs}
18495 @tab @code{vec_absd}
18496 @tab @code{vec_abss}
18497 @item @code{vec_add}
18498 @tab @code{vec_addc}
18499 @tab @code{vec_adde}
18500 @item @code{vec_addec}
18501 @tab @code{vec_adds}
18502 @tab @code{vec_all_eq}
18503 @item @code{vec_all_ge}
18504 @tab @code{vec_all_gt}
18505 @tab @code{vec_all_in}
18506 @item @code{vec_all_le}
18507 @tab @code{vec_all_lt}
18508 @tab @code{vec_all_nan}
18509 @item @code{vec_all_ne}
18510 @tab @code{vec_all_nge}
18511 @tab @code{vec_all_ngt}
18512 @item @code{vec_all_nle}
18513 @tab @code{vec_all_nlt}
18514 @tab @code{vec_all_numeric}
18515 @item @code{vec_and}
18516 @tab @code{vec_andc}
18517 @tab @code{vec_any_eq}
18518 @item @code{vec_any_ge}
18519 @tab @code{vec_any_gt}
18520 @tab @code{vec_any_le}
18521 @item @code{vec_any_lt}
18522 @tab @code{vec_any_nan}
18523 @tab @code{vec_any_ne}
18524 @item @code{vec_any_nge}
18525 @tab @code{vec_any_ngt}
18526 @tab @code{vec_any_nle}
18527 @item @code{vec_any_nlt}
18528 @tab @code{vec_any_numeric}
18529 @tab @code{vec_any_out}
18530 @item @code{vec_avg}
18531 @tab @code{vec_bperm}
18532 @tab @code{vec_ceil}
18533 @item @code{vec_cipher_be}
18534 @tab @code{vec_cipherlast_be}
18535 @tab @code{vec_cmpb}
18536 @item @code{vec_cmpeq}
18537 @tab @code{vec_cmpge}
18538 @tab @code{vec_cmpgt}
18539 @item @code{vec_cmple}
18540 @tab @code{vec_cmplt}
18541 @tab @code{vec_cmpne}
18542 @item @code{vec_cmpnez}
18543 @tab @code{vec_cntlz}
18544 @tab @code{vec_cntlz_lsbb}
18545 @item @code{vec_cnttz}
18546 @tab @code{vec_cnttz_lsbb}
18547 @tab @code{vec_cpsgn}
18548 @item @code{vec_ctf}
18549 @tab @code{vec_cts}
18550 @tab @code{vec_ctu}
18551 @item @code{vec_div}
18552 @tab @code{vec_double}
18553 @tab @code{vec_doublee}
18554 @item @code{vec_doubleh}
18555 @tab @code{vec_doublel}
18556 @tab @code{vec_doubleo}
18557 @item @code{vec_eqv}
18558 @tab @code{vec_expte}
18559 @tab @code{vec_extract}
18560 @item @code{vec_extract_exp}
18561 @tab @code{vec_extract_fp32_from_shorth}
18562 @tab @code{vec_extract_fp32_from_shortl}
18563 @item @code{vec_extract_sig}
18564 @tab @code{vec_extract_4b}
18565 @tab @code{vec_first_match_index}
18566 @item @code{vec_first_match_or_eos_index}
18567 @tab @code{vec_first_mismatch_index}
18568 @tab @code{vec_first_mismatch_or_eos_index}
18569 @item @code{vec_float}
18570 @tab @code{vec_float2}
18571 @tab @code{vec_floate}
18572 @item @code{vec_floato}
18573 @tab @code{vec_floor}
18575 @item @code{vec_insert}
18576 @tab @code{vec_insert_exp}
18577 @tab @code{vec_insert4b}
18578 @item @code{vec_ld}
18579 @tab @code{vec_lde}
18580 @tab @code{vec_ldl}
18581 @item @code{vec_loge}
18582 @tab @code{vec_madd}
18583 @tab @code{vec_madds}
18584 @item @code{vec_max}
18585 @tab @code{vec_mergee}
18586 @tab @code{vec_mergeh}
18587 @item @code{vec_mergel}
18588 @tab @code{vec_mergeo}
18589 @tab @code{vec_mfvscr}
18590 @item @code{vec_min}
18591 @tab @code{vec_mradds}
18592 @tab @code{vec_msub}
18593 @item @code{vec_msum}
18594 @tab @code{vec_msums}
18595 @tab @code{vec_mtvscr}
18596 @item @code{vec_mul}
18597 @tab @code{vec_mule}
18598 @tab @code{vec_mulo}
18599 @item @code{vec_nabs}
18600 @tab @code{vec_nand}
18601 @tab @code{vec_ncipher_be}
18602 @item @code{vec_ncipherlast_be}
18603 @tab @code{vec_nearbyint}
18604 @tab @code{vec_neg}
18605 @item @code{vec_nmadd}
18606 @tab @code{vec_nmsub}
18607 @tab @code{vec_nor}
18608 @item @code{vec_or}
18609 @tab @code{vec_orc}
18610 @tab @code{vec_pack}
18611 @item @code{vec_pack_to_short_fp32}
18612 @tab @code{vec_packpx}
18613 @tab @code{vec_packs}
18614 @item @code{vec_packsu}
18615 @tab @code{vec_parity_lsbb}
18616 @tab @code{vec_perm}
18617 @item @code{vec_permxor}
18618 @tab @code{vec_pmsum_be}
18619 @tab @code{vec_popcnt}
18620 @item @code{vec_re}
18621 @tab @code{vec_recipdiv}
18622 @tab @code{vec_revb}
18623 @item @code{vec_reve}
18624 @tab @code{vec_rint}
18626 @item @code{vec_rlmi}
18627 @tab @code{vec_rlnm}
18628 @tab @code{vec_round}
18629 @item @code{vec_rsqrt}
18630 @tab @code{vec_rsqrte}
18631 @tab @code{vec_sbox_be}
18632 @item @code{vec_sel}
18633 @tab @code{vec_shasigma_be}
18634 @tab @code{vec_signed}
18635 @item @code{vec_signed2}
18636 @tab @code{vec_signede}
18637 @tab @code{vec_signedo}
18638 @item @code{vec_sl}
18639 @tab @code{vec_sld}
18640 @tab @code{vec_sldw}
18641 @item @code{vec_sll}
18642 @tab @code{vec_slo}
18643 @tab @code{vec_slv}
18644 @item @code{vec_splat}
18645 @tab @code{vec_splat_s8}
18646 @tab @code{vec_splat_s16}
18647 @item @code{vec_splat_s32}
18648 @tab @code{vec_splat_u8}
18649 @tab @code{vec_splat_u16}
18650 @item @code{vec_splat_u32}
18651 @tab @code{vec_splats}
18652 @tab @code{vec_sqrt}
18653 @item @code{vec_sr}
18654 @tab @code{vec_sra}
18655 @tab @code{vec_srl}
18656 @item @code{vec_sro}
18657 @tab @code{vec_srv}
18659 @item @code{vec_ste}
18660 @tab @code{vec_stl}
18661 @tab @code{vec_sub}
18662 @item @code{vec_subc}
18663 @tab @code{vec_sube}
18664 @tab @code{vec_subec}
18665 @item @code{vec_subs}
18666 @tab @code{vec_sum2s}
18667 @tab @code{vec_sum4s}
18668 @item @code{vec_sums}
18669 @tab @code{vec_test_data_class}
18670 @tab @code{vec_trunc}
18671 @item @code{vec_unpackh}
18672 @tab @code{vec_unpackl}
18673 @tab @code{vec_unsigned}
18674 @item @code{vec_unsigned2}
18675 @tab @code{vec_unsignede}
18676 @tab @code{vec_unsignedo}
18677 @item @code{vec_xl}
18678 @tab @code{vec_xl_be}
18679 @tab @code{vec_xl_len}
18680 @item @code{vec_xl_len_r}
18681 @tab @code{vec_xor}
18682 @tab @code{vec_xst}
18683 @item @code{vec_xst_be}
18684 @tab @code{vec_xst_len}
18685 @tab @code{vec_xst_len_r}
18690 * PowerPC AltiVec Built-in Functions on ISA 2.05::
18691 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
18692 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
18693 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
18694 * PowerPC AltiVec Built-in Functions Available on ISA 3.1::
18697 @node PowerPC AltiVec Built-in Functions on ISA 2.05
18698 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
18700 The following interfaces are supported for the generic and specific
18701 AltiVec operations and the AltiVec predicates. In cases where there
18702 is a direct mapping between generic and specific operations, only the
18703 generic names are shown here, although the specific operations can also
18706 Arguments that are documented as @code{const int} require literal
18707 integral values within the range required for that operation.
18709 Only functions excluded from the PVIPR are listed here.
18712 void vec_dss (const int);
18714 void vec_dssall (void);
18716 void vec_dst (const vector unsigned char *, int, const int);
18717 void vec_dst (const vector signed char *, int, const int);
18718 void vec_dst (const vector bool char *, int, const int);
18719 void vec_dst (const vector unsigned short *, int, const int);
18720 void vec_dst (const vector signed short *, int, const int);
18721 void vec_dst (const vector bool short *, int, const int);
18722 void vec_dst (const vector pixel *, int, const int);
18723 void vec_dst (const vector unsigned int *, int, const int);
18724 void vec_dst (const vector signed int *, int, const int);
18725 void vec_dst (const vector bool int *, int, const int);
18726 void vec_dst (const vector float *, int, const int);
18727 void vec_dst (const unsigned char *, int, const int);
18728 void vec_dst (const signed char *, int, const int);
18729 void vec_dst (const unsigned short *, int, const int);
18730 void vec_dst (const short *, int, const int);
18731 void vec_dst (const unsigned int *, int, const int);
18732 void vec_dst (const int *, int, const int);
18733 void vec_dst (const float *, int, const int);
18735 void vec_dstst (const vector unsigned char *, int, const int);
18736 void vec_dstst (const vector signed char *, int, const int);
18737 void vec_dstst (const vector bool char *, int, const int);
18738 void vec_dstst (const vector unsigned short *, int, const int);
18739 void vec_dstst (const vector signed short *, int, const int);
18740 void vec_dstst (const vector bool short *, int, const int);
18741 void vec_dstst (const vector pixel *, int, const int);
18742 void vec_dstst (const vector unsigned int *, int, const int);
18743 void vec_dstst (const vector signed int *, int, const int);
18744 void vec_dstst (const vector bool int *, int, const int);
18745 void vec_dstst (const vector float *, int, const int);
18746 void vec_dstst (const unsigned char *, int, const int);
18747 void vec_dstst (const signed char *, int, const int);
18748 void vec_dstst (const unsigned short *, int, const int);
18749 void vec_dstst (const short *, int, const int);
18750 void vec_dstst (const unsigned int *, int, const int);
18751 void vec_dstst (const int *, int, const int);
18752 void vec_dstst (const unsigned long *, int, const int);
18753 void vec_dstst (const long *, int, const int);
18754 void vec_dstst (const float *, int, const int);
18756 void vec_dststt (const vector unsigned char *, int, const int);
18757 void vec_dststt (const vector signed char *, int, const int);
18758 void vec_dststt (const vector bool char *, int, const int);
18759 void vec_dststt (const vector unsigned short *, int, const int);
18760 void vec_dststt (const vector signed short *, int, const int);
18761 void vec_dststt (const vector bool short *, int, const int);
18762 void vec_dststt (const vector pixel *, int, const int);
18763 void vec_dststt (const vector unsigned int *, int, const int);
18764 void vec_dststt (const vector signed int *, int, const int);
18765 void vec_dststt (const vector bool int *, int, const int);
18766 void vec_dststt (const vector float *, int, const int);
18767 void vec_dststt (const unsigned char *, int, const int);
18768 void vec_dststt (const signed char *, int, const int);
18769 void vec_dststt (const unsigned short *, int, const int);
18770 void vec_dststt (const short *, int, const int);
18771 void vec_dststt (const unsigned int *, int, const int);
18772 void vec_dststt (const int *, int, const int);
18773 void vec_dststt (const float *, int, const int);
18775 void vec_dstt (const vector unsigned char *, int, const int);
18776 void vec_dstt (const vector signed char *, int, const int);
18777 void vec_dstt (const vector bool char *, int, const int);
18778 void vec_dstt (const vector unsigned short *, int, const int);
18779 void vec_dstt (const vector signed short *, int, const int);
18780 void vec_dstt (const vector bool short *, int, const int);
18781 void vec_dstt (const vector pixel *, int, const int);
18782 void vec_dstt (const vector unsigned int *, int, const int);
18783 void vec_dstt (const vector signed int *, int, const int);
18784 void vec_dstt (const vector bool int *, int, const int);
18785 void vec_dstt (const vector float *, int, const int);
18786 void vec_dstt (const unsigned char *, int, const int);
18787 void vec_dstt (const signed char *, int, const int);
18788 void vec_dstt (const unsigned short *, int, const int);
18789 void vec_dstt (const short *, int, const int);
18790 void vec_dstt (const unsigned int *, int, const int);
18791 void vec_dstt (const int *, int, const int);
18792 void vec_dstt (const float *, int, const int);
18794 vector signed char vec_lvebx (int, char *);
18795 vector unsigned char vec_lvebx (int, unsigned char *);
18797 vector signed short vec_lvehx (int, short *);
18798 vector unsigned short vec_lvehx (int, unsigned short *);
18800 vector float vec_lvewx (int, float *);
18801 vector signed int vec_lvewx (int, int *);
18802 vector unsigned int vec_lvewx (int, unsigned int *);
18804 vector unsigned char vec_lvsl (int, const unsigned char *);
18805 vector unsigned char vec_lvsl (int, const signed char *);
18806 vector unsigned char vec_lvsl (int, const unsigned short *);
18807 vector unsigned char vec_lvsl (int, const short *);
18808 vector unsigned char vec_lvsl (int, const unsigned int *);
18809 vector unsigned char vec_lvsl (int, const int *);
18810 vector unsigned char vec_lvsl (int, const float *);
18812 vector unsigned char vec_lvsr (int, const unsigned char *);
18813 vector unsigned char vec_lvsr (int, const signed char *);
18814 vector unsigned char vec_lvsr (int, const unsigned short *);
18815 vector unsigned char vec_lvsr (int, const short *);
18816 vector unsigned char vec_lvsr (int, const unsigned int *);
18817 vector unsigned char vec_lvsr (int, const int *);
18818 vector unsigned char vec_lvsr (int, const float *);
18820 void vec_stvebx (vector signed char, int, signed char *);
18821 void vec_stvebx (vector unsigned char, int, unsigned char *);
18822 void vec_stvebx (vector bool char, int, signed char *);
18823 void vec_stvebx (vector bool char, int, unsigned char *);
18825 void vec_stvehx (vector signed short, int, short *);
18826 void vec_stvehx (vector unsigned short, int, unsigned short *);
18827 void vec_stvehx (vector bool short, int, short *);
18828 void vec_stvehx (vector bool short, int, unsigned short *);
18830 void vec_stvewx (vector float, int, float *);
18831 void vec_stvewx (vector signed int, int, int *);
18832 void vec_stvewx (vector unsigned int, int, unsigned int *);
18833 void vec_stvewx (vector bool int, int, int *);
18834 void vec_stvewx (vector bool int, int, unsigned int *);
18836 vector float vec_vaddfp (vector float, vector float);
18838 vector signed char vec_vaddsbs (vector bool char, vector signed char);
18839 vector signed char vec_vaddsbs (vector signed char, vector bool char);
18840 vector signed char vec_vaddsbs (vector signed char, vector signed char);
18842 vector signed short vec_vaddshs (vector bool short, vector signed short);
18843 vector signed short vec_vaddshs (vector signed short, vector bool short);
18844 vector signed short vec_vaddshs (vector signed short, vector signed short);
18846 vector signed int vec_vaddsws (vector bool int, vector signed int);
18847 vector signed int vec_vaddsws (vector signed int, vector bool int);
18848 vector signed int vec_vaddsws (vector signed int, vector signed int);
18850 vector signed char vec_vaddubm (vector bool char, vector signed char);
18851 vector signed char vec_vaddubm (vector signed char, vector bool char);
18852 vector signed char vec_vaddubm (vector signed char, vector signed char);
18853 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
18854 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
18855 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
18857 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
18858 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
18859 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
18861 vector signed short vec_vadduhm (vector bool short, vector signed short);
18862 vector signed short vec_vadduhm (vector signed short, vector bool short);
18863 vector signed short vec_vadduhm (vector signed short, vector signed short);
18864 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
18865 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
18866 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
18868 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
18869 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
18870 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
18872 vector signed int vec_vadduwm (vector bool int, vector signed int);
18873 vector signed int vec_vadduwm (vector signed int, vector bool int);
18874 vector signed int vec_vadduwm (vector signed int, vector signed int);
18875 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
18876 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
18877 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
18879 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
18880 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
18881 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
18883 vector signed char vec_vavgsb (vector signed char, vector signed char);
18885 vector signed short vec_vavgsh (vector signed short, vector signed short);
18887 vector signed int vec_vavgsw (vector signed int, vector signed int);
18889 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
18891 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
18893 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
18895 vector float vec_vcfsx (vector signed int, const int);
18897 vector float vec_vcfux (vector unsigned int, const int);
18899 vector bool int vec_vcmpeqfp (vector float, vector float);
18901 vector bool char vec_vcmpequb (vector signed char, vector signed char);
18902 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
18904 vector bool short vec_vcmpequh (vector signed short, vector signed short);
18905 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
18907 vector bool int vec_vcmpequw (vector signed int, vector signed int);
18908 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
18910 vector bool int vec_vcmpgtfp (vector float, vector float);
18912 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
18914 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
18916 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
18918 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
18920 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
18922 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
18924 vector float vec_vmaxfp (vector float, vector float);
18926 vector signed char vec_vmaxsb (vector bool char, vector signed char);
18927 vector signed char vec_vmaxsb (vector signed char, vector bool char);
18928 vector signed char vec_vmaxsb (vector signed char, vector signed char);
18930 vector signed short vec_vmaxsh (vector bool short, vector signed short);
18931 vector signed short vec_vmaxsh (vector signed short, vector bool short);
18932 vector signed short vec_vmaxsh (vector signed short, vector signed short);
18934 vector signed int vec_vmaxsw (vector bool int, vector signed int);
18935 vector signed int vec_vmaxsw (vector signed int, vector bool int);
18936 vector signed int vec_vmaxsw (vector signed int, vector signed int);
18938 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
18939 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
18940 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
18942 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
18943 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
18944 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
18946 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
18947 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
18948 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
18950 vector float vec_vminfp (vector float, vector float);
18952 vector signed char vec_vminsb (vector bool char, vector signed char);
18953 vector signed char vec_vminsb (vector signed char, vector bool char);
18954 vector signed char vec_vminsb (vector signed char, vector signed char);
18956 vector signed short vec_vminsh (vector bool short, vector signed short);
18957 vector signed short vec_vminsh (vector signed short, vector bool short);
18958 vector signed short vec_vminsh (vector signed short, vector signed short);
18960 vector signed int vec_vminsw (vector bool int, vector signed int);
18961 vector signed int vec_vminsw (vector signed int, vector bool int);
18962 vector signed int vec_vminsw (vector signed int, vector signed int);
18964 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
18965 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
18966 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
18968 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
18969 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
18970 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
18972 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
18973 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
18974 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
18976 vector bool char vec_vmrghb (vector bool char, vector bool char);
18977 vector signed char vec_vmrghb (vector signed char, vector signed char);
18978 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
18980 vector bool short vec_vmrghh (vector bool short, vector bool short);
18981 vector signed short vec_vmrghh (vector signed short, vector signed short);
18982 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
18983 vector pixel vec_vmrghh (vector pixel, vector pixel);
18985 vector float vec_vmrghw (vector float, vector float);
18986 vector bool int vec_vmrghw (vector bool int, vector bool int);
18987 vector signed int vec_vmrghw (vector signed int, vector signed int);
18988 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
18990 vector bool char vec_vmrglb (vector bool char, vector bool char);
18991 vector signed char vec_vmrglb (vector signed char, vector signed char);
18992 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
18994 vector bool short vec_vmrglh (vector bool short, vector bool short);
18995 vector signed short vec_vmrglh (vector signed short, vector signed short);
18996 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
18997 vector pixel vec_vmrglh (vector pixel, vector pixel);
18999 vector float vec_vmrglw (vector float, vector float);
19000 vector signed int vec_vmrglw (vector signed int, vector signed int);
19001 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
19002 vector bool int vec_vmrglw (vector bool int, vector bool int);
19004 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
19005 vector signed int);
19007 vector signed int vec_vmsumshm (vector signed short, vector signed short,
19008 vector signed int);
19010 vector signed int vec_vmsumshs (vector signed short, vector signed short,
19011 vector signed int);
19013 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
19014 vector unsigned int);
19016 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
19017 vector unsigned int);
19019 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
19020 vector unsigned int);
19022 vector signed short vec_vmulesb (vector signed char, vector signed char);
19024 vector signed int vec_vmulesh (vector signed short, vector signed short);
19026 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
19028 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
19030 vector signed short vec_vmulosb (vector signed char, vector signed char);
19032 vector signed int vec_vmulosh (vector signed short, vector signed short);
19034 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
19036 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
19038 vector signed char vec_vpkshss (vector signed short, vector signed short);
19040 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
19042 vector signed short vec_vpkswss (vector signed int, vector signed int);
19044 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
19046 vector bool char vec_vpkuhum (vector bool short, vector bool short);
19047 vector signed char vec_vpkuhum (vector signed short, vector signed short);
19048 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
19050 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
19052 vector bool short vec_vpkuwum (vector bool int, vector bool int);
19053 vector signed short vec_vpkuwum (vector signed int, vector signed int);
19054 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
19056 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
19058 vector signed char vec_vrlb (vector signed char, vector unsigned char);
19059 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
19061 vector signed short vec_vrlh (vector signed short, vector unsigned short);
19062 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
19064 vector signed int vec_vrlw (vector signed int, vector unsigned int);
19065 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
19067 vector signed char vec_vslb (vector signed char, vector unsigned char);
19068 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
19070 vector signed short vec_vslh (vector signed short, vector unsigned short);
19071 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
19073 vector signed int vec_vslw (vector signed int, vector unsigned int);
19074 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
19076 vector signed char vec_vspltb (vector signed char, const int);
19077 vector unsigned char vec_vspltb (vector unsigned char, const int);
19078 vector bool char vec_vspltb (vector bool char, const int);
19080 vector bool short vec_vsplth (vector bool short, const int);
19081 vector signed short vec_vsplth (vector signed short, const int);
19082 vector unsigned short vec_vsplth (vector unsigned short, const int);
19083 vector pixel vec_vsplth (vector pixel, const int);
19085 vector float vec_vspltw (vector float, const int);
19086 vector signed int vec_vspltw (vector signed int, const int);
19087 vector unsigned int vec_vspltw (vector unsigned int, const int);
19088 vector bool int vec_vspltw (vector bool int, const int);
19090 vector signed char vec_vsrab (vector signed char, vector unsigned char);
19091 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
19093 vector signed short vec_vsrah (vector signed short, vector unsigned short);
19094 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
19096 vector signed int vec_vsraw (vector signed int, vector unsigned int);
19097 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
19099 vector signed char vec_vsrb (vector signed char, vector unsigned char);
19100 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
19102 vector signed short vec_vsrh (vector signed short, vector unsigned short);
19103 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
19105 vector signed int vec_vsrw (vector signed int, vector unsigned int);
19106 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
19108 vector float vec_vsubfp (vector float, vector float);
19110 vector signed char vec_vsubsbs (vector bool char, vector signed char);
19111 vector signed char vec_vsubsbs (vector signed char, vector bool char);
19112 vector signed char vec_vsubsbs (vector signed char, vector signed char);
19114 vector signed short vec_vsubshs (vector bool short, vector signed short);
19115 vector signed short vec_vsubshs (vector signed short, vector bool short);
19116 vector signed short vec_vsubshs (vector signed short, vector signed short);
19118 vector signed int vec_vsubsws (vector bool int, vector signed int);
19119 vector signed int vec_vsubsws (vector signed int, vector bool int);
19120 vector signed int vec_vsubsws (vector signed int, vector signed int);
19122 vector signed char vec_vsububm (vector bool char, vector signed char);
19123 vector signed char vec_vsububm (vector signed char, vector bool char);
19124 vector signed char vec_vsububm (vector signed char, vector signed char);
19125 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
19126 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
19127 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
19129 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
19130 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
19131 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
19133 vector signed short vec_vsubuhm (vector bool short, vector signed short);
19134 vector signed short vec_vsubuhm (vector signed short, vector bool short);
19135 vector signed short vec_vsubuhm (vector signed short, vector signed short);
19136 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
19137 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
19138 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
19140 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
19141 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
19142 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
19144 vector signed int vec_vsubuwm (vector bool int, vector signed int);
19145 vector signed int vec_vsubuwm (vector signed int, vector bool int);
19146 vector signed int vec_vsubuwm (vector signed int, vector signed int);
19147 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
19148 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
19149 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
19151 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
19152 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
19153 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
19155 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
19157 vector signed int vec_vsum4shs (vector signed short, vector signed int);
19159 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
19161 vector unsigned int vec_vupkhpx (vector pixel);
19163 vector bool short vec_vupkhsb (vector bool char);
19164 vector signed short vec_vupkhsb (vector signed char);
19166 vector bool int vec_vupkhsh (vector bool short);
19167 vector signed int vec_vupkhsh (vector signed short);
19169 vector unsigned int vec_vupklpx (vector pixel);
19171 vector bool short vec_vupklsb (vector bool char);
19172 vector signed short vec_vupklsb (vector signed char);
19174 vector bool int vec_vupklsh (vector bool short);
19175 vector signed int vec_vupklsh (vector signed short);
19178 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
19179 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
19181 The AltiVec built-in functions described in this section are
19182 available on the PowerPC family of processors starting with ISA 2.06
19183 or later. These are normally enabled by adding @option{-mvsx} to the
19186 When @option{-mvsx} is used, the following additional vector types are
19190 vector unsigned __int128
19191 vector signed __int128
19192 vector unsigned long long int
19193 vector signed long long int
19197 The long long types are only implemented for 64-bit code generation.
19199 Only functions excluded from the PVIPR are listed here.
19202 void vec_dst (const unsigned long *, int, const int);
19203 void vec_dst (const long *, int, const int);
19205 void vec_dststt (const unsigned long *, int, const int);
19206 void vec_dststt (const long *, int, const int);
19208 void vec_dstt (const unsigned long *, int, const int);
19209 void vec_dstt (const long *, int, const int);
19211 vector unsigned char vec_lvsl (int, const unsigned long *);
19212 vector unsigned char vec_lvsl (int, const long *);
19214 vector unsigned char vec_lvsr (int, const unsigned long *);
19215 vector unsigned char vec_lvsr (int, const long *);
19217 vector unsigned char vec_lvsl (int, const double *);
19218 vector unsigned char vec_lvsr (int, const double *);
19220 vector double vec_vsx_ld (int, const vector double *);
19221 vector double vec_vsx_ld (int, const double *);
19222 vector float vec_vsx_ld (int, const vector float *);
19223 vector float vec_vsx_ld (int, const float *);
19224 vector bool int vec_vsx_ld (int, const vector bool int *);
19225 vector signed int vec_vsx_ld (int, const vector signed int *);
19226 vector signed int vec_vsx_ld (int, const int *);
19227 vector signed int vec_vsx_ld (int, const long *);
19228 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
19229 vector unsigned int vec_vsx_ld (int, const unsigned int *);
19230 vector unsigned int vec_vsx_ld (int, const unsigned long *);
19231 vector bool short vec_vsx_ld (int, const vector bool short *);
19232 vector pixel vec_vsx_ld (int, const vector pixel *);
19233 vector signed short vec_vsx_ld (int, const vector signed short *);
19234 vector signed short vec_vsx_ld (int, const short *);
19235 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
19236 vector unsigned short vec_vsx_ld (int, const unsigned short *);
19237 vector bool char vec_vsx_ld (int, const vector bool char *);
19238 vector signed char vec_vsx_ld (int, const vector signed char *);
19239 vector signed char vec_vsx_ld (int, const signed char *);
19240 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
19241 vector unsigned char vec_vsx_ld (int, const unsigned char *);
19243 void vec_vsx_st (vector double, int, vector double *);
19244 void vec_vsx_st (vector double, int, double *);
19245 void vec_vsx_st (vector float, int, vector float *);
19246 void vec_vsx_st (vector float, int, float *);
19247 void vec_vsx_st (vector signed int, int, vector signed int *);
19248 void vec_vsx_st (vector signed int, int, int *);
19249 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
19250 void vec_vsx_st (vector unsigned int, int, unsigned int *);
19251 void vec_vsx_st (vector bool int, int, vector bool int *);
19252 void vec_vsx_st (vector bool int, int, unsigned int *);
19253 void vec_vsx_st (vector bool int, int, int *);
19254 void vec_vsx_st (vector signed short, int, vector signed short *);
19255 void vec_vsx_st (vector signed short, int, short *);
19256 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
19257 void vec_vsx_st (vector unsigned short, int, unsigned short *);
19258 void vec_vsx_st (vector bool short, int, vector bool short *);
19259 void vec_vsx_st (vector bool short, int, unsigned short *);
19260 void vec_vsx_st (vector pixel, int, vector pixel *);
19261 void vec_vsx_st (vector pixel, int, unsigned short *);
19262 void vec_vsx_st (vector pixel, int, short *);
19263 void vec_vsx_st (vector bool short, int, short *);
19264 void vec_vsx_st (vector signed char, int, vector signed char *);
19265 void vec_vsx_st (vector signed char, int, signed char *);
19266 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
19267 void vec_vsx_st (vector unsigned char, int, unsigned char *);
19268 void vec_vsx_st (vector bool char, int, vector bool char *);
19269 void vec_vsx_st (vector bool char, int, unsigned char *);
19270 void vec_vsx_st (vector bool char, int, signed char *);
19272 vector double vec_xxpermdi (vector double, vector double, const int);
19273 vector float vec_xxpermdi (vector float, vector float, const int);
19274 vector long long vec_xxpermdi (vector long long, vector long long, const int);
19275 vector unsigned long long vec_xxpermdi (vector unsigned long long,
19276 vector unsigned long long, const int);
19277 vector int vec_xxpermdi (vector int, vector int, const int);
19278 vector unsigned int vec_xxpermdi (vector unsigned int,
19279 vector unsigned int, const int);
19280 vector short vec_xxpermdi (vector short, vector short, const int);
19281 vector unsigned short vec_xxpermdi (vector unsigned short,
19282 vector unsigned short, const int);
19283 vector signed char vec_xxpermdi (vector signed char, vector signed char,
19285 vector unsigned char vec_xxpermdi (vector unsigned char,
19286 vector unsigned char, const int);
19288 vector double vec_xxsldi (vector double, vector double, int);
19289 vector float vec_xxsldi (vector float, vector float, int);
19290 vector long long vec_xxsldi (vector long long, vector long long, int);
19291 vector unsigned long long vec_xxsldi (vector unsigned long long,
19292 vector unsigned long long, int);
19293 vector int vec_xxsldi (vector int, vector int, int);
19294 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
19295 vector short vec_xxsldi (vector short, vector short, int);
19296 vector unsigned short vec_xxsldi (vector unsigned short,
19297 vector unsigned short, int);
19298 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
19299 vector unsigned char vec_xxsldi (vector unsigned char,
19300 vector unsigned char, int);
19303 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
19304 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
19305 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
19306 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
19307 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
19309 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
19310 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
19312 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19313 instruction set are available, the following additional functions are
19314 available for both 32-bit and 64-bit targets. For 64-bit targets, you
19315 can use @var{vector long} instead of @var{vector long long},
19316 @var{vector bool long} instead of @var{vector bool long long}, and
19317 @var{vector unsigned long} instead of @var{vector unsigned long long}.
19319 Only functions excluded from the PVIPR are listed here.
19322 vector long long vec_vaddudm (vector long long, vector long long);
19323 vector long long vec_vaddudm (vector bool long long, vector long long);
19324 vector long long vec_vaddudm (vector long long, vector bool long long);
19325 vector unsigned long long vec_vaddudm (vector unsigned long long,
19326 vector unsigned long long);
19327 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
19328 vector unsigned long long);
19329 vector unsigned long long vec_vaddudm (vector unsigned long long,
19330 vector bool unsigned long long);
19332 vector long long vec_vclz (vector long long);
19333 vector unsigned long long vec_vclz (vector unsigned long long);
19334 vector int vec_vclz (vector int);
19335 vector unsigned int vec_vclz (vector int);
19336 vector short vec_vclz (vector short);
19337 vector unsigned short vec_vclz (vector unsigned short);
19338 vector signed char vec_vclz (vector signed char);
19339 vector unsigned char vec_vclz (vector unsigned char);
19341 vector signed char vec_vclzb (vector signed char);
19342 vector unsigned char vec_vclzb (vector unsigned char);
19344 vector long long vec_vclzd (vector long long);
19345 vector unsigned long long vec_vclzd (vector unsigned long long);
19347 vector short vec_vclzh (vector short);
19348 vector unsigned short vec_vclzh (vector unsigned short);
19350 vector int vec_vclzw (vector int);
19351 vector unsigned int vec_vclzw (vector int);
19353 vector signed char vec_vgbbd (vector signed char);
19354 vector unsigned char vec_vgbbd (vector unsigned char);
19356 vector long long vec_vmaxsd (vector long long, vector long long);
19358 vector unsigned long long vec_vmaxud (vector unsigned long long,
19359 unsigned vector long long);
19361 vector long long vec_vminsd (vector long long, vector long long);
19363 vector unsigned long long vec_vminud (vector long long, vector long long);
19365 vector int vec_vpksdss (vector long long, vector long long);
19366 vector unsigned int vec_vpksdss (vector long long, vector long long);
19368 vector unsigned int vec_vpkudus (vector unsigned long long,
19369 vector unsigned long long);
19371 vector int vec_vpkudum (vector long long, vector long long);
19372 vector unsigned int vec_vpkudum (vector unsigned long long,
19373 vector unsigned long long);
19374 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
19376 vector long long vec_vpopcnt (vector long long);
19377 vector unsigned long long vec_vpopcnt (vector unsigned long long);
19378 vector int vec_vpopcnt (vector int);
19379 vector unsigned int vec_vpopcnt (vector int);
19380 vector short vec_vpopcnt (vector short);
19381 vector unsigned short vec_vpopcnt (vector unsigned short);
19382 vector signed char vec_vpopcnt (vector signed char);
19383 vector unsigned char vec_vpopcnt (vector unsigned char);
19385 vector signed char vec_vpopcntb (vector signed char);
19386 vector unsigned char vec_vpopcntb (vector unsigned char);
19388 vector long long vec_vpopcntd (vector long long);
19389 vector unsigned long long vec_vpopcntd (vector unsigned long long);
19391 vector short vec_vpopcnth (vector short);
19392 vector unsigned short vec_vpopcnth (vector unsigned short);
19394 vector int vec_vpopcntw (vector int);
19395 vector unsigned int vec_vpopcntw (vector int);
19397 vector long long vec_vrld (vector long long, vector unsigned long long);
19398 vector unsigned long long vec_vrld (vector unsigned long long,
19399 vector unsigned long long);
19401 vector long long vec_vsld (vector long long, vector unsigned long long);
19402 vector long long vec_vsld (vector unsigned long long,
19403 vector unsigned long long);
19405 vector long long vec_vsrad (vector long long, vector unsigned long long);
19406 vector unsigned long long vec_vsrad (vector unsigned long long,
19407 vector unsigned long long);
19409 vector long long vec_vsrd (vector long long, vector unsigned long long);
19410 vector unsigned long long char vec_vsrd (vector unsigned long long,
19411 vector unsigned long long);
19413 vector long long vec_vsubudm (vector long long, vector long long);
19414 vector long long vec_vsubudm (vector bool long long, vector long long);
19415 vector long long vec_vsubudm (vector long long, vector bool long long);
19416 vector unsigned long long vec_vsubudm (vector unsigned long long,
19417 vector unsigned long long);
19418 vector unsigned long long vec_vsubudm (vector bool long long,
19419 vector unsigned long long);
19420 vector unsigned long long vec_vsubudm (vector unsigned long long,
19421 vector bool long long);
19423 vector long long vec_vupkhsw (vector int);
19424 vector unsigned long long vec_vupkhsw (vector unsigned int);
19426 vector long long vec_vupklsw (vector int);
19427 vector unsigned long long vec_vupklsw (vector int);
19430 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19431 instruction set are available, the following additional functions are
19432 available for 64-bit targets. New vector types
19433 (@var{vector __int128} and @var{vector __uint128}) are available
19434 to hold the @var{__int128} and @var{__uint128} types to use these
19437 The normal vector extract, and set operations work on
19438 @var{vector __int128} and @var{vector __uint128} types,
19439 but the index value must be 0.
19441 Only functions excluded from the PVIPR are listed here.
19444 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
19445 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
19447 vector __int128 vec_vadduqm (vector __int128, vector __int128);
19448 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
19450 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
19452 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
19455 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
19457 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
19460 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
19462 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
19465 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
19467 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
19470 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
19471 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
19473 __int128 vec_vsubuqm (__int128, __int128);
19474 __uint128 vec_vsubuqm (__uint128, __uint128);
19476 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
19477 vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char,
19479 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
19480 int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int);
19481 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
19482 int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int);
19483 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
19484 int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int);
19485 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
19486 int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int);
19488 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
19489 vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char,
19491 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
19492 int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int);
19493 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
19494 int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int);
19495 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
19496 int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int);
19497 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
19498 int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int);
19501 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
19502 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
19504 The following additional built-in functions are also available for the
19505 PowerPC family of processors, starting with ISA 3.0
19506 (@option{-mcpu=power9}) or later.
19508 Only instructions excluded from the PVIPR are listed here.
19511 unsigned int scalar_extract_exp (double source);
19512 unsigned long long int scalar_extract_exp (__ieee128 source);
19514 unsigned long long int scalar_extract_sig (double source);
19515 unsigned __int128 scalar_extract_sig (__ieee128 source);
19517 double scalar_insert_exp (unsigned long long int significand,
19518 unsigned long long int exponent);
19519 double scalar_insert_exp (double significand, unsigned long long int exponent);
19521 ieee_128 scalar_insert_exp (unsigned __int128 significand,
19522 unsigned long long int exponent);
19523 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
19525 int scalar_cmp_exp_gt (double arg1, double arg2);
19526 int scalar_cmp_exp_lt (double arg1, double arg2);
19527 int scalar_cmp_exp_eq (double arg1, double arg2);
19528 int scalar_cmp_exp_unordered (double arg1, double arg2);
19530 bool scalar_test_data_class (float source, const int condition);
19531 bool scalar_test_data_class (double source, const int condition);
19532 bool scalar_test_data_class (__ieee128 source, const int condition);
19534 bool scalar_test_neg (float source);
19535 bool scalar_test_neg (double source);
19536 bool scalar_test_neg (__ieee128 source);
19539 The @code{scalar_extract_exp} and @code{scalar_extract_sig}
19540 functions require a 64-bit environment supporting ISA 3.0 or later.
19541 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
19542 functions return the significand and the biased exponent value
19543 respectively of their @code{source} arguments.
19544 When supplied with a 64-bit @code{source} argument, the
19545 result returned by @code{scalar_extract_sig} has
19546 the @code{0x0010000000000000} bit set if the
19547 function's @code{source} argument is in normalized form.
19548 Otherwise, this bit is set to 0.
19549 When supplied with a 128-bit @code{source} argument, the
19550 @code{0x00010000000000000000000000000000} bit of the result is
19552 Note that the sign of the significand is not represented in the result
19553 returned from the @code{scalar_extract_sig} function. Use the
19554 @code{scalar_test_neg} function to test the sign of its @code{double}
19557 The @code{scalar_insert_exp}
19558 functions require a 64-bit environment supporting ISA 3.0 or later.
19559 When supplied with a 64-bit first argument, the
19560 @code{scalar_insert_exp} built-in function returns a double-precision
19561 floating point value that is constructed by assembling the values of its
19562 @code{significand} and @code{exponent} arguments. The sign of the
19563 result is copied from the most significant bit of the
19564 @code{significand} argument. The significand and exponent components
19565 of the result are composed of the least significant 11 bits of the
19566 @code{exponent} argument and the least significant 52 bits of the
19567 @code{significand} argument respectively.
19569 When supplied with a 128-bit first argument, the
19570 @code{scalar_insert_exp} built-in function returns a quad-precision
19571 ieee floating point value. The sign bit of the result is copied from
19572 the most significant bit of the @code{significand} argument.
19573 The significand and exponent components of the result are composed of
19574 the least significant 15 bits of the @code{exponent} argument and the
19575 least significant 112 bits of the @code{significand} argument respectively.
19577 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
19578 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
19579 functions return a non-zero value if @code{arg1} is greater than, less
19580 than, equal to, or not comparable to @code{arg2} respectively. The
19581 arguments are not comparable if one or the other equals NaN (not a
19584 The @code{scalar_test_data_class} built-in function returns 1
19585 if any of the condition tests enabled by the value of the
19586 @code{condition} variable are true, and 0 otherwise. The
19587 @code{condition} argument must be a compile-time constant integer with
19588 value not exceeding 127. The
19589 @code{condition} argument is encoded as a bitmask with each bit
19590 enabling the testing of a different condition, as characterized by the
19594 0x20 Test for +Infinity
19595 0x10 Test for -Infinity
19596 0x08 Test for +Zero
19597 0x04 Test for -Zero
19598 0x02 Test for +Denormal
19599 0x01 Test for -Denormal
19602 The @code{scalar_test_neg} built-in function returns 1 if its
19603 @code{source} argument holds a negative value, 0 otherwise.
19605 The following built-in functions are also available for the PowerPC family
19606 of processors, starting with ISA 3.0 or later
19607 (@option{-mcpu=power9}). These string functions are described
19608 separately in order to group the descriptions closer to the function
19611 Only functions excluded from the PVIPR are listed here.
19614 int vec_all_nez (vector signed char, vector signed char);
19615 int vec_all_nez (vector unsigned char, vector unsigned char);
19616 int vec_all_nez (vector signed short, vector signed short);
19617 int vec_all_nez (vector unsigned short, vector unsigned short);
19618 int vec_all_nez (vector signed int, vector signed int);
19619 int vec_all_nez (vector unsigned int, vector unsigned int);
19621 int vec_any_eqz (vector signed char, vector signed char);
19622 int vec_any_eqz (vector unsigned char, vector unsigned char);
19623 int vec_any_eqz (vector signed short, vector signed short);
19624 int vec_any_eqz (vector unsigned short, vector unsigned short);
19625 int vec_any_eqz (vector signed int, vector signed int);
19626 int vec_any_eqz (vector unsigned int, vector unsigned int);
19628 signed char vec_xlx (unsigned int index, vector signed char data);
19629 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
19630 signed short vec_xlx (unsigned int index, vector signed short data);
19631 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
19632 signed int vec_xlx (unsigned int index, vector signed int data);
19633 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
19634 float vec_xlx (unsigned int index, vector float data);
19636 signed char vec_xrx (unsigned int index, vector signed char data);
19637 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
19638 signed short vec_xrx (unsigned int index, vector signed short data);
19639 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
19640 signed int vec_xrx (unsigned int index, vector signed int data);
19641 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
19642 float vec_xrx (unsigned int index, vector float data);
19645 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
19646 perform pairwise comparisons between the elements at the same
19647 positions within their two vector arguments.
19648 The @code{vec_all_nez} function returns a
19649 non-zero value if and only if all pairwise comparisons are not
19650 equal and no element of either vector argument contains a zero.
19651 The @code{vec_any_eqz} function returns a
19652 non-zero value if and only if at least one pairwise comparison is equal
19653 or if at least one element of either vector argument contains a zero.
19654 The @code{vec_cmpnez} function returns a vector of the same type as
19655 its two arguments, within which each element consists of all ones to
19656 denote that either the corresponding elements of the incoming arguments are
19657 not equal or that at least one of the corresponding elements contains
19658 zero. Otherwise, the element of the returned vector contains all zeros.
19660 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
19661 element selected by the @code{index} argument from the vector
19662 represented by the @code{data} argument. The @code{index} argument
19663 always specifies a byte offset, regardless of the size of the vector
19664 element. With @code{vec_xlx}, @code{index} is the offset of the first
19665 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
19666 represents the last byte of the element to be extracted, measured
19667 from the right end of the vector. In other words, the last byte of
19668 the element to be extracted is found at position @code{(15 - index)}.
19669 There is no requirement that @code{index} be a multiple of the vector
19670 element size. However, if the size of the vector element added to
19671 @code{index} is greater than 15, the content of the returned value is
19674 The following functions are also available if the ISA 3.0 instruction
19675 set additions (@option{-mcpu=power9}) are available.
19677 Only functions excluded from the PVIPR are listed here.
19680 vector long long vec_vctz (vector long long);
19681 vector unsigned long long vec_vctz (vector unsigned long long);
19682 vector int vec_vctz (vector int);
19683 vector unsigned int vec_vctz (vector int);
19684 vector short vec_vctz (vector short);
19685 vector unsigned short vec_vctz (vector unsigned short);
19686 vector signed char vec_vctz (vector signed char);
19687 vector unsigned char vec_vctz (vector unsigned char);
19689 vector signed char vec_vctzb (vector signed char);
19690 vector unsigned char vec_vctzb (vector unsigned char);
19692 vector long long vec_vctzd (vector long long);
19693 vector unsigned long long vec_vctzd (vector unsigned long long);
19695 vector short vec_vctzh (vector short);
19696 vector unsigned short vec_vctzh (vector unsigned short);
19698 vector int vec_vctzw (vector int);
19699 vector unsigned int vec_vctzw (vector int);
19701 vector int vec_vprtyb (vector int);
19702 vector unsigned int vec_vprtyb (vector unsigned int);
19703 vector long long vec_vprtyb (vector long long);
19704 vector unsigned long long vec_vprtyb (vector unsigned long long);
19706 vector int vec_vprtybw (vector int);
19707 vector unsigned int vec_vprtybw (vector unsigned int);
19709 vector long long vec_vprtybd (vector long long);
19710 vector unsigned long long vec_vprtybd (vector unsigned long long);
19713 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
19717 vector long vec_vprtyb (vector long);
19718 vector unsigned long vec_vprtyb (vector unsigned long);
19719 vector __int128 vec_vprtyb (vector __int128);
19720 vector __uint128 vec_vprtyb (vector __uint128);
19722 vector long vec_vprtybd (vector long);
19723 vector unsigned long vec_vprtybd (vector unsigned long);
19725 vector __int128 vec_vprtybq (vector __int128);
19726 vector __uint128 vec_vprtybd (vector __uint128);
19729 The following built-in functions are available for the PowerPC family
19730 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}).
19732 Only functions excluded from the PVIPR are listed here.
19735 __vector unsigned char
19736 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
19737 __vector unsigned short
19738 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
19739 __vector unsigned int
19740 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
19743 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
19744 @code{vec_absdw} built-in functions each computes the absolute
19745 differences of the pairs of vector elements supplied in its two vector
19746 arguments, placing the absolute differences into the corresponding
19747 elements of the vector result.
19749 The following built-in functions are available for the PowerPC family
19750 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
19752 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
19753 vector unsigned long long vec_vrlnm (vector unsigned long long,
19754 vector unsigned long long);
19757 The result of @code{vec_vrlnm} is obtained by rotating each element
19758 of the first argument vector left and ANDing it with a mask. The
19759 second argument vector contains the mask beginning in bits 11:15,
19760 the mask end in bits 19:23, and the shift count in bits 27:31,
19763 If the cryptographic instructions are enabled (@option{-mcrypto} or
19764 @option{-mcpu=power8}), the following builtins are enabled.
19766 Only functions excluded from the PVIPR are listed here.
19769 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
19771 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
19772 vector unsigned long long);
19774 vector unsigned long long __builtin_crypto_vcipherlast
19775 (vector unsigned long long,
19776 vector unsigned long long);
19778 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
19779 vector unsigned long long);
19781 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
19782 vector unsigned long long);
19784 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
19785 vector unsigned char,
19786 vector unsigned char);
19788 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
19789 vector unsigned short,
19790 vector unsigned short);
19792 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
19793 vector unsigned int,
19794 vector unsigned int);
19796 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
19797 vector unsigned long long,
19798 vector unsigned long long);
19800 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
19801 vector unsigned char);
19803 vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short,
19804 vector unsigned short);
19806 vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int,
19807 vector unsigned int);
19809 vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long,
19810 vector unsigned long long);
19812 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
19815 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
19818 The second argument to @var{__builtin_crypto_vshasigmad} and
19819 @var{__builtin_crypto_vshasigmaw} must be a constant
19820 integer that is 0 or 1. The third argument to these built-in functions
19821 must be a constant integer in the range of 0 to 15.
19823 The following sign extension builtins are provided:
19826 vector signed int vec_signexti (vector signed char a);
19827 vector signed long long vec_signextll (vector signed char a);
19828 vector signed int vec_signexti (vector signed short a);
19829 vector signed long long vec_signextll (vector signed short a);
19830 vector signed long long vec_signextll (vector signed int a);
19831 vector signed long long vec_signextq (vector signed long long a);
19834 Each element of the result is produced by sign-extending the element of the
19835 input vector that would fall in the least significant portion of the result
19836 element. For example, a sign-extension of a vector signed char to a vector
19837 signed long long will sign extend the rightmost byte of each doubleword.
19839 @node PowerPC AltiVec Built-in Functions Available on ISA 3.1
19840 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1
19842 The following additional built-in functions are also available for the
19843 PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}):
19847 @exdent vector unsigned long long int
19848 @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int);
19850 Perform a vector centrifuge operation, as if implemented by the
19851 @code{vcfuged} instruction.
19855 @exdent vector unsigned long long int
19856 @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int);
19858 Perform a vector count leading zeros under bit mask operation, as if
19859 implemented by the @code{vclzdm} instruction.
19863 @exdent vector unsigned long long int
19864 @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int);
19866 Perform a vector count trailing zeros under bit mask operation, as if
19867 implemented by the @code{vctzdm} instruction.
19871 @exdent vector signed char
19872 @exdent vec_clrl (vector signed char a, unsigned int n);
19873 @exdent vector unsigned char
19874 @exdent vec_clrl (vector unsigned char a, unsigned int n);
19876 Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if
19877 implemented by the @code{vclrlb} instruction on a big-endian target
19878 and by the @code{vclrrb} instruction on a little-endian target. A
19879 value of @code{n} that is greater than 16 is treated as if it equaled 16.
19883 @exdent vector signed char
19884 @exdent vec_clrr (vector signed char a, unsigned int n);
19885 @exdent vector unsigned char
19886 @exdent vec_clrr (vector unsigned char a, unsigned int n);
19888 Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if
19889 implemented by the @code{vclrrb} instruction on a big-endian target
19890 and by the @code{vclrlb} instruction on a little-endian target. A
19891 value of @code{n} that is greater than 16 is treated as if it equaled 16.
19895 @exdent vector unsigned long long int
19896 @exdent vec_gnb (vector unsigned __int128, const unsigned char);
19898 Perform a 128-bit vector gather operation, as if implemented by the
19899 @code{vgnb} instruction. The second argument must be a literal
19900 integer value between 2 and 7 inclusive.
19907 @exdent vector unsigned long long int
19908 @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int);
19909 @exdent vector unsigned long long int
19910 @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int);
19911 @exdent vector unsigned long long int
19912 @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int);
19913 @exdent vector unsigned long long int
19914 @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int);
19916 Extract an element from two concatenated vectors starting at the given byte index
19917 in natural-endian order, and place it zero-extended in doubleword 1 of the result
19918 according to natural element order. If the byte index is out of range for the
19919 data type, the intrinsic will be rejected.
19920 For little-endian, this output will match the placement by the hardware
19921 instruction, i.e., dword[0] in RTL notation. For big-endian, an additional
19922 instruction is needed to move it from the "left" doubleword to the "right" one.
19923 For little-endian, semantics matching the @code{vextdubvrx},
19924 @code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for
19925 big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx},
19926 @code{vextduwvlx} instructions
19927 will be generated. Note that some fairly anomalous results can be generated if
19928 the byte index is not aligned on an element boundary for the element being
19929 extracted. This is a limitation of the bi-endian vector programming model is
19930 consistent with the limitation on @code{vec_perm}.
19931 @findex vec_extractl
19934 @exdent vector unsigned long long int
19935 @exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int);
19936 @exdent vector unsigned long long int
19937 @exdent vec_extracth (vector unsigned short, vector unsigned short,
19939 @exdent vector unsigned long long int
19940 @exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int);
19941 @exdent vector unsigned long long int
19942 @exdent vec_extracth (vector unsigned long long, vector unsigned long long,
19945 Extract an element from two concatenated vectors starting at the given byte
19946 index. The index is based on big endian order for a little endian system.
19947 Similarly, the index is based on little endian order for a big endian system.
19948 The extraced elements are zero-extended and put in doubleword 1
19949 according to natural element order. If the byte index is out of range for the
19950 data type, the intrinsic will be rejected. For little-endian, this output
19951 will match the placement by the hardware instruction (vextdubvrx, vextduhvrx,
19952 vextduwvrx, vextddvrx) i.e., dword[0] in RTL
19953 notation. For big-endian, an additional instruction is needed to move it
19954 from the "left" doubleword to the "right" one. For little-endian, semantics
19955 matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx}
19956 instructions will be generated, while for big-endian, semantics matching the
19957 @code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will
19958 be generated. Note that some fairly anomalous
19959 results can be generated if the byte index is not aligned on the
19960 element boundary for the element being extracted. This is a
19961 limitation of the bi-endian vector programming model consistent with the
19962 limitation on @code{vec_perm}.
19963 @findex vec_extracth
19965 @exdent vector unsigned long long int
19966 @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int);
19968 Perform a vector parallel bits deposit operation, as if implemented by
19969 the @code{vpdepd} instruction.
19975 @exdent vector unsigned char
19976 @exdent vec_insertl (unsigned char, vector unsigned char, unsigned int);
19977 @exdent vector unsigned short
19978 @exdent vec_insertl (unsigned short, vector unsigned short, unsigned int);
19979 @exdent vector unsigned int
19980 @exdent vec_insertl (unsigned int, vector unsigned int, unsigned int);
19981 @exdent vector unsigned long long
19982 @exdent vec_insertl (unsigned long long, vector unsigned long long,
19984 @exdent vector unsigned char
19985 @exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int;
19986 @exdent vector unsigned short
19987 @exdent vec_insertl (vector unsigned short, vector unsigned short,
19989 @exdent vector unsigned int
19990 @exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int);
19993 Let src be the first argument, when the first argument is a scalar, or the
19994 rightmost element of the left doubleword of the first argument, when the first
19995 argument is a vector. Insert the source into the destination at the position
19996 given by the third argument, using natural element order in the second
19997 argument. The rest of the second argument is unchanged. If the byte
19998 index is greater than 14 for halfwords, greater than 12 for words, or
19999 greater than 8 for doublewords the result is undefined. For little-endian,
20000 the generated code will be semantically equivalent to @code{vins[bhwd]rx}
20001 instructions. Similarly for big-endian it will be semantically equivalent
20002 to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be
20003 generated if the byte index is not aligned on an element boundary for the
20004 type of element being inserted.
20005 @findex vec_insertl
20008 @exdent vector unsigned char
20009 @exdent vec_inserth (unsigned char, vector unsigned char, unsigned int);
20010 @exdent vector unsigned short
20011 @exdent vec_inserth (unsigned short, vector unsigned short, unsigned int);
20012 @exdent vector unsigned int
20013 @exdent vec_inserth (unsigned int, vector unsigned int, unsigned int);
20014 @exdent vector unsigned long long
20015 @exdent vec_inserth (unsigned long long, vector unsigned long long,
20017 @exdent vector unsigned char
20018 @exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int);
20019 @exdent vector unsigned short
20020 @exdent vec_inserth (vector unsigned short, vector unsigned short,
20022 @exdent vector unsigned int
20023 @exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int);
20026 Let src be the first argument, when the first argument is a scalar, or the
20027 rightmost element of the first argument, when the first argument is a vector.
20028 Insert src into the second argument at the position identified by the third
20029 argument, using opposite element order in the second argument, and leaving the
20030 rest of the second argument unchanged. If the byte index is greater than 14
20031 for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be
20032 rejected. Note that the underlying hardware instruction uses the same register
20033 for the second argument and the result.
20034 For little-endian, the code generation will be semantically equivalent to
20035 @code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to
20036 @code{vins[bhwd]rx}.
20037 Note that some fairly anomalous results can be generated if the byte index is
20038 not aligned on an element boundary for the sort of element being inserted.
20039 @findex vec_inserth
20041 Vector Replace Element
20043 @exdent vector signed int vec_replace_elt (vector signed int, signed int,
20045 @exdent vector unsigned int vec_replace_elt (vector unsigned int,
20046 unsigned int, const int);
20047 @exdent vector float vec_replace_elt (vector float, float, const int);
20048 @exdent vector signed long long vec_replace_elt (vector signed long long,
20049 signed long long, const int);
20050 @exdent vector unsigned long long vec_replace_elt (vector unsigned long long,
20051 unsigned long long, const int);
20052 @exdent vector double rec_replace_elt (vector double, double, const int);
20054 The third argument (constrained to [0,3]) identifies the natural-endian
20055 element number of the first argument that will be replaced by the second
20056 argument to produce the result. The other elements of the first argument will
20057 remain unchanged in the result.
20059 If it's desirable to insert a word at an unaligned position, use
20060 vec_replace_unaligned instead.
20062 @findex vec_replace_element
20064 Vector Replace Unaligned
20066 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
20067 signed int, const int);
20068 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
20069 unsigned int, const int);
20070 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
20072 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
20073 signed long long, const int);
20074 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
20075 unsigned long long, const int);
20076 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
20077 double, const int);
20080 The second argument replaces a portion of the first argument to produce the
20081 result, with the rest of the first argument unchanged in the result. The
20082 third argument identifies the byte index (using left-to-right, or big-endian
20083 order) where the high-order byte of the second argument will be placed, with
20084 the remaining bytes of the second argument placed naturally "to the right"
20085 of the high-order byte.
20087 The programmer is responsible for understanding the endianness issues involved
20088 with the first argument and the result.
20089 @findex vec_replace_unaligned
20091 Vector Shift Left Double Bit Immediate
20093 @exdent vector signed char vec_sldb (vector signed char, vector signed char,
20094 const unsigned int);
20095 @exdent vector unsigned char vec_sldb (vector unsigned char,
20096 vector unsigned char, const unsigned int);
20097 @exdent vector signed short vec_sldb (vector signed short, vector signed short,
20098 const unsigned int);
20099 @exdent vector unsigned short vec_sldb (vector unsigned short,
20100 vector unsigned short, const unsigned int);
20101 @exdent vector signed int vec_sldb (vector signed int, vector signed int,
20102 const unsigned int);
20103 @exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int,
20104 const unsigned int);
20105 @exdent vector signed long long vec_sldb (vector signed long long,
20106 vector signed long long, const unsigned int);
20107 @exdent vector unsigned long long vec_sldb (vector unsigned long long,
20108 vector unsigned long long, const unsigned int);
20111 Shift the combined input vectors left by the amount specified by the low-order
20112 three bits of the third argument, and return the leftmost remaining 128 bits.
20113 Code using this instruction must be endian-aware.
20117 Vector Shift Right Double Bit Immediate
20120 @exdent vector signed char vec_srdb (vector signed char, vector signed char,
20121 const unsigned int);
20122 @exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char,
20123 const unsigned int);
20124 @exdent vector signed short vec_srdb (vector signed short, vector signed short,
20125 const unsigned int);
20126 @exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short,
20127 const unsigned int);
20128 @exdent vector signed int vec_srdb (vector signed int, vector signed int,
20129 const unsigned int);
20130 @exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int,
20131 const unsigned int);
20132 @exdent vector signed long long vec_srdb (vector signed long long,
20133 vector signed long long, const unsigned int);
20134 @exdent vector unsigned long long vec_srdb (vector unsigned long long,
20135 vector unsigned long long, const unsigned int);
20138 Shift the combined input vectors right by the amount specified by the low-order
20139 three bits of the third argument, and return the remaining 128 bits. Code
20140 using this built-in must be endian-aware.
20147 @exdent vector signed int vec_splati (const signed int);
20148 @exdent vector float vec_splati (const float);
20151 Splat a 32-bit immediate into a vector of words.
20156 @exdent vector double vec_splatid (const float);
20159 Convert a single precision floating-point value to double-precision and splat
20160 the result to a vector of double-precision floats.
20162 @findex vec_splatid
20165 @exdent vector signed int vec_splati_ins (vector signed int,
20166 const unsigned int, const signed int);
20167 @exdent vector unsigned int vec_splati_ins (vector unsigned int,
20168 const unsigned int, const unsigned int);
20169 @exdent vector float vec_splati_ins (vector float, const unsigned int,
20173 Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word
20174 identified by argument 2 of each doubleword of argument 1 and return the
20175 result. The other words of argument 1 are unchanged.
20177 @findex vec_splati_ins
20179 Vector Blend Variable
20182 @exdent vector signed char vec_blendv (vector signed char, vector signed char,
20183 vector unsigned char);
20184 @exdent vector unsigned char vec_blendv (vector unsigned char,
20185 vector unsigned char, vector unsigned char);
20186 @exdent vector signed short vec_blendv (vector signed short,
20187 vector signed short, vector unsigned short);
20188 @exdent vector unsigned short vec_blendv (vector unsigned short,
20189 vector unsigned short, vector unsigned short);
20190 @exdent vector signed int vec_blendv (vector signed int, vector signed int,
20191 vector unsigned int);
20192 @exdent vector unsigned int vec_blendv (vector unsigned int,
20193 vector unsigned int, vector unsigned int);
20194 @exdent vector signed long long vec_blendv (vector signed long long,
20195 vector signed long long, vector unsigned long long);
20196 @exdent vector unsigned long long vec_blendv (vector unsigned long long,
20197 vector unsigned long long, vector unsigned long long);
20198 @exdent vector float vec_blendv (vector float, vector float,
20199 vector unsigned int);
20200 @exdent vector double vec_blendv (vector double, vector double,
20201 vector unsigned long long);
20204 Blend the first and second argument vectors according to the sign bits of the
20205 corresponding elements of the third argument vector. This is similar to the
20206 @code{vsel} and @code{xxsel} instructions but for bigger elements.
20210 Vector Permute Extended
20213 @exdent vector signed char vec_permx (vector signed char, vector signed char,
20214 vector unsigned char, const int);
20215 @exdent vector unsigned char vec_permx (vector unsigned char,
20216 vector unsigned char, vector unsigned char, const int);
20217 @exdent vector signed short vec_permx (vector signed short,
20218 vector signed short, vector unsigned char, const int);
20219 @exdent vector unsigned short vec_permx (vector unsigned short,
20220 vector unsigned short, vector unsigned char, const int);
20221 @exdent vector signed int vec_permx (vector signed int, vector signed int,
20222 vector unsigned char, const int);
20223 @exdent vector unsigned int vec_permx (vector unsigned int,
20224 vector unsigned int, vector unsigned char, const int);
20225 @exdent vector signed long long vec_permx (vector signed long long,
20226 vector signed long long, vector unsigned char, const int);
20227 @exdent vector unsigned long long vec_permx (vector unsigned long long,
20228 vector unsigned long long, vector unsigned char, const int);
20229 @exdent vector float (vector float, vector float, vector unsigned char,
20231 @exdent vector double (vector double, vector double, vector unsigned char,
20235 Perform a partial permute of the first two arguments, which form a 32-byte
20236 section of an emulated vector up to 256 bytes wide, using the partial permute
20237 control vector in the third argument. The fourth argument (constrained to
20238 values of 0-7) identifies which 32-byte section of the emulated vector is
20239 contained in the first two arguments.
20243 @exdent vector unsigned long long int
20244 @exdent vec_pext (vector unsigned long long int, vector unsigned long long int);
20246 Perform a vector parallel bit extract operation, as if implemented by
20247 the @code{vpextd} instruction.
20251 @exdent vector unsigned char vec_stril (vector unsigned char);
20252 @exdent vector signed char vec_stril (vector signed char);
20253 @exdent vector unsigned short vec_stril (vector unsigned short);
20254 @exdent vector signed short vec_stril (vector signed short);
20256 Isolate the left-most non-zero elements of the incoming vector argument,
20257 replacing all elements to the right of the left-most zero element
20258 found within the argument with zero. The typical implementation uses
20259 the @code{vstribl} or @code{vstrihl} instruction on big-endian targets
20260 and uses the @code{vstribr} or @code{vstrihr} instruction on
20261 little-endian targets.
20265 @exdent int vec_stril_p (vector unsigned char);
20266 @exdent int vec_stril_p (vector signed char);
20267 @exdent int short vec_stril_p (vector unsigned short);
20268 @exdent int vec_stril_p (vector signed short);
20270 Return a non-zero value if and only if the argument contains a zero
20271 element. The typical implementation uses
20272 the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets
20273 and uses the @code{vstribr.} or @code{vstrihr.} instruction on
20274 little-endian targets. Choose this built-in to check for presence of
20275 zero element if the same argument is also passed to @code{vec_stril}.
20276 @findex vec_stril_p
20279 @exdent vector unsigned char vec_strir (vector unsigned char);
20280 @exdent vector signed char vec_strir (vector signed char);
20281 @exdent vector unsigned short vec_strir (vector unsigned short);
20282 @exdent vector signed short vec_strir (vector signed short);
20284 Isolate the right-most non-zero elements of the incoming vector argument,
20285 replacing all elements to the left of the right-most zero element
20286 found within the argument with zero. The typical implementation uses
20287 the @code{vstribr} or @code{vstrihr} instruction on big-endian targets
20288 and uses the @code{vstribl} or @code{vstrihl} instruction on
20289 little-endian targets.
20293 @exdent int vec_strir_p (vector unsigned char);
20294 @exdent int vec_strir_p (vector signed char);
20295 @exdent int short vec_strir_p (vector unsigned short);
20296 @exdent int vec_strir_p (vector signed short);
20298 Return a non-zero value if and only if the argument contains a zero
20299 element. The typical implementation uses
20300 the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets
20301 and uses the @code{vstribl.} or @code{vstrihl.} instruction on
20302 little-endian targets. Choose this built-in to check for presence of
20303 zero element if the same argument is also passed to @code{vec_strir}.
20304 @findex vec_strir_p
20307 @exdent vector unsigned char
20308 @exdent vec_ternarylogic (vector unsigned char, vector unsigned char,
20309 vector unsigned char, const unsigned int);
20310 @exdent vector unsigned short
20311 @exdent vec_ternarylogic (vector unsigned short, vector unsigned short,
20312 vector unsigned short, const unsigned int);
20313 @exdent vector unsigned int
20314 @exdent vec_ternarylogic (vector unsigned int, vector unsigned int,
20315 vector unsigned int, const unsigned int);
20316 @exdent vector unsigned long long int
20317 @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int,
20318 vector unsigned long long int, const unsigned int);
20319 @exdent vector unsigned __int128
20320 @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128,
20321 vector unsigned __int128, const unsigned int);
20323 Perform a 128-bit vector evaluate operation, as if implemented by the
20324 @code{xxeval} instruction. The fourth argument must be a literal
20325 integer value between 0 and 255 inclusive.
20326 @findex vec_ternarylogic
20329 @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int);
20330 @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int);
20331 @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int);
20332 @exdent vector unsigned int vec_genpcvm (vector unsigned long long int,
20336 Vector Integer Multiply/Divide/Modulo
20339 @exdent vector signed int
20340 @exdent vec_mulh (vector signed int a, vector signed int b);
20341 @exdent vector unsigned int
20342 @exdent vec_mulh (vector unsigned int a, vector unsigned int b);
20345 For each integer value @code{i} from 0 to 3, do the following. The integer
20346 value in word element @code{i} of a is multiplied by the integer value in word
20347 element @code{i} of b. The high-order 32 bits of the 64-bit product are placed
20348 into word element @code{i} of the vector returned.
20351 @exdent vector signed long long
20352 @exdent vec_mulh (vector signed long long a, vector signed long long b);
20353 @exdent vector unsigned long long
20354 @exdent vec_mulh (vector unsigned long long a, vector unsigned long long b);
20357 For each integer value @code{i} from 0 to 1, do the following. The integer
20358 value in doubleword element @code{i} of a is multiplied by the integer value in
20359 doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product
20360 are placed into doubleword element @code{i} of the vector returned.
20363 @exdent vector unsigned long long
20364 @exdent vec_mul (vector unsigned long long a, vector unsigned long long b);
20365 @exdent vector signed long long
20366 @exdent vec_mul (vector signed long long a, vector signed long long b);
20369 For each integer value @code{i} from 0 to 1, do the following. The integer
20370 value in doubleword element @code{i} of a is multiplied by the integer value in
20371 doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product
20372 are placed into doubleword element @code{i} of the vector returned.
20375 @exdent vector signed int
20376 @exdent vec_div (vector signed int a, vector signed int b);
20377 @exdent vector unsigned int
20378 @exdent vec_div (vector unsigned int a, vector unsigned int b);
20381 For each integer value @code{i} from 0 to 3, do the following. The integer in
20382 word element @code{i} of a is divided by the integer in word element @code{i}
20383 of b. The unique integer quotient is placed into the word element @code{i} of
20384 the vector returned. If an attempt is made to perform any of the divisions
20385 <anything> ÷ 0 then the quotient is undefined.
20388 @exdent vector signed long long
20389 @exdent vec_div (vector signed long long a, vector signed long long b);
20390 @exdent vector unsigned long long
20391 @exdent vec_div (vector unsigned long long a, vector unsigned long long b);
20394 For each integer value @code{i} from 0 to 1, do the following. The integer in
20395 doubleword element @code{i} of a is divided by the integer in doubleword
20396 element @code{i} of b. The unique integer quotient is placed into the
20397 doubleword element @code{i} of the vector returned. If an attempt is made to
20398 perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then
20399 the quotient is undefined.
20402 @exdent vector signed int
20403 @exdent vec_dive (vector signed int a, vector signed int b);
20404 @exdent vector unsigned int
20405 @exdent vec_dive (vector unsigned int a, vector unsigned int b);
20408 For each integer value @code{i} from 0 to 3, do the following. The integer in
20409 word element @code{i} of a is shifted left by 32 bits, then divided by the
20410 integer in word element @code{i} of b. The unique integer quotient is placed
20411 into the word element @code{i} of the vector returned. If the quotient cannot
20412 be represented in 32 bits, or if an attempt is made to perform any of the
20413 divisions <anything> ÷ 0 then the quotient is undefined.
20416 @exdent vector signed long long
20417 @exdent vec_dive (vector signed long long a, vector signed long long b);
20418 @exdent vector unsigned long long
20419 @exdent vec_dive (vector unsigned long long a, vector unsigned long long b);
20422 For each integer value @code{i} from 0 to 1, do the following. The integer in
20423 doubleword element @code{i} of a is shifted left by 64 bits, then divided by
20424 the integer in doubleword element @code{i} of b. The unique integer quotient is
20425 placed into the doubleword element @code{i} of the vector returned. If the
20426 quotient cannot be represented in 64 bits, or if an attempt is made to perform
20427 <anything> ÷ 0 then the quotient is undefined.
20430 @exdent vector signed int
20431 @exdent vec_mod (vector signed int a, vector signed int b);
20432 @exdent vector unsigned int
20433 @exdent vec_mod (vector unsigned int a, vector unsigned int b);
20436 For each integer value @code{i} from 0 to 3, do the following. The integer in
20437 word element @code{i} of a is divided by the integer in word element @code{i}
20438 of b. The unique integer remainder is placed into the word element @code{i} of
20439 the vector returned. If an attempt is made to perform any of the divisions
20440 0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined.
20443 @exdent vector signed long long
20444 @exdent vec_mod (vector signed long long a, vector signed long long b);
20445 @exdent vector unsigned long long
20446 @exdent vec_mod (vector unsigned long long a, vector unsigned long long b);
20449 For each integer value @code{i} from 0 to 1, do the following. The integer in
20450 doubleword element @code{i} of a is divided by the integer in doubleword
20451 element @code{i} of b. The unique integer remainder is placed into the
20452 doubleword element @code{i} of the vector returned. If an attempt is made to
20453 perform <anything> ÷ 0 then the remainder is undefined.
20455 Generate PCV from specified Mask size, as if implemented by the
20456 @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where
20457 immediate value is either 0, 1, 2 or 3.
20458 @findex vec_genpcvm
20461 @exdent vector unsigned __int128 vec_rl (vector unsigned __int128 A,
20462 vector unsigned __int128 B);
20463 @exdent vector signed __int128 vec_rl (vector signed __int128 A,
20464 vector unsigned __int128 B);
20467 Result value: Each element of R is obtained by rotating the corresponding element
20468 of A left by the number of bits specified by the corresponding element of B.
20472 @exdent vector unsigned __int128 vec_rlmi (vector unsigned __int128,
20473 vector unsigned __int128,
20474 vector unsigned __int128);
20475 @exdent vector signed __int128 vec_rlmi (vector signed __int128,
20476 vector signed __int128,
20477 vector unsigned __int128);
20480 Returns the result of rotating the first input and inserting it under mask
20481 into the second input. The first bit in the mask, the last bit in the mask are
20482 obtained from the two 7-bit fields bits [108:115] and bits [117:123]
20483 respectively of the second input. The shift is obtained from the third input
20484 in the 7-bit field [125:131] where all bits counted from zero at the left.
20487 @exdent vector unsigned __int128 vec_rlnm (vector unsigned __int128,
20488 vector unsigned __int128,
20489 vector unsigned __int128);
20490 @exdent vector signed __int128 vec_rlnm (vector signed __int128,
20491 vector unsigned __int128,
20492 vector unsigned __int128);
20495 Returns the result of rotating the first input and ANDing it with a mask. The
20496 first bit in the mask and the last bit in the mask are obtained from the two
20497 7-bit fields bits [117:123] and bits [125:131] respectively of the second
20498 input. The shift is obtained from the third input in the 7-bit field bits
20499 [125:131] where all bits counted from zero at the left.
20502 @exdent vector unsigned __int128 vec_sl(vector unsigned __int128 A, vector unsigned __int128 B);
20503 @exdent vector signed __int128 vec_sl(vector signed __int128 A, vector unsigned __int128 B);
20506 Result value: Each element of R is obtained by shifting the corresponding element of
20507 A left by the number of bits specified by the corresponding element of B.
20510 @exdent vector unsigned __int128 vec_sr(vector unsigned __int128 A, vector unsigned __int128 B);
20511 @exdent vector signed __int128 vec_sr(vector signed __int128 A, vector unsigned __int128 B);
20514 Result value: Each element of R is obtained by shifting the corresponding element of
20515 A right by the number of bits specified by the corresponding element of B.
20518 @exdent vector unsigned __int128 vec_sra(vector unsigned __int128 A, vector unsigned __int128 B);
20519 @exdent vector signed __int128 vec_sra(vector signed __int128 A, vector unsigned __int128 B);
20522 Result value: Each element of R is obtained by arithmetic shifting the corresponding
20523 element of A right by the number of bits specified by the corresponding element of B.
20526 @exdent vector unsigned __int128 vec_mule (vector unsigned long long,
20527 vector unsigned long long);
20528 @exdent vector signed __int128 vec_mule (vector signed long long,
20529 vector signed long long);
20532 Returns a vector containing a 128-bit integer result of multiplying the even
20533 doubleword elements of the two inputs.
20536 @exdent vector unsigned __int128 vec_mulo (vector unsigned long long,
20537 vector unsigned long long);
20538 @exdent vector signed __int128 vec_mulo (vector signed long long,
20539 vector signed long long);
20542 Returns a vector containing a 128-bit integer result of multiplying the odd
20543 doubleword elements of the two inputs.
20546 @exdent vector unsigned __int128 vec_div (vector unsigned __int128,
20547 vector unsigned __int128);
20548 @exdent vector signed __int128 vec_div (vector signed __int128,
20549 vector signed __int128);
20552 Returns the result of dividing the first operand by the second operand. An
20553 attempt to divide any value by zero or to divide the most negative signed
20554 128-bit integer by negative one results in an undefined value.
20557 @exdent vector unsigned __int128 vec_dive (vector unsigned __int128,
20558 vector unsigned __int128);
20559 @exdent vector signed __int128 vec_dive (vector signed __int128,
20560 vector signed __int128);
20563 The result is produced by shifting the first input left by 128 bits and
20564 dividing by the second. If an attempt is made to divide by zero or the result
20565 is larger than 128 bits, the result is undefined.
20568 @exdent vector unsigned __int128 vec_mod (vector unsigned __int128,
20569 vector unsigned __int128);
20570 @exdent vector signed __int128 vec_mod (vector signed __int128,
20571 vector signed __int128);
20574 The result is the modulo result of dividing the first input by the second
20577 The following builtins perform 128-bit vector comparisons. The
20578 @code{vec_all_xx}, @code{vec_any_xx}, and @code{vec_cmpxx}, where @code{xx} is
20579 one of the operations @code{eq, ne, gt, lt, ge, le} perform pairwise
20580 comparisons between the elements at the same positions within their two vector
20581 arguments. The @code{vec_all_xx}function returns a non-zero value if and only
20582 if all pairwise comparisons are true. The @code{vec_any_xx} function returns
20583 a non-zero value if and only if at least one pairwise comparison is true. The
20584 @code{vec_cmpxx}function returns a vector of the same type as its two
20585 arguments, within which each element consists of all ones to denote that
20586 specified logical comparison of the corresponding elements was true.
20587 Otherwise, the element of the returned vector contains all zeros.
20590 vector bool __int128 vec_cmpeq (vector signed __int128, vector signed __int128);
20591 vector bool __int128 vec_cmpeq (vector unsigned __int128, vector unsigned __int128);
20592 vector bool __int128 vec_cmpne (vector signed __int128, vector signed __int128);
20593 vector bool __int128 vec_cmpne (vector unsigned __int128, vector unsigned __int128);
20594 vector bool __int128 vec_cmpgt (vector signed __int128, vector signed __int128);
20595 vector bool __int128 vec_cmpgt (vector unsigned __int128, vector unsigned __int128);
20596 vector bool __int128 vec_cmplt (vector signed __int128, vector signed __int128);
20597 vector bool __int128 vec_cmplt (vector unsigned __int128, vector unsigned __int128);
20598 vector bool __int128 vec_cmpge (vector signed __int128, vector signed __int128);
20599 vector bool __int128 vec_cmpge (vector unsigned __int128, vector unsigned __int128);
20600 vector bool __int128 vec_cmple (vector signed __int128, vector signed __int128);
20601 vector bool __int128 vec_cmple (vector unsigned __int128, vector unsigned __int128);
20603 int vec_all_eq (vector signed __int128, vector signed __int128);
20604 int vec_all_eq (vector unsigned __int128, vector unsigned __int128);
20605 int vec_all_ne (vector signed __int128, vector signed __int128);
20606 int vec_all_ne (vector unsigned __int128, vector unsigned __int128);
20607 int vec_all_gt (vector signed __int128, vector signed __int128);
20608 int vec_all_gt (vector unsigned __int128, vector unsigned __int128);
20609 int vec_all_lt (vector signed __int128, vector signed __int128);
20610 int vec_all_lt (vector unsigned __int128, vector unsigned __int128);
20611 int vec_all_ge (vector signed __int128, vector signed __int128);
20612 int vec_all_ge (vector unsigned __int128, vector unsigned __int128);
20613 int vec_all_le (vector signed __int128, vector signed __int128);
20614 int vec_all_le (vector unsigned __int128, vector unsigned __int128);
20616 int vec_any_eq (vector signed __int128, vector signed __int128);
20617 int vec_any_eq (vector unsigned __int128, vector unsigned __int128);
20618 int vec_any_ne (vector signed __int128, vector signed __int128);
20619 int vec_any_ne (vector unsigned __int128, vector unsigned __int128);
20620 int vec_any_gt (vector signed __int128, vector signed __int128);
20621 int vec_any_gt (vector unsigned __int128, vector unsigned __int128);
20622 int vec_any_lt (vector signed __int128, vector signed __int128);
20623 int vec_any_lt (vector unsigned __int128, vector unsigned __int128);
20624 int vec_any_ge (vector signed __int128, vector signed __int128);
20625 int vec_any_ge (vector unsigned __int128, vector unsigned __int128);
20626 int vec_any_le (vector signed __int128, vector signed __int128);
20627 int vec_any_le (vector unsigned __int128, vector unsigned __int128);
20631 @node PowerPC Hardware Transactional Memory Built-in Functions
20632 @subsection PowerPC Hardware Transactional Memory Built-in Functions
20633 GCC provides two interfaces for accessing the Hardware Transactional
20634 Memory (HTM) instructions available on some of the PowerPC family
20635 of processors (eg, POWER8). The two interfaces come in a low level
20636 interface, consisting of built-in functions specific to PowerPC and a
20637 higher level interface consisting of inline functions that are common
20638 between PowerPC and S/390.
20640 @subsubsection PowerPC HTM Low Level Built-in Functions
20642 The following low level built-in functions are available with
20643 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
20644 They all generate the machine instruction that is part of the name.
20646 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
20647 the full 4-bit condition register value set by their associated hardware
20648 instruction. The header file @code{htmintrin.h} defines some macros that can
20649 be used to decipher the return value. The @code{__builtin_tbegin} builtin
20650 returns a simple @code{true} or @code{false} value depending on whether a transaction was
20651 successfully started or not. The arguments of the builtins match exactly the
20652 type and order of the associated hardware instruction's operands, except for
20653 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
20654 Refer to the ISA manual for a description of each instruction's operands.
20657 unsigned int __builtin_tbegin (unsigned int);
20658 unsigned int __builtin_tend (unsigned int);
20660 unsigned int __builtin_tabort (unsigned int);
20661 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int);
20662 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int);
20663 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int);
20664 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int);
20666 unsigned int __builtin_tcheck (void);
20667 unsigned int __builtin_treclaim (unsigned int);
20668 unsigned int __builtin_trechkpt (void);
20669 unsigned int __builtin_tsr (unsigned int);
20672 In addition to the above HTM built-ins, we have added built-ins for
20673 some common extended mnemonics of the HTM instructions:
20676 unsigned int __builtin_tendall (void);
20677 unsigned int __builtin_tresume (void);
20678 unsigned int __builtin_tsuspend (void);
20681 Note that the semantics of the above HTM builtins are required to mimic
20682 the locking semantics used for critical sections. Builtins that are used
20683 to create a new transaction or restart a suspended transaction must have
20684 lock acquisition like semantics while those builtins that end or suspend a
20685 transaction must have lock release like semantics. Specifically, this must
20686 mimic lock semantics as specified by C++11, for example: Lock acquisition is
20687 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
20688 that returns 0, and lock release is as-if an execution of
20689 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
20690 implicit implementation-defined lock used for all transactions. The HTM
20691 instructions associated with with the builtins inherently provide the
20692 correct acquisition and release hardware barriers required. However,
20693 the compiler must also be prohibited from moving loads and stores across
20694 the builtins in a way that would violate their semantics. This has been
20695 accomplished by adding memory barriers to the associated HTM instructions
20696 (which is a conservative approach to provide acquire and release semantics).
20697 Earlier versions of the compiler did not treat the HTM instructions as
20698 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
20699 be used to determine whether the current compiler treats HTM instructions
20700 as memory barriers or not. This allows the user to explicitly add memory
20701 barriers to their code when using an older version of the compiler.
20703 The following set of built-in functions are available to gain access
20704 to the HTM specific special purpose registers.
20707 unsigned long __builtin_get_texasr (void);
20708 unsigned long __builtin_get_texasru (void);
20709 unsigned long __builtin_get_tfhar (void);
20710 unsigned long __builtin_get_tfiar (void);
20712 void __builtin_set_texasr (unsigned long);
20713 void __builtin_set_texasru (unsigned long);
20714 void __builtin_set_tfhar (unsigned long);
20715 void __builtin_set_tfiar (unsigned long);
20718 Example usage of these low level built-in functions may look like:
20721 #include <htmintrin.h>
20723 int num_retries = 10;
20727 if (__builtin_tbegin (0))
20729 /* Transaction State Initiated. */
20730 if (is_locked (lock))
20731 __builtin_tabort (0);
20732 ... transaction code...
20733 __builtin_tend (0);
20738 /* Transaction State Failed. Use locks if the transaction
20739 failure is "persistent" or we've tried too many times. */
20740 if (num_retries-- <= 0
20741 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
20743 acquire_lock (lock);
20744 ... non transactional fallback path...
20745 release_lock (lock);
20752 One final built-in function has been added that returns the value of
20753 the 2-bit Transaction State field of the Machine Status Register (MSR)
20754 as stored in @code{CR0}.
20757 unsigned long __builtin_ttest (void)
20760 This built-in can be used to determine the current transaction state
20761 using the following code example:
20764 #include <htmintrin.h>
20766 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
20768 if (tx_state == _HTM_TRANSACTIONAL)
20770 /* Code to use in transactional state. */
20772 else if (tx_state == _HTM_NONTRANSACTIONAL)
20774 /* Code to use in non-transactional state. */
20776 else if (tx_state == _HTM_SUSPENDED)
20778 /* Code to use in transaction suspended state. */
20782 @subsubsection PowerPC HTM High Level Inline Functions
20784 The following high level HTM interface is made available by including
20785 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
20786 where CPU is `power8' or later. This interface is common between PowerPC
20787 and S/390, allowing users to write one HTM source implementation that
20788 can be compiled and executed on either system.
20791 long __TM_simple_begin (void);
20792 long __TM_begin (void* const TM_buff);
20793 long __TM_end (void);
20794 void __TM_abort (void);
20795 void __TM_named_abort (unsigned char const code);
20796 void __TM_resume (void);
20797 void __TM_suspend (void);
20799 long __TM_is_user_abort (void* const TM_buff);
20800 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code);
20801 long __TM_is_illegal (void* const TM_buff);
20802 long __TM_is_footprint_exceeded (void* const TM_buff);
20803 long __TM_nesting_depth (void* const TM_buff);
20804 long __TM_is_nested_too_deep(void* const TM_buff);
20805 long __TM_is_conflict(void* const TM_buff);
20806 long __TM_is_failure_persistent(void* const TM_buff);
20807 long __TM_failure_address(void* const TM_buff);
20808 long long __TM_failure_code(void* const TM_buff);
20811 Using these common set of HTM inline functions, we can create
20812 a more portable version of the HTM example in the previous
20813 section that will work on either PowerPC or S/390:
20816 #include <htmxlintrin.h>
20818 int num_retries = 10;
20819 TM_buff_type TM_buff;
20823 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
20825 /* Transaction State Initiated. */
20826 if (is_locked (lock))
20828 ... transaction code...
20834 /* Transaction State Failed. Use locks if the transaction
20835 failure is "persistent" or we've tried too many times. */
20836 if (num_retries-- <= 0
20837 || __TM_is_failure_persistent (TM_buff))
20839 acquire_lock (lock);
20840 ... non transactional fallback path...
20841 release_lock (lock);
20848 @node PowerPC Atomic Memory Operation Functions
20849 @subsection PowerPC Atomic Memory Operation Functions
20850 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
20851 instructions. GCC provides support for these instructions in 64-bit
20852 environments. All of the functions are declared in the include file
20855 The functions supported are:
20860 uint32_t amo_lwat_add (uint32_t *, uint32_t);
20861 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
20862 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
20863 uint32_t amo_lwat_and (uint32_t *, uint32_t);
20864 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
20865 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
20866 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
20868 int32_t amo_lwat_sadd (int32_t *, int32_t);
20869 int32_t amo_lwat_smax (int32_t *, int32_t);
20870 int32_t amo_lwat_smin (int32_t *, int32_t);
20871 int32_t amo_lwat_sswap (int32_t *, int32_t);
20873 uint64_t amo_ldat_add (uint64_t *, uint64_t);
20874 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
20875 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
20876 uint64_t amo_ldat_and (uint64_t *, uint64_t);
20877 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
20878 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
20879 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
20881 int64_t amo_ldat_sadd (int64_t *, int64_t);
20882 int64_t amo_ldat_smax (int64_t *, int64_t);
20883 int64_t amo_ldat_smin (int64_t *, int64_t);
20884 int64_t amo_ldat_sswap (int64_t *, int64_t);
20886 void amo_stwat_add (uint32_t *, uint32_t);
20887 void amo_stwat_xor (uint32_t *, uint32_t);
20888 void amo_stwat_ior (uint32_t *, uint32_t);
20889 void amo_stwat_and (uint32_t *, uint32_t);
20890 void amo_stwat_umax (uint32_t *, uint32_t);
20891 void amo_stwat_umin (uint32_t *, uint32_t);
20893 void amo_stwat_sadd (int32_t *, int32_t);
20894 void amo_stwat_smax (int32_t *, int32_t);
20895 void amo_stwat_smin (int32_t *, int32_t);
20897 void amo_stdat_add (uint64_t *, uint64_t);
20898 void amo_stdat_xor (uint64_t *, uint64_t);
20899 void amo_stdat_ior (uint64_t *, uint64_t);
20900 void amo_stdat_and (uint64_t *, uint64_t);
20901 void amo_stdat_umax (uint64_t *, uint64_t);
20902 void amo_stdat_umin (uint64_t *, uint64_t);
20904 void amo_stdat_sadd (int64_t *, int64_t);
20905 void amo_stdat_smax (int64_t *, int64_t);
20906 void amo_stdat_smin (int64_t *, int64_t);
20909 @node PowerPC Matrix-Multiply Assist Built-in Functions
20910 @subsection PowerPC Matrix-Multiply Assist Built-in Functions
20911 ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions.
20912 GCC provides support for these instructions through the following built-in
20913 functions which are enabled with the @code{-mmma} option. The vec_t type
20914 below is defined to be a normal vector unsigned char type. The uint2, uint4
20915 and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants
20916 respectively. The compiler will verify that they are constants and that
20917 their values are within range.
20919 The built-in functions supported are:
20922 void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t);
20923 void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t);
20924 void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t);
20925 void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t);
20926 void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t);
20927 void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t);
20928 void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t);
20930 void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t);
20931 void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t);
20932 void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t);
20933 void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t);
20934 void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t);
20935 void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t);
20936 void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t);
20937 void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t);
20938 void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t);
20939 void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t);
20940 void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t);
20941 void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t);
20942 void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t);
20943 void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t);
20944 void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t);
20945 void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t);
20946 void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t);
20948 void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
20949 void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
20951 void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20952 void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20953 void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20955 void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20956 void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20957 void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20958 void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20960 void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20961 void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20962 void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20963 void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20964 void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20965 void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20966 void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20967 void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20968 void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20969 void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20971 void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4);
20972 void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4);
20973 void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4);
20974 void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4);
20975 void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4);
20977 void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t);
20978 void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t);
20979 void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t);
20980 void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t);
20981 void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t);
20983 void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20984 void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20985 void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20986 void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20987 void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20989 void __builtin_mma_xxmtacc (__vector_quad *);
20990 void __builtin_mma_xxmfacc (__vector_quad *);
20991 void __builtin_mma_xxsetaccz (__vector_quad *);
20993 void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t);
20994 void __builtin_mma_disassemble_acc (void *, __vector_quad *);
20996 void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t);
20997 void __builtin_vsx_disassemble_pair (void *, __vector_pair *);
20999 vec_t __builtin_vsx_xvcvspbf16 (vec_t);
21000 vec_t __builtin_vsx_xvcvbf16spn (vec_t);
21002 __vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *);
21003 void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *);
21006 @node PRU Built-in Functions
21007 @subsection PRU Built-in Functions
21009 GCC provides a couple of special builtin functions to aid in utilizing
21010 special PRU instructions.
21012 The built-in functions supported are:
21015 @item __delay_cycles (long long @var{cycles})
21016 This inserts an instruction sequence that takes exactly @var{cycles}
21017 cycles (between 0 and 0xffffffff) to complete. The inserted sequence
21018 may use jumps, loops, or no-ops, and does not interfere with any other
21019 instructions. Note that @var{cycles} must be a compile-time constant
21020 integer - that is, you must pass a number, not a variable that may be
21021 optimized to a constant later. The number of cycles delayed by this
21024 @item __halt (void)
21025 This inserts a HALT instruction to stop processor execution.
21027 @item unsigned int __lmbd (unsigned int @var{wordval}, unsigned int @var{bitval})
21028 This inserts LMBD instruction to calculate the left-most bit with value
21029 @var{bitval} in value @var{wordval}. Only the least significant bit
21030 of @var{bitval} is taken into account.
21033 @node RISC-V Built-in Functions
21034 @subsection RISC-V Built-in Functions
21036 These built-in functions are available for the RISC-V family of
21039 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
21040 Returns the value that is currently set in the @samp{tp} register.
21043 @node RX Built-in Functions
21044 @subsection RX Built-in Functions
21045 GCC supports some of the RX instructions which cannot be expressed in
21046 the C programming language via the use of built-in functions. The
21047 following functions are supported:
21049 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
21050 Generates the @code{brk} machine instruction.
21053 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
21054 Generates the @code{clrpsw} machine instruction to clear the specified
21055 bit in the processor status word.
21058 @deftypefn {Built-in Function} void __builtin_rx_int (int)
21059 Generates the @code{int} machine instruction to generate an interrupt
21060 with the specified value.
21063 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
21064 Generates the @code{machi} machine instruction to add the result of
21065 multiplying the top 16 bits of the two arguments into the
21069 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
21070 Generates the @code{maclo} machine instruction to add the result of
21071 multiplying the bottom 16 bits of the two arguments into the
21075 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
21076 Generates the @code{mulhi} machine instruction to place the result of
21077 multiplying the top 16 bits of the two arguments into the
21081 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
21082 Generates the @code{mullo} machine instruction to place the result of
21083 multiplying the bottom 16 bits of the two arguments into the
21087 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
21088 Generates the @code{mvfachi} machine instruction to read the top
21089 32 bits of the accumulator.
21092 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
21093 Generates the @code{mvfacmi} machine instruction to read the middle
21094 32 bits of the accumulator.
21097 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
21098 Generates the @code{mvfc} machine instruction which reads the control
21099 register specified in its argument and returns its value.
21102 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
21103 Generates the @code{mvtachi} machine instruction to set the top
21104 32 bits of the accumulator.
21107 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
21108 Generates the @code{mvtaclo} machine instruction to set the bottom
21109 32 bits of the accumulator.
21112 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
21113 Generates the @code{mvtc} machine instruction which sets control
21114 register number @code{reg} to @code{val}.
21117 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
21118 Generates the @code{mvtipl} machine instruction set the interrupt
21122 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
21123 Generates the @code{racw} machine instruction to round the accumulator
21124 according to the specified mode.
21127 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
21128 Generates the @code{revw} machine instruction which swaps the bytes in
21129 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
21130 and also bits 16--23 occupy bits 24--31 and vice versa.
21133 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
21134 Generates the @code{rmpa} machine instruction which initiates a
21135 repeated multiply and accumulate sequence.
21138 @deftypefn {Built-in Function} void __builtin_rx_round (float)
21139 Generates the @code{round} machine instruction which returns the
21140 floating-point argument rounded according to the current rounding mode
21141 set in the floating-point status word register.
21144 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
21145 Generates the @code{sat} machine instruction which returns the
21146 saturated value of the argument.
21149 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
21150 Generates the @code{setpsw} machine instruction to set the specified
21151 bit in the processor status word.
21154 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
21155 Generates the @code{wait} machine instruction.
21158 @node S/390 System z Built-in Functions
21159 @subsection S/390 System z Built-in Functions
21160 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
21161 Generates the @code{tbegin} machine instruction starting a
21162 non-constrained hardware transaction. If the parameter is non-NULL the
21163 memory area is used to store the transaction diagnostic buffer and
21164 will be passed as first operand to @code{tbegin}. This buffer can be
21165 defined using the @code{struct __htm_tdb} C struct defined in
21166 @code{htmintrin.h} and must reside on a double-word boundary. The
21167 second tbegin operand is set to @code{0xff0c}. This enables
21168 save/restore of all GPRs and disables aborts for FPR and AR
21169 manipulations inside the transaction body. The condition code set by
21170 the tbegin instruction is returned as integer value. The tbegin
21171 instruction by definition overwrites the content of all FPRs. The
21172 compiler will generate code which saves and restores the FPRs. For
21173 soft-float code it is recommended to used the @code{*_nofloat}
21174 variant. In order to prevent a TDB from being written it is required
21175 to pass a constant zero value as parameter. Passing a zero value
21176 through a variable is not sufficient. Although modifications of
21177 access registers inside the transaction will not trigger an
21178 transaction abort it is not supported to actually modify them. Access
21179 registers do not get saved when entering a transaction. They will have
21180 undefined state when reaching the abort code.
21183 Macros for the possible return codes of tbegin are defined in the
21184 @code{htmintrin.h} header file:
21187 @item _HTM_TBEGIN_STARTED
21188 @code{tbegin} has been executed as part of normal processing. The
21189 transaction body is supposed to be executed.
21190 @item _HTM_TBEGIN_INDETERMINATE
21191 The transaction was aborted due to an indeterminate condition which
21192 might be persistent.
21193 @item _HTM_TBEGIN_TRANSIENT
21194 The transaction aborted due to a transient failure. The transaction
21195 should be re-executed in that case.
21196 @item _HTM_TBEGIN_PERSISTENT
21197 The transaction aborted due to a persistent failure. Re-execution
21198 under same circumstances will not be productive.
21201 @defmac _HTM_FIRST_USER_ABORT_CODE
21202 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
21203 specifies the first abort code which can be used for
21204 @code{__builtin_tabort}. Values below this threshold are reserved for
21208 @deftp {Data type} {struct __htm_tdb}
21209 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
21210 the structure of the transaction diagnostic block as specified in the
21211 Principles of Operation manual chapter 5-91.
21214 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
21215 Same as @code{__builtin_tbegin} but without FPR saves and restores.
21216 Using this variant in code making use of FPRs will leave the FPRs in
21217 undefined state when entering the transaction abort handler code.
21220 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
21221 In addition to @code{__builtin_tbegin} a loop for transient failures
21222 is generated. If tbegin returns a condition code of 2 the transaction
21223 will be retried as often as specified in the second argument. The
21224 perform processor assist instruction is used to tell the CPU about the
21225 number of fails so far.
21228 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
21229 Same as @code{__builtin_tbegin_retry} but without FPR saves and
21230 restores. Using this variant in code making use of FPRs will leave
21231 the FPRs in undefined state when entering the transaction abort
21235 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
21236 Generates the @code{tbeginc} machine instruction starting a constrained
21237 hardware transaction. The second operand is set to @code{0xff08}.
21240 @deftypefn {Built-in Function} int __builtin_tend (void)
21241 Generates the @code{tend} machine instruction finishing a transaction
21242 and making the changes visible to other threads. The condition code
21243 generated by tend is returned as integer value.
21246 @deftypefn {Built-in Function} void __builtin_tabort (int)
21247 Generates the @code{tabort} machine instruction with the specified
21248 abort code. Abort codes from 0 through 255 are reserved and will
21249 result in an error message.
21252 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
21253 Generates the @code{ppa rX,rY,1} machine instruction. Where the
21254 integer parameter is loaded into rX and a value of zero is loaded into
21255 rY. The integer parameter specifies the number of times the
21256 transaction repeatedly aborted.
21259 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
21260 Generates the @code{etnd} machine instruction. The current nesting
21261 depth is returned as integer value. For a nesting depth of 0 the code
21262 is not executed as part of an transaction.
21265 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
21267 Generates the @code{ntstg} machine instruction. The second argument
21268 is written to the first arguments location. The store operation will
21269 not be rolled-back in case of an transaction abort.
21272 @node SH Built-in Functions
21273 @subsection SH Built-in Functions
21274 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
21275 families of processors:
21277 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
21278 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
21279 used by system code that manages threads and execution contexts. The compiler
21280 normally does not generate code that modifies the contents of @samp{GBR} and
21281 thus the value is preserved across function calls. Changing the @samp{GBR}
21282 value in user code must be done with caution, since the compiler might use
21283 @samp{GBR} in order to access thread local variables.
21287 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
21288 Returns the value that is currently set in the @samp{GBR} register.
21289 Memory loads and stores that use the thread pointer as a base address are
21290 turned into @samp{GBR} based displacement loads and stores, if possible.
21298 int get_tcb_value (void)
21300 // Generate @samp{mov.l @@(8,gbr),r0} instruction
21301 return ((my_tcb*)__builtin_thread_pointer ())->c;
21307 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
21308 Returns the value that is currently set in the @samp{FPSCR} register.
21311 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
21312 Sets the @samp{FPSCR} register to the specified value @var{val}, while
21313 preserving the current values of the FR, SZ and PR bits.
21316 @node SPARC VIS Built-in Functions
21317 @subsection SPARC VIS Built-in Functions
21319 GCC supports SIMD operations on the SPARC using both the generic vector
21320 extensions (@pxref{Vector Extensions}) as well as built-in functions for
21321 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
21322 switch, the VIS extension is exposed as the following built-in functions:
21325 typedef int v1si __attribute__ ((vector_size (4)));
21326 typedef int v2si __attribute__ ((vector_size (8)));
21327 typedef short v4hi __attribute__ ((vector_size (8)));
21328 typedef short v2hi __attribute__ ((vector_size (4)));
21329 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
21330 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
21332 void __builtin_vis_write_gsr (int64_t);
21333 int64_t __builtin_vis_read_gsr (void);
21335 void * __builtin_vis_alignaddr (void *, long);
21336 void * __builtin_vis_alignaddrl (void *, long);
21337 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
21338 v2si __builtin_vis_faligndatav2si (v2si, v2si);
21339 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
21340 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
21342 v4hi __builtin_vis_fexpand (v4qi);
21344 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
21345 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
21346 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
21347 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
21348 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
21349 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
21350 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
21352 v4qi __builtin_vis_fpack16 (v4hi);
21353 v8qi __builtin_vis_fpack32 (v2si, v8qi);
21354 v2hi __builtin_vis_fpackfix (v2si);
21355 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
21357 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
21359 long __builtin_vis_edge8 (void *, void *);
21360 long __builtin_vis_edge8l (void *, void *);
21361 long __builtin_vis_edge16 (void *, void *);
21362 long __builtin_vis_edge16l (void *, void *);
21363 long __builtin_vis_edge32 (void *, void *);
21364 long __builtin_vis_edge32l (void *, void *);
21366 long __builtin_vis_fcmple16 (v4hi, v4hi);
21367 long __builtin_vis_fcmple32 (v2si, v2si);
21368 long __builtin_vis_fcmpne16 (v4hi, v4hi);
21369 long __builtin_vis_fcmpne32 (v2si, v2si);
21370 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
21371 long __builtin_vis_fcmpgt32 (v2si, v2si);
21372 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
21373 long __builtin_vis_fcmpeq32 (v2si, v2si);
21375 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
21376 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
21377 v2si __builtin_vis_fpadd32 (v2si, v2si);
21378 v1si __builtin_vis_fpadd32s (v1si, v1si);
21379 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
21380 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
21381 v2si __builtin_vis_fpsub32 (v2si, v2si);
21382 v1si __builtin_vis_fpsub32s (v1si, v1si);
21384 long __builtin_vis_array8 (long, long);
21385 long __builtin_vis_array16 (long, long);
21386 long __builtin_vis_array32 (long, long);
21389 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
21390 functions also become available:
21393 long __builtin_vis_bmask (long, long);
21394 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
21395 v2si __builtin_vis_bshufflev2si (v2si, v2si);
21396 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
21397 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
21399 long __builtin_vis_edge8n (void *, void *);
21400 long __builtin_vis_edge8ln (void *, void *);
21401 long __builtin_vis_edge16n (void *, void *);
21402 long __builtin_vis_edge16ln (void *, void *);
21403 long __builtin_vis_edge32n (void *, void *);
21404 long __builtin_vis_edge32ln (void *, void *);
21407 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
21408 functions also become available:
21411 void __builtin_vis_cmask8 (long);
21412 void __builtin_vis_cmask16 (long);
21413 void __builtin_vis_cmask32 (long);
21415 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
21417 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
21418 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
21419 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
21420 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
21421 v2si __builtin_vis_fsll16 (v2si, v2si);
21422 v2si __builtin_vis_fslas16 (v2si, v2si);
21423 v2si __builtin_vis_fsrl16 (v2si, v2si);
21424 v2si __builtin_vis_fsra16 (v2si, v2si);
21426 long __builtin_vis_pdistn (v8qi, v8qi);
21428 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
21430 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
21431 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
21433 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
21434 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
21435 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
21436 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
21437 v2si __builtin_vis_fpadds32 (v2si, v2si);
21438 v1si __builtin_vis_fpadds32s (v1si, v1si);
21439 v2si __builtin_vis_fpsubs32 (v2si, v2si);
21440 v1si __builtin_vis_fpsubs32s (v1si, v1si);
21442 long __builtin_vis_fucmple8 (v8qi, v8qi);
21443 long __builtin_vis_fucmpne8 (v8qi, v8qi);
21444 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
21445 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
21447 float __builtin_vis_fhadds (float, float);
21448 double __builtin_vis_fhaddd (double, double);
21449 float __builtin_vis_fhsubs (float, float);
21450 double __builtin_vis_fhsubd (double, double);
21451 float __builtin_vis_fnhadds (float, float);
21452 double __builtin_vis_fnhaddd (double, double);
21454 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
21455 int64_t __builtin_vis_xmulx (int64_t, int64_t);
21456 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
21459 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
21460 functions also become available:
21463 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
21464 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
21465 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
21466 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
21468 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
21469 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
21470 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
21471 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
21473 long __builtin_vis_fpcmple8 (v8qi, v8qi);
21474 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
21475 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
21476 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
21477 long __builtin_vis_fpcmpule32 (v2si, v2si);
21478 long __builtin_vis_fpcmpugt32 (v2si, v2si);
21480 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
21481 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
21482 v2si __builtin_vis_fpmax32 (v2si, v2si);
21484 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
21485 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
21486 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
21488 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
21489 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
21490 v2si __builtin_vis_fpmin32 (v2si, v2si);
21492 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
21493 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
21494 v2si __builtin_vis_fpminu32 (v2si, v2si);
21497 When you use the @option{-mvis4b} switch, the VIS version 4.0B
21498 built-in functions also become available:
21501 v8qi __builtin_vis_dictunpack8 (double, int);
21502 v4hi __builtin_vis_dictunpack16 (double, int);
21503 v2si __builtin_vis_dictunpack32 (double, int);
21505 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
21506 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
21507 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
21508 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
21510 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
21511 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
21512 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
21513 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
21515 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
21516 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
21517 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
21518 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
21520 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
21521 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
21522 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
21523 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
21524 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
21525 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
21527 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
21528 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
21529 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
21531 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
21532 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
21533 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
21536 @node TI C6X Built-in Functions
21537 @subsection TI C6X Built-in Functions
21539 GCC provides intrinsics to access certain instructions of the TI C6X
21540 processors. These intrinsics, listed below, are available after
21541 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
21542 to C6X instructions.
21545 int _sadd (int, int);
21546 int _ssub (int, int);
21547 int _sadd2 (int, int);
21548 int _ssub2 (int, int);
21549 long long _mpy2 (int, int);
21550 long long _smpy2 (int, int);
21551 int _add4 (int, int);
21552 int _sub4 (int, int);
21553 int _saddu4 (int, int);
21555 int _smpy (int, int);
21556 int _smpyh (int, int);
21557 int _smpyhl (int, int);
21558 int _smpylh (int, int);
21560 int _sshl (int, int);
21561 int _subc (int, int);
21563 int _avg2 (int, int);
21564 int _avgu4 (int, int);
21566 int _clrr (int, int);
21567 int _extr (int, int);
21568 int _extru (int, int);
21573 @node x86 Built-in Functions
21574 @subsection x86 Built-in Functions
21576 These built-in functions are available for the x86-32 and x86-64 family
21577 of computers, depending on the command-line switches used.
21579 If you specify command-line switches such as @option{-msse},
21580 the compiler could use the extended instruction sets even if the built-ins
21581 are not used explicitly in the program. For this reason, applications
21582 that perform run-time CPU detection must compile separate files for each
21583 supported architecture, using the appropriate flags. In particular,
21584 the file containing the CPU detection code should be compiled without
21587 The following machine modes are available for use with MMX built-in functions
21588 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
21589 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
21590 vector of eight 8-bit integers. Some of the built-in functions operate on
21591 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
21593 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
21594 of two 32-bit floating-point values.
21596 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
21597 floating-point values. Some instructions use a vector of four 32-bit
21598 integers, these use @code{V4SI}. Finally, some instructions operate on an
21599 entire vector register, interpreting it as a 128-bit integer, these use mode
21602 The x86-32 and x86-64 family of processors use additional built-in
21603 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
21604 floating point and @code{TC} 128-bit complex floating-point values.
21606 The following floating-point built-in functions are always available. All
21607 of them implement the function that is part of the name.
21610 __float128 __builtin_fabsq (__float128)
21611 __float128 __builtin_copysignq (__float128, __float128)
21614 The following built-in functions are always available.
21617 @item __float128 __builtin_infq (void)
21618 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
21619 @findex __builtin_infq
21621 @item __float128 __builtin_huge_valq (void)
21622 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
21623 @findex __builtin_huge_valq
21625 @item __float128 __builtin_nanq (void)
21626 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
21627 @findex __builtin_nanq
21629 @item __float128 __builtin_nansq (void)
21630 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
21631 @findex __builtin_nansq
21634 The following built-in function is always available.
21637 @item void __builtin_ia32_pause (void)
21638 Generates the @code{pause} machine instruction with a compiler memory
21642 The following built-in functions are always available and can be used to
21643 check the target platform type.
21645 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
21646 This function runs the CPU detection code to check the type of CPU and the
21647 features supported. This built-in function needs to be invoked along with the built-in functions
21648 to check CPU type and features, @code{__builtin_cpu_is} and
21649 @code{__builtin_cpu_supports}, only when used in a function that is
21650 executed before any constructors are called. The CPU detection code is
21651 automatically executed in a very high priority constructor.
21653 For example, this function has to be used in @code{ifunc} resolvers that
21654 check for CPU type using the built-in functions @code{__builtin_cpu_is}
21655 and @code{__builtin_cpu_supports}, or in constructors on targets that
21656 don't support constructor priority.
21659 static void (*resolve_memcpy (void)) (void)
21661 // ifunc resolvers fire before constructors, explicitly call the init
21663 __builtin_cpu_init ();
21664 if (__builtin_cpu_supports ("ssse3"))
21665 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
21667 return default_memcpy;
21670 void *memcpy (void *, const void *, size_t)
21671 __attribute__ ((ifunc ("resolve_memcpy")));
21676 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
21677 This function returns a positive integer if the run-time CPU
21678 is of type @var{cpuname}
21679 and returns @code{0} otherwise. The following CPU names can be detected:
21692 Intel Silvermont CPU.
21701 Intel Core i7 Nehalem CPU.
21704 Intel Core i7 Westmere CPU.
21707 Intel Core i7 Sandy Bridge CPU.
21710 Intel Core i7 Ivy Bridge CPU.
21713 Intel Core i7 Haswell CPU.
21716 Intel Core i7 Broadwell CPU.
21719 Intel Core i7 Skylake CPU.
21721 @item skylake-avx512
21722 Intel Core i7 Skylake AVX512 CPU.
21725 Intel Core i7 Cannon Lake CPU.
21727 @item icelake-client
21728 Intel Core i7 Ice Lake Client CPU.
21730 @item icelake-server
21731 Intel Core i7 Ice Lake Server CPU.
21734 Intel Core i7 Cascadelake CPU.
21737 Intel Core i7 Tigerlake CPU.
21740 Intel Core i7 Cooperlake CPU.
21742 @item sapphirerapids
21743 Intel Core i7 sapphirerapids CPU.
21746 Intel Core i7 Alderlake CPU.
21749 Intel Core i7 Rocketlake CPU.
21752 Intel Atom Bonnell CPU.
21755 Intel Atom Silvermont CPU.
21758 Intel Atom Goldmont CPU.
21760 @item goldmont-plus
21761 Intel Atom Goldmont Plus CPU.
21764 Intel Atom Tremont CPU.
21767 Intel Knights Landing CPU.
21770 Intel Knights Mill CPU.
21773 ZHAOXIN lujiazui CPU.
21776 AMD Family 10h CPU.
21779 AMD Family 10h Barcelona CPU.
21782 AMD Family 10h Shanghai CPU.
21785 AMD Family 10h Istanbul CPU.
21788 AMD Family 14h CPU.
21791 AMD Family 15h CPU.
21794 AMD Family 15h Bulldozer version 1.
21797 AMD Family 15h Bulldozer version 2.
21800 AMD Family 15h Bulldozer version 3.
21803 AMD Family 15h Bulldozer version 4.
21806 AMD Family 16h CPU.
21809 AMD Family 17h CPU.
21812 AMD Family 17h Zen version 1.
21815 AMD Family 17h Zen version 2.
21818 AMD Family 19h CPU.
21821 AMD Family 19h Zen version 3.
21824 Baseline x86-64 microarchitecture level (as defined in x86-64 psABI).
21827 x86-64-v2 microarchitecture level.
21830 x86-64-v3 microarchitecture level.
21833 x86-64-v4 microarchitecture level.
21836 Here is an example:
21838 if (__builtin_cpu_is ("corei7"))
21840 do_corei7 (); // Core i7 specific implementation.
21844 do_generic (); // Generic implementation.
21849 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
21850 This function returns a positive integer if the run-time CPU
21851 supports @var{feature}
21852 and returns @code{0} otherwise. The following features can be detected:
21860 POPCNT instruction.
21868 SSSE3 instructions.
21870 SSE4.1 instructions.
21872 SSE4.2 instructions.
21878 SSE4A instructions.
21886 AVX512F instructions.
21894 PCLMUL instructions.
21896 AVX512VL instructions.
21898 AVX512BW instructions.
21900 AVX512DQ instructions.
21902 AVX512CD instructions.
21904 AVX512ER instructions.
21906 AVX512PF instructions.
21908 AVX512VBMI instructions.
21910 AVX512IFMA instructions.
21912 AVX5124VNNIW instructions.
21914 AVX5124FMAPS instructions.
21915 @item avx512vpopcntdq
21916 AVX512VPOPCNTDQ instructions.
21918 AVX512VBMI2 instructions.
21922 VPCLMULQDQ instructions.
21924 AVX512VNNI instructions.
21926 AVX512BITALG instructions.
21929 Here is an example:
21931 if (__builtin_cpu_supports ("popcnt"))
21933 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
21937 count = generic_countbits (n); //generic implementation.
21942 The following built-in functions are made available by @option{-mmmx}.
21943 All of them generate the machine instruction that is part of the name.
21946 v8qi __builtin_ia32_paddb (v8qi, v8qi);
21947 v4hi __builtin_ia32_paddw (v4hi, v4hi);
21948 v2si __builtin_ia32_paddd (v2si, v2si);
21949 v8qi __builtin_ia32_psubb (v8qi, v8qi);
21950 v4hi __builtin_ia32_psubw (v4hi, v4hi);
21951 v2si __builtin_ia32_psubd (v2si, v2si);
21952 v8qi __builtin_ia32_paddsb (v8qi, v8qi);
21953 v4hi __builtin_ia32_paddsw (v4hi, v4hi);
21954 v8qi __builtin_ia32_psubsb (v8qi, v8qi);
21955 v4hi __builtin_ia32_psubsw (v4hi, v4hi);
21956 v8qi __builtin_ia32_paddusb (v8qi, v8qi);
21957 v4hi __builtin_ia32_paddusw (v4hi, v4hi);
21958 v8qi __builtin_ia32_psubusb (v8qi, v8qi);
21959 v4hi __builtin_ia32_psubusw (v4hi, v4hi);
21960 v4hi __builtin_ia32_pmullw (v4hi, v4hi);
21961 v4hi __builtin_ia32_pmulhw (v4hi, v4hi);
21962 di __builtin_ia32_pand (di, di);
21963 di __builtin_ia32_pandn (di,di);
21964 di __builtin_ia32_por (di, di);
21965 di __builtin_ia32_pxor (di, di);
21966 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi);
21967 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi);
21968 v2si __builtin_ia32_pcmpeqd (v2si, v2si);
21969 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi);
21970 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi);
21971 v2si __builtin_ia32_pcmpgtd (v2si, v2si);
21972 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi);
21973 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi);
21974 v2si __builtin_ia32_punpckhdq (v2si, v2si);
21975 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi);
21976 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi);
21977 v2si __builtin_ia32_punpckldq (v2si, v2si);
21978 v8qi __builtin_ia32_packsswb (v4hi, v4hi);
21979 v4hi __builtin_ia32_packssdw (v2si, v2si);
21980 v8qi __builtin_ia32_packuswb (v4hi, v4hi);
21982 v4hi __builtin_ia32_psllw (v4hi, v4hi);
21983 v2si __builtin_ia32_pslld (v2si, v2si);
21984 v1di __builtin_ia32_psllq (v1di, v1di);
21985 v4hi __builtin_ia32_psrlw (v4hi, v4hi);
21986 v2si __builtin_ia32_psrld (v2si, v2si);
21987 v1di __builtin_ia32_psrlq (v1di, v1di);
21988 v4hi __builtin_ia32_psraw (v4hi, v4hi);
21989 v2si __builtin_ia32_psrad (v2si, v2si);
21990 v4hi __builtin_ia32_psllwi (v4hi, int);
21991 v2si __builtin_ia32_pslldi (v2si, int);
21992 v1di __builtin_ia32_psllqi (v1di, int);
21993 v4hi __builtin_ia32_psrlwi (v4hi, int);
21994 v2si __builtin_ia32_psrldi (v2si, int);
21995 v1di __builtin_ia32_psrlqi (v1di, int);
21996 v4hi __builtin_ia32_psrawi (v4hi, int);
21997 v2si __builtin_ia32_psradi (v2si, int);
22000 The following built-in functions are made available either with
22001 @option{-msse}, or with @option{-m3dnowa}. All of them generate
22002 the machine instruction that is part of the name.
22005 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi);
22006 v8qi __builtin_ia32_pavgb (v8qi, v8qi);
22007 v4hi __builtin_ia32_pavgw (v4hi, v4hi);
22008 v1di __builtin_ia32_psadbw (v8qi, v8qi);
22009 v8qi __builtin_ia32_pmaxub (v8qi, v8qi);
22010 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi);
22011 v8qi __builtin_ia32_pminub (v8qi, v8qi);
22012 v4hi __builtin_ia32_pminsw (v4hi, v4hi);
22013 int __builtin_ia32_pmovmskb (v8qi);
22014 void __builtin_ia32_maskmovq (v8qi, v8qi, char *);
22015 void __builtin_ia32_movntq (di *, di);
22016 void __builtin_ia32_sfence (void);
22019 The following built-in functions are available when @option{-msse} is used.
22020 All of them generate the machine instruction that is part of the name.
22023 int __builtin_ia32_comieq (v4sf, v4sf);
22024 int __builtin_ia32_comineq (v4sf, v4sf);
22025 int __builtin_ia32_comilt (v4sf, v4sf);
22026 int __builtin_ia32_comile (v4sf, v4sf);
22027 int __builtin_ia32_comigt (v4sf, v4sf);
22028 int __builtin_ia32_comige (v4sf, v4sf);
22029 int __builtin_ia32_ucomieq (v4sf, v4sf);
22030 int __builtin_ia32_ucomineq (v4sf, v4sf);
22031 int __builtin_ia32_ucomilt (v4sf, v4sf);
22032 int __builtin_ia32_ucomile (v4sf, v4sf);
22033 int __builtin_ia32_ucomigt (v4sf, v4sf);
22034 int __builtin_ia32_ucomige (v4sf, v4sf);
22035 v4sf __builtin_ia32_addps (v4sf, v4sf);
22036 v4sf __builtin_ia32_subps (v4sf, v4sf);
22037 v4sf __builtin_ia32_mulps (v4sf, v4sf);
22038 v4sf __builtin_ia32_divps (v4sf, v4sf);
22039 v4sf __builtin_ia32_addss (v4sf, v4sf);
22040 v4sf __builtin_ia32_subss (v4sf, v4sf);
22041 v4sf __builtin_ia32_mulss (v4sf, v4sf);
22042 v4sf __builtin_ia32_divss (v4sf, v4sf);
22043 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf);
22044 v4sf __builtin_ia32_cmpltps (v4sf, v4sf);
22045 v4sf __builtin_ia32_cmpleps (v4sf, v4sf);
22046 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf);
22047 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf);
22048 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf);
22049 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf);
22050 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf);
22051 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf);
22052 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf);
22053 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf);
22054 v4sf __builtin_ia32_cmpordps (v4sf, v4sf);
22055 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf);
22056 v4sf __builtin_ia32_cmpltss (v4sf, v4sf);
22057 v4sf __builtin_ia32_cmpless (v4sf, v4sf);
22058 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf);
22059 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf);
22060 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf);
22061 v4sf __builtin_ia32_cmpnless (v4sf, v4sf);
22062 v4sf __builtin_ia32_cmpordss (v4sf, v4sf);
22063 v4sf __builtin_ia32_maxps (v4sf, v4sf);
22064 v4sf __builtin_ia32_maxss (v4sf, v4sf);
22065 v4sf __builtin_ia32_minps (v4sf, v4sf);
22066 v4sf __builtin_ia32_minss (v4sf, v4sf);
22067 v4sf __builtin_ia32_andps (v4sf, v4sf);
22068 v4sf __builtin_ia32_andnps (v4sf, v4sf);
22069 v4sf __builtin_ia32_orps (v4sf, v4sf);
22070 v4sf __builtin_ia32_xorps (v4sf, v4sf);
22071 v4sf __builtin_ia32_movss (v4sf, v4sf);
22072 v4sf __builtin_ia32_movhlps (v4sf, v4sf);
22073 v4sf __builtin_ia32_movlhps (v4sf, v4sf);
22074 v4sf __builtin_ia32_unpckhps (v4sf, v4sf);
22075 v4sf __builtin_ia32_unpcklps (v4sf, v4sf);
22076 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si);
22077 v4sf __builtin_ia32_cvtsi2ss (v4sf, int);
22078 v2si __builtin_ia32_cvtps2pi (v4sf);
22079 int __builtin_ia32_cvtss2si (v4sf);
22080 v2si __builtin_ia32_cvttps2pi (v4sf);
22081 int __builtin_ia32_cvttss2si (v4sf);
22082 v4sf __builtin_ia32_rcpps (v4sf);
22083 v4sf __builtin_ia32_rsqrtps (v4sf);
22084 v4sf __builtin_ia32_sqrtps (v4sf);
22085 v4sf __builtin_ia32_rcpss (v4sf);
22086 v4sf __builtin_ia32_rsqrtss (v4sf);
22087 v4sf __builtin_ia32_sqrtss (v4sf);
22088 v4sf __builtin_ia32_shufps (v4sf, v4sf, int);
22089 void __builtin_ia32_movntps (float *, v4sf);
22090 int __builtin_ia32_movmskps (v4sf);
22093 The following built-in functions are available when @option{-msse} is used.
22096 @item v4sf __builtin_ia32_loadups (float *)
22097 Generates the @code{movups} machine instruction as a load from memory.
22098 @item void __builtin_ia32_storeups (float *, v4sf)
22099 Generates the @code{movups} machine instruction as a store to memory.
22100 @item v4sf __builtin_ia32_loadss (float *)
22101 Generates the @code{movss} machine instruction as a load from memory.
22102 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
22103 Generates the @code{movhps} machine instruction as a load from memory.
22104 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
22105 Generates the @code{movlps} machine instruction as a load from memory
22106 @item void __builtin_ia32_storehps (v2sf *, v4sf)
22107 Generates the @code{movhps} machine instruction as a store to memory.
22108 @item void __builtin_ia32_storelps (v2sf *, v4sf)
22109 Generates the @code{movlps} machine instruction as a store to memory.
22112 The following built-in functions are available when @option{-msse2} is used.
22113 All of them generate the machine instruction that is part of the name.
22116 int __builtin_ia32_comisdeq (v2df, v2df);
22117 int __builtin_ia32_comisdlt (v2df, v2df);
22118 int __builtin_ia32_comisdle (v2df, v2df);
22119 int __builtin_ia32_comisdgt (v2df, v2df);
22120 int __builtin_ia32_comisdge (v2df, v2df);
22121 int __builtin_ia32_comisdneq (v2df, v2df);
22122 int __builtin_ia32_ucomisdeq (v2df, v2df);
22123 int __builtin_ia32_ucomisdlt (v2df, v2df);
22124 int __builtin_ia32_ucomisdle (v2df, v2df);
22125 int __builtin_ia32_ucomisdgt (v2df, v2df);
22126 int __builtin_ia32_ucomisdge (v2df, v2df);
22127 int __builtin_ia32_ucomisdneq (v2df, v2df);
22128 v2df __builtin_ia32_cmpeqpd (v2df, v2df);
22129 v2df __builtin_ia32_cmpltpd (v2df, v2df);
22130 v2df __builtin_ia32_cmplepd (v2df, v2df);
22131 v2df __builtin_ia32_cmpgtpd (v2df, v2df);
22132 v2df __builtin_ia32_cmpgepd (v2df, v2df);
22133 v2df __builtin_ia32_cmpunordpd (v2df, v2df);
22134 v2df __builtin_ia32_cmpneqpd (v2df, v2df);
22135 v2df __builtin_ia32_cmpnltpd (v2df, v2df);
22136 v2df __builtin_ia32_cmpnlepd (v2df, v2df);
22137 v2df __builtin_ia32_cmpngtpd (v2df, v2df);
22138 v2df __builtin_ia32_cmpngepd (v2df, v2df);
22139 v2df __builtin_ia32_cmpordpd (v2df, v2df);
22140 v2df __builtin_ia32_cmpeqsd (v2df, v2df);
22141 v2df __builtin_ia32_cmpltsd (v2df, v2df);
22142 v2df __builtin_ia32_cmplesd (v2df, v2df);
22143 v2df __builtin_ia32_cmpunordsd (v2df, v2df);
22144 v2df __builtin_ia32_cmpneqsd (v2df, v2df);
22145 v2df __builtin_ia32_cmpnltsd (v2df, v2df);
22146 v2df __builtin_ia32_cmpnlesd (v2df, v2df);
22147 v2df __builtin_ia32_cmpordsd (v2df, v2df);
22148 v2di __builtin_ia32_paddq (v2di, v2di);
22149 v2di __builtin_ia32_psubq (v2di, v2di);
22150 v2df __builtin_ia32_addpd (v2df, v2df);
22151 v2df __builtin_ia32_subpd (v2df, v2df);
22152 v2df __builtin_ia32_mulpd (v2df, v2df);
22153 v2df __builtin_ia32_divpd (v2df, v2df);
22154 v2df __builtin_ia32_addsd (v2df, v2df);
22155 v2df __builtin_ia32_subsd (v2df, v2df);
22156 v2df __builtin_ia32_mulsd (v2df, v2df);
22157 v2df __builtin_ia32_divsd (v2df, v2df);
22158 v2df __builtin_ia32_minpd (v2df, v2df);
22159 v2df __builtin_ia32_maxpd (v2df, v2df);
22160 v2df __builtin_ia32_minsd (v2df, v2df);
22161 v2df __builtin_ia32_maxsd (v2df, v2df);
22162 v2df __builtin_ia32_andpd (v2df, v2df);
22163 v2df __builtin_ia32_andnpd (v2df, v2df);
22164 v2df __builtin_ia32_orpd (v2df, v2df);
22165 v2df __builtin_ia32_xorpd (v2df, v2df);
22166 v2df __builtin_ia32_movsd (v2df, v2df);
22167 v2df __builtin_ia32_unpckhpd (v2df, v2df);
22168 v2df __builtin_ia32_unpcklpd (v2df, v2df);
22169 v16qi __builtin_ia32_paddb128 (v16qi, v16qi);
22170 v8hi __builtin_ia32_paddw128 (v8hi, v8hi);
22171 v4si __builtin_ia32_paddd128 (v4si, v4si);
22172 v2di __builtin_ia32_paddq128 (v2di, v2di);
22173 v16qi __builtin_ia32_psubb128 (v16qi, v16qi);
22174 v8hi __builtin_ia32_psubw128 (v8hi, v8hi);
22175 v4si __builtin_ia32_psubd128 (v4si, v4si);
22176 v2di __builtin_ia32_psubq128 (v2di, v2di);
22177 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi);
22178 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi);
22179 v2di __builtin_ia32_pand128 (v2di, v2di);
22180 v2di __builtin_ia32_pandn128 (v2di, v2di);
22181 v2di __builtin_ia32_por128 (v2di, v2di);
22182 v2di __builtin_ia32_pxor128 (v2di, v2di);
22183 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi);
22184 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi);
22185 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi);
22186 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi);
22187 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si);
22188 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi);
22189 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi);
22190 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si);
22191 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi);
22192 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi);
22193 v16qi __builtin_ia32_pminub128 (v16qi, v16qi);
22194 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi);
22195 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi);
22196 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi);
22197 v4si __builtin_ia32_punpckhdq128 (v4si, v4si);
22198 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di);
22199 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi);
22200 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi);
22201 v4si __builtin_ia32_punpckldq128 (v4si, v4si);
22202 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di);
22203 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi);
22204 v8hi __builtin_ia32_packssdw128 (v4si, v4si);
22205 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi);
22206 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi);
22207 void __builtin_ia32_maskmovdqu (v16qi, v16qi);
22208 v2df __builtin_ia32_loadupd (double *);
22209 void __builtin_ia32_storeupd (double *, v2df);
22210 v2df __builtin_ia32_loadhpd (v2df, double const *);
22211 v2df __builtin_ia32_loadlpd (v2df, double const *);
22212 int __builtin_ia32_movmskpd (v2df);
22213 int __builtin_ia32_pmovmskb128 (v16qi);
22214 void __builtin_ia32_movnti (int *, int);
22215 void __builtin_ia32_movnti64 (long long int *, long long int);
22216 void __builtin_ia32_movntpd (double *, v2df);
22217 void __builtin_ia32_movntdq (v2df *, v2df);
22218 v4si __builtin_ia32_pshufd (v4si, int);
22219 v8hi __builtin_ia32_pshuflw (v8hi, int);
22220 v8hi __builtin_ia32_pshufhw (v8hi, int);
22221 v2di __builtin_ia32_psadbw128 (v16qi, v16qi);
22222 v2df __builtin_ia32_sqrtpd (v2df);
22223 v2df __builtin_ia32_sqrtsd (v2df);
22224 v2df __builtin_ia32_shufpd (v2df, v2df, int);
22225 v2df __builtin_ia32_cvtdq2pd (v4si);
22226 v4sf __builtin_ia32_cvtdq2ps (v4si);
22227 v4si __builtin_ia32_cvtpd2dq (v2df);
22228 v2si __builtin_ia32_cvtpd2pi (v2df);
22229 v4sf __builtin_ia32_cvtpd2ps (v2df);
22230 v4si __builtin_ia32_cvttpd2dq (v2df);
22231 v2si __builtin_ia32_cvttpd2pi (v2df);
22232 v2df __builtin_ia32_cvtpi2pd (v2si);
22233 int __builtin_ia32_cvtsd2si (v2df);
22234 int __builtin_ia32_cvttsd2si (v2df);
22235 long long __builtin_ia32_cvtsd2si64 (v2df);
22236 long long __builtin_ia32_cvttsd2si64 (v2df);
22237 v4si __builtin_ia32_cvtps2dq (v4sf);
22238 v2df __builtin_ia32_cvtps2pd (v4sf);
22239 v4si __builtin_ia32_cvttps2dq (v4sf);
22240 v2df __builtin_ia32_cvtsi2sd (v2df, int);
22241 v2df __builtin_ia32_cvtsi642sd (v2df, long long);
22242 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df);
22243 v2df __builtin_ia32_cvtss2sd (v2df, v4sf);
22244 void __builtin_ia32_clflush (const void *);
22245 void __builtin_ia32_lfence (void);
22246 void __builtin_ia32_mfence (void);
22247 v16qi __builtin_ia32_loaddqu (const char *);
22248 void __builtin_ia32_storedqu (char *, v16qi);
22249 v1di __builtin_ia32_pmuludq (v2si, v2si);
22250 v2di __builtin_ia32_pmuludq128 (v4si, v4si);
22251 v8hi __builtin_ia32_psllw128 (v8hi, v8hi);
22252 v4si __builtin_ia32_pslld128 (v4si, v4si);
22253 v2di __builtin_ia32_psllq128 (v2di, v2di);
22254 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi);
22255 v4si __builtin_ia32_psrld128 (v4si, v4si);
22256 v2di __builtin_ia32_psrlq128 (v2di, v2di);
22257 v8hi __builtin_ia32_psraw128 (v8hi, v8hi);
22258 v4si __builtin_ia32_psrad128 (v4si, v4si);
22259 v2di __builtin_ia32_pslldqi128 (v2di, int);
22260 v8hi __builtin_ia32_psllwi128 (v8hi, int);
22261 v4si __builtin_ia32_pslldi128 (v4si, int);
22262 v2di __builtin_ia32_psllqi128 (v2di, int);
22263 v2di __builtin_ia32_psrldqi128 (v2di, int);
22264 v8hi __builtin_ia32_psrlwi128 (v8hi, int);
22265 v4si __builtin_ia32_psrldi128 (v4si, int);
22266 v2di __builtin_ia32_psrlqi128 (v2di, int);
22267 v8hi __builtin_ia32_psrawi128 (v8hi, int);
22268 v4si __builtin_ia32_psradi128 (v4si, int);
22269 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi);
22270 v2di __builtin_ia32_movq128 (v2di);
22273 The following built-in functions are available when @option{-msse3} is used.
22274 All of them generate the machine instruction that is part of the name.
22277 v2df __builtin_ia32_addsubpd (v2df, v2df);
22278 v4sf __builtin_ia32_addsubps (v4sf, v4sf);
22279 v2df __builtin_ia32_haddpd (v2df, v2df);
22280 v4sf __builtin_ia32_haddps (v4sf, v4sf);
22281 v2df __builtin_ia32_hsubpd (v2df, v2df);
22282 v4sf __builtin_ia32_hsubps (v4sf, v4sf);
22283 v16qi __builtin_ia32_lddqu (char const *);
22284 void __builtin_ia32_monitor (void *, unsigned int, unsigned int);
22285 v4sf __builtin_ia32_movshdup (v4sf);
22286 v4sf __builtin_ia32_movsldup (v4sf);
22287 void __builtin_ia32_mwait (unsigned int, unsigned int);
22290 The following built-in functions are available when @option{-mssse3} is used.
22291 All of them generate the machine instruction that is part of the name.
22294 v2si __builtin_ia32_phaddd (v2si, v2si);
22295 v4hi __builtin_ia32_phaddw (v4hi, v4hi);
22296 v4hi __builtin_ia32_phaddsw (v4hi, v4hi);
22297 v2si __builtin_ia32_phsubd (v2si, v2si);
22298 v4hi __builtin_ia32_phsubw (v4hi, v4hi);
22299 v4hi __builtin_ia32_phsubsw (v4hi, v4hi);
22300 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi);
22301 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi);
22302 v8qi __builtin_ia32_pshufb (v8qi, v8qi);
22303 v8qi __builtin_ia32_psignb (v8qi, v8qi);
22304 v2si __builtin_ia32_psignd (v2si, v2si);
22305 v4hi __builtin_ia32_psignw (v4hi, v4hi);
22306 v1di __builtin_ia32_palignr (v1di, v1di, int);
22307 v8qi __builtin_ia32_pabsb (v8qi);
22308 v2si __builtin_ia32_pabsd (v2si);
22309 v4hi __builtin_ia32_pabsw (v4hi);
22312 The following built-in functions are available when @option{-mssse3} is used.
22313 All of them generate the machine instruction that is part of the name.
22316 v4si __builtin_ia32_phaddd128 (v4si, v4si);
22317 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi);
22318 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi);
22319 v4si __builtin_ia32_phsubd128 (v4si, v4si);
22320 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi);
22321 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi);
22322 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi);
22323 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi);
22324 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi);
22325 v16qi __builtin_ia32_psignb128 (v16qi, v16qi);
22326 v4si __builtin_ia32_psignd128 (v4si, v4si);
22327 v8hi __builtin_ia32_psignw128 (v8hi, v8hi);
22328 v2di __builtin_ia32_palignr128 (v2di, v2di, int);
22329 v16qi __builtin_ia32_pabsb128 (v16qi);
22330 v4si __builtin_ia32_pabsd128 (v4si);
22331 v8hi __builtin_ia32_pabsw128 (v8hi);
22334 The following built-in functions are available when @option{-msse4.1} is
22335 used. All of them generate the machine instruction that is part of the
22339 v2df __builtin_ia32_blendpd (v2df, v2df, const int);
22340 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int);
22341 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df);
22342 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf);
22343 v2df __builtin_ia32_dppd (v2df, v2df, const int);
22344 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int);
22345 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int);
22346 v2di __builtin_ia32_movntdqa (v2di *);
22347 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int);
22348 v8hi __builtin_ia32_packusdw128 (v4si, v4si);
22349 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi);
22350 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int);
22351 v2di __builtin_ia32_pcmpeqq (v2di, v2di);
22352 v8hi __builtin_ia32_phminposuw128 (v8hi);
22353 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi);
22354 v4si __builtin_ia32_pmaxsd128 (v4si, v4si);
22355 v4si __builtin_ia32_pmaxud128 (v4si, v4si);
22356 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi);
22357 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi);
22358 v4si __builtin_ia32_pminsd128 (v4si, v4si);
22359 v4si __builtin_ia32_pminud128 (v4si, v4si);
22360 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi);
22361 v4si __builtin_ia32_pmovsxbd128 (v16qi);
22362 v2di __builtin_ia32_pmovsxbq128 (v16qi);
22363 v8hi __builtin_ia32_pmovsxbw128 (v16qi);
22364 v2di __builtin_ia32_pmovsxdq128 (v4si);
22365 v4si __builtin_ia32_pmovsxwd128 (v8hi);
22366 v2di __builtin_ia32_pmovsxwq128 (v8hi);
22367 v4si __builtin_ia32_pmovzxbd128 (v16qi);
22368 v2di __builtin_ia32_pmovzxbq128 (v16qi);
22369 v8hi __builtin_ia32_pmovzxbw128 (v16qi);
22370 v2di __builtin_ia32_pmovzxdq128 (v4si);
22371 v4si __builtin_ia32_pmovzxwd128 (v8hi);
22372 v2di __builtin_ia32_pmovzxwq128 (v8hi);
22373 v2di __builtin_ia32_pmuldq128 (v4si, v4si);
22374 v4si __builtin_ia32_pmulld128 (v4si, v4si);
22375 int __builtin_ia32_ptestc128 (v2di, v2di);
22376 int __builtin_ia32_ptestnzc128 (v2di, v2di);
22377 int __builtin_ia32_ptestz128 (v2di, v2di);
22378 v2df __builtin_ia32_roundpd (v2df, const int);
22379 v4sf __builtin_ia32_roundps (v4sf, const int);
22380 v2df __builtin_ia32_roundsd (v2df, v2df, const int);
22381 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int);
22384 The following built-in functions are available when @option{-msse4.1} is
22388 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
22389 Generates the @code{insertps} machine instruction.
22390 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
22391 Generates the @code{pextrb} machine instruction.
22392 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
22393 Generates the @code{pinsrb} machine instruction.
22394 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
22395 Generates the @code{pinsrd} machine instruction.
22396 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
22397 Generates the @code{pinsrq} machine instruction in 64bit mode.
22400 The following built-in functions are changed to generate new SSE4.1
22401 instructions when @option{-msse4.1} is used.
22404 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
22405 Generates the @code{extractps} machine instruction.
22406 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
22407 Generates the @code{pextrd} machine instruction.
22408 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
22409 Generates the @code{pextrq} machine instruction in 64bit mode.
22412 The following built-in functions are available when @option{-msse4.2} is
22413 used. All of them generate the machine instruction that is part of the
22417 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int);
22418 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int);
22419 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int);
22420 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int);
22421 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int);
22422 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int);
22423 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int);
22424 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int);
22425 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int);
22426 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int);
22427 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int);
22428 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int);
22429 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int);
22430 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int);
22431 v2di __builtin_ia32_pcmpgtq (v2di, v2di);
22434 The following built-in functions are available when @option{-msse4.2} is
22438 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
22439 Generates the @code{crc32b} machine instruction.
22440 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
22441 Generates the @code{crc32w} machine instruction.
22442 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
22443 Generates the @code{crc32l} machine instruction.
22444 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
22445 Generates the @code{crc32q} machine instruction.
22448 The following built-in functions are changed to generate new SSE4.2
22449 instructions when @option{-msse4.2} is used.
22452 @item int __builtin_popcount (unsigned int)
22453 Generates the @code{popcntl} machine instruction.
22454 @item int __builtin_popcountl (unsigned long)
22455 Generates the @code{popcntl} or @code{popcntq} machine instruction,
22456 depending on the size of @code{unsigned long}.
22457 @item int __builtin_popcountll (unsigned long long)
22458 Generates the @code{popcntq} machine instruction.
22461 The following built-in functions are available when @option{-mavx} is
22462 used. All of them generate the machine instruction that is part of the
22466 v4df __builtin_ia32_addpd256 (v4df,v4df);
22467 v8sf __builtin_ia32_addps256 (v8sf,v8sf);
22468 v4df __builtin_ia32_addsubpd256 (v4df,v4df);
22469 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf);
22470 v4df __builtin_ia32_andnpd256 (v4df,v4df);
22471 v8sf __builtin_ia32_andnps256 (v8sf,v8sf);
22472 v4df __builtin_ia32_andpd256 (v4df,v4df);
22473 v8sf __builtin_ia32_andps256 (v8sf,v8sf);
22474 v4df __builtin_ia32_blendpd256 (v4df,v4df,int);
22475 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int);
22476 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df);
22477 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf);
22478 v2df __builtin_ia32_cmppd (v2df,v2df,int);
22479 v4df __builtin_ia32_cmppd256 (v4df,v4df,int);
22480 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int);
22481 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int);
22482 v2df __builtin_ia32_cmpsd (v2df,v2df,int);
22483 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int);
22484 v4df __builtin_ia32_cvtdq2pd256 (v4si);
22485 v8sf __builtin_ia32_cvtdq2ps256 (v8si);
22486 v4si __builtin_ia32_cvtpd2dq256 (v4df);
22487 v4sf __builtin_ia32_cvtpd2ps256 (v4df);
22488 v8si __builtin_ia32_cvtps2dq256 (v8sf);
22489 v4df __builtin_ia32_cvtps2pd256 (v4sf);
22490 v4si __builtin_ia32_cvttpd2dq256 (v4df);
22491 v8si __builtin_ia32_cvttps2dq256 (v8sf);
22492 v4df __builtin_ia32_divpd256 (v4df,v4df);
22493 v8sf __builtin_ia32_divps256 (v8sf,v8sf);
22494 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int);
22495 v4df __builtin_ia32_haddpd256 (v4df,v4df);
22496 v8sf __builtin_ia32_haddps256 (v8sf,v8sf);
22497 v4df __builtin_ia32_hsubpd256 (v4df,v4df);
22498 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf);
22499 v32qi __builtin_ia32_lddqu256 (pcchar);
22500 v32qi __builtin_ia32_loaddqu256 (pcchar);
22501 v4df __builtin_ia32_loadupd256 (pcdouble);
22502 v8sf __builtin_ia32_loadups256 (pcfloat);
22503 v2df __builtin_ia32_maskloadpd (pcv2df,v2df);
22504 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df);
22505 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf);
22506 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf);
22507 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df);
22508 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df);
22509 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf);
22510 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf);
22511 v4df __builtin_ia32_maxpd256 (v4df,v4df);
22512 v8sf __builtin_ia32_maxps256 (v8sf,v8sf);
22513 v4df __builtin_ia32_minpd256 (v4df,v4df);
22514 v8sf __builtin_ia32_minps256 (v8sf,v8sf);
22515 v4df __builtin_ia32_movddup256 (v4df);
22516 int __builtin_ia32_movmskpd256 (v4df);
22517 int __builtin_ia32_movmskps256 (v8sf);
22518 v8sf __builtin_ia32_movshdup256 (v8sf);
22519 v8sf __builtin_ia32_movsldup256 (v8sf);
22520 v4df __builtin_ia32_mulpd256 (v4df,v4df);
22521 v8sf __builtin_ia32_mulps256 (v8sf,v8sf);
22522 v4df __builtin_ia32_orpd256 (v4df,v4df);
22523 v8sf __builtin_ia32_orps256 (v8sf,v8sf);
22524 v2df __builtin_ia32_pd_pd256 (v4df);
22525 v4df __builtin_ia32_pd256_pd (v2df);
22526 v4sf __builtin_ia32_ps_ps256 (v8sf);
22527 v8sf __builtin_ia32_ps256_ps (v4sf);
22528 int __builtin_ia32_ptestc256 (v4di,v4di,ptest);
22529 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest);
22530 int __builtin_ia32_ptestz256 (v4di,v4di,ptest);
22531 v8sf __builtin_ia32_rcpps256 (v8sf);
22532 v4df __builtin_ia32_roundpd256 (v4df,int);
22533 v8sf __builtin_ia32_roundps256 (v8sf,int);
22534 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf);
22535 v8sf __builtin_ia32_rsqrtps256 (v8sf);
22536 v4df __builtin_ia32_shufpd256 (v4df,v4df,int);
22537 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int);
22538 v4si __builtin_ia32_si_si256 (v8si);
22539 v8si __builtin_ia32_si256_si (v4si);
22540 v4df __builtin_ia32_sqrtpd256 (v4df);
22541 v8sf __builtin_ia32_sqrtps_nr256 (v8sf);
22542 v8sf __builtin_ia32_sqrtps256 (v8sf);
22543 void __builtin_ia32_storedqu256 (pchar,v32qi);
22544 void __builtin_ia32_storeupd256 (pdouble,v4df);
22545 void __builtin_ia32_storeups256 (pfloat,v8sf);
22546 v4df __builtin_ia32_subpd256 (v4df,v4df);
22547 v8sf __builtin_ia32_subps256 (v8sf,v8sf);
22548 v4df __builtin_ia32_unpckhpd256 (v4df,v4df);
22549 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf);
22550 v4df __builtin_ia32_unpcklpd256 (v4df,v4df);
22551 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf);
22552 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df);
22553 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf);
22554 v4df __builtin_ia32_vbroadcastsd256 (pcdouble);
22555 v4sf __builtin_ia32_vbroadcastss (pcfloat);
22556 v8sf __builtin_ia32_vbroadcastss256 (pcfloat);
22557 v2df __builtin_ia32_vextractf128_pd256 (v4df,int);
22558 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int);
22559 v4si __builtin_ia32_vextractf128_si256 (v8si,int);
22560 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int);
22561 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int);
22562 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int);
22563 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int);
22564 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int);
22565 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int);
22566 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int);
22567 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int);
22568 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int);
22569 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int);
22570 v2df __builtin_ia32_vpermilpd (v2df,int);
22571 v4df __builtin_ia32_vpermilpd256 (v4df,int);
22572 v4sf __builtin_ia32_vpermilps (v4sf,int);
22573 v8sf __builtin_ia32_vpermilps256 (v8sf,int);
22574 v2df __builtin_ia32_vpermilvarpd (v2df,v2di);
22575 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di);
22576 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si);
22577 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si);
22578 int __builtin_ia32_vtestcpd (v2df,v2df,ptest);
22579 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest);
22580 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest);
22581 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest);
22582 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest);
22583 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest);
22584 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest);
22585 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest);
22586 int __builtin_ia32_vtestzpd (v2df,v2df,ptest);
22587 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest);
22588 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest);
22589 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest);
22590 void __builtin_ia32_vzeroall (void);
22591 void __builtin_ia32_vzeroupper (void);
22592 v4df __builtin_ia32_xorpd256 (v4df,v4df);
22593 v8sf __builtin_ia32_xorps256 (v8sf,v8sf);
22596 The following built-in functions are available when @option{-mavx2} is
22597 used. All of them generate the machine instruction that is part of the
22601 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int);
22602 v32qi __builtin_ia32_pabsb256 (v32qi);
22603 v16hi __builtin_ia32_pabsw256 (v16hi);
22604 v8si __builtin_ia32_pabsd256 (v8si);
22605 v16hi __builtin_ia32_packssdw256 (v8si,v8si);
22606 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi);
22607 v16hi __builtin_ia32_packusdw256 (v8si,v8si);
22608 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi);
22609 v32qi __builtin_ia32_paddb256 (v32qi,v32qi);
22610 v16hi __builtin_ia32_paddw256 (v16hi,v16hi);
22611 v8si __builtin_ia32_paddd256 (v8si,v8si);
22612 v4di __builtin_ia32_paddq256 (v4di,v4di);
22613 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi);
22614 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi);
22615 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi);
22616 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi);
22617 v4di __builtin_ia32_palignr256 (v4di,v4di,int);
22618 v4di __builtin_ia32_andsi256 (v4di,v4di);
22619 v4di __builtin_ia32_andnotsi256 (v4di,v4di);
22620 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi);
22621 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi);
22622 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi);
22623 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int);
22624 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi);
22625 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi);
22626 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si);
22627 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di);
22628 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi);
22629 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi);
22630 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si);
22631 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di);
22632 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi);
22633 v8si __builtin_ia32_phaddd256 (v8si,v8si);
22634 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi);
22635 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi);
22636 v8si __builtin_ia32_phsubd256 (v8si,v8si);
22637 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi);
22638 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi);
22639 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi);
22640 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi);
22641 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi);
22642 v8si __builtin_ia32_pmaxsd256 (v8si,v8si);
22643 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi);
22644 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi);
22645 v8si __builtin_ia32_pmaxud256 (v8si,v8si);
22646 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi);
22647 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi);
22648 v8si __builtin_ia32_pminsd256 (v8si,v8si);
22649 v32qi __builtin_ia32_pminub256 (v32qi,v32qi);
22650 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi);
22651 v8si __builtin_ia32_pminud256 (v8si,v8si);
22652 int __builtin_ia32_pmovmskb256 (v32qi);
22653 v16hi __builtin_ia32_pmovsxbw256 (v16qi);
22654 v8si __builtin_ia32_pmovsxbd256 (v16qi);
22655 v4di __builtin_ia32_pmovsxbq256 (v16qi);
22656 v8si __builtin_ia32_pmovsxwd256 (v8hi);
22657 v4di __builtin_ia32_pmovsxwq256 (v8hi);
22658 v4di __builtin_ia32_pmovsxdq256 (v4si);
22659 v16hi __builtin_ia32_pmovzxbw256 (v16qi);
22660 v8si __builtin_ia32_pmovzxbd256 (v16qi);
22661 v4di __builtin_ia32_pmovzxbq256 (v16qi);
22662 v8si __builtin_ia32_pmovzxwd256 (v8hi);
22663 v4di __builtin_ia32_pmovzxwq256 (v8hi);
22664 v4di __builtin_ia32_pmovzxdq256 (v4si);
22665 v4di __builtin_ia32_pmuldq256 (v8si,v8si);
22666 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi);
22667 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi);
22668 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi);
22669 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi);
22670 v8si __builtin_ia32_pmulld256 (v8si,v8si);
22671 v4di __builtin_ia32_pmuludq256 (v8si,v8si);
22672 v4di __builtin_ia32_por256 (v4di,v4di);
22673 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi);
22674 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi);
22675 v8si __builtin_ia32_pshufd256 (v8si,int);
22676 v16hi __builtin_ia32_pshufhw256 (v16hi,int);
22677 v16hi __builtin_ia32_pshuflw256 (v16hi,int);
22678 v32qi __builtin_ia32_psignb256 (v32qi,v32qi);
22679 v16hi __builtin_ia32_psignw256 (v16hi,v16hi);
22680 v8si __builtin_ia32_psignd256 (v8si,v8si);
22681 v4di __builtin_ia32_pslldqi256 (v4di,int);
22682 v16hi __builtin_ia32_psllwi256 (16hi,int);
22683 v16hi __builtin_ia32_psllw256(v16hi,v8hi);
22684 v8si __builtin_ia32_pslldi256 (v8si,int);
22685 v8si __builtin_ia32_pslld256(v8si,v4si);
22686 v4di __builtin_ia32_psllqi256 (v4di,int);
22687 v4di __builtin_ia32_psllq256(v4di,v2di);
22688 v16hi __builtin_ia32_psrawi256 (v16hi,int);
22689 v16hi __builtin_ia32_psraw256 (v16hi,v8hi);
22690 v8si __builtin_ia32_psradi256 (v8si,int);
22691 v8si __builtin_ia32_psrad256 (v8si,v4si);
22692 v4di __builtin_ia32_psrldqi256 (v4di, int);
22693 v16hi __builtin_ia32_psrlwi256 (v16hi,int);
22694 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi);
22695 v8si __builtin_ia32_psrldi256 (v8si,int);
22696 v8si __builtin_ia32_psrld256 (v8si,v4si);
22697 v4di __builtin_ia32_psrlqi256 (v4di,int);
22698 v4di __builtin_ia32_psrlq256(v4di,v2di);
22699 v32qi __builtin_ia32_psubb256 (v32qi,v32qi);
22700 v32hi __builtin_ia32_psubw256 (v16hi,v16hi);
22701 v8si __builtin_ia32_psubd256 (v8si,v8si);
22702 v4di __builtin_ia32_psubq256 (v4di,v4di);
22703 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi);
22704 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi);
22705 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi);
22706 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi);
22707 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi);
22708 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi);
22709 v8si __builtin_ia32_punpckhdq256 (v8si,v8si);
22710 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di);
22711 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi);
22712 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi);
22713 v8si __builtin_ia32_punpckldq256 (v8si,v8si);
22714 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di);
22715 v4di __builtin_ia32_pxor256 (v4di,v4di);
22716 v4di __builtin_ia32_movntdqa256 (pv4di);
22717 v4sf __builtin_ia32_vbroadcastss_ps (v4sf);
22718 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf);
22719 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df);
22720 v4di __builtin_ia32_vbroadcastsi256 (v2di);
22721 v4si __builtin_ia32_pblendd128 (v4si,v4si);
22722 v8si __builtin_ia32_pblendd256 (v8si,v8si);
22723 v32qi __builtin_ia32_pbroadcastb256 (v16qi);
22724 v16hi __builtin_ia32_pbroadcastw256 (v8hi);
22725 v8si __builtin_ia32_pbroadcastd256 (v4si);
22726 v4di __builtin_ia32_pbroadcastq256 (v2di);
22727 v16qi __builtin_ia32_pbroadcastb128 (v16qi);
22728 v8hi __builtin_ia32_pbroadcastw128 (v8hi);
22729 v4si __builtin_ia32_pbroadcastd128 (v4si);
22730 v2di __builtin_ia32_pbroadcastq128 (v2di);
22731 v8si __builtin_ia32_permvarsi256 (v8si,v8si);
22732 v4df __builtin_ia32_permdf256 (v4df,int);
22733 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf);
22734 v4di __builtin_ia32_permdi256 (v4di,int);
22735 v4di __builtin_ia32_permti256 (v4di,v4di,int);
22736 v4di __builtin_ia32_extract128i256 (v4di,int);
22737 v4di __builtin_ia32_insert128i256 (v4di,v2di,int);
22738 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si);
22739 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di);
22740 v4si __builtin_ia32_maskloadd (pcv4si,v4si);
22741 v2di __builtin_ia32_maskloadq (pcv2di,v2di);
22742 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si);
22743 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di);
22744 void __builtin_ia32_maskstored (pv4si,v4si,v4si);
22745 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di);
22746 v8si __builtin_ia32_psllv8si (v8si,v8si);
22747 v4si __builtin_ia32_psllv4si (v4si,v4si);
22748 v4di __builtin_ia32_psllv4di (v4di,v4di);
22749 v2di __builtin_ia32_psllv2di (v2di,v2di);
22750 v8si __builtin_ia32_psrav8si (v8si,v8si);
22751 v4si __builtin_ia32_psrav4si (v4si,v4si);
22752 v8si __builtin_ia32_psrlv8si (v8si,v8si);
22753 v4si __builtin_ia32_psrlv4si (v4si,v4si);
22754 v4di __builtin_ia32_psrlv4di (v4di,v4di);
22755 v2di __builtin_ia32_psrlv2di (v2di,v2di);
22756 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int);
22757 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int);
22758 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int);
22759 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int);
22760 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int);
22761 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int);
22762 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int);
22763 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int);
22764 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int);
22765 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int);
22766 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int);
22767 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int);
22768 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int);
22769 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int);
22770 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int);
22771 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int);
22774 The following built-in functions are available when @option{-maes} is
22775 used. All of them generate the machine instruction that is part of the
22779 v2di __builtin_ia32_aesenc128 (v2di, v2di);
22780 v2di __builtin_ia32_aesenclast128 (v2di, v2di);
22781 v2di __builtin_ia32_aesdec128 (v2di, v2di);
22782 v2di __builtin_ia32_aesdeclast128 (v2di, v2di);
22783 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int);
22784 v2di __builtin_ia32_aesimc128 (v2di);
22787 The following built-in function is available when @option{-mpclmul} is
22791 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
22792 Generates the @code{pclmulqdq} machine instruction.
22795 The following built-in function is available when @option{-mfsgsbase} is
22796 used. All of them generate the machine instruction that is part of the
22800 unsigned int __builtin_ia32_rdfsbase32 (void);
22801 unsigned long long __builtin_ia32_rdfsbase64 (void);
22802 unsigned int __builtin_ia32_rdgsbase32 (void);
22803 unsigned long long __builtin_ia32_rdgsbase64 (void);
22804 void _writefsbase_u32 (unsigned int);
22805 void _writefsbase_u64 (unsigned long long);
22806 void _writegsbase_u32 (unsigned int);
22807 void _writegsbase_u64 (unsigned long long);
22810 The following built-in function is available when @option{-mrdrnd} is
22811 used. All of them generate the machine instruction that is part of the
22815 unsigned int __builtin_ia32_rdrand16_step (unsigned short *);
22816 unsigned int __builtin_ia32_rdrand32_step (unsigned int *);
22817 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *);
22820 The following built-in function is available when @option{-mptwrite} is
22821 used. All of them generate the machine instruction that is part of the
22825 void __builtin_ia32_ptwrite32 (unsigned);
22826 void __builtin_ia32_ptwrite64 (unsigned long long);
22829 The following built-in functions are available when @option{-msse4a} is used.
22830 All of them generate the machine instruction that is part of the name.
22833 void __builtin_ia32_movntsd (double *, v2df);
22834 void __builtin_ia32_movntss (float *, v4sf);
22835 v2di __builtin_ia32_extrq (v2di, v16qi);
22836 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int);
22837 v2di __builtin_ia32_insertq (v2di, v2di);
22838 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int);
22841 The following built-in functions are available when @option{-mxop} is used.
22843 v2df __builtin_ia32_vfrczpd (v2df);
22844 v4sf __builtin_ia32_vfrczps (v4sf);
22845 v2df __builtin_ia32_vfrczsd (v2df);
22846 v4sf __builtin_ia32_vfrczss (v4sf);
22847 v4df __builtin_ia32_vfrczpd256 (v4df);
22848 v8sf __builtin_ia32_vfrczps256 (v8sf);
22849 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di);
22850 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di);
22851 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si);
22852 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi);
22853 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi);
22854 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df);
22855 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf);
22856 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di);
22857 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si);
22858 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi);
22859 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi);
22860 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df);
22861 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf);
22862 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi);
22863 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi);
22864 v4si __builtin_ia32_vpcomeqd (v4si, v4si);
22865 v2di __builtin_ia32_vpcomeqq (v2di, v2di);
22866 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi);
22867 v4si __builtin_ia32_vpcomequd (v4si, v4si);
22868 v2di __builtin_ia32_vpcomequq (v2di, v2di);
22869 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi);
22870 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi);
22871 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi);
22872 v4si __builtin_ia32_vpcomfalsed (v4si, v4si);
22873 v2di __builtin_ia32_vpcomfalseq (v2di, v2di);
22874 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi);
22875 v4si __builtin_ia32_vpcomfalseud (v4si, v4si);
22876 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di);
22877 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi);
22878 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi);
22879 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi);
22880 v4si __builtin_ia32_vpcomged (v4si, v4si);
22881 v2di __builtin_ia32_vpcomgeq (v2di, v2di);
22882 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi);
22883 v4si __builtin_ia32_vpcomgeud (v4si, v4si);
22884 v2di __builtin_ia32_vpcomgeuq (v2di, v2di);
22885 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi);
22886 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi);
22887 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi);
22888 v4si __builtin_ia32_vpcomgtd (v4si, v4si);
22889 v2di __builtin_ia32_vpcomgtq (v2di, v2di);
22890 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi);
22891 v4si __builtin_ia32_vpcomgtud (v4si, v4si);
22892 v2di __builtin_ia32_vpcomgtuq (v2di, v2di);
22893 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi);
22894 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi);
22895 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi);
22896 v4si __builtin_ia32_vpcomled (v4si, v4si);
22897 v2di __builtin_ia32_vpcomleq (v2di, v2di);
22898 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi);
22899 v4si __builtin_ia32_vpcomleud (v4si, v4si);
22900 v2di __builtin_ia32_vpcomleuq (v2di, v2di);
22901 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi);
22902 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi);
22903 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi);
22904 v4si __builtin_ia32_vpcomltd (v4si, v4si);
22905 v2di __builtin_ia32_vpcomltq (v2di, v2di);
22906 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi);
22907 v4si __builtin_ia32_vpcomltud (v4si, v4si);
22908 v2di __builtin_ia32_vpcomltuq (v2di, v2di);
22909 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi);
22910 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi);
22911 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi);
22912 v4si __builtin_ia32_vpcomned (v4si, v4si);
22913 v2di __builtin_ia32_vpcomneq (v2di, v2di);
22914 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi);
22915 v4si __builtin_ia32_vpcomneud (v4si, v4si);
22916 v2di __builtin_ia32_vpcomneuq (v2di, v2di);
22917 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi);
22918 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi);
22919 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi);
22920 v4si __builtin_ia32_vpcomtrued (v4si, v4si);
22921 v2di __builtin_ia32_vpcomtrueq (v2di, v2di);
22922 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi);
22923 v4si __builtin_ia32_vpcomtrueud (v4si, v4si);
22924 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di);
22925 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi);
22926 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi);
22927 v4si __builtin_ia32_vphaddbd (v16qi);
22928 v2di __builtin_ia32_vphaddbq (v16qi);
22929 v8hi __builtin_ia32_vphaddbw (v16qi);
22930 v2di __builtin_ia32_vphadddq (v4si);
22931 v4si __builtin_ia32_vphaddubd (v16qi);
22932 v2di __builtin_ia32_vphaddubq (v16qi);
22933 v8hi __builtin_ia32_vphaddubw (v16qi);
22934 v2di __builtin_ia32_vphaddudq (v4si);
22935 v4si __builtin_ia32_vphadduwd (v8hi);
22936 v2di __builtin_ia32_vphadduwq (v8hi);
22937 v4si __builtin_ia32_vphaddwd (v8hi);
22938 v2di __builtin_ia32_vphaddwq (v8hi);
22939 v8hi __builtin_ia32_vphsubbw (v16qi);
22940 v2di __builtin_ia32_vphsubdq (v4si);
22941 v4si __builtin_ia32_vphsubwd (v8hi);
22942 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si);
22943 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di);
22944 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di);
22945 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si);
22946 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di);
22947 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di);
22948 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si);
22949 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi);
22950 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si);
22951 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi);
22952 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si);
22953 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si);
22954 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi);
22955 v16qi __builtin_ia32_vprotb (v16qi, v16qi);
22956 v4si __builtin_ia32_vprotd (v4si, v4si);
22957 v2di __builtin_ia32_vprotq (v2di, v2di);
22958 v8hi __builtin_ia32_vprotw (v8hi, v8hi);
22959 v16qi __builtin_ia32_vpshab (v16qi, v16qi);
22960 v4si __builtin_ia32_vpshad (v4si, v4si);
22961 v2di __builtin_ia32_vpshaq (v2di, v2di);
22962 v8hi __builtin_ia32_vpshaw (v8hi, v8hi);
22963 v16qi __builtin_ia32_vpshlb (v16qi, v16qi);
22964 v4si __builtin_ia32_vpshld (v4si, v4si);
22965 v2di __builtin_ia32_vpshlq (v2di, v2di);
22966 v8hi __builtin_ia32_vpshlw (v8hi, v8hi);
22969 The following built-in functions are available when @option{-mfma4} is used.
22970 All of them generate the machine instruction that is part of the name.
22973 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df);
22974 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf);
22975 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df);
22976 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf);
22977 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df);
22978 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf);
22979 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df);
22980 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf);
22981 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df);
22982 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf);
22983 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df);
22984 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf);
22985 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df);
22986 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf);
22987 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df);
22988 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf);
22989 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df);
22990 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf);
22991 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df);
22992 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf);
22993 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df);
22994 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf);
22995 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df);
22996 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf);
22997 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df);
22998 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf);
22999 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df);
23000 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf);
23001 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df);
23002 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf);
23003 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df);
23004 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf);
23008 The following built-in functions are available when @option{-mlwp} is used.
23011 void __builtin_ia32_llwpcb16 (void *);
23012 void __builtin_ia32_llwpcb32 (void *);
23013 void __builtin_ia32_llwpcb64 (void *);
23014 void * __builtin_ia32_llwpcb16 (void);
23015 void * __builtin_ia32_llwpcb32 (void);
23016 void * __builtin_ia32_llwpcb64 (void);
23017 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short);
23018 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int);
23019 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int);
23020 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short);
23021 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int);
23022 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int);
23025 The following built-in functions are available when @option{-mbmi} is used.
23026 All of them generate the machine instruction that is part of the name.
23028 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
23029 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
23032 The following built-in functions are available when @option{-mbmi2} is used.
23033 All of them generate the machine instruction that is part of the name.
23035 unsigned int _bzhi_u32 (unsigned int, unsigned int);
23036 unsigned int _pdep_u32 (unsigned int, unsigned int);
23037 unsigned int _pext_u32 (unsigned int, unsigned int);
23038 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long);
23039 unsigned long long _pdep_u64 (unsigned long long, unsigned long long);
23040 unsigned long long _pext_u64 (unsigned long long, unsigned long long);
23043 The following built-in functions are available when @option{-mlzcnt} is used.
23044 All of them generate the machine instruction that is part of the name.
23046 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
23047 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
23048 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
23051 The following built-in functions are available when @option{-mfxsr} is used.
23052 All of them generate the machine instruction that is part of the name.
23054 void __builtin_ia32_fxsave (void *);
23055 void __builtin_ia32_fxrstor (void *);
23056 void __builtin_ia32_fxsave64 (void *);
23057 void __builtin_ia32_fxrstor64 (void *);
23060 The following built-in functions are available when @option{-mxsave} is used.
23061 All of them generate the machine instruction that is part of the name.
23063 void __builtin_ia32_xsave (void *, long long);
23064 void __builtin_ia32_xrstor (void *, long long);
23065 void __builtin_ia32_xsave64 (void *, long long);
23066 void __builtin_ia32_xrstor64 (void *, long long);
23069 The following built-in functions are available when @option{-mxsaveopt} is used.
23070 All of them generate the machine instruction that is part of the name.
23072 void __builtin_ia32_xsaveopt (void *, long long);
23073 void __builtin_ia32_xsaveopt64 (void *, long long);
23076 The following built-in functions are available when @option{-mtbm} is used.
23077 Both of them generate the immediate form of the bextr machine instruction.
23079 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
23080 const unsigned int);
23081 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
23082 const unsigned long long);
23086 The following built-in functions are available when @option{-m3dnow} is used.
23087 All of them generate the machine instruction that is part of the name.
23090 void __builtin_ia32_femms (void);
23091 v8qi __builtin_ia32_pavgusb (v8qi, v8qi);
23092 v2si __builtin_ia32_pf2id (v2sf);
23093 v2sf __builtin_ia32_pfacc (v2sf, v2sf);
23094 v2sf __builtin_ia32_pfadd (v2sf, v2sf);
23095 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf);
23096 v2si __builtin_ia32_pfcmpge (v2sf, v2sf);
23097 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf);
23098 v2sf __builtin_ia32_pfmax (v2sf, v2sf);
23099 v2sf __builtin_ia32_pfmin (v2sf, v2sf);
23100 v2sf __builtin_ia32_pfmul (v2sf, v2sf);
23101 v2sf __builtin_ia32_pfrcp (v2sf);
23102 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf);
23103 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf);
23104 v2sf __builtin_ia32_pfrsqrt (v2sf);
23105 v2sf __builtin_ia32_pfsub (v2sf, v2sf);
23106 v2sf __builtin_ia32_pfsubr (v2sf, v2sf);
23107 v2sf __builtin_ia32_pi2fd (v2si);
23108 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi);
23111 The following built-in functions are available when @option{-m3dnowa} is used.
23112 All of them generate the machine instruction that is part of the name.
23115 v2si __builtin_ia32_pf2iw (v2sf);
23116 v2sf __builtin_ia32_pfnacc (v2sf, v2sf);
23117 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf);
23118 v2sf __builtin_ia32_pi2fw (v2si);
23119 v2sf __builtin_ia32_pswapdsf (v2sf);
23120 v2si __builtin_ia32_pswapdsi (v2si);
23123 The following built-in functions are available when @option{-mrtm} is used
23124 They are used for restricted transactional memory. These are the internal
23125 low level functions. Normally the functions in
23126 @ref{x86 transactional memory intrinsics} should be used instead.
23129 int __builtin_ia32_xbegin ();
23130 void __builtin_ia32_xend ();
23131 void __builtin_ia32_xabort (status);
23132 int __builtin_ia32_xtest ();
23135 The following built-in functions are available when @option{-mmwaitx} is used.
23136 All of them generate the machine instruction that is part of the name.
23138 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int);
23139 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int);
23142 The following built-in functions are available when @option{-mclzero} is used.
23143 All of them generate the machine instruction that is part of the name.
23145 void __builtin_i32_clzero (void *);
23148 The following built-in functions are available when @option{-mpku} is used.
23149 They generate reads and writes to PKRU.
23151 void __builtin_ia32_wrpkru (unsigned int);
23152 unsigned int __builtin_ia32_rdpkru ();
23155 The following built-in functions are available when
23156 @option{-mshstk} option is used. They support shadow stack
23157 machine instructions from Intel Control-flow Enforcement Technology (CET).
23158 Each built-in function generates the machine instruction that is part
23159 of the function's name. These are the internal low-level functions.
23160 Normally the functions in @ref{x86 control-flow protection intrinsics}
23161 should be used instead.
23164 unsigned int __builtin_ia32_rdsspd (void);
23165 unsigned long long __builtin_ia32_rdsspq (void);
23166 void __builtin_ia32_incsspd (unsigned int);
23167 void __builtin_ia32_incsspq (unsigned long long);
23168 void __builtin_ia32_saveprevssp(void);
23169 void __builtin_ia32_rstorssp(void *);
23170 void __builtin_ia32_wrssd(unsigned int, void *);
23171 void __builtin_ia32_wrssq(unsigned long long, void *);
23172 void __builtin_ia32_wrussd(unsigned int, void *);
23173 void __builtin_ia32_wrussq(unsigned long long, void *);
23174 void __builtin_ia32_setssbsy(void);
23175 void __builtin_ia32_clrssbsy(void *);
23178 @node x86 transactional memory intrinsics
23179 @subsection x86 Transactional Memory Intrinsics
23181 These hardware transactional memory intrinsics for x86 allow you to use
23182 memory transactions with RTM (Restricted Transactional Memory).
23183 This support is enabled with the @option{-mrtm} option.
23184 For using HLE (Hardware Lock Elision) see
23185 @ref{x86 specific memory model extensions for transactional memory} instead.
23187 A memory transaction commits all changes to memory in an atomic way,
23188 as visible to other threads. If the transaction fails it is rolled back
23189 and all side effects discarded.
23191 Generally there is no guarantee that a memory transaction ever succeeds
23192 and suitable fallback code always needs to be supplied.
23194 @deftypefn {RTM Function} {unsigned} _xbegin ()
23195 Start a RTM (Restricted Transactional Memory) transaction.
23196 Returns @code{_XBEGIN_STARTED} when the transaction
23197 started successfully (note this is not 0, so the constant has to be
23198 explicitly tested).
23200 If the transaction aborts, all side effects
23201 are undone and an abort code encoded as a bit mask is returned.
23202 The following macros are defined:
23205 @item _XABORT_EXPLICIT
23206 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
23207 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
23208 @item _XABORT_RETRY
23209 Transaction retry is possible.
23210 @item _XABORT_CONFLICT
23211 Transaction abort due to a memory conflict with another thread.
23212 @item _XABORT_CAPACITY
23213 Transaction abort due to the transaction using too much memory.
23214 @item _XABORT_DEBUG
23215 Transaction abort due to a debug trap.
23216 @item _XABORT_NESTED
23217 Transaction abort in an inner nested transaction.
23220 There is no guarantee
23221 any transaction ever succeeds, so there always needs to be a valid
23225 @deftypefn {RTM Function} {void} _xend ()
23226 Commit the current transaction. When no transaction is active this faults.
23227 All memory side effects of the transaction become visible
23228 to other threads in an atomic manner.
23231 @deftypefn {RTM Function} {int} _xtest ()
23232 Return a nonzero value if a transaction is currently active, otherwise 0.
23235 @deftypefn {RTM Function} {void} _xabort (status)
23236 Abort the current transaction. When no transaction is active this is a no-op.
23237 The @var{status} is an 8-bit constant; its value is encoded in the return
23238 value from @code{_xbegin}.
23241 Here is an example showing handling for @code{_XABORT_RETRY}
23242 and a fallback path for other failures:
23245 #include <immintrin.h>
23247 int n_tries, max_tries;
23248 unsigned status = _XABORT_EXPLICIT;
23251 for (n_tries = 0; n_tries < max_tries; n_tries++)
23253 status = _xbegin ();
23254 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
23257 if (status == _XBEGIN_STARTED)
23259 ... transaction code...
23264 ... non-transactional fallback path...
23269 Note that, in most cases, the transactional and non-transactional code
23270 must synchronize together to ensure consistency.
23272 @node x86 control-flow protection intrinsics
23273 @subsection x86 Control-Flow Protection Intrinsics
23275 @deftypefn {CET Function} {ret_type} _get_ssp (void)
23276 Get the current value of shadow stack pointer if shadow stack support
23277 from Intel CET is enabled in the hardware or @code{0} otherwise.
23278 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
23279 and @code{unsigned int} for 32-bit targets.
23282 @deftypefn {CET Function} void _inc_ssp (unsigned int)
23283 Increment the current shadow stack pointer by the size specified by the
23284 function argument. The argument is masked to a byte value for security
23285 reasons, so to increment by more than 255 bytes you must call the function
23289 The shadow stack unwind code looks like:
23292 #include <immintrin.h>
23294 /* Unwind the shadow stack for EH. */
23295 #define _Unwind_Frames_Extra(x) \
23298 _Unwind_Word ssp = _get_ssp (); \
23301 _Unwind_Word tmp = (x); \
23302 while (tmp > 255) \
23314 This code runs unconditionally on all 64-bit processors. For 32-bit
23315 processors the code runs on those that support multi-byte NOP instructions.
23317 @node Target Format Checks
23318 @section Format Checks Specific to Particular Target Machines
23320 For some target machines, GCC supports additional options to the
23322 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
23325 * Solaris Format Checks::
23326 * Darwin Format Checks::
23329 @node Solaris Format Checks
23330 @subsection Solaris Format Checks
23332 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
23333 check. @code{cmn_err} accepts a subset of the standard @code{printf}
23334 conversions, and the two-argument @code{%b} conversion for displaying
23335 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
23337 @node Darwin Format Checks
23338 @subsection Darwin Format Checks
23340 In addition to the full set of format archetypes (attribute format style
23341 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
23342 @code{strfmon}), Darwin targets also support the @code{CFString} (or
23343 @code{__CFString__}) archetype in the @code{format} attribute.
23344 Declarations with this archetype are parsed for correct syntax
23345 and argument types. However, parsing of the format string itself and
23346 validating arguments against it in calls to such functions is currently
23349 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
23350 also be used as format arguments. Note that the relevant headers are only likely to be
23351 available on Darwin (OSX) installations. On such installations, the XCode and system
23352 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
23353 associated functions.
23356 @section Pragmas Accepted by GCC
23358 @cindex @code{#pragma}
23360 GCC supports several types of pragmas, primarily in order to compile
23361 code originally written for other compilers. Note that in general
23362 we do not recommend the use of pragmas; @xref{Function Attributes},
23363 for further explanation.
23365 The GNU C preprocessor recognizes several pragmas in addition to the
23366 compiler pragmas documented here. Refer to the CPP manual for more
23370 * AArch64 Pragmas::
23375 * RS/6000 and PowerPC Pragmas::
23378 * Solaris Pragmas::
23379 * Symbol-Renaming Pragmas::
23380 * Structure-Layout Pragmas::
23382 * Diagnostic Pragmas::
23383 * Visibility Pragmas::
23384 * Push/Pop Macro Pragmas::
23385 * Function Specific Option Pragmas::
23386 * Loop-Specific Pragmas::
23389 @node AArch64 Pragmas
23390 @subsection AArch64 Pragmas
23392 The pragmas defined by the AArch64 target correspond to the AArch64
23393 target function attributes. They can be specified as below:
23395 #pragma GCC target("string")
23398 where @code{@var{string}} can be any string accepted as an AArch64 target
23399 attribute. @xref{AArch64 Function Attributes}, for more details
23400 on the permissible values of @code{string}.
23403 @subsection ARM Pragmas
23405 The ARM target defines pragmas for controlling the default addition of
23406 @code{long_call} and @code{short_call} attributes to functions.
23407 @xref{Function Attributes}, for information about the effects of these
23412 @cindex pragma, long_calls
23413 Set all subsequent functions to have the @code{long_call} attribute.
23415 @item no_long_calls
23416 @cindex pragma, no_long_calls
23417 Set all subsequent functions to have the @code{short_call} attribute.
23419 @item long_calls_off
23420 @cindex pragma, long_calls_off
23421 Do not affect the @code{long_call} or @code{short_call} attributes of
23422 subsequent functions.
23426 @subsection M32C Pragmas
23429 @item GCC memregs @var{number}
23430 @cindex pragma, memregs
23431 Overrides the command-line option @code{-memregs=} for the current
23432 file. Use with care! This pragma must be before any function in the
23433 file, and mixing different memregs values in different objects may
23434 make them incompatible. This pragma is useful when a
23435 performance-critical function uses a memreg for temporary values,
23436 as it may allow you to reduce the number of memregs used.
23438 @item ADDRESS @var{name} @var{address}
23439 @cindex pragma, address
23440 For any declared symbols matching @var{name}, this does three things
23441 to that symbol: it forces the symbol to be located at the given
23442 address (a number), it forces the symbol to be volatile, and it
23443 changes the symbol's scope to be static. This pragma exists for
23444 compatibility with other compilers, but note that the common
23445 @code{1234H} numeric syntax is not supported (use @code{0x1234}
23449 #pragma ADDRESS port3 0x103
23456 @subsection MeP Pragmas
23460 @item custom io_volatile (on|off)
23461 @cindex pragma, custom io_volatile
23462 Overrides the command-line option @code{-mio-volatile} for the current
23463 file. Note that for compatibility with future GCC releases, this
23464 option should only be used once before any @code{io} variables in each
23467 @item GCC coprocessor available @var{registers}
23468 @cindex pragma, coprocessor available
23469 Specifies which coprocessor registers are available to the register
23470 allocator. @var{registers} may be a single register, register range
23471 separated by ellipses, or comma-separated list of those. Example:
23474 #pragma GCC coprocessor available $c0...$c10, $c28
23477 @item GCC coprocessor call_saved @var{registers}
23478 @cindex pragma, coprocessor call_saved
23479 Specifies which coprocessor registers are to be saved and restored by
23480 any function using them. @var{registers} may be a single register,
23481 register range separated by ellipses, or comma-separated list of
23485 #pragma GCC coprocessor call_saved $c4...$c6, $c31
23488 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
23489 @cindex pragma, coprocessor subclass
23490 Creates and defines a register class. These register classes can be
23491 used by inline @code{asm} constructs. @var{registers} may be a single
23492 register, register range separated by ellipses, or comma-separated
23493 list of those. Example:
23496 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
23498 asm ("cpfoo %0" : "=B" (x));
23501 @item GCC disinterrupt @var{name} , @var{name} @dots{}
23502 @cindex pragma, disinterrupt
23503 For the named functions, the compiler adds code to disable interrupts
23504 for the duration of those functions. If any functions so named
23505 are not encountered in the source, a warning is emitted that the pragma is
23506 not used. Examples:
23509 #pragma disinterrupt foo
23510 #pragma disinterrupt bar, grill
23511 int foo () @{ @dots{} @}
23514 @item GCC call @var{name} , @var{name} @dots{}
23515 @cindex pragma, call
23516 For the named functions, the compiler always uses a register-indirect
23517 call model when calling the named functions. Examples:
23527 @subsection PRU Pragmas
23531 @item ctable_entry @var{index} @var{constant_address}
23532 @cindex pragma, ctable_entry
23533 Specifies that the PRU CTABLE entry given by @var{index} has the value
23534 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
23535 when the load/store address is known and can be addressed with some CTABLE
23536 entry. For example:
23539 /* will compile to "sbco Rx, 2, 0x10, 4" */
23540 #pragma ctable_entry 2 0x4802a000
23541 *(unsigned int *)0x4802a010 = val;
23546 @node RS/6000 and PowerPC Pragmas
23547 @subsection RS/6000 and PowerPC Pragmas
23549 The RS/6000 and PowerPC targets define one pragma for controlling
23550 whether or not the @code{longcall} attribute is added to function
23551 declarations by default. This pragma overrides the @option{-mlongcall}
23552 option, but not the @code{longcall} and @code{shortcall} attributes.
23553 @xref{RS/6000 and PowerPC Options}, for more information about when long
23554 calls are and are not necessary.
23558 @cindex pragma, longcall
23559 Apply the @code{longcall} attribute to all subsequent function
23563 Do not apply the @code{longcall} attribute to subsequent function
23567 @c Describe h8300 pragmas here.
23568 @c Describe sh pragmas here.
23569 @c Describe v850 pragmas here.
23571 @node S/390 Pragmas
23572 @subsection S/390 Pragmas
23574 The pragmas defined by the S/390 target correspond to the S/390
23575 target function attributes and some the additional options:
23582 Note that options of the pragma, unlike options of the target
23583 attribute, do change the value of preprocessor macros like
23584 @code{__VEC__}. They can be specified as below:
23587 #pragma GCC target("string[,string]...")
23588 #pragma GCC target("string"[,"string"]...)
23591 @node Darwin Pragmas
23592 @subsection Darwin Pragmas
23594 The following pragmas are available for all architectures running the
23595 Darwin operating system. These are useful for compatibility with other
23599 @item mark @var{tokens}@dots{}
23600 @cindex pragma, mark
23601 This pragma is accepted, but has no effect.
23603 @item options align=@var{alignment}
23604 @cindex pragma, options align
23605 This pragma sets the alignment of fields in structures. The values of
23606 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
23607 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
23608 properly; to restore the previous setting, use @code{reset} for the
23611 @item segment @var{tokens}@dots{}
23612 @cindex pragma, segment
23613 This pragma is accepted, but has no effect.
23615 @item unused (@var{var} [, @var{var}]@dots{})
23616 @cindex pragma, unused
23617 This pragma declares variables to be possibly unused. GCC does not
23618 produce warnings for the listed variables. The effect is similar to
23619 that of the @code{unused} attribute, except that this pragma may appear
23620 anywhere within the variables' scopes.
23623 @node Solaris Pragmas
23624 @subsection Solaris Pragmas
23626 The Solaris target supports @code{#pragma redefine_extname}
23627 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
23628 @code{#pragma} directives for compatibility with the system compiler.
23631 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
23632 @cindex pragma, align
23634 Increase the minimum alignment of each @var{variable} to @var{alignment}.
23635 This is the same as GCC's @code{aligned} attribute @pxref{Variable
23636 Attributes}). Macro expansion occurs on the arguments to this pragma
23637 when compiling C and Objective-C@. It does not currently occur when
23638 compiling C++, but this is a bug which may be fixed in a future
23641 @item fini (@var{function} [, @var{function}]...)
23642 @cindex pragma, fini
23644 This pragma causes each listed @var{function} to be called after
23645 main, or during shared module unloading, by adding a call to the
23646 @code{.fini} section.
23648 @item init (@var{function} [, @var{function}]...)
23649 @cindex pragma, init
23651 This pragma causes each listed @var{function} to be called during
23652 initialization (before @code{main}) or during shared module loading, by
23653 adding a call to the @code{.init} section.
23657 @node Symbol-Renaming Pragmas
23658 @subsection Symbol-Renaming Pragmas
23660 GCC supports a @code{#pragma} directive that changes the name used in
23661 assembly for a given declaration. While this pragma is supported on all
23662 platforms, it is intended primarily to provide compatibility with the
23663 Solaris system headers. This effect can also be achieved using the asm
23664 labels extension (@pxref{Asm Labels}).
23667 @item redefine_extname @var{oldname} @var{newname}
23668 @cindex pragma, redefine_extname
23670 This pragma gives the C function @var{oldname} the assembly symbol
23671 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
23672 is defined if this pragma is available (currently on all platforms).
23675 This pragma and the @code{asm} labels extension interact in a complicated
23676 manner. Here are some corner cases you may want to be aware of:
23679 @item This pragma silently applies only to declarations with external
23680 linkage. The @code{asm} label feature does not have this restriction.
23682 @item In C++, this pragma silently applies only to declarations with
23683 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
23685 @item If either of the ways of changing the assembly name of a
23686 declaration are applied to a declaration whose assembly name has
23687 already been determined (either by a previous use of one of these
23688 features, or because the compiler needed the assembly name in order to
23689 generate code), and the new name is different, a warning issues and
23690 the name does not change.
23692 @item The @var{oldname} used by @code{#pragma redefine_extname} is
23693 always the C-language name.
23696 @node Structure-Layout Pragmas
23697 @subsection Structure-Layout Pragmas
23699 For compatibility with Microsoft Windows compilers, GCC supports a
23700 set of @code{#pragma} directives that change the maximum alignment of
23701 members of structures (other than zero-width bit-fields), unions, and
23702 classes subsequently defined. The @var{n} value below always is required
23703 to be a small power of two and specifies the new alignment in bytes.
23706 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
23707 @item @code{#pragma pack()} sets the alignment to the one that was in
23708 effect when compilation started (see also command-line option
23709 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
23710 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
23711 setting on an internal stack and then optionally sets the new alignment.
23712 @item @code{#pragma pack(pop)} restores the alignment setting to the one
23713 saved at the top of the internal stack (and removes that stack entry).
23714 Note that @code{#pragma pack([@var{n}])} does not influence this internal
23715 stack; thus it is possible to have @code{#pragma pack(push)} followed by
23716 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
23717 @code{#pragma pack(pop)}.
23720 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
23721 directive which lays out structures and unions subsequently defined as the
23722 documented @code{__attribute__ ((ms_struct))}.
23725 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
23726 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
23727 @item @code{#pragma ms_struct reset} goes back to the default layout.
23730 Most targets also support the @code{#pragma scalar_storage_order} directive
23731 which lays out structures and unions subsequently defined as the documented
23732 @code{__attribute__ ((scalar_storage_order))}.
23735 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
23736 of the scalar fields to big-endian.
23737 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
23738 of the scalar fields to little-endian.
23739 @item @code{#pragma scalar_storage_order default} goes back to the endianness
23740 that was in effect when compilation started (see also command-line option
23741 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
23745 @subsection Weak Pragmas
23747 For compatibility with SVR4, GCC supports a set of @code{#pragma}
23748 directives for declaring symbols to be weak, and defining weak
23752 @item #pragma weak @var{symbol}
23753 @cindex pragma, weak
23754 This pragma declares @var{symbol} to be weak, as if the declaration
23755 had the attribute of the same name. The pragma may appear before
23756 or after the declaration of @var{symbol}. It is not an error for
23757 @var{symbol} to never be defined at all.
23759 @item #pragma weak @var{symbol1} = @var{symbol2}
23760 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
23761 It is an error if @var{symbol2} is not defined in the current
23765 @node Diagnostic Pragmas
23766 @subsection Diagnostic Pragmas
23768 GCC allows the user to selectively enable or disable certain types of
23769 diagnostics, and change the kind of the diagnostic. For example, a
23770 project's policy might require that all sources compile with
23771 @option{-Werror} but certain files might have exceptions allowing
23772 specific types of warnings. Or, a project might selectively enable
23773 diagnostics and treat them as errors depending on which preprocessor
23774 macros are defined.
23777 @item #pragma GCC diagnostic @var{kind} @var{option}
23778 @cindex pragma, diagnostic
23780 Modifies the disposition of a diagnostic. Note that not all
23781 diagnostics are modifiable; at the moment only warnings (normally
23782 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
23783 Use @option{-fdiagnostics-show-option} to determine which diagnostics
23784 are controllable and which option controls them.
23786 @var{kind} is @samp{error} to treat this diagnostic as an error,
23787 @samp{warning} to treat it like a warning (even if @option{-Werror} is
23788 in effect), or @samp{ignored} if the diagnostic is to be ignored.
23789 @var{option} is a double quoted string that matches the command-line
23793 #pragma GCC diagnostic warning "-Wformat"
23794 #pragma GCC diagnostic error "-Wformat"
23795 #pragma GCC diagnostic ignored "-Wformat"
23798 Note that these pragmas override any command-line options. GCC keeps
23799 track of the location of each pragma, and issues diagnostics according
23800 to the state as of that point in the source file. Thus, pragmas occurring
23801 after a line do not affect diagnostics caused by that line.
23803 @item #pragma GCC diagnostic push
23804 @itemx #pragma GCC diagnostic pop
23806 Causes GCC to remember the state of the diagnostics as of each
23807 @code{push}, and restore to that point at each @code{pop}. If a
23808 @code{pop} has no matching @code{push}, the command-line options are
23812 #pragma GCC diagnostic error "-Wuninitialized"
23813 foo(a); /* error is given for this one */
23814 #pragma GCC diagnostic push
23815 #pragma GCC diagnostic ignored "-Wuninitialized"
23816 foo(b); /* no diagnostic for this one */
23817 #pragma GCC diagnostic pop
23818 foo(c); /* error is given for this one */
23819 #pragma GCC diagnostic pop
23820 foo(d); /* depends on command-line options */
23823 @item #pragma GCC diagnostic ignored_attributes
23825 Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress
23826 warnings about unknown scoped attributes (in C++11 and C2X). For example,
23827 @code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables
23828 warning about the following declaration:
23831 [[vendor::attr]] void f();
23834 whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents
23835 warning about both of these declarations:
23838 [[vendor::safe]] void f();
23839 [[vendor::unsafe]] void f2();
23844 GCC also offers a simple mechanism for printing messages during
23848 @item #pragma message @var{string}
23849 @cindex pragma, diagnostic
23851 Prints @var{string} as a compiler message on compilation. The message
23852 is informational only, and is neither a compilation warning nor an
23853 error. Newlines can be included in the string by using the @samp{\n}
23857 #pragma message "Compiling " __FILE__ "..."
23860 @var{string} may be parenthesized, and is printed with location
23861 information. For example,
23864 #define DO_PRAGMA(x) _Pragma (#x)
23865 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
23867 TODO(Remember to fix this)
23871 prints @samp{/tmp/file.c:4: note: #pragma message:
23872 TODO - Remember to fix this}.
23874 @item #pragma GCC error @var{message}
23875 @cindex pragma, diagnostic
23876 Generates an error message. This pragma @emph{is} considered to
23877 indicate an error in the compilation, and it will be treated as such.
23879 Newlines can be included in the string by using the @samp{\n}
23880 escape sequence. They will be displayed as newlines even if the
23881 @option{-fmessage-length} option is set to zero.
23883 The error is only generated if the pragma is present in the code after
23884 pre-processing has been completed. It does not matter however if the
23885 code containing the pragma is unreachable:
23889 #pragma GCC error "this error is not seen"
23894 #pragma GCC error "this error is seen"
23898 @item #pragma GCC warning @var{message}
23899 @cindex pragma, diagnostic
23900 This is just like @samp{pragma GCC error} except that a warning
23901 message is issued instead of an error message. Unless
23902 @option{-Werror} is in effect, in which case this pragma will generate
23907 @node Visibility Pragmas
23908 @subsection Visibility Pragmas
23911 @item #pragma GCC visibility push(@var{visibility})
23912 @itemx #pragma GCC visibility pop
23913 @cindex pragma, visibility
23915 This pragma allows the user to set the visibility for multiple
23916 declarations without having to give each a visibility attribute
23917 (@pxref{Function Attributes}).
23919 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
23920 declarations. Class members and template specializations are not
23921 affected; if you want to override the visibility for a particular
23922 member or instantiation, you must use an attribute.
23927 @node Push/Pop Macro Pragmas
23928 @subsection Push/Pop Macro Pragmas
23930 For compatibility with Microsoft Windows compilers, GCC supports
23931 @samp{#pragma push_macro(@var{"macro_name"})}
23932 and @samp{#pragma pop_macro(@var{"macro_name"})}.
23935 @item #pragma push_macro(@var{"macro_name"})
23936 @cindex pragma, push_macro
23937 This pragma saves the value of the macro named as @var{macro_name} to
23938 the top of the stack for this macro.
23940 @item #pragma pop_macro(@var{"macro_name"})
23941 @cindex pragma, pop_macro
23942 This pragma sets the value of the macro named as @var{macro_name} to
23943 the value on top of the stack for this macro. If the stack for
23944 @var{macro_name} is empty, the value of the macro remains unchanged.
23951 #pragma push_macro("X")
23954 #pragma pop_macro("X")
23959 In this example, the definition of X as 1 is saved by @code{#pragma
23960 push_macro} and restored by @code{#pragma pop_macro}.
23962 @node Function Specific Option Pragmas
23963 @subsection Function Specific Option Pragmas
23966 @item #pragma GCC target (@var{string}, @dots{})
23967 @cindex pragma GCC target
23969 This pragma allows you to set target-specific options for functions
23970 defined later in the source file. One or more strings can be
23971 specified. Each function that is defined after this point is treated
23972 as if it had been declared with one @code{target(}@var{string}@code{)}
23973 attribute for each @var{string} argument. The parentheses around
23974 the strings in the pragma are optional. @xref{Function Attributes},
23975 for more information about the @code{target} attribute and the attribute
23978 The @code{#pragma GCC target} pragma is presently implemented for
23979 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
23981 @item #pragma GCC optimize (@var{string}, @dots{})
23982 @cindex pragma GCC optimize
23984 This pragma allows you to set global optimization options for functions
23985 defined later in the source file. One or more strings can be
23986 specified. Each function that is defined after this point is treated
23987 as if it had been declared with one @code{optimize(}@var{string}@code{)}
23988 attribute for each @var{string} argument. The parentheses around
23989 the strings in the pragma are optional. @xref{Function Attributes},
23990 for more information about the @code{optimize} attribute and the attribute
23993 @item #pragma GCC push_options
23994 @itemx #pragma GCC pop_options
23995 @cindex pragma GCC push_options
23996 @cindex pragma GCC pop_options
23998 These pragmas maintain a stack of the current target and optimization
23999 options. It is intended for include files where you temporarily want
24000 to switch to using a different @samp{#pragma GCC target} or
24001 @samp{#pragma GCC optimize} and then to pop back to the previous
24004 @item #pragma GCC reset_options
24005 @cindex pragma GCC reset_options
24007 This pragma clears the current @code{#pragma GCC target} and
24008 @code{#pragma GCC optimize} to use the default switches as specified
24009 on the command line.
24013 @node Loop-Specific Pragmas
24014 @subsection Loop-Specific Pragmas
24017 @item #pragma GCC ivdep
24018 @cindex pragma GCC ivdep
24020 With this pragma, the programmer asserts that there are no loop-carried
24021 dependencies which would prevent consecutive iterations of
24022 the following loop from executing concurrently with SIMD
24023 (single instruction multiple data) instructions.
24025 For example, the compiler can only unconditionally vectorize the following
24026 loop with the pragma:
24029 void foo (int n, int *a, int *b, int *c)
24033 for (i = 0; i < n; ++i)
24034 a[i] = b[i] + c[i];
24039 In this example, using the @code{restrict} qualifier had the same
24040 effect. In the following example, that would not be possible. Assume
24041 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
24042 that it can unconditionally vectorize the following loop:
24045 void ignore_vec_dep (int *a, int k, int c, int m)
24048 for (int i = 0; i < m; i++)
24049 a[i] = a[i + k] * c;
24053 @item #pragma GCC unroll @var{n}
24054 @cindex pragma GCC unroll @var{n}
24056 You can use this pragma to control how many times a loop should be unrolled.
24057 It must be placed immediately before a @code{for}, @code{while} or @code{do}
24058 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
24059 @var{n} is an integer constant expression specifying the unrolling factor.
24060 The values of @math{0} and @math{1} block any unrolling of the loop.
24064 @node Unnamed Fields
24065 @section Unnamed Structure and Union Fields
24066 @cindex @code{struct}
24067 @cindex @code{union}
24069 As permitted by ISO C11 and for compatibility with other compilers,
24070 GCC allows you to define
24071 a structure or union that contains, as fields, structures and unions
24072 without names. For example:
24086 In this example, you are able to access members of the unnamed
24087 union with code like @samp{foo.b}. Note that only unnamed structs and
24088 unions are allowed, you may not have, for example, an unnamed
24091 You must never create such structures that cause ambiguous field definitions.
24092 For example, in this structure:
24104 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
24105 The compiler gives errors for such constructs.
24107 @opindex fms-extensions
24108 Unless @option{-fms-extensions} is used, the unnamed field must be a
24109 structure or union definition without a tag (for example, @samp{struct
24110 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
24111 also be a definition with a tag such as @samp{struct foo @{ int a;
24112 @};}, a reference to a previously defined structure or union such as
24113 @samp{struct foo;}, or a reference to a @code{typedef} name for a
24114 previously defined structure or union type.
24116 @opindex fplan9-extensions
24117 The option @option{-fplan9-extensions} enables
24118 @option{-fms-extensions} as well as two other extensions. First, a
24119 pointer to a structure is automatically converted to a pointer to an
24120 anonymous field for assignments and function calls. For example:
24123 struct s1 @{ int a; @};
24124 struct s2 @{ struct s1; @};
24125 extern void f1 (struct s1 *);
24126 void f2 (struct s2 *p) @{ f1 (p); @}
24130 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
24131 converted into a pointer to the anonymous field.
24133 Second, when the type of an anonymous field is a @code{typedef} for a
24134 @code{struct} or @code{union}, code may refer to the field using the
24135 name of the @code{typedef}.
24138 typedef struct @{ int a; @} s1;
24139 struct s2 @{ s1; @};
24140 s1 f1 (struct s2 *p) @{ return p->s1; @}
24143 These usages are only permitted when they are not ambiguous.
24146 @section Thread-Local Storage
24147 @cindex Thread-Local Storage
24148 @cindex @acronym{TLS}
24149 @cindex @code{__thread}
24151 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
24152 are allocated such that there is one instance of the variable per extant
24153 thread. The runtime model GCC uses to implement this originates
24154 in the IA-64 processor-specific ABI, but has since been migrated
24155 to other processors as well. It requires significant support from
24156 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
24157 system libraries (@file{libc.so} and @file{libpthread.so}), so it
24158 is not available everywhere.
24160 At the user level, the extension is visible with a new storage
24161 class keyword: @code{__thread}. For example:
24165 extern __thread struct state s;
24166 static __thread char *p;
24169 The @code{__thread} specifier may be used alone, with the @code{extern}
24170 or @code{static} specifiers, but with no other storage class specifier.
24171 When used with @code{extern} or @code{static}, @code{__thread} must appear
24172 immediately after the other storage class specifier.
24174 The @code{__thread} specifier may be applied to any global, file-scoped
24175 static, function-scoped static, or static data member of a class. It may
24176 not be applied to block-scoped automatic or non-static data member.
24178 When the address-of operator is applied to a thread-local variable, it is
24179 evaluated at run time and returns the address of the current thread's
24180 instance of that variable. An address so obtained may be used by any
24181 thread. When a thread terminates, any pointers to thread-local variables
24182 in that thread become invalid.
24184 No static initialization may refer to the address of a thread-local variable.
24186 In C++, if an initializer is present for a thread-local variable, it must
24187 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
24190 See @uref{https://www.akkadia.org/drepper/tls.pdf,
24191 ELF Handling For Thread-Local Storage} for a detailed explanation of
24192 the four thread-local storage addressing models, and how the runtime
24193 is expected to function.
24196 * C99 Thread-Local Edits::
24197 * C++98 Thread-Local Edits::
24200 @node C99 Thread-Local Edits
24201 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
24203 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
24204 that document the exact semantics of the language extension.
24208 @cite{5.1.2 Execution environments}
24210 Add new text after paragraph 1
24213 Within either execution environment, a @dfn{thread} is a flow of
24214 control within a program. It is implementation defined whether
24215 or not there may be more than one thread associated with a program.
24216 It is implementation defined how threads beyond the first are
24217 created, the name and type of the function called at thread
24218 startup, and how threads may be terminated. However, objects
24219 with thread storage duration shall be initialized before thread
24224 @cite{6.2.4 Storage durations of objects}
24226 Add new text before paragraph 3
24229 An object whose identifier is declared with the storage-class
24230 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
24231 Its lifetime is the entire execution of the thread, and its
24232 stored value is initialized only once, prior to thread startup.
24236 @cite{6.4.1 Keywords}
24238 Add @code{__thread}.
24241 @cite{6.7.1 Storage-class specifiers}
24243 Add @code{__thread} to the list of storage class specifiers in
24246 Change paragraph 2 to
24249 With the exception of @code{__thread}, at most one storage-class
24250 specifier may be given [@dots{}]. The @code{__thread} specifier may
24251 be used alone, or immediately following @code{extern} or
24255 Add new text after paragraph 6
24258 The declaration of an identifier for a variable that has
24259 block scope that specifies @code{__thread} shall also
24260 specify either @code{extern} or @code{static}.
24262 The @code{__thread} specifier shall be used only with
24267 @node C++98 Thread-Local Edits
24268 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
24270 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
24271 that document the exact semantics of the language extension.
24275 @b{[intro.execution]}
24277 New text after paragraph 4
24280 A @dfn{thread} is a flow of control within the abstract machine.
24281 It is implementation defined whether or not there may be more than
24285 New text after paragraph 7
24288 It is unspecified whether additional action must be taken to
24289 ensure when and whether side effects are visible to other threads.
24295 Add @code{__thread}.
24298 @b{[basic.start.main]}
24300 Add after paragraph 5
24303 The thread that begins execution at the @code{main} function is called
24304 the @dfn{main thread}. It is implementation defined how functions
24305 beginning threads other than the main thread are designated or typed.
24306 A function so designated, as well as the @code{main} function, is called
24307 a @dfn{thread startup function}. It is implementation defined what
24308 happens if a thread startup function returns. It is implementation
24309 defined what happens to other threads when any thread calls @code{exit}.
24313 @b{[basic.start.init]}
24315 Add after paragraph 4
24318 The storage for an object of thread storage duration shall be
24319 statically initialized before the first statement of the thread startup
24320 function. An object of thread storage duration shall not require
24321 dynamic initialization.
24325 @b{[basic.start.term]}
24327 Add after paragraph 3
24330 The type of an object with thread storage duration shall not have a
24331 non-trivial destructor, nor shall it be an array type whose elements
24332 (directly or indirectly) have non-trivial destructors.
24338 Add ``thread storage duration'' to the list in paragraph 1.
24343 Thread, static, and automatic storage durations are associated with
24344 objects introduced by declarations [@dots{}].
24347 Add @code{__thread} to the list of specifiers in paragraph 3.
24350 @b{[basic.stc.thread]}
24352 New section before @b{[basic.stc.static]}
24355 The keyword @code{__thread} applied to a non-local object gives the
24356 object thread storage duration.
24358 A local variable or class data member declared both @code{static}
24359 and @code{__thread} gives the variable or member thread storage
24364 @b{[basic.stc.static]}
24369 All objects that have neither thread storage duration, dynamic
24370 storage duration nor are local [@dots{}].
24376 Add @code{__thread} to the list in paragraph 1.
24381 With the exception of @code{__thread}, at most one
24382 @var{storage-class-specifier} shall appear in a given
24383 @var{decl-specifier-seq}. The @code{__thread} specifier may
24384 be used alone, or immediately following the @code{extern} or
24385 @code{static} specifiers. [@dots{}]
24388 Add after paragraph 5
24391 The @code{__thread} specifier can be applied only to the names of objects
24392 and to anonymous unions.
24398 Add after paragraph 6
24401 Non-@code{static} members shall not be @code{__thread}.
24405 @node Binary constants
24406 @section Binary Constants using the @samp{0b} Prefix
24407 @cindex Binary constants using the @samp{0b} prefix
24409 Integer constants can be written as binary constants, consisting of a
24410 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
24411 @samp{0B}. This is particularly useful in environments that operate a
24412 lot on the bit level (like microcontrollers).
24414 The following statements are identical:
24423 The type of these constants follows the same rules as for octal or
24424 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
24427 @node C++ Extensions
24428 @chapter Extensions to the C++ Language
24429 @cindex extensions, C++ language
24430 @cindex C++ language extensions
24432 The GNU compiler provides these extensions to the C++ language (and you
24433 can also use most of the C language extensions in your C++ programs). If you
24434 want to write code that checks whether these features are available, you can
24435 test for the GNU compiler the same way as for C programs: check for a
24436 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
24437 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
24438 Predefined Macros,cpp,The GNU C Preprocessor}).
24441 * C++ Volatiles:: What constitutes an access to a volatile object.
24442 * Restricted Pointers:: C99 restricted pointers and references.
24443 * Vague Linkage:: Where G++ puts inlines, vtables and such.
24444 * C++ Interface:: You can use a single C++ header file for both
24445 declarations and definitions.
24446 * Template Instantiation:: Methods for ensuring that exactly one copy of
24447 each needed template instantiation is emitted.
24448 * Bound member functions:: You can extract a function pointer to the
24449 method denoted by a @samp{->*} or @samp{.*} expression.
24450 * C++ Attributes:: Variable, function, and type attributes for C++ only.
24451 * Function Multiversioning:: Declaring multiple function versions.
24452 * Type Traits:: Compiler support for type traits.
24453 * C++ Concepts:: Improved support for generic programming.
24454 * Deprecated Features:: Things will disappear from G++.
24455 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
24458 @node C++ Volatiles
24459 @section When is a Volatile C++ Object Accessed?
24460 @cindex accessing volatiles
24461 @cindex volatile read
24462 @cindex volatile write
24463 @cindex volatile access
24465 The C++ standard differs from the C standard in its treatment of
24466 volatile objects. It fails to specify what constitutes a volatile
24467 access, except to say that C++ should behave in a similar manner to C
24468 with respect to volatiles, where possible. However, the different
24469 lvalueness of expressions between C and C++ complicate the behavior.
24470 G++ behaves the same as GCC for volatile access, @xref{C
24471 Extensions,,Volatiles}, for a description of GCC's behavior.
24473 The C and C++ language specifications differ when an object is
24474 accessed in a void context:
24477 volatile int *src = @var{somevalue};
24481 The C++ standard specifies that such expressions do not undergo lvalue
24482 to rvalue conversion, and that the type of the dereferenced object may
24483 be incomplete. The C++ standard does not specify explicitly that it
24484 is lvalue to rvalue conversion that is responsible for causing an
24485 access. There is reason to believe that it is, because otherwise
24486 certain simple expressions become undefined. However, because it
24487 would surprise most programmers, G++ treats dereferencing a pointer to
24488 volatile object of complete type as GCC would do for an equivalent
24489 type in C@. When the object has incomplete type, G++ issues a
24490 warning; if you wish to force an error, you must force a conversion to
24491 rvalue with, for instance, a static cast.
24493 When using a reference to volatile, G++ does not treat equivalent
24494 expressions as accesses to volatiles, but instead issues a warning that
24495 no volatile is accessed. The rationale for this is that otherwise it
24496 becomes difficult to determine where volatile access occur, and not
24497 possible to ignore the return value from functions returning volatile
24498 references. Again, if you wish to force a read, cast the reference to
24501 G++ implements the same behavior as GCC does when assigning to a
24502 volatile object---there is no reread of the assigned-to object, the
24503 assigned rvalue is reused. Note that in C++ assignment expressions
24504 are lvalues, and if used as an lvalue, the volatile object is
24505 referred to. For instance, @var{vref} refers to @var{vobj}, as
24506 expected, in the following example:
24510 volatile int &vref = vobj = @var{something};
24513 @node Restricted Pointers
24514 @section Restricting Pointer Aliasing
24515 @cindex restricted pointers
24516 @cindex restricted references
24517 @cindex restricted this pointer
24519 As with the C front end, G++ understands the C99 feature of restricted pointers,
24520 specified with the @code{__restrict__}, or @code{__restrict} type
24521 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
24522 language flag, @code{restrict} is not a keyword in C++.
24524 In addition to allowing restricted pointers, you can specify restricted
24525 references, which indicate that the reference is not aliased in the local
24529 void fn (int *__restrict__ rptr, int &__restrict__ rref)
24536 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
24537 @var{rref} refers to a (different) unaliased integer.
24539 You may also specify whether a member function's @var{this} pointer is
24540 unaliased by using @code{__restrict__} as a member function qualifier.
24543 void T::fn () __restrict__
24550 Within the body of @code{T::fn}, @var{this} has the effective
24551 definition @code{T *__restrict__ const this}. Notice that the
24552 interpretation of a @code{__restrict__} member function qualifier is
24553 different to that of @code{const} or @code{volatile} qualifier, in that it
24554 is applied to the pointer rather than the object. This is consistent with
24555 other compilers that implement restricted pointers.
24557 As with all outermost parameter qualifiers, @code{__restrict__} is
24558 ignored in function definition matching. This means you only need to
24559 specify @code{__restrict__} in a function definition, rather than
24560 in a function prototype as well.
24562 @node Vague Linkage
24563 @section Vague Linkage
24564 @cindex vague linkage
24566 There are several constructs in C++ that require space in the object
24567 file but are not clearly tied to a single translation unit. We say that
24568 these constructs have ``vague linkage''. Typically such constructs are
24569 emitted wherever they are needed, though sometimes we can be more
24573 @item Inline Functions
24574 Inline functions are typically defined in a header file which can be
24575 included in many different compilations. Hopefully they can usually be
24576 inlined, but sometimes an out-of-line copy is necessary, if the address
24577 of the function is taken or if inlining fails. In general, we emit an
24578 out-of-line copy in all translation units where one is needed. As an
24579 exception, we only emit inline virtual functions with the vtable, since
24580 it always requires a copy.
24582 Local static variables and string constants used in an inline function
24583 are also considered to have vague linkage, since they must be shared
24584 between all inlined and out-of-line instances of the function.
24588 C++ virtual functions are implemented in most compilers using a lookup
24589 table, known as a vtable. The vtable contains pointers to the virtual
24590 functions provided by a class, and each object of the class contains a
24591 pointer to its vtable (or vtables, in some multiple-inheritance
24592 situations). If the class declares any non-inline, non-pure virtual
24593 functions, the first one is chosen as the ``key method'' for the class,
24594 and the vtable is only emitted in the translation unit where the key
24597 @emph{Note:} If the chosen key method is later defined as inline, the
24598 vtable is still emitted in every translation unit that defines it.
24599 Make sure that any inline virtuals are declared inline in the class
24600 body, even if they are not defined there.
24602 @item @code{type_info} objects
24603 @cindex @code{type_info}
24605 C++ requires information about types to be written out in order to
24606 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
24607 For polymorphic classes (classes with virtual functions), the @samp{type_info}
24608 object is written out along with the vtable so that @samp{dynamic_cast}
24609 can determine the dynamic type of a class object at run time. For all
24610 other types, we write out the @samp{type_info} object when it is used: when
24611 applying @samp{typeid} to an expression, throwing an object, or
24612 referring to a type in a catch clause or exception specification.
24614 @item Template Instantiations
24615 Most everything in this section also applies to template instantiations,
24616 but there are other options as well.
24617 @xref{Template Instantiation,,Where's the Template?}.
24621 When used with GNU ld version 2.8 or later on an ELF system such as
24622 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
24623 these constructs will be discarded at link time. This is known as
24626 On targets that don't support COMDAT, but do support weak symbols, GCC
24627 uses them. This way one copy overrides all the others, but
24628 the unused copies still take up space in the executable.
24630 For targets that do not support either COMDAT or weak symbols,
24631 most entities with vague linkage are emitted as local symbols to
24632 avoid duplicate definition errors from the linker. This does not happen
24633 for local statics in inlines, however, as having multiple copies
24634 almost certainly breaks things.
24636 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
24637 another way to control placement of these constructs.
24639 @node C++ Interface
24640 @section C++ Interface and Implementation Pragmas
24642 @cindex interface and implementation headers, C++
24643 @cindex C++ interface and implementation headers
24644 @cindex pragmas, interface and implementation
24646 @code{#pragma interface} and @code{#pragma implementation} provide the
24647 user with a way of explicitly directing the compiler to emit entities
24648 with vague linkage (and debugging information) in a particular
24651 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
24652 by COMDAT support and the ``key method'' heuristic
24653 mentioned in @ref{Vague Linkage}. Using them can actually cause your
24654 program to grow due to unnecessary out-of-line copies of inline
24658 @item #pragma interface
24659 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
24660 @kindex #pragma interface
24661 Use this directive in @emph{header files} that define object classes, to save
24662 space in most of the object files that use those classes. Normally,
24663 local copies of certain information (backup copies of inline member
24664 functions, debugging information, and the internal tables that implement
24665 virtual functions) must be kept in each object file that includes class
24666 definitions. You can use this pragma to avoid such duplication. When a
24667 header file containing @samp{#pragma interface} is included in a
24668 compilation, this auxiliary information is not generated (unless
24669 the main input source file itself uses @samp{#pragma implementation}).
24670 Instead, the object files contain references to be resolved at link
24673 The second form of this directive is useful for the case where you have
24674 multiple headers with the same name in different directories. If you
24675 use this form, you must specify the same string to @samp{#pragma
24678 @item #pragma implementation
24679 @itemx #pragma implementation "@var{objects}.h"
24680 @kindex #pragma implementation
24681 Use this pragma in a @emph{main input file}, when you want full output from
24682 included header files to be generated (and made globally visible). The
24683 included header file, in turn, should use @samp{#pragma interface}.
24684 Backup copies of inline member functions, debugging information, and the
24685 internal tables used to implement virtual functions are all generated in
24686 implementation files.
24688 @cindex implied @code{#pragma implementation}
24689 @cindex @code{#pragma implementation}, implied
24690 @cindex naming convention, implementation headers
24691 If you use @samp{#pragma implementation} with no argument, it applies to
24692 an include file with the same basename@footnote{A file's @dfn{basename}
24693 is the name stripped of all leading path information and of trailing
24694 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
24695 file. For example, in @file{allclass.cc}, giving just
24696 @samp{#pragma implementation}
24697 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
24699 Use the string argument if you want a single implementation file to
24700 include code from multiple header files. (You must also use
24701 @samp{#include} to include the header file; @samp{#pragma
24702 implementation} only specifies how to use the file---it doesn't actually
24705 There is no way to split up the contents of a single header file into
24706 multiple implementation files.
24709 @cindex inlining and C++ pragmas
24710 @cindex C++ pragmas, effect on inlining
24711 @cindex pragmas in C++, effect on inlining
24712 @samp{#pragma implementation} and @samp{#pragma interface} also have an
24713 effect on function inlining.
24715 If you define a class in a header file marked with @samp{#pragma
24716 interface}, the effect on an inline function defined in that class is
24717 similar to an explicit @code{extern} declaration---the compiler emits
24718 no code at all to define an independent version of the function. Its
24719 definition is used only for inlining with its callers.
24721 @opindex fno-implement-inlines
24722 Conversely, when you include the same header file in a main source file
24723 that declares it as @samp{#pragma implementation}, the compiler emits
24724 code for the function itself; this defines a version of the function
24725 that can be found via pointers (or by callers compiled without
24726 inlining). If all calls to the function can be inlined, you can avoid
24727 emitting the function by compiling with @option{-fno-implement-inlines}.
24728 If any calls are not inlined, you will get linker errors.
24730 @node Template Instantiation
24731 @section Where's the Template?
24732 @cindex template instantiation
24734 C++ templates were the first language feature to require more
24735 intelligence from the environment than was traditionally found on a UNIX
24736 system. Somehow the compiler and linker have to make sure that each
24737 template instance occurs exactly once in the executable if it is needed,
24738 and not at all otherwise. There are two basic approaches to this
24739 problem, which are referred to as the Borland model and the Cfront model.
24742 @item Borland model
24743 Borland C++ solved the template instantiation problem by adding the code
24744 equivalent of common blocks to their linker; the compiler emits template
24745 instances in each translation unit that uses them, and the linker
24746 collapses them together. The advantage of this model is that the linker
24747 only has to consider the object files themselves; there is no external
24748 complexity to worry about. The disadvantage is that compilation time
24749 is increased because the template code is being compiled repeatedly.
24750 Code written for this model tends to include definitions of all
24751 templates in the header file, since they must be seen to be
24755 The AT&T C++ translator, Cfront, solved the template instantiation
24756 problem by creating the notion of a template repository, an
24757 automatically maintained place where template instances are stored. A
24758 more modern version of the repository works as follows: As individual
24759 object files are built, the compiler places any template definitions and
24760 instantiations encountered in the repository. At link time, the link
24761 wrapper adds in the objects in the repository and compiles any needed
24762 instances that were not previously emitted. The advantages of this
24763 model are more optimal compilation speed and the ability to use the
24764 system linker; to implement the Borland model a compiler vendor also
24765 needs to replace the linker. The disadvantages are vastly increased
24766 complexity, and thus potential for error; for some code this can be
24767 just as transparent, but in practice it can been very difficult to build
24768 multiple programs in one directory and one program in multiple
24769 directories. Code written for this model tends to separate definitions
24770 of non-inline member templates into a separate file, which should be
24771 compiled separately.
24774 G++ implements the Borland model on targets where the linker supports it,
24775 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
24776 Otherwise G++ implements neither automatic model.
24778 You have the following options for dealing with template instantiations:
24782 Do nothing. Code written for the Borland model works fine, but
24783 each translation unit contains instances of each of the templates it
24784 uses. The duplicate instances will be discarded by the linker, but in
24785 a large program, this can lead to an unacceptable amount of code
24786 duplication in object files or shared libraries.
24788 Duplicate instances of a template can be avoided by defining an explicit
24789 instantiation in one object file, and preventing the compiler from doing
24790 implicit instantiations in any other object files by using an explicit
24791 instantiation declaration, using the @code{extern template} syntax:
24794 extern template int max (int, int);
24797 This syntax is defined in the C++ 2011 standard, but has been supported by
24798 G++ and other compilers since well before 2011.
24800 Explicit instantiations can be used for the largest or most frequently
24801 duplicated instances, without having to know exactly which other instances
24802 are used in the rest of the program. You can scatter the explicit
24803 instantiations throughout your program, perhaps putting them in the
24804 translation units where the instances are used or the translation units
24805 that define the templates themselves; you can put all of the explicit
24806 instantiations you need into one big file; or you can create small files
24813 template class Foo<int>;
24814 template ostream& operator <<
24815 (ostream&, const Foo<int>&);
24819 for each of the instances you need, and create a template instantiation
24820 library from those.
24822 This is the simplest option, but also offers flexibility and
24823 fine-grained control when necessary. It is also the most portable
24824 alternative and programs using this approach will work with most modern
24828 @opindex fno-implicit-templates
24829 Compile your code with @option{-fno-implicit-templates} to disable the
24830 implicit generation of template instances, and explicitly instantiate
24831 all the ones you use. This approach requires more knowledge of exactly
24832 which instances you need than do the others, but it's less
24833 mysterious and allows greater control if you want to ensure that only
24834 the intended instances are used.
24836 If you are using Cfront-model code, you can probably get away with not
24837 using @option{-fno-implicit-templates} when compiling files that don't
24838 @samp{#include} the member template definitions.
24840 If you use one big file to do the instantiations, you may want to
24841 compile it without @option{-fno-implicit-templates} so you get all of the
24842 instances required by your explicit instantiations (but not by any
24843 other files) without having to specify them as well.
24845 In addition to forward declaration of explicit instantiations
24846 (with @code{extern}), G++ has extended the template instantiation
24847 syntax to support instantiation of the compiler support data for a
24848 template class (i.e.@: the vtable) without instantiating any of its
24849 members (with @code{inline}), and instantiation of only the static data
24850 members of a template class, without the support data or member
24851 functions (with @code{static}):
24854 inline template class Foo<int>;
24855 static template class Foo<int>;
24859 @node Bound member functions
24860 @section Extracting the Function Pointer from a Bound Pointer to Member Function
24862 @cindex pointer to member function
24863 @cindex bound pointer to member function
24865 In C++, pointer to member functions (PMFs) are implemented using a wide
24866 pointer of sorts to handle all the possible call mechanisms; the PMF
24867 needs to store information about how to adjust the @samp{this} pointer,
24868 and if the function pointed to is virtual, where to find the vtable, and
24869 where in the vtable to look for the member function. If you are using
24870 PMFs in an inner loop, you should really reconsider that decision. If
24871 that is not an option, you can extract the pointer to the function that
24872 would be called for a given object/PMF pair and call it directly inside
24873 the inner loop, to save a bit of time.
24875 Note that you still pay the penalty for the call through a
24876 function pointer; on most modern architectures, such a call defeats the
24877 branch prediction features of the CPU@. This is also true of normal
24878 virtual function calls.
24880 The syntax for this extension is
24884 extern int (A::*fp)();
24885 typedef int (*fptr)(A *);
24887 fptr p = (fptr)(a.*fp);
24890 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
24891 no object is needed to obtain the address of the function. They can be
24892 converted to function pointers directly:
24895 fptr p1 = (fptr)(&A::foo);
24898 @opindex Wno-pmf-conversions
24899 You must specify @option{-Wno-pmf-conversions} to use this extension.
24901 @node C++ Attributes
24902 @section C++-Specific Variable, Function, and Type Attributes
24904 Some attributes only make sense for C++ programs.
24907 @item abi_tag ("@var{tag}", ...)
24908 @cindex @code{abi_tag} function attribute
24909 @cindex @code{abi_tag} variable attribute
24910 @cindex @code{abi_tag} type attribute
24911 The @code{abi_tag} attribute can be applied to a function, variable, or class
24912 declaration. It modifies the mangled name of the entity to
24913 incorporate the tag name, in order to distinguish the function or
24914 class from an earlier version with a different ABI; perhaps the class
24915 has changed size, or the function has a different return type that is
24916 not encoded in the mangled name.
24918 The attribute can also be applied to an inline namespace, but does not
24919 affect the mangled name of the namespace; in this case it is only used
24920 for @option{-Wabi-tag} warnings and automatic tagging of functions and
24921 variables. Tagging inline namespaces is generally preferable to
24922 tagging individual declarations, but the latter is sometimes
24923 necessary, such as when only certain members of a class need to be
24926 The argument can be a list of strings of arbitrary length. The
24927 strings are sorted on output, so the order of the list is
24930 A redeclaration of an entity must not add new ABI tags,
24931 since doing so would change the mangled name.
24933 The ABI tags apply to a name, so all instantiations and
24934 specializations of a template have the same tags. The attribute will
24935 be ignored if applied to an explicit specialization or instantiation.
24937 The @option{-Wabi-tag} flag enables a warning about a class which does
24938 not have all the ABI tags used by its subobjects and virtual functions; for users with code
24939 that needs to coexist with an earlier ABI, using this option can help
24940 to find all affected types that need to be tagged.
24942 When a type involving an ABI tag is used as the type of a variable or
24943 return type of a function where that tag is not already present in the
24944 signature of the function, the tag is automatically applied to the
24945 variable or function. @option{-Wabi-tag} also warns about this
24946 situation; this warning can be avoided by explicitly tagging the
24947 variable or function or moving it into a tagged inline namespace.
24949 @item init_priority (@var{priority})
24950 @cindex @code{init_priority} variable attribute
24952 In Standard C++, objects defined at namespace scope are guaranteed to be
24953 initialized in an order in strict accordance with that of their definitions
24954 @emph{in a given translation unit}. No guarantee is made for initializations
24955 across translation units. However, GNU C++ allows users to control the
24956 order of initialization of objects defined at namespace scope with the
24957 @code{init_priority} attribute by specifying a relative @var{priority},
24958 a constant integral expression currently bounded between 101 and 65535
24959 inclusive. Lower numbers indicate a higher priority.
24961 In the following example, @code{A} would normally be created before
24962 @code{B}, but the @code{init_priority} attribute reverses that order:
24965 Some_Class A __attribute__ ((init_priority (2000)));
24966 Some_Class B __attribute__ ((init_priority (543)));
24970 Note that the particular values of @var{priority} do not matter; only their
24974 @cindex @code{warn_unused} type attribute
24976 For C++ types with non-trivial constructors and/or destructors it is
24977 impossible for the compiler to determine whether a variable of this
24978 type is truly unused if it is not referenced. This type attribute
24979 informs the compiler that variables of this type should be warned
24980 about if they appear to be unused, just like variables of fundamental
24983 This attribute is appropriate for types which just represent a value,
24984 such as @code{std::string}; it is not appropriate for types which
24985 control a resource, such as @code{std::lock_guard}.
24987 This attribute is also accepted in C, but it is unnecessary because C
24988 does not have constructors or destructors.
24992 @node Function Multiversioning
24993 @section Function Multiversioning
24994 @cindex function versions
24996 With the GNU C++ front end, for x86 targets, you may specify multiple
24997 versions of a function, where each function is specialized for a
24998 specific target feature. At runtime, the appropriate version of the
24999 function is automatically executed depending on the characteristics of
25000 the execution platform. Here is an example.
25003 __attribute__ ((target ("default")))
25006 // The default version of foo.
25010 __attribute__ ((target ("sse4.2")))
25013 // foo version for SSE4.2
25017 __attribute__ ((target ("arch=atom")))
25020 // foo version for the Intel ATOM processor
25024 __attribute__ ((target ("arch=amdfam10")))
25027 // foo version for the AMD Family 0x10 processors.
25034 assert ((*p) () == foo ());
25039 In the above example, four versions of function foo are created. The
25040 first version of foo with the target attribute "default" is the default
25041 version. This version gets executed when no other target specific
25042 version qualifies for execution on a particular platform. A new version
25043 of foo is created by using the same function signature but with a
25044 different target string. Function foo is called or a pointer to it is
25045 taken just like a regular function. GCC takes care of doing the
25046 dispatching to call the right version at runtime. Refer to the
25047 @uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
25048 Function Multiversioning} for more details.
25051 @section Type Traits
25053 The C++ front end implements syntactic extensions that allow
25054 compile-time determination of
25055 various characteristics of a type (or of a
25059 @item __has_nothrow_assign (type)
25060 If @code{type} is @code{const}-qualified or is a reference type then
25061 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
25062 is @code{true} then the trait is @code{true}, else if @code{type} is
25063 a cv-qualified class or union type with copy assignment operators that are
25064 known not to throw an exception then the trait is @code{true}, else it is
25066 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25067 @code{void}, or an array of unknown bound.
25069 @item __has_nothrow_copy (type)
25070 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
25071 @code{true}, else if @code{type} is a cv-qualified class or union type
25072 with copy constructors that are known not to throw an exception then
25073 the trait is @code{true}, else it is @code{false}.
25074 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25075 @code{void}, or an array of unknown bound.
25077 @item __has_nothrow_constructor (type)
25078 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
25079 is @code{true}, else if @code{type} is a cv class or union type (or array
25080 thereof) with a default constructor that is known not to throw an
25081 exception then the trait is @code{true}, else it is @code{false}.
25082 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25083 @code{void}, or an array of unknown bound.
25085 @item __has_trivial_assign (type)
25086 If @code{type} is @code{const}- qualified or is a reference type then
25087 the trait is @code{false}. Otherwise if @code{__is_trivial (type)} is
25088 @code{true} then the trait is @code{true}, else if @code{type} is
25089 a cv-qualified class or union type with a trivial copy assignment
25090 ([class.copy]) then the trait is @code{true}, else it is @code{false}.
25091 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25092 @code{void}, or an array of unknown bound.
25094 @item __has_trivial_copy (type)
25095 If @code{__is_trivial (type)} is @code{true} or @code{type} is a reference
25096 type then the trait is @code{true}, else if @code{type} is a cv class
25097 or union type with a trivial copy constructor ([class.copy]) then the trait
25098 is @code{true}, else it is @code{false}. Requires: @code{type} shall be
25099 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
25102 @item __has_trivial_constructor (type)
25103 If @code{__is_trivial (type)} is @code{true} then the trait is @code{true},
25104 else if @code{type} is a cv-qualified class or union type (or array thereof)
25105 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
25106 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 __has_trivial_destructor (type)
25111 If @code{__is_trivial (type)} is @code{true} or @code{type} is a reference type
25112 then the trait is @code{true}, else if @code{type} is a cv class or union
25113 type (or array thereof) with a trivial destructor ([class.dtor]) then
25114 the trait is @code{true}, else it is @code{false}.
25115 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25116 @code{void}, or an array of unknown bound.
25118 @item __has_virtual_destructor (type)
25119 If @code{type} is a class type with a virtual destructor
25120 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
25121 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25122 @code{void}, or an array of unknown bound.
25124 @item __is_abstract (type)
25125 If @code{type} is an abstract class ([class.abstract]) then the trait
25126 is @code{true}, else it is @code{false}.
25127 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25128 @code{void}, or an array of unknown bound.
25130 @item __is_base_of (base_type, derived_type)
25131 If @code{base_type} is a base class of @code{derived_type}
25132 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
25133 Top-level cv-qualifications of @code{base_type} and
25134 @code{derived_type} are ignored. For the purposes of this trait, a
25135 class type is considered is own base.
25136 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
25137 are @code{true} and @code{base_type} and @code{derived_type} are not the same
25138 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
25139 type. A diagnostic is produced if this requirement is not met.
25141 @item __is_class (type)
25142 If @code{type} is a cv-qualified class type, and not a union type
25143 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
25145 @item __is_empty (type)
25146 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
25147 Otherwise @code{type} is considered empty if and only if: @code{type}
25148 has no non-static data members, or all non-static data members, if
25149 any, are bit-fields of length 0, and @code{type} has no virtual
25150 members, and @code{type} has no virtual base classes, and @code{type}
25151 has no base classes @code{base_type} for which
25152 @code{__is_empty (base_type)} is @code{false}.
25153 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25154 @code{void}, or an array of unknown bound.
25156 @item __is_enum (type)
25157 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
25158 @code{true}, else it is @code{false}.
25160 @item __is_literal_type (type)
25161 If @code{type} is a literal type ([basic.types]) the trait is
25162 @code{true}, else it is @code{false}.
25163 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25164 @code{void}, or an array of unknown bound.
25166 @item __is_pod (type)
25167 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
25168 else it is @code{false}.
25169 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25170 @code{void}, or an array of unknown bound.
25172 @item __is_polymorphic (type)
25173 If @code{type} is a polymorphic class ([class.virtual]) then the trait
25174 is @code{true}, else it is @code{false}.
25175 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25176 @code{void}, or an array of unknown bound.
25178 @item __is_standard_layout (type)
25179 If @code{type} is a standard-layout type ([basic.types]) the trait is
25180 @code{true}, else it is @code{false}.
25181 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25182 @code{void}, or an array of unknown bound.
25184 @item __is_trivial (type)
25185 If @code{type} is a trivial type ([basic.types]) the trait is
25186 @code{true}, else it is @code{false}.
25187 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25188 @code{void}, or an array of unknown bound.
25190 @item __is_union (type)
25191 If @code{type} is a cv union type ([basic.compound]) the trait is
25192 @code{true}, else it is @code{false}.
25194 @item __underlying_type (type)
25195 The underlying type of @code{type}.
25196 Requires: @code{type} shall be an enumeration type ([dcl.enum]).
25198 @item __integer_pack (length)
25199 When used as the pattern of a pack expansion within a template
25200 definition, expands to a template argument pack containing integers
25201 from @code{0} to @code{length-1}. This is provided for efficient
25202 implementation of @code{std::make_integer_sequence}.
25208 @section C++ Concepts
25210 C++ concepts provide much-improved support for generic programming. In
25211 particular, they allow the specification of constraints on template arguments.
25212 The constraints are used to extend the usual overloading and partial
25213 specialization capabilities of the language, allowing generic data structures
25214 and algorithms to be ``refined'' based on their properties rather than their
25217 The following keywords are reserved for concepts.
25221 States an expression as an assumption, and if possible, verifies that the
25222 assumption is valid. For example, @code{assume(n > 0)}.
25225 Introduces an axiom definition. Axioms introduce requirements on values.
25228 Introduces a universally quantified object in an axiom. For example,
25229 @code{forall (int n) n + 0 == n}).
25232 Introduces a concept definition. Concepts are sets of syntactic and semantic
25233 requirements on types and their values.
25236 Introduces constraints on template arguments or requirements for a member
25237 function of a class template.
25241 The front end also exposes a number of internal mechanism that can be used
25242 to simplify the writing of type traits. Note that some of these traits are
25243 likely to be removed in the future.
25246 @item __is_same (type1, type2)
25247 A binary type trait: @code{true} whenever the type arguments are the same.
25252 @node Deprecated Features
25253 @section Deprecated Features
25255 In the past, the GNU C++ compiler was extended to experiment with new
25256 features, at a time when the C++ language was still evolving. Now that
25257 the C++ standard is complete, some of those features are superseded by
25258 superior alternatives. Using the old features might cause a warning in
25259 some cases that the feature will be dropped in the future. In other
25260 cases, the feature might be gone already.
25262 G++ allows a virtual function returning @samp{void *} to be overridden
25263 by one returning a different pointer type. This extension to the
25264 covariant return type rules is now deprecated and will be removed from a
25267 The use of default arguments in function pointers, function typedefs
25268 and other places where they are not permitted by the standard is
25269 deprecated and will be removed from a future version of G++.
25271 G++ allows floating-point literals to appear in integral constant expressions,
25272 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
25273 This extension is deprecated and will be removed from a future version.
25275 G++ allows static data members of const floating-point type to be declared
25276 with an initializer in a class definition. The standard only allows
25277 initializers for static members of const integral types and const
25278 enumeration types so this extension has been deprecated and will be removed
25279 from a future version.
25281 G++ allows attributes to follow a parenthesized direct initializer,
25282 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
25283 has been ignored since G++ 3.3 and is deprecated.
25285 G++ allows anonymous structs and unions to have members that are not
25286 public non-static data members (i.e.@: fields). These extensions are
25289 @node Backwards Compatibility
25290 @section Backwards Compatibility
25291 @cindex Backwards Compatibility
25292 @cindex ARM [Annotated C++ Reference Manual]
25294 Now that there is a definitive ISO standard C++, G++ has a specification
25295 to adhere to. The C++ language evolved over time, and features that
25296 used to be acceptable in previous drafts of the standard, such as the ARM
25297 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
25298 compilation of C++ written to such drafts, G++ contains some backwards
25299 compatibilities. @emph{All such backwards compatibility features are
25300 liable to disappear in future versions of G++.} They should be considered
25301 deprecated. @xref{Deprecated Features}.
25305 @item Implicit C language
25306 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
25307 scope to set the language. On such systems, all system header files are
25308 implicitly scoped inside a C language scope. Such headers must
25309 correctly prototype function argument types, there is no leeway for
25310 @code{()} to indicate an unspecified set of arguments.
25314 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
25315 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr