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 @cindex @code{__real__} keyword
990 @cindex @code{__imag__} keyword
991 To extract the real part of a complex-valued expression @var{exp}, write
992 @code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
993 extract the imaginary part. This is a GNU extension; for values of
994 floating type, you should use the ISO C99 functions @code{crealf},
995 @code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
996 @code{cimagl}, declared in @code{<complex.h>} and also provided as
997 built-in functions by GCC@.
999 @cindex complex conjugation
1000 The operator @samp{~} performs complex conjugation when used on a value
1001 with a complex type. This is a GNU extension; for values of
1002 floating type, you should use the ISO C99 functions @code{conjf},
1003 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
1004 provided as built-in functions by GCC@.
1006 GCC can allocate complex automatic variables in a noncontiguous
1007 fashion; it's even possible for the real part to be in a register while
1008 the imaginary part is on the stack (or vice versa). Only the DWARF
1009 debug info format can represent this, so use of DWARF is recommended.
1010 If you are using the stabs debug info format, GCC describes a noncontiguous
1011 complex variable as if it were two separate variables of noncomplex type.
1012 If the variable's actual name is @code{foo}, the two fictitious
1013 variables are named @code{foo$real} and @code{foo$imag}. You can
1014 examine and set these two fictitious variables with your debugger.
1016 @node Floating Types
1017 @section Additional Floating Types
1018 @cindex additional floating types
1019 @cindex @code{_Float@var{n}} data types
1020 @cindex @code{_Float@var{n}x} data types
1021 @cindex @code{__float80} data type
1022 @cindex @code{__float128} data type
1023 @cindex @code{__ibm128} data type
1024 @cindex @code{w} floating point suffix
1025 @cindex @code{q} floating point suffix
1026 @cindex @code{W} floating point suffix
1027 @cindex @code{Q} floating point suffix
1029 ISO/IEC TS 18661-3:2015 defines C support for additional floating
1030 types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
1031 these type names; the set of types supported depends on the target
1032 architecture. These types are not supported when compiling C++.
1033 Constants with these types use suffixes @code{f@var{n}} or
1034 @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
1035 names can be used together with @code{_Complex} to declare complex
1038 As an extension, GNU C and GNU C++ support additional floating
1039 types, which are not supported by all targets.
1041 @item @code{__float128} is available on i386, x86_64, IA-64, and
1042 hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
1043 the vector scalar (VSX) instruction set. @code{__float128} supports
1044 the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64
1045 other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
1046 On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
1049 @item @code{__float80} is available on the i386, x86_64, and IA-64
1050 targets, and supports the 80-bit (@code{XFmode}) floating type. It is
1051 an alias for the type name @code{_Float64x} on these targets.
1053 @item @code{__ibm128} is available on PowerPC targets, and provides
1054 access to the IBM extended double format which is the current format
1055 used for @code{long double}. When @code{long double} transitions to
1056 @code{__float128} on PowerPC in the future, @code{__ibm128} will remain
1057 for use in conversions between the two types.
1060 Support for these additional types includes the arithmetic operators:
1061 add, subtract, multiply, divide; unary arithmetic operators;
1062 relational operators; equality operators; and conversions to and from
1063 integer and other floating types. Use a suffix @samp{w} or @samp{W}
1064 in a literal constant of type @code{__float80} or type
1065 @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}.
1067 In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
1068 on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
1069 expected in future versions of GCC that @code{_Float128} and @code{__float128}
1070 will be enabled automatically.
1072 The @code{_Float128} type is supported on all systems where
1073 @code{__float128} is supported or where @code{long double} has the
1074 IEEE binary128 format. The @code{_Float64x} type is supported on all
1075 systems where @code{__float128} is supported. The @code{_Float32}
1076 type is supported on all systems supporting IEEE binary32; the
1077 @code{_Float64} and @code{_Float32x} types are supported on all systems
1078 supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
1079 systems by default, on ARM systems when the IEEE format for 16-bit
1080 floating-point types is selected with @option{-mfp16-format=ieee} and,
1081 for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently
1082 support @code{_Float128x} on any systems.
1084 On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
1085 types using the corresponding internal complex type, @code{XCmode} for
1086 @code{__float80} type and @code{TCmode} for @code{__float128} type:
1089 typedef _Complex float __attribute__((mode(TC))) _Complex128;
1090 typedef _Complex float __attribute__((mode(XC))) _Complex80;
1093 On the PowerPC Linux VSX targets, you can declare complex types using
1094 the corresponding internal complex type, @code{KCmode} for
1095 @code{__float128} type and @code{ICmode} for @code{__ibm128} type:
1098 typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
1099 typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
1102 @node Half-Precision
1103 @section Half-Precision Floating Point
1104 @cindex half-precision floating point
1105 @cindex @code{__fp16} data type
1106 @cindex @code{__Float16} data type
1108 On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
1109 point via the @code{__fp16} type defined in the ARM C Language Extensions.
1110 On ARM systems, you must enable this type explicitly with the
1111 @option{-mfp16-format} command-line option in order to use it.
1112 On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit)
1113 floating point via the @code{_Float16} type. For C++, x86 provides a builtin
1114 type named @code{_Float16} which contains same data format as C.
1116 ARM targets support two incompatible representations for half-precision
1117 floating-point values. You must choose one of the representations and
1118 use it consistently in your program.
1120 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
1121 This format can represent normalized values in the range of @math{2^{-14}} to 65504.
1122 There are 11 bits of significand precision, approximately 3
1125 Specifying @option{-mfp16-format=alternative} selects the ARM
1126 alternative format. This representation is similar to the IEEE
1127 format, but does not support infinities or NaNs. Instead, the range
1128 of exponents is extended, so that this format can represent normalized
1129 values in the range of @math{2^{-14}} to 131008.
1131 The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
1132 not require use of the @option{-mfp16-format} command-line option.
1134 The @code{__fp16} type may only be used as an argument to intrinsics defined
1135 in @code{<arm_fp16.h>}, or as a storage format. For purposes of
1136 arithmetic and other operations, @code{__fp16} values in C or C++
1137 expressions are automatically promoted to @code{float}.
1139 The ARM target provides hardware support for conversions between
1140 @code{__fp16} and @code{float} values
1141 as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
1142 hardware support for conversions between @code{__fp16} and @code{double}
1143 values. GCC generates code using these hardware instructions if you
1144 compile with options to select an FPU that provides them;
1145 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
1146 in addition to the @option{-mfp16-format} option to select
1147 a half-precision format.
1149 Language-level support for the @code{__fp16} data type is
1150 independent of whether GCC generates code using hardware floating-point
1151 instructions. In cases where hardware support is not specified, GCC
1152 implements conversions between @code{__fp16} and other types as library
1155 It is recommended that portable code use the @code{_Float16} type defined
1156 by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
1158 On x86 targets with SSE2 enabled, without @option{-mavx512fp16},
1159 all operations will be emulated by software emulation and the @code{float}
1160 instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the
1161 intermediate result of the operation as 32-bit precision. This may lead to
1162 inconsistent behavior between software emulation and AVX512-FP16 instructions.
1163 Using @option{-fexcess-precision=16} will force round back after each operation.
1165 Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of
1166 software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round
1167 after each operation. The same is true with @option{-fexcess-precision=standard}
1168 and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse},
1169 @option{-fexcess-precision=standard} alone does the same thing as before,
1170 It is useful for code that does not have @code{_Float16} and runs on the x87
1174 @section Decimal Floating Types
1175 @cindex decimal floating types
1176 @cindex @code{_Decimal32} data type
1177 @cindex @code{_Decimal64} data type
1178 @cindex @code{_Decimal128} data type
1179 @cindex @code{df} integer suffix
1180 @cindex @code{dd} integer suffix
1181 @cindex @code{dl} integer suffix
1182 @cindex @code{DF} integer suffix
1183 @cindex @code{DD} integer suffix
1184 @cindex @code{DL} integer suffix
1186 As an extension, GNU C supports decimal floating types as
1187 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
1188 floating types in GCC will evolve as the draft technical report changes.
1189 Calling conventions for any target might also change. Not all targets
1190 support decimal floating types.
1192 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
1193 @code{_Decimal128}. They use a radix of ten, unlike the floating types
1194 @code{float}, @code{double}, and @code{long double} whose radix is not
1195 specified by the C standard but is usually two.
1197 Support for decimal floating types includes the arithmetic operators
1198 add, subtract, multiply, divide; unary arithmetic operators;
1199 relational operators; equality operators; and conversions to and from
1200 integer and other floating types. Use a suffix @samp{df} or
1201 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1202 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1205 GCC support of decimal float as specified by the draft technical report
1210 When the value of a decimal floating type cannot be represented in the
1211 integer type to which it is being converted, the result is undefined
1212 rather than the result value specified by the draft technical report.
1215 GCC does not provide the C library functionality associated with
1216 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1217 @file{wchar.h}, which must come from a separate C library implementation.
1218 Because of this the GNU C compiler does not define macro
1219 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1220 the technical report.
1223 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1224 are supported by the DWARF debug information format.
1230 ISO C99 and ISO C++17 support floating-point numbers written not only in
1231 the usual decimal notation, such as @code{1.55e1}, but also numbers such as
1232 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
1233 supports this in C90 mode (except in some cases when strictly
1234 conforming) and in C++98, C++11 and C++14 modes. In that format the
1235 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1236 mandatory. The exponent is a decimal number that indicates the power of
1237 2 by which the significant part is multiplied. Thus @samp{0x1.f} is
1244 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1245 is the same as @code{1.55e1}.
1247 Unlike for floating-point numbers in the decimal notation the exponent
1248 is always required in the hexadecimal notation. Otherwise the compiler
1249 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
1250 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1251 extension for floating-point constants of type @code{float}.
1254 @section Fixed-Point Types
1255 @cindex fixed-point types
1256 @cindex @code{_Fract} data type
1257 @cindex @code{_Accum} data type
1258 @cindex @code{_Sat} data type
1259 @cindex @code{hr} fixed-suffix
1260 @cindex @code{r} fixed-suffix
1261 @cindex @code{lr} fixed-suffix
1262 @cindex @code{llr} fixed-suffix
1263 @cindex @code{uhr} fixed-suffix
1264 @cindex @code{ur} fixed-suffix
1265 @cindex @code{ulr} fixed-suffix
1266 @cindex @code{ullr} fixed-suffix
1267 @cindex @code{hk} fixed-suffix
1268 @cindex @code{k} fixed-suffix
1269 @cindex @code{lk} fixed-suffix
1270 @cindex @code{llk} fixed-suffix
1271 @cindex @code{uhk} fixed-suffix
1272 @cindex @code{uk} fixed-suffix
1273 @cindex @code{ulk} fixed-suffix
1274 @cindex @code{ullk} fixed-suffix
1275 @cindex @code{HR} fixed-suffix
1276 @cindex @code{R} fixed-suffix
1277 @cindex @code{LR} fixed-suffix
1278 @cindex @code{LLR} fixed-suffix
1279 @cindex @code{UHR} fixed-suffix
1280 @cindex @code{UR} fixed-suffix
1281 @cindex @code{ULR} fixed-suffix
1282 @cindex @code{ULLR} fixed-suffix
1283 @cindex @code{HK} fixed-suffix
1284 @cindex @code{K} fixed-suffix
1285 @cindex @code{LK} fixed-suffix
1286 @cindex @code{LLK} fixed-suffix
1287 @cindex @code{UHK} fixed-suffix
1288 @cindex @code{UK} fixed-suffix
1289 @cindex @code{ULK} fixed-suffix
1290 @cindex @code{ULLK} fixed-suffix
1292 As an extension, GNU C supports fixed-point types as
1293 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
1294 types in GCC will evolve as the draft technical report changes.
1295 Calling conventions for any target might also change. Not all targets
1296 support fixed-point types.
1298 The fixed-point types are
1299 @code{short _Fract},
1302 @code{long long _Fract},
1303 @code{unsigned short _Fract},
1304 @code{unsigned _Fract},
1305 @code{unsigned long _Fract},
1306 @code{unsigned long long _Fract},
1307 @code{_Sat short _Fract},
1309 @code{_Sat long _Fract},
1310 @code{_Sat long long _Fract},
1311 @code{_Sat unsigned short _Fract},
1312 @code{_Sat unsigned _Fract},
1313 @code{_Sat unsigned long _Fract},
1314 @code{_Sat unsigned long long _Fract},
1315 @code{short _Accum},
1318 @code{long long _Accum},
1319 @code{unsigned short _Accum},
1320 @code{unsigned _Accum},
1321 @code{unsigned long _Accum},
1322 @code{unsigned long long _Accum},
1323 @code{_Sat short _Accum},
1325 @code{_Sat long _Accum},
1326 @code{_Sat long long _Accum},
1327 @code{_Sat unsigned short _Accum},
1328 @code{_Sat unsigned _Accum},
1329 @code{_Sat unsigned long _Accum},
1330 @code{_Sat unsigned long long _Accum}.
1332 Fixed-point data values contain fractional and optional integral parts.
1333 The format of fixed-point data varies and depends on the target machine.
1335 Support for fixed-point types includes:
1338 prefix and postfix increment and decrement operators (@code{++}, @code{--})
1340 unary arithmetic operators (@code{+}, @code{-}, @code{!})
1342 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1344 binary shift operators (@code{<<}, @code{>>})
1346 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1348 equality operators (@code{==}, @code{!=})
1350 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1351 @code{<<=}, @code{>>=})
1353 conversions to and from integer, floating-point, or fixed-point types
1356 Use a suffix in a fixed-point literal constant:
1358 @item @samp{hr} or @samp{HR} for @code{short _Fract} and
1359 @code{_Sat short _Fract}
1360 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1361 @item @samp{lr} or @samp{LR} for @code{long _Fract} and
1362 @code{_Sat long _Fract}
1363 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1364 @code{_Sat long long _Fract}
1365 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1366 @code{_Sat unsigned short _Fract}
1367 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1368 @code{_Sat unsigned _Fract}
1369 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1370 @code{_Sat unsigned long _Fract}
1371 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1372 and @code{_Sat unsigned long long _Fract}
1373 @item @samp{hk} or @samp{HK} for @code{short _Accum} and
1374 @code{_Sat short _Accum}
1375 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1376 @item @samp{lk} or @samp{LK} for @code{long _Accum} and
1377 @code{_Sat long _Accum}
1378 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1379 @code{_Sat long long _Accum}
1380 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1381 @code{_Sat unsigned short _Accum}
1382 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1383 @code{_Sat unsigned _Accum}
1384 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1385 @code{_Sat unsigned long _Accum}
1386 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1387 and @code{_Sat unsigned long long _Accum}
1390 GCC support of fixed-point types as specified by the draft technical report
1395 Pragmas to control overflow and rounding behaviors are not implemented.
1398 Fixed-point types are supported by the DWARF debug information format.
1400 @node Named Address Spaces
1401 @section Named Address Spaces
1402 @cindex Named Address Spaces
1404 As an extension, GNU C supports named address spaces as
1405 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
1406 address spaces in GCC will evolve as the draft technical report
1407 changes. Calling conventions for any target might also change. At
1408 present, only the AVR, M32C, PRU, RL78, and x86 targets support
1409 address spaces other than the generic address space.
1411 Address space identifiers may be used exactly like any other C type
1412 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1413 document for more details.
1415 @anchor{AVR Named Address Spaces}
1416 @subsection AVR Named Address Spaces
1418 On the AVR target, there are several address spaces that can be used
1419 in order to put read-only data into the flash memory and access that
1420 data by means of the special instructions @code{LPM} or @code{ELPM}
1421 needed to read from flash.
1423 Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
1424 flash memory by means of @code{LD*} instructions because the flash
1425 memory is mapped into the RAM address space. There is @emph{no need}
1426 for language extensions like @code{__flash} or attribute
1427 @ref{AVR Variable Attributes,,@code{progmem}}.
1428 The default linker description files for these devices cater for that
1429 feature and @code{.rodata} stays in flash: The compiler just generates
1430 @code{LD*} instructions, and the linker script adds core specific
1431 offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
1432 @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
1433 See @ref{AVR Options} for a list of respective devices.
1435 For devices not in @code{avrtiny} or @code{avrxmega3},
1436 any data including read-only data is located in RAM (the generic
1437 address space) because flash memory is not visible in the RAM address
1438 space. In order to locate read-only data in flash memory @emph{and}
1439 to generate the right instructions to access this data without
1440 using (inline) assembler code, special address spaces are needed.
1444 @cindex @code{__flash} AVR Named Address Spaces
1445 The @code{__flash} qualifier locates data in the
1446 @code{.progmem.data} section. Data is read using the @code{LPM}
1447 instruction. Pointers to this address space are 16 bits wide.
1454 @cindex @code{__flash1} AVR Named Address Spaces
1455 @cindex @code{__flash2} AVR Named Address Spaces
1456 @cindex @code{__flash3} AVR Named Address Spaces
1457 @cindex @code{__flash4} AVR Named Address Spaces
1458 @cindex @code{__flash5} AVR Named Address Spaces
1459 These are 16-bit address spaces locating data in section
1460 @code{.progmem@var{N}.data} where @var{N} refers to
1461 address space @code{__flash@var{N}}.
1462 The compiler sets the @code{RAMPZ} segment register appropriately
1463 before reading data by means of the @code{ELPM} instruction.
1466 @cindex @code{__memx} AVR Named Address Spaces
1467 This is a 24-bit address space that linearizes flash and RAM:
1468 If the high bit of the address is set, data is read from
1469 RAM using the lower two bytes as RAM address.
1470 If the high bit of the address is clear, data is read from flash
1471 with @code{RAMPZ} set according to the high byte of the address.
1472 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1474 Objects in this address space are located in @code{.progmemx.data}.
1480 char my_read (const __flash char ** p)
1482 /* p is a pointer to RAM that points to a pointer to flash.
1483 The first indirection of p reads that flash pointer
1484 from RAM and the second indirection reads a char from this
1490 /* Locate array[] in flash memory */
1491 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1497 /* Return 17 by reading from flash memory */
1498 return array[array[i]];
1503 For each named address space supported by avr-gcc there is an equally
1504 named but uppercase built-in macro defined.
1505 The purpose is to facilitate testing if respective address space
1506 support is available or not:
1510 const __flash int var = 1;
1517 #include <avr/pgmspace.h> /* From AVR-LibC */
1519 const int var PROGMEM = 1;
1523 return (int) pgm_read_word (&var);
1525 #endif /* __FLASH */
1529 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1530 locates data in flash but
1531 accesses to these data read from generic address space, i.e.@:
1533 so that you need special accessors like @code{pgm_read_byte}
1534 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1535 together with attribute @code{progmem}.
1538 @b{Limitations and caveats}
1542 Reading across the 64@tie{}KiB section boundary of
1543 the @code{__flash} or @code{__flash@var{N}} address spaces
1544 shows undefined behavior. The only address space that
1545 supports reading across the 64@tie{}KiB flash segment boundaries is
1549 If you use one of the @code{__flash@var{N}} address spaces
1550 you must arrange your linker script to locate the
1551 @code{.progmem@var{N}.data} sections according to your needs.
1554 Any data or pointers to the non-generic address spaces must
1555 be qualified as @code{const}, i.e.@: as read-only data.
1556 This still applies if the data in one of these address
1557 spaces like software version number or calibration lookup table are intended to
1558 be changed after load time by, say, a boot loader. In this case
1559 the right qualification is @code{const} @code{volatile} so that the compiler
1560 must not optimize away known values or insert them
1561 as immediates into operands of instructions.
1564 The following code initializes a variable @code{pfoo}
1565 located in static storage with a 24-bit address:
1567 extern const __memx char foo;
1568 const __memx void *pfoo = &foo;
1572 On the reduced Tiny devices like ATtiny40, no address spaces are supported.
1573 Just use vanilla C / C++ code without overhead as outlined above.
1574 Attribute @code{progmem} is supported but works differently,
1575 see @ref{AVR Variable Attributes}.
1579 @subsection M32C Named Address Spaces
1580 @cindex @code{__far} M32C Named Address Spaces
1582 On the M32C target, with the R8C and M16C CPU variants, variables
1583 qualified with @code{__far} are accessed using 32-bit addresses in
1584 order to access memory beyond the first 64@tie{}Ki bytes. If
1585 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1588 @subsection PRU Named Address Spaces
1589 @cindex @code{__regio_symbol} PRU Named Address Spaces
1591 On the PRU target, variables qualified with @code{__regio_symbol} are
1592 aliases used to access the special I/O CPU registers. They must be
1593 declared as @code{extern} because such variables will not be allocated in
1594 any data memory. They must also be marked as @code{volatile}, and can
1595 only be 32-bit integer types. The only names those variables can have
1596 are @code{__R30} and @code{__R31}, representing respectively the
1597 @code{R30} and @code{R31} special I/O CPU registers. Hence the following
1598 example is the only valid usage of @code{__regio_symbol}:
1601 extern volatile __regio_symbol uint32_t __R30;
1602 extern volatile __regio_symbol uint32_t __R31;
1605 @subsection RL78 Named Address Spaces
1606 @cindex @code{__far} RL78 Named Address Spaces
1608 On the RL78 target, variables qualified with @code{__far} are accessed
1609 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1610 addresses. Non-far variables are assumed to appear in the topmost
1611 64@tie{}KiB of the address space.
1613 @subsection x86 Named Address Spaces
1614 @cindex x86 named address spaces
1616 On the x86 target, variables may be declared as being relative
1617 to the @code{%fs} or @code{%gs} segments.
1622 @cindex @code{__seg_fs} x86 named address space
1623 @cindex @code{__seg_gs} x86 named address space
1624 The object is accessed with the respective segment override prefix.
1626 The respective segment base must be set via some method specific to
1627 the operating system. Rather than require an expensive system call
1628 to retrieve the segment base, these address spaces are not considered
1629 to be subspaces of the generic (flat) address space. This means that
1630 explicit casts are required to convert pointers between these address
1631 spaces and the generic address space. In practice the application
1632 should cast to @code{uintptr_t} and apply the segment base offset
1633 that it installed previously.
1635 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1636 defined when these address spaces are supported.
1640 @section Arrays of Length Zero
1641 @cindex arrays of length zero
1642 @cindex zero-length arrays
1643 @cindex length-zero arrays
1644 @cindex flexible array members
1646 Declaring zero-length arrays is allowed in GNU C as an extension.
1647 A zero-length array can be useful as the last element of a structure
1648 that is really a header for a variable-length object:
1656 struct line *thisline = (struct line *)
1657 malloc (sizeof (struct line) + this_length);
1658 thisline->length = this_length;
1661 Although the size of a zero-length array is zero, an array member of
1662 this kind may increase the size of the enclosing type as a result of tail
1663 padding. The offset of a zero-length array member from the beginning
1664 of the enclosing structure is the same as the offset of an array with
1665 one or more elements of the same type. The alignment of a zero-length
1666 array is the same as the alignment of its elements.
1668 Declaring zero-length arrays in other contexts, including as interior
1669 members of structure objects or as non-member objects, is discouraged.
1670 Accessing elements of zero-length arrays declared in such contexts is
1671 undefined and may be diagnosed.
1673 In the absence of the zero-length array extension, in ISO C90
1674 the @code{contents} array in the example above would typically be declared
1675 to have a single element. Unlike a zero-length array which only contributes
1676 to the size of the enclosing structure for the purposes of alignment,
1677 a one-element array always occupies at least as much space as a single
1678 object of the type. Although using one-element arrays this way is
1679 discouraged, GCC handles accesses to trailing one-element array members
1680 analogously to zero-length arrays.
1682 The preferred mechanism to declare variable-length types like
1683 @code{struct line} above is the ISO C99 @dfn{flexible array member},
1684 with slightly different syntax and semantics:
1688 Flexible array members are written as @code{contents[]} without
1692 Flexible array members have incomplete type, and so the @code{sizeof}
1693 operator may not be applied. As a quirk of the original implementation
1694 of zero-length arrays, @code{sizeof} evaluates to zero.
1697 Flexible array members may only appear as the last member of a
1698 @code{struct} that is otherwise non-empty.
1701 A structure containing a flexible array member, or a union containing
1702 such a structure (possibly recursively), may not be a member of a
1703 structure or an element of an array. (However, these uses are
1704 permitted by GCC as extensions.)
1707 Non-empty initialization of zero-length
1708 arrays is treated like any case where there are more initializer
1709 elements than the array holds, in that a suitable warning about ``excess
1710 elements in array'' is given, and the excess elements (all of them, in
1711 this case) are ignored.
1713 GCC allows static initialization of flexible array members.
1714 This is equivalent to defining a new structure containing the original
1715 structure followed by an array of sufficient size to contain the data.
1716 E.g.@: in the following, @code{f1} is constructed as if it were declared
1722 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1725 struct f1 f1; int data[3];
1726 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1730 The convenience of this extension is that @code{f1} has the desired
1731 type, eliminating the need to consistently refer to @code{f2.f1}.
1733 This has symmetry with normal static arrays, in that an array of
1734 unknown size is also written with @code{[]}.
1736 Of course, this extension only makes sense if the extra data comes at
1737 the end of a top-level object, as otherwise we would be overwriting
1738 data at subsequent offsets. To avoid undue complication and confusion
1739 with initialization of deeply nested arrays, we simply disallow any
1740 non-empty initialization except when the structure is the top-level
1741 object. For example:
1744 struct foo @{ int x; int y[]; @};
1745 struct bar @{ struct foo z; @};
1747 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1748 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1749 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1750 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1753 @node Empty Structures
1754 @section Structures with No Members
1755 @cindex empty structures
1756 @cindex zero-size structures
1758 GCC permits a C structure to have no members:
1765 The structure has size zero. In C++, empty structures are part
1766 of the language. G++ treats empty structures as if they had a single
1767 member of type @code{char}.
1769 @node Variable Length
1770 @section Arrays of Variable Length
1771 @cindex variable-length arrays
1772 @cindex arrays of variable length
1775 Variable-length automatic arrays are allowed in ISO C99, and as an
1776 extension GCC accepts them in C90 mode and in C++. These arrays are
1777 declared like any other automatic arrays, but with a length that is not
1778 a constant expression. The storage is allocated at the point of
1779 declaration and deallocated when the block scope containing the declaration
1785 concat_fopen (char *s1, char *s2, char *mode)
1787 char str[strlen (s1) + strlen (s2) + 1];
1790 return fopen (str, mode);
1794 @cindex scope of a variable length array
1795 @cindex variable-length array scope
1796 @cindex deallocating variable length arrays
1797 Jumping or breaking out of the scope of the array name deallocates the
1798 storage. Jumping into the scope is not allowed; you get an error
1801 @cindex variable-length array in a structure
1802 As an extension, GCC accepts variable-length arrays as a member of
1803 a structure or a union. For example:
1809 struct S @{ int x[n]; @};
1813 @cindex @code{alloca} vs variable-length arrays
1814 You can use the function @code{alloca} to get an effect much like
1815 variable-length arrays. The function @code{alloca} is available in
1816 many other C implementations (but not in all). On the other hand,
1817 variable-length arrays are more elegant.
1819 There are other differences between these two methods. Space allocated
1820 with @code{alloca} exists until the containing @emph{function} returns.
1821 The space for a variable-length array is deallocated as soon as the array
1822 name's scope ends, unless you also use @code{alloca} in this scope.
1824 You can also use variable-length arrays as arguments to functions:
1828 tester (int len, char data[len][len])
1834 The length of an array is computed once when the storage is allocated
1835 and is remembered for the scope of the array in case you access it with
1838 If you want to pass the array first and the length afterward, you can
1839 use a forward declaration in the parameter list---another GNU extension.
1843 tester (int len; char data[len][len], int len)
1849 @cindex parameter forward declaration
1850 The @samp{int len} before the semicolon is a @dfn{parameter forward
1851 declaration}, and it serves the purpose of making the name @code{len}
1852 known when the declaration of @code{data} is parsed.
1854 You can write any number of such parameter forward declarations in the
1855 parameter list. They can be separated by commas or semicolons, but the
1856 last one must end with a semicolon, which is followed by the ``real''
1857 parameter declarations. Each forward declaration must match a ``real''
1858 declaration in parameter name and data type. ISO C99 does not support
1859 parameter forward declarations.
1861 @node Variadic Macros
1862 @section Macros with a Variable Number of Arguments.
1863 @cindex variable number of arguments
1864 @cindex macro with variable arguments
1865 @cindex rest argument (in macro)
1866 @cindex variadic macros
1868 In the ISO C standard of 1999, a macro can be declared to accept a
1869 variable number of arguments much as a function can. The syntax for
1870 defining the macro is similar to that of a function. Here is an
1874 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1878 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1879 such a macro, it represents the zero or more tokens until the closing
1880 parenthesis that ends the invocation, including any commas. This set of
1881 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1882 wherever it appears. See the CPP manual for more information.
1884 GCC has long supported variadic macros, and used a different syntax that
1885 allowed you to give a name to the variable arguments just like any other
1886 argument. Here is an example:
1889 #define debug(format, args...) fprintf (stderr, format, args)
1893 This is in all ways equivalent to the ISO C example above, but arguably
1894 more readable and descriptive.
1896 GNU CPP has two further variadic macro extensions, and permits them to
1897 be used with either of the above forms of macro definition.
1899 In standard C, you are not allowed to leave the variable argument out
1900 entirely; but you are allowed to pass an empty argument. For example,
1901 this invocation is invalid in ISO C, because there is no comma after
1908 GNU CPP permits you to completely omit the variable arguments in this
1909 way. In the above examples, the compiler would complain, though since
1910 the expansion of the macro still has the extra comma after the format
1913 To help solve this problem, CPP behaves specially for variable arguments
1914 used with the token paste operator, @samp{##}. If instead you write
1917 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1921 and if the variable arguments are omitted or empty, the @samp{##}
1922 operator causes the preprocessor to remove the comma before it. If you
1923 do provide some variable arguments in your macro invocation, GNU CPP
1924 does not complain about the paste operation and instead places the
1925 variable arguments after the comma. Just like any other pasted macro
1926 argument, these arguments are not macro expanded.
1928 @node Escaped Newlines
1929 @section Slightly Looser Rules for Escaped Newlines
1930 @cindex escaped newlines
1931 @cindex newlines (escaped)
1933 The preprocessor treatment of escaped newlines is more relaxed
1934 than that specified by the C90 standard, which requires the newline
1935 to immediately follow a backslash.
1936 GCC's implementation allows whitespace in the form
1937 of spaces, horizontal and vertical tabs, and form feeds between the
1938 backslash and the subsequent newline. The preprocessor issues a
1939 warning, but treats it as a valid escaped newline and combines the two
1940 lines to form a single logical line. This works within comments and
1941 tokens, as well as between tokens. Comments are @emph{not} treated as
1942 whitespace for the purposes of this relaxation, since they have not
1943 yet been replaced with spaces.
1946 @section Non-Lvalue Arrays May Have Subscripts
1947 @cindex subscripting
1948 @cindex arrays, non-lvalue
1950 @cindex subscripting and function values
1951 In ISO C99, arrays that are not lvalues still decay to pointers, and
1952 may be subscripted, although they may not be modified or used after
1953 the next sequence point and the unary @samp{&} operator may not be
1954 applied to them. As an extension, GNU C allows such arrays to be
1955 subscripted in C90 mode, though otherwise they do not decay to
1956 pointers outside C99 mode. For example,
1957 this is valid in GNU C though not valid in C90:
1961 struct foo @{int a[4];@};
1967 return f().a[index];
1973 @section Arithmetic on @code{void}- and Function-Pointers
1974 @cindex void pointers, arithmetic
1975 @cindex void, size of pointer to
1976 @cindex function pointers, arithmetic
1977 @cindex function, size of pointer to
1979 In GNU C, addition and subtraction operations are supported on pointers to
1980 @code{void} and on pointers to functions. This is done by treating the
1981 size of a @code{void} or of a function as 1.
1983 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1984 and on function types, and returns 1.
1986 @opindex Wpointer-arith
1987 The option @option{-Wpointer-arith} requests a warning if these extensions
1990 @node Variadic Pointer Args
1991 @section Pointer Arguments in Variadic Functions
1992 @cindex pointer arguments in variadic functions
1993 @cindex variadic functions, pointer arguments
1995 Standard C requires that pointer types used with @code{va_arg} in
1996 functions with variable argument lists either must be compatible with
1997 that of the actual argument, or that one type must be a pointer to
1998 @code{void} and the other a pointer to a character type. GNU C
1999 implements the POSIX XSI extension that additionally permits the use
2000 of @code{va_arg} with a pointer type to receive arguments of any other
2003 In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
2004 to consume an argument of any pointer type.
2006 @node Pointers to Arrays
2007 @section Pointers to Arrays with Qualifiers Work as Expected
2008 @cindex pointers to arrays
2009 @cindex const qualifier
2011 In GNU C, pointers to arrays with qualifiers work similar to pointers
2012 to other qualified types. For example, a value of type @code{int (*)[5]}
2013 can be used to initialize a variable of type @code{const int (*)[5]}.
2014 These types are incompatible in ISO C because the @code{const} qualifier
2015 is formally attached to the element type of the array and not the
2020 transpose (int N, int M, double out[M][N], const double in[N][M]);
2024 transpose(3, 2, y, x);
2028 @section Non-Constant Initializers
2029 @cindex initializers, non-constant
2030 @cindex non-constant initializers
2032 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
2033 automatic variable are not required to be constant expressions in GNU C@.
2034 Here is an example of an initializer with run-time varying elements:
2037 foo (float f, float g)
2039 float beat_freqs[2] = @{ f-g, f+g @};
2044 @node Compound Literals
2045 @section Compound Literals
2046 @cindex constructor expressions
2047 @cindex initializations in expressions
2048 @cindex structures, constructor expression
2049 @cindex expressions, constructor
2050 @cindex compound literals
2051 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
2053 A compound literal looks like a cast of a brace-enclosed aggregate
2054 initializer list. Its value is an object of the type specified in
2055 the cast, containing the elements specified in the initializer.
2056 Unlike the result of a cast, a compound literal is an lvalue. ISO
2057 C99 and later support compound literals. As an extension, GCC
2058 supports compound literals also in C90 mode and in C++, although
2059 as explained below, the C++ semantics are somewhat different.
2061 Usually, the specified type of a compound literal is a structure. Assume
2062 that @code{struct foo} and @code{structure} are declared as shown:
2065 struct foo @{int a; char b[2];@} structure;
2069 Here is an example of constructing a @code{struct foo} with a compound literal:
2072 structure = ((struct foo) @{x + y, 'a', 0@});
2076 This is equivalent to writing the following:
2080 struct foo temp = @{x + y, 'a', 0@};
2085 You can also construct an array, though this is dangerous in C++, as
2086 explained below. If all the elements of the compound literal are
2087 (made up of) simple constant expressions suitable for use in
2088 initializers of objects of static storage duration, then the compound
2089 literal can be coerced to a pointer to its first element and used in
2090 such an initializer, as shown here:
2093 char **foo = (char *[]) @{ "x", "y", "z" @};
2096 Compound literals for scalar types and union types are also allowed. In
2097 the following example the variable @code{i} is initialized to the value
2098 @code{2}, the result of incrementing the unnamed object created by
2099 the compound literal.
2102 int i = ++(int) @{ 1 @};
2105 As a GNU extension, GCC allows initialization of objects with static storage
2106 duration by compound literals (which is not possible in ISO C99 because
2107 the initializer is not a constant).
2108 It is handled as if the object were initialized only with the brace-enclosed
2109 list if the types of the compound literal and the object match.
2110 The elements of the compound literal must be constant.
2111 If the object being initialized has array type of unknown size, the size is
2112 determined by the size of the compound literal.
2115 static struct foo x = (struct foo) @{1, 'a', 'b'@};
2116 static int y[] = (int []) @{1, 2, 3@};
2117 static int z[] = (int [3]) @{1@};
2121 The above lines are equivalent to the following:
2123 static struct foo x = @{1, 'a', 'b'@};
2124 static int y[] = @{1, 2, 3@};
2125 static int z[] = @{1, 0, 0@};
2128 In C, a compound literal designates an unnamed object with static or
2129 automatic storage duration. In C++, a compound literal designates a
2130 temporary object that only lives until the end of its full-expression.
2131 As a result, well-defined C code that takes the address of a subobject
2132 of a compound literal can be undefined in C++, so G++ rejects
2133 the conversion of a temporary array to a pointer. For instance, if
2134 the array compound literal example above appeared inside a function,
2135 any subsequent use of @code{foo} in C++ would have undefined behavior
2136 because the lifetime of the array ends after the declaration of @code{foo}.
2138 As an optimization, G++ sometimes gives array compound literals longer
2139 lifetimes: when the array either appears outside a function or has
2140 a @code{const}-qualified type. If @code{foo} and its initializer had
2141 elements of type @code{char *const} rather than @code{char *}, or if
2142 @code{foo} were a global variable, the array would have static storage
2143 duration. But it is probably safest just to avoid the use of array
2144 compound literals in C++ code.
2146 @node Designated Inits
2147 @section Designated Initializers
2148 @cindex initializers with labeled elements
2149 @cindex labeled elements in initializers
2150 @cindex case labels in initializers
2151 @cindex designated initializers
2153 Standard C90 requires the elements of an initializer to appear in a fixed
2154 order, the same as the order of the elements in the array or structure
2157 In ISO C99 you can give the elements in any order, specifying the array
2158 indices or structure field names they apply to, and GNU C allows this as
2159 an extension in C90 mode as well. This extension is not
2160 implemented in GNU C++.
2162 To specify an array index, write
2163 @samp{[@var{index}] =} before the element value. For example,
2166 int a[6] = @{ [4] = 29, [2] = 15 @};
2173 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
2177 The index values must be constant expressions, even if the array being
2178 initialized is automatic.
2180 An alternative syntax for this that has been obsolete since GCC 2.5 but
2181 GCC still accepts is to write @samp{[@var{index}]} before the element
2182 value, with no @samp{=}.
2184 To initialize a range of elements to the same value, write
2185 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2186 extension. For example,
2189 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2193 If the value in it has side effects, the side effects happen only once,
2194 not for each initialized field by the range initializer.
2197 Note that the length of the array is the highest value specified
2200 In a structure initializer, specify the name of a field to initialize
2201 with @samp{.@var{fieldname} =} before the element value. For example,
2202 given the following structure,
2205 struct point @{ int x, y; @};
2209 the following initialization
2212 struct point p = @{ .y = yvalue, .x = xvalue @};
2219 struct point p = @{ xvalue, yvalue @};
2222 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2223 @samp{@var{fieldname}:}, as shown here:
2226 struct point p = @{ y: yvalue, x: xvalue @};
2229 Omitted fields are implicitly initialized the same as for objects
2230 that have static storage duration.
2233 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2234 @dfn{designator}. You can also use a designator (or the obsolete colon
2235 syntax) when initializing a union, to specify which element of the union
2236 should be used. For example,
2239 union foo @{ int i; double d; @};
2241 union foo f = @{ .d = 4 @};
2245 converts 4 to a @code{double} to store it in the union using
2246 the second element. By contrast, casting 4 to type @code{union foo}
2247 stores it into the union as the integer @code{i}, since it is
2248 an integer. @xref{Cast to Union}.
2250 You can combine this technique of naming elements with ordinary C
2251 initialization of successive elements. Each initializer element that
2252 does not have a designator applies to the next consecutive element of the
2253 array or structure. For example,
2256 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2263 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2266 Labeling the elements of an array initializer is especially useful
2267 when the indices are characters or belong to an @code{enum} type.
2272 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2273 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2276 @cindex designator lists
2277 You can also write a series of @samp{.@var{fieldname}} and
2278 @samp{[@var{index}]} designators before an @samp{=} to specify a
2279 nested subobject to initialize; the list is taken relative to the
2280 subobject corresponding to the closest surrounding brace pair. For
2281 example, with the @samp{struct point} declaration above:
2284 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2287 If the same field is initialized multiple times, or overlapping
2288 fields of a union are initialized, the value from the last
2289 initialization is used. When a field of a union is itself a structure,
2290 the entire structure from the last field initialized is used. If any previous
2291 initializer has side effect, it is unspecified whether the side effect
2292 happens or not. Currently, GCC discards the side-effecting
2293 initializer expressions and issues a warning.
2296 @section Case Ranges
2298 @cindex ranges in case statements
2300 You can specify a range of consecutive values in a single @code{case} label,
2304 case @var{low} ... @var{high}:
2308 This has the same effect as the proper number of individual @code{case}
2309 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2311 This feature is especially useful for ranges of ASCII character codes:
2317 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2318 it may be parsed wrong when you use it with integer values. For example,
2333 @section Cast to a Union Type
2334 @cindex cast to a union
2335 @cindex union, casting to a
2337 A cast to a union type is a C extension not available in C++. It looks
2338 just like ordinary casts with the constraint that the type specified is
2339 a union type. You can specify the type either with the @code{union}
2340 keyword or with a @code{typedef} name that refers to a union. The result
2341 of a cast to a union is a temporary rvalue of the union type with a member
2342 whose type matches that of the operand initialized to the value of
2343 the operand. The effect of a cast to a union is similar to a compound
2344 literal except that it yields an rvalue like standard casts do.
2345 @xref{Compound Literals}.
2347 Expressions that may be cast to the union type are those whose type matches
2348 at least one of the members of the union. Thus, given the following union
2352 union foo @{ int i; double d; @};
2359 both @code{x} and @code{y} can be cast to type @code{union foo} and
2360 the following assignments
2365 are shorthand equivalents of these
2367 z = (union foo) @{ .i = x @};
2368 z = (union foo) @{ .d = y @};
2371 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
2372 has no member of type @code{float}.
2374 Using the cast as the right-hand side of an assignment to a variable of
2375 union type is equivalent to storing in a member of the union with
2381 u = (union foo) x @equiv{} u.i = x
2382 u = (union foo) y @equiv{} u.d = y
2385 You can also use the union cast as a function argument:
2388 void hack (union foo);
2390 hack ((union foo) x);
2393 @node Mixed Labels and Declarations
2394 @section Mixed Declarations, Labels and Code
2395 @cindex mixed declarations and code
2396 @cindex declarations, mixed with code
2397 @cindex code, mixed with declarations
2399 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2400 within compound statements. ISO C2X allows labels to be
2401 placed before declarations and at the end of a compound statement.
2402 As an extension, GNU C also allows all this in C90 mode. For example,
2412 Each identifier is visible from where it is declared until the end of
2413 the enclosing block.
2415 @node Function Attributes
2416 @section Declaring Attributes of Functions
2417 @cindex function attributes
2418 @cindex declaring attributes of functions
2419 @cindex @code{volatile} applied to function
2420 @cindex @code{const} applied to function
2422 In GNU C and C++, you can use function attributes to specify certain
2423 function properties that may help the compiler optimize calls or
2424 check code more carefully for correctness. For example, you
2425 can use attributes to specify that a function never returns
2426 (@code{noreturn}), returns a value depending only on the values of
2427 its arguments (@code{const}), or has @code{printf}-style arguments
2430 You can also use attributes to control memory placement, code
2431 generation options or call/return conventions within the function
2432 being annotated. Many of these attributes are target-specific. For
2433 example, many targets support attributes for defining interrupt
2434 handler functions, which typically must follow special register usage
2435 and return conventions. Such attributes are described in the subsection
2436 for each target. However, a considerable number of attributes are
2437 supported by most, if not all targets. Those are described in
2438 the @ref{Common Function Attributes} section.
2440 Function attributes are introduced by the @code{__attribute__} keyword
2441 in the declaration of a function, followed by an attribute specification
2442 enclosed in double parentheses. You can specify multiple attributes in
2443 a declaration by separating them by commas within the double parentheses
2444 or by immediately following one attribute specification with another.
2445 @xref{Attribute Syntax}, for the exact rules on attribute syntax and
2446 placement. Compatible attribute specifications on distinct declarations
2447 of the same function are merged. An attribute specification that is not
2448 compatible with attributes already applied to a declaration of the same
2449 function is ignored with a warning.
2451 Some function attributes take one or more arguments that refer to
2452 the function's parameters by their positions within the function parameter
2453 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2454 Unless specified otherwise, positional arguments that specify properties
2455 of parameters with pointer types can also specify the same properties of
2456 the implicit C++ @code{this} argument in non-static member functions, and
2457 of parameters of reference to a pointer type. For ordinary functions,
2458 position one refers to the first parameter on the list. In C++ non-static
2459 member functions, position one refers to the implicit @code{this} pointer.
2460 The same restrictions and effects apply to function attributes used with
2461 ordinary functions or C++ member functions.
2463 GCC also supports attributes on
2464 variable declarations (@pxref{Variable Attributes}),
2465 labels (@pxref{Label Attributes}),
2466 enumerators (@pxref{Enumerator Attributes}),
2467 statements (@pxref{Statement Attributes}),
2468 and types (@pxref{Type Attributes}).
2470 There is some overlap between the purposes of attributes and pragmas
2471 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2472 found convenient to use @code{__attribute__} to achieve a natural
2473 attachment of attributes to their corresponding declarations, whereas
2474 @code{#pragma} is of use for compatibility with other compilers
2475 or constructs that do not naturally form part of the grammar.
2477 In addition to the attributes documented here,
2478 GCC plugins may provide their own attributes.
2481 * Common Function Attributes::
2482 * AArch64 Function Attributes::
2483 * AMD GCN Function Attributes::
2484 * ARC Function Attributes::
2485 * ARM Function Attributes::
2486 * AVR Function Attributes::
2487 * Blackfin Function Attributes::
2488 * BPF Function Attributes::
2489 * CR16 Function Attributes::
2490 * C-SKY Function Attributes::
2491 * Epiphany Function Attributes::
2492 * H8/300 Function Attributes::
2493 * IA-64 Function Attributes::
2494 * M32C Function Attributes::
2495 * M32R/D Function Attributes::
2496 * m68k Function Attributes::
2497 * MCORE Function Attributes::
2498 * MeP Function Attributes::
2499 * MicroBlaze Function Attributes::
2500 * Microsoft Windows Function Attributes::
2501 * MIPS Function Attributes::
2502 * MSP430 Function Attributes::
2503 * NDS32 Function Attributes::
2504 * Nios II Function Attributes::
2505 * Nvidia PTX Function Attributes::
2506 * PowerPC Function Attributes::
2507 * RISC-V Function Attributes::
2508 * RL78 Function Attributes::
2509 * RX Function Attributes::
2510 * S/390 Function Attributes::
2511 * SH Function Attributes::
2512 * Symbian OS Function Attributes::
2513 * V850 Function Attributes::
2514 * Visium Function Attributes::
2515 * x86 Function Attributes::
2516 * Xstormy16 Function Attributes::
2519 @node Common Function Attributes
2520 @subsection Common Function Attributes
2522 The following attributes are supported on most targets.
2525 @c Keep this table alphabetized by attribute name. Treat _ as space.
2527 @item access (@var{access-mode}, @var{ref-index})
2528 @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
2530 The @code{access} attribute enables the detection of invalid or unsafe
2531 accesses by functions to which they apply or their callers, as well as
2532 write-only accesses to objects that are never read from. Such accesses
2533 may be diagnosed by warnings such as @option{-Wstringop-overflow},
2534 @option{-Wuninitialized}, @option{-Wunused}, and others.
2536 The @code{access} attribute specifies that a function to whose by-reference
2537 arguments the attribute applies accesses the referenced object according to
2538 @var{access-mode}. The @var{access-mode} argument is required and must be
2539 one of four names: @code{read_only}, @code{read_write}, @code{write_only},
2540 or @code{none}. The remaining two are positional arguments.
2542 The required @var{ref-index} positional argument denotes a function
2543 argument of pointer (or in C++, reference) type that is subject to
2544 the access. The same pointer argument can be referenced by at most one
2545 distinct @code{access} attribute.
2547 The optional @var{size-index} positional argument denotes a function
2548 argument of integer type that specifies the maximum size of the access.
2549 The size is the number of elements of the type referenced by @var{ref-index},
2550 or the number of bytes when the pointer type is @code{void*}. When no
2551 @var{size-index} argument is specified, the pointer argument must be either
2552 null or point to a space that is suitably aligned and large for at least one
2553 object of the referenced type (this implies that a past-the-end pointer is
2554 not a valid argument). The actual size of the access may be less but it
2557 The @code{read_only} access mode specifies that the pointer to which it
2558 applies is used to read the referenced object but not write to it. Unless
2559 the argument specifying the size of the access denoted by @var{size-index}
2560 is zero, the referenced object must be initialized. The mode implies
2561 a stronger guarantee than the @code{const} qualifier which, when cast away
2562 from a pointer, does not prevent the pointed-to object from being modified.
2563 Examples of the use of the @code{read_only} access mode is the argument to
2564 the @code{puts} function, or the second and third arguments to
2565 the @code{memcpy} function.
2568 __attribute__ ((access (read_only, 1))) int puts (const char*);
2569 __attribute__ ((access (read_only, 2, 3))) void* memcpy (void*, const void*, size_t);
2572 The @code{read_write} access mode applies to arguments of pointer types
2573 without the @code{const} qualifier. It specifies that the pointer to which
2574 it applies is used to both read and write the referenced object. Unless
2575 the argument specifying the size of the access denoted by @var{size-index}
2576 is zero, the object referenced by the pointer must be initialized. An example
2577 of the use of the @code{read_write} access mode is the first argument to
2578 the @code{strcat} function.
2581 __attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*);
2584 The @code{write_only} access mode applies to arguments of pointer types
2585 without the @code{const} qualifier. It specifies that the pointer to which
2586 it applies is used to write to the referenced object but not read from it.
2587 The object referenced by the pointer need not be initialized. An example
2588 of the use of the @code{write_only} access mode is the first argument to
2589 the @code{strcpy} function, or the first two arguments to the @code{fgets}
2593 __attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*);
2594 __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*);
2597 The access mode @code{none} specifies that the pointer to which it applies
2598 is not used to access the referenced object at all. Unless the pointer is
2599 null the pointed-to object must exist and have at least the size as denoted
2600 by the @var{size-index} argument. When the optional @var{size-index}
2601 argument is omitted for an argument of @code{void*} type the actual pointer
2602 agument is ignored. The referenced object need not be initialized.
2603 The mode is intended to be used as a means to help validate the expected
2604 object size, for example in functions that call @code{__builtin_object_size}.
2605 @xref{Object Size Checking}.
2607 @item alias ("@var{target}")
2608 @cindex @code{alias} function attribute
2609 The @code{alias} attribute causes the declaration to be emitted as an alias
2610 for another symbol, which must have been previously declared with the same
2611 type, and for variables, also the same size and alignment. Declaring an alias
2612 with a different type than the target is undefined and may be diagnosed. As
2613 an example, the following declarations:
2616 void __f () @{ /* @r{Do something.} */; @}
2617 void f () __attribute__ ((weak, alias ("__f")));
2621 define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
2622 for the target must be used. It is an error if @samp{__f} is not defined in
2623 the same translation unit.
2625 This attribute requires assembler and object file support,
2626 and may not be available on all targets.
2629 @itemx aligned (@var{alignment})
2630 @cindex @code{aligned} function attribute
2631 The @code{aligned} attribute specifies a minimum alignment for
2632 the first instruction of the function, measured in bytes. When specified,
2633 @var{alignment} must be an integer constant power of 2. Specifying no
2634 @var{alignment} argument implies the ideal alignment for the target.
2635 The @code{__alignof__} operator can be used to determine what that is
2636 (@pxref{Alignment}). The attribute has no effect when a definition for
2637 the function is not provided in the same translation unit.
2639 The attribute cannot be used to decrease the alignment of a function
2640 previously declared with a more restrictive alignment; only to increase
2641 it. Attempts to do otherwise are diagnosed. Some targets specify
2642 a minimum default alignment for functions that is greater than 1. On
2643 such targets, specifying a less restrictive alignment is silently ignored.
2644 Using the attribute overrides the effect of the @option{-falign-functions}
2645 (@pxref{Optimize Options}) option for this function.
2647 Note that the effectiveness of @code{aligned} attributes may be
2648 limited by inherent limitations in the system linker
2649 and/or object file format. On some systems, the
2650 linker is only able to arrange for functions to be aligned up to a
2651 certain maximum alignment. (For some linkers, the maximum supported
2652 alignment may be very very small.) See your linker documentation for
2653 further information.
2655 The @code{aligned} attribute can also be used for variables and fields
2656 (@pxref{Variable Attributes}.)
2658 @item alloc_align (@var{position})
2659 @cindex @code{alloc_align} function attribute
2660 The @code{alloc_align} attribute may be applied to a function that
2661 returns a pointer and takes at least one argument of an integer or
2663 It indicates that the returned pointer is aligned on a boundary given
2664 by the function argument at @var{position}. Meaningful alignments are
2665 powers of 2 greater than one. GCC uses this information to improve
2666 pointer alignment analysis.
2668 The function parameter denoting the allocated alignment is specified by
2669 one constant integer argument whose number is the argument of the attribute.
2670 Argument numbering starts at one.
2675 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2679 declares that @code{my_memalign} returns memory with minimum alignment
2680 given by parameter 1.
2682 @item alloc_size (@var{position})
2683 @itemx alloc_size (@var{position-1}, @var{position-2})
2684 @cindex @code{alloc_size} function attribute
2685 The @code{alloc_size} attribute may be applied to a function that
2686 returns a pointer and takes at least one argument of an integer or
2688 It indicates that the returned pointer points to memory whose size is
2689 given by the function argument at @var{position-1}, or by the product
2690 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2691 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2692 information to improve the results of @code{__builtin_object_size}.
2694 The function parameter(s) denoting the allocated size are specified by
2695 one or two integer arguments supplied to the attribute. The allocated size
2696 is either the value of the single function argument specified or the product
2697 of the two function arguments specified. Argument numbering starts at
2698 one for ordinary functions, and at two for C++ non-static member functions.
2703 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2704 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2708 declares that @code{my_calloc} returns memory of the size given by
2709 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2710 of the size given by parameter 2.
2713 @cindex @code{always_inline} function attribute
2714 Generally, functions are not inlined unless optimization is specified.
2715 For functions declared inline, this attribute inlines the function
2716 independent of any restrictions that otherwise apply to inlining.
2717 Failure to inline such a function is diagnosed as an error.
2718 Note that if such a function is called indirectly the compiler may
2719 or may not inline it depending on optimization level and a failure
2720 to inline an indirect call may or may not be diagnosed.
2723 @cindex @code{artificial} function attribute
2724 This attribute is useful for small inline wrappers that if possible
2725 should appear during debugging as a unit. Depending on the debug
2726 info format it either means marking the function as artificial
2727 or using the caller location for all instructions within the inlined
2730 @item assume_aligned (@var{alignment})
2731 @itemx assume_aligned (@var{alignment}, @var{offset})
2732 @cindex @code{assume_aligned} function attribute
2733 The @code{assume_aligned} attribute may be applied to a function that
2734 returns a pointer. It indicates that the returned pointer is aligned
2735 on a boundary given by @var{alignment}. If the attribute has two
2736 arguments, the second argument is misalignment @var{offset}. Meaningful
2737 values of @var{alignment} are powers of 2 greater than one. Meaningful
2738 values of @var{offset} are greater than zero and less than @var{alignment}.
2743 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2744 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2748 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2749 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2753 @cindex @code{cold} function attribute
2754 The @code{cold} attribute on functions is used to inform the compiler that
2755 the function is unlikely to be executed. The function is optimized for
2756 size rather than speed and on many targets it is placed into a special
2757 subsection of the text section so all cold functions appear close together,
2758 improving code locality of non-cold parts of program. The paths leading
2759 to calls of cold functions within code are marked as unlikely by the branch
2760 prediction mechanism. It is thus useful to mark functions used to handle
2761 unlikely conditions, such as @code{perror}, as cold to improve optimization
2762 of hot functions that do call marked functions in rare occasions.
2764 When profile feedback is available, via @option{-fprofile-use}, cold functions
2765 are automatically detected and this attribute is ignored.
2768 @cindex @code{const} function attribute
2769 @cindex functions that have no side effects
2770 Calls to functions whose return value is not affected by changes to
2771 the observable state of the program and that have no observable effects
2772 on such state other than to return a value may lend themselves to
2773 optimizations such as common subexpression elimination. Declaring such
2774 functions with the @code{const} attribute allows GCC to avoid emitting
2775 some calls in repeated invocations of the function with the same argument
2781 int square (int) __attribute__ ((const));
2785 tells GCC that subsequent calls to function @code{square} with the same
2786 argument value can be replaced by the result of the first call regardless
2787 of the statements in between.
2789 The @code{const} attribute prohibits a function from reading objects
2790 that affect its return value between successive invocations. However,
2791 functions declared with the attribute can safely read objects that do
2792 not change their return value, such as non-volatile constants.
2794 The @code{const} attribute imposes greater restrictions on a function's
2795 definition than the similar @code{pure} attribute. Declaring the same
2796 function with both the @code{const} and the @code{pure} attribute is
2797 diagnosed. Because a const function cannot have any observable side
2798 effects it does not make sense for it to return @code{void}. Declaring
2799 such a function is diagnosed.
2801 @cindex pointer arguments
2802 Note that a function that has pointer arguments and examines the data
2803 pointed to must @emph{not} be declared @code{const} if the pointed-to
2804 data might change between successive invocations of the function. In
2805 general, since a function cannot distinguish data that might change
2806 from data that cannot, const functions should never take pointer or,
2807 in C++, reference arguments. Likewise, a function that calls a non-const
2808 function usually must not be const itself.
2812 @itemx constructor (@var{priority})
2813 @itemx destructor (@var{priority})
2814 @cindex @code{constructor} function attribute
2815 @cindex @code{destructor} function attribute
2816 The @code{constructor} attribute causes the function to be called
2817 automatically before execution enters @code{main ()}. Similarly, the
2818 @code{destructor} attribute causes the function to be called
2819 automatically after @code{main ()} completes or @code{exit ()} is
2820 called. Functions with these attributes are useful for
2821 initializing data that is used implicitly during the execution of
2824 On some targets the attributes also accept an integer argument to
2825 specify a priority to control the order in which constructor and
2826 destructor functions are run. A constructor
2827 with a smaller priority number runs before a constructor with a larger
2828 priority number; the opposite relationship holds for destructors. Note
2829 that priorities 0-100 are reserved. So, if you have a constructor that
2830 allocates a resource and a destructor that deallocates the same
2831 resource, both functions typically have the same priority. The
2832 priorities for constructor and destructor functions are the same as
2833 those specified for namespace-scope C++ objects (@pxref{C++ Attributes}).
2834 However, at present, the order in which constructors for C++ objects
2835 with static storage duration and functions decorated with attribute
2836 @code{constructor} are invoked is unspecified. In mixed declarations,
2837 attribute @code{init_priority} can be used to impose a specific ordering.
2839 Using the argument forms of the @code{constructor} and @code{destructor}
2840 attributes on targets where the feature is not supported is rejected with
2844 @itemx copy (@var{function})
2845 @cindex @code{copy} function attribute
2846 The @code{copy} attribute applies the set of attributes with which
2847 @var{function} has been declared to the declaration of the function
2848 to which the attribute is applied. The attribute is designed for
2849 libraries that define aliases or function resolvers that are expected
2850 to specify the same set of attributes as their targets. The @code{copy}
2851 attribute can be used with functions, variables, or types. However,
2852 the kind of symbol to which the attribute is applied (either function
2853 or variable) must match the kind of symbol to which the argument refers.
2854 The @code{copy} attribute copies only syntactic and semantic attributes
2855 but not attributes that affect a symbol's linkage or visibility such as
2856 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2857 and @code{target_clones} attribute are also not copied.
2858 @xref{Common Type Attributes}.
2859 @xref{Common Variable Attributes}.
2861 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2862 and @code{copy} attributes to define an alias named @var{alloc} for function
2863 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2864 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2865 the same type as the target function. As a result of the @code{copy}
2866 attribute the alias also shares the same attributes as the target.
2869 #define StrongAlias(TargetFunc, AliasDecl) \
2870 extern __typeof__ (TargetFunc) AliasDecl \
2871 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2873 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2874 void* allocate (size_t);
2875 StrongAlias (allocate, alloc);
2879 @itemx deprecated (@var{msg})
2880 @cindex @code{deprecated} function attribute
2881 The @code{deprecated} attribute results in a warning if the function
2882 is used anywhere in the source file. This is useful when identifying
2883 functions that are expected to be removed in a future version of a
2884 program. The warning also includes the location of the declaration
2885 of the deprecated function, to enable users to easily find further
2886 information about why the function is deprecated, or what they should
2887 do instead. Note that the warnings only occurs for uses:
2890 int old_fn () __attribute__ ((deprecated));
2892 int (*fn_ptr)() = old_fn;
2896 results in a warning on line 3 but not line 2. The optional @var{msg}
2897 argument, which must be a string, is printed in the warning if
2900 The @code{deprecated} attribute can also be used for variables and
2901 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2903 The message attached to the attribute is affected by the setting of
2904 the @option{-fmessage-length} option.
2907 @itemx unavailable (@var{msg})
2908 @cindex @code{unavailable} function attribute
2909 The @code{unavailable} attribute results in an error if the function
2910 is used anywhere in the source file. This is useful when identifying
2911 functions that have been removed from a particular variation of an
2912 interface. Other than emitting an error rather than a warning, the
2913 @code{unavailable} attribute behaves in the same manner as
2916 The @code{unavailable} attribute can also be used for variables and
2917 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2919 @item error ("@var{message}")
2920 @itemx warning ("@var{message}")
2921 @cindex @code{error} function attribute
2922 @cindex @code{warning} function attribute
2923 If the @code{error} or @code{warning} attribute
2924 is used on a function declaration and a call to such a function
2925 is not eliminated through dead code elimination or other optimizations,
2926 an error or warning (respectively) that includes @var{message} is diagnosed.
2928 for compile-time checking, especially together with @code{__builtin_constant_p}
2929 and inline functions where checking the inline function arguments is not
2930 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2932 While it is possible to leave the function undefined and thus invoke
2933 a link failure (to define the function with
2934 a message in @code{.gnu.warning*} section),
2935 when using these attributes the problem is diagnosed
2936 earlier and with exact location of the call even in presence of inline
2937 functions or when not emitting debugging information.
2939 @item externally_visible
2940 @cindex @code{externally_visible} function attribute
2941 This attribute, attached to a global variable or function, nullifies
2942 the effect of the @option{-fwhole-program} command-line option, so the
2943 object remains visible outside the current compilation unit.
2945 If @option{-fwhole-program} is used together with @option{-flto} and
2946 @command{gold} is used as the linker plugin,
2947 @code{externally_visible} attributes are automatically added to functions
2948 (not variable yet due to a current @command{gold} issue)
2949 that are accessed outside of LTO objects according to resolution file
2950 produced by @command{gold}.
2951 For other linkers that cannot generate resolution file,
2952 explicit @code{externally_visible} attributes are still necessary.
2955 @cindex @code{flatten} function attribute
2956 Generally, inlining into a function is limited. For a function marked with
2957 this attribute, every call inside this function is inlined, if possible.
2958 Functions declared with attribute @code{noinline} and similar are not
2959 inlined. Whether the function itself is considered for inlining depends
2960 on its size and the current inlining parameters.
2962 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2963 @cindex @code{format} function attribute
2964 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2966 The @code{format} attribute specifies that a function takes @code{printf},
2967 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2968 should be type-checked against a format string. For example, the
2973 my_printf (void *my_object, const char *my_format, ...)
2974 __attribute__ ((format (printf, 2, 3)));
2978 causes the compiler to check the arguments in calls to @code{my_printf}
2979 for consistency with the @code{printf} style format string argument
2982 The parameter @var{archetype} determines how the format string is
2983 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2984 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2985 @code{strfmon}. (You can also use @code{__printf__},
2986 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2987 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2988 @code{ms_strftime} are also present.
2989 @var{archetype} values such as @code{printf} refer to the formats accepted
2990 by the system's C runtime library,
2991 while values prefixed with @samp{gnu_} always refer
2992 to the formats accepted by the GNU C Library. On Microsoft Windows
2993 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2994 @file{msvcrt.dll} library.
2995 The parameter @var{string-index}
2996 specifies which argument is the format string argument (starting
2997 from 1), while @var{first-to-check} is the number of the first
2998 argument to check against the format string. For functions
2999 where the arguments are not available to be checked (such as
3000 @code{vprintf}), specify the third parameter as zero. In this case the
3001 compiler only checks the format string for consistency. For
3002 @code{strftime} formats, the third parameter is required to be zero.
3003 Since non-static C++ methods have an implicit @code{this} argument, the
3004 arguments of such methods should be counted from two, not one, when
3005 giving values for @var{string-index} and @var{first-to-check}.
3007 In the example above, the format string (@code{my_format}) is the second
3008 argument of the function @code{my_print}, and the arguments to check
3009 start with the third argument, so the correct parameters for the format
3010 attribute are 2 and 3.
3012 @opindex ffreestanding
3013 @opindex fno-builtin
3014 The @code{format} attribute allows you to identify your own functions
3015 that take format strings as arguments, so that GCC can check the
3016 calls to these functions for errors. The compiler always (unless
3017 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
3018 for the standard library functions @code{printf}, @code{fprintf},
3019 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
3020 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
3021 warnings are requested (using @option{-Wformat}), so there is no need to
3022 modify the header file @file{stdio.h}. In C99 mode, the functions
3023 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
3024 @code{vsscanf} are also checked. Except in strictly conforming C
3025 standard modes, the X/Open function @code{strfmon} is also checked as
3026 are @code{printf_unlocked} and @code{fprintf_unlocked}.
3027 @xref{C Dialect Options,,Options Controlling C Dialect}.
3029 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
3030 recognized in the same context. Declarations including these format attributes
3031 are parsed for correct syntax, however the result of checking of such format
3032 strings is not yet defined, and is not carried out by this version of the
3035 The target may also provide additional types of format checks.
3036 @xref{Target Format Checks,,Format Checks Specific to Particular
3039 @item format_arg (@var{string-index})
3040 @cindex @code{format_arg} function attribute
3041 @opindex Wformat-nonliteral
3042 The @code{format_arg} attribute specifies that a function takes one or
3043 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
3044 @code{strfmon} style function and modifies it (for example, to translate
3045 it into another language), so the result can be passed to a
3046 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
3047 function (with the remaining arguments to the format function the same
3048 as they would have been for the unmodified string). Multiple
3049 @code{format_arg} attributes may be applied to the same function, each
3050 designating a distinct parameter as a format string. For example, the
3055 my_dgettext (char *my_domain, const char *my_format)
3056 __attribute__ ((format_arg (2)));
3060 causes the compiler to check the arguments in calls to a @code{printf},
3061 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
3062 format string argument is a call to the @code{my_dgettext} function, for
3063 consistency with the format string argument @code{my_format}. If the
3064 @code{format_arg} attribute had not been specified, all the compiler
3065 could tell in such calls to format functions would be that the format
3066 string argument is not constant; this would generate a warning when
3067 @option{-Wformat-nonliteral} is used, but the calls could not be checked
3068 without the attribute.
3070 In calls to a function declared with more than one @code{format_arg}
3071 attribute, each with a distinct argument value, the corresponding
3072 actual function arguments are checked against all format strings
3073 designated by the attributes. This capability is designed to support
3074 the GNU @code{ngettext} family of functions.
3076 The parameter @var{string-index} specifies which argument is the format
3077 string argument (starting from one). Since non-static C++ methods have
3078 an implicit @code{this} argument, the arguments of such methods should
3079 be counted from two.
3081 The @code{format_arg} attribute allows you to identify your own
3082 functions that modify format strings, so that GCC can check the
3083 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
3084 type function whose operands are a call to one of your own function.
3085 The compiler always treats @code{gettext}, @code{dgettext}, and
3086 @code{dcgettext} in this manner except when strict ISO C support is
3087 requested by @option{-ansi} or an appropriate @option{-std} option, or
3088 @option{-ffreestanding} or @option{-fno-builtin}
3089 is used. @xref{C Dialect Options,,Options
3090 Controlling C Dialect}.
3092 For Objective-C dialects, the @code{format-arg} attribute may refer to an
3093 @code{NSString} reference for compatibility with the @code{format} attribute
3096 The target may also allow additional types in @code{format-arg} attributes.
3097 @xref{Target Format Checks,,Format Checks Specific to Particular
3101 @cindex @code{gnu_inline} function attribute
3102 This attribute should be used with a function that is also declared
3103 with the @code{inline} keyword. It directs GCC to treat the function
3104 as if it were defined in gnu90 mode even when compiling in C99 or
3107 If the function is declared @code{extern}, then this definition of the
3108 function is used only for inlining. In no case is the function
3109 compiled as a standalone function, not even if you take its address
3110 explicitly. Such an address becomes an external reference, as if you
3111 had only declared the function, and had not defined it. This has
3112 almost the effect of a macro. The way to use this is to put a
3113 function definition in a header file with this attribute, and put
3114 another copy of the function, without @code{extern}, in a library
3115 file. The definition in the header file causes most calls to the
3116 function to be inlined. If any uses of the function remain, they
3117 refer to the single copy in the library. Note that the two
3118 definitions of the functions need not be precisely the same, although
3119 if they do not have the same effect your program may behave oddly.
3121 In C, if the function is neither @code{extern} nor @code{static}, then
3122 the function is compiled as a standalone function, as well as being
3123 inlined where possible.
3125 This is how GCC traditionally handled functions declared
3126 @code{inline}. Since ISO C99 specifies a different semantics for
3127 @code{inline}, this function attribute is provided as a transition
3128 measure and as a useful feature in its own right. This attribute is
3129 available in GCC 4.1.3 and later. It is available if either of the
3130 preprocessor macros @code{__GNUC_GNU_INLINE__} or
3131 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
3132 Function is As Fast As a Macro}.
3134 In C++, this attribute does not depend on @code{extern} in any way,
3135 but it still requires the @code{inline} keyword to enable its special
3139 @cindex @code{hot} function attribute
3140 The @code{hot} attribute on a function is used to inform the compiler that
3141 the function is a hot spot of the compiled program. The function is
3142 optimized more aggressively and on many targets it is placed into a special
3143 subsection of the text section so all hot functions appear close together,
3146 When profile feedback is available, via @option{-fprofile-use}, hot functions
3147 are automatically detected and this attribute is ignored.
3149 @item ifunc ("@var{resolver}")
3150 @cindex @code{ifunc} function attribute
3151 @cindex indirect functions
3152 @cindex functions that are dynamically resolved
3153 The @code{ifunc} attribute is used to mark a function as an indirect
3154 function using the STT_GNU_IFUNC symbol type extension to the ELF
3155 standard. This allows the resolution of the symbol value to be
3156 determined dynamically at load time, and an optimized version of the
3157 routine to be selected for the particular processor or other system
3158 characteristics determined then. To use this attribute, first define
3159 the implementation functions available, and a resolver function that
3160 returns a pointer to the selected implementation function. The
3161 implementation functions' declarations must match the API of the
3162 function being implemented. The resolver should be declared to
3163 be a function taking no arguments and returning a pointer to
3164 a function of the same type as the implementation. For example:
3167 void *my_memcpy (void *dst, const void *src, size_t len)
3173 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3175 return my_memcpy; // we will just always select this routine
3180 The exported header file declaring the function the user calls would
3184 extern void *memcpy (void *, const void *, size_t);
3188 allowing the user to call @code{memcpy} as a regular function, unaware of
3189 the actual implementation. Finally, the indirect function needs to be
3190 defined in the same translation unit as the resolver function:
3193 void *memcpy (void *, const void *, size_t)
3194 __attribute__ ((ifunc ("resolve_memcpy")));
3197 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3198 of the resolver function. A C++ resolver for a non-static member function
3199 of class @code{C} should be declared to return a pointer to a non-member
3200 function taking pointer to @code{C} as the first argument, followed by
3201 the same arguments as of the implementation function. G++ checks
3202 the signatures of the two functions and issues
3203 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3204 for the necessary cast from a pointer to the implementation member function
3205 to the type of the corresponding non-member function use
3206 the @option{-Wno-pmf-conversions} option. For example:
3212 int debug_impl (int);
3213 int optimized_impl (int);
3215 typedef int Func (S*, int);
3217 static Func* resolver ();
3220 int interface (int);
3223 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3224 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3226 S::Func* S::resolver ()
3228 int (S::*pimpl) (int)
3229 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3231 // Cast triggers -Wno-pmf-conversions.
3232 return reinterpret_cast<Func*>(pimpl);
3235 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3238 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3239 and GNU C Library version 2.11.1 are required to use this feature.
3242 @itemx interrupt_handler
3243 Many GCC back ends support attributes to indicate that a function is
3244 an interrupt handler, which tells the compiler to generate function
3245 entry and exit sequences that differ from those from regular
3246 functions. The exact syntax and behavior are target-specific;
3247 refer to the following subsections for details.
3250 @cindex @code{leaf} function attribute
3251 Calls to external functions with this attribute must return to the
3252 current compilation unit only by return or by exception handling. In
3253 particular, a leaf function is not allowed to invoke callback functions
3254 passed to it from the current compilation unit, directly call functions
3255 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3256 might still call functions from other compilation units and thus they
3257 are not necessarily leaf in the sense that they contain no function
3260 The attribute is intended for library functions to improve dataflow
3261 analysis. The compiler takes the hint that any data not escaping the
3262 current compilation unit cannot be used or modified by the leaf
3263 function. For example, the @code{sin} function is a leaf function, but
3264 @code{qsort} is not.
3266 Note that leaf functions might indirectly run a signal handler defined
3267 in the current compilation unit that uses static variables. Similarly,
3268 when lazy symbol resolution is in effect, leaf functions might invoke
3269 indirect functions whose resolver function or implementation function is
3270 defined in the current compilation unit and uses static variables. There
3271 is no standard-compliant way to write such a signal handler, resolver
3272 function, or implementation function, and the best that you can do is to
3273 remove the @code{leaf} attribute or mark all such static variables
3274 @code{volatile}. Lastly, for ELF-based systems that support symbol
3275 interposition, care should be taken that functions defined in the
3276 current compilation unit do not unexpectedly interpose other symbols
3277 based on the defined standards mode and defined feature test macros;
3278 otherwise an inadvertent callback would be added.
3280 The attribute has no effect on functions defined within the current
3281 compilation unit. This is to allow easy merging of multiple compilation
3282 units into one, for example, by using the link-time optimization. For
3283 this reason the attribute is not allowed on types to annotate indirect
3287 @item malloc (@var{deallocator})
3288 @item malloc (@var{deallocator}, @var{ptr-index})
3289 @cindex @code{malloc} function attribute
3290 @cindex functions that behave like malloc
3291 Attribute @code{malloc} indicates that a function is @code{malloc}-like,
3292 i.e., that the pointer @var{P} returned by the function cannot alias any
3293 other pointer valid when the function returns, and moreover no
3294 pointers to valid objects occur in any storage addressed by @var{P}. In
3295 addition, the GCC predicts that a function with the attribute returns
3296 non-null in most cases.
3298 Independently, the form of the attribute with one or two arguments
3299 associates @code{deallocator} as a suitable deallocation function for
3300 pointers returned from the @code{malloc}-like function. @var{ptr-index}
3301 denotes the positional argument to which when the pointer is passed in
3302 calls to @code{deallocator} has the effect of deallocating it.
3304 Using the attribute with no arguments is designed to improve optimization
3305 by relying on the aliasing property it implies. Functions like @code{malloc}
3306 and @code{calloc} have this property because they return a pointer to
3307 uninitialized or zeroed-out, newly obtained storage. However, functions
3308 like @code{realloc} do not have this property, as they may return pointers
3309 to storage containing pointers to existing objects. Additionally, since
3310 all such functions are assumed to return null only infrequently, callers
3311 can be optimized based on that assumption.
3313 Associating a function with a @var{deallocator} helps detect calls to
3314 mismatched allocation and deallocation functions and diagnose them under
3315 the control of options such as @option{-Wmismatched-dealloc}. It also
3316 makes it possible to diagnose attempts to deallocate objects that were not
3317 allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate
3318 that an allocation function both satisifies the nonaliasing property and
3319 has a deallocator associated with it, both the plain form of the attribute
3320 and the one with the @var{deallocator} argument must be used. The same
3321 function can be both an allocator and a deallocator. Since inlining one
3322 of the associated functions but not the other could result in apparent
3323 mismatches, this form of attribute @code{malloc} is not accepted on inline
3324 functions. For the same reason, using the attribute prevents both
3325 the allocation and deallocation functions from being expanded inline.
3327 For example, besides stating that the functions return pointers that do
3328 not alias any others, the following declarations make @code{fclose}
3329 a suitable deallocator for pointers returned from all functions except
3330 @code{popen}, and @code{pclose} as the only suitable deallocator for
3331 pointers returned from @code{popen}. The deallocator functions must
3332 be declared before they can be referenced in the attribute.
3338 __attribute__ ((malloc, malloc (fclose, 1)))
3339 FILE* fdopen (int, const char*);
3340 __attribute__ ((malloc, malloc (fclose, 1)))
3341 FILE* fopen (const char*, const char*);
3342 __attribute__ ((malloc, malloc (fclose, 1)))
3343 FILE* fmemopen(void *, size_t, const char *);
3344 __attribute__ ((malloc, malloc (pclose, 1)))
3345 FILE* popen (const char*, const char*);
3346 __attribute__ ((malloc, malloc (fclose, 1)))
3347 FILE* tmpfile (void);
3350 The warnings guarded by @option{-fanalyzer} respect allocation and
3351 deallocation pairs marked with the @code{malloc}. In particular:
3356 The analyzer will emit a @option{-Wanalyzer-mismatching-deallocation}
3357 diagnostic if there is an execution path in which the result of an
3358 allocation call is passed to a different deallocator.
3361 The analyzer will emit a @option{-Wanalyzer-double-free}
3362 diagnostic if there is an execution path in which a value is passed
3363 more than once to a deallocation call.
3366 The analyzer will consider the possibility that an allocation function
3367 could fail and return NULL. It will emit
3368 @option{-Wanalyzer-possible-null-dereference} and
3369 @option{-Wanalyzer-possible-null-argument} diagnostics if there are
3370 execution paths in which an unchecked result of an allocation call is
3371 dereferenced or passed to a function requiring a non-null argument.
3372 If the allocator always returns non-null, use
3373 @code{__attribute__ ((returns_nonnull))} to suppress these warnings.
3376 char *xstrdup (const char *)
3377 __attribute__((malloc (free), returns_nonnull));
3381 The analyzer will emit a @option{-Wanalyzer-use-after-free}
3382 diagnostic if there is an execution path in which the memory passed
3383 by pointer to a deallocation call is used after the deallocation.
3386 The analyzer will emit a @option{-Wanalyzer-malloc-leak} diagnostic if
3387 there is an execution path in which the result of an allocation call
3388 is leaked (without being passed to the deallocation function).
3391 The analyzer will emit a @option{-Wanalyzer-free-of-non-heap} diagnostic
3392 if a deallocation function is used on a global or on-stack variable.
3396 The analyzer assumes that deallocators can gracefully handle the @code{NULL}
3397 pointer. If this is not the case, the deallocator can be marked with
3398 @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit
3399 a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
3400 in which the deallocator is called with NULL.
3403 @cindex @code{no_icf} function attribute
3404 This function attribute prevents a functions from being merged with another
3405 semantically equivalent function.
3407 @item no_instrument_function
3408 @cindex @code{no_instrument_function} function attribute
3409 @opindex finstrument-functions
3412 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3413 given, profiling function calls are
3414 generated at entry and exit of most user-compiled functions.
3415 Functions with this attribute are not so instrumented.
3417 @item no_profile_instrument_function
3418 @cindex @code{no_profile_instrument_function} function attribute
3419 The @code{no_profile_instrument_function} attribute on functions is used
3420 to inform the compiler that it should not process any profile feedback based
3421 optimization code instrumentation.
3424 @cindex @code{no_reorder} function attribute
3425 Do not reorder functions or variables marked @code{no_reorder}
3426 against each other or top level assembler statements the executable.
3427 The actual order in the program will depend on the linker command
3428 line. Static variables marked like this are also not removed.
3429 This has a similar effect
3430 as the @option{-fno-toplevel-reorder} option, but only applies to the
3433 @item no_sanitize ("@var{sanitize_option}")
3434 @cindex @code{no_sanitize} function attribute
3435 The @code{no_sanitize} attribute on functions is used
3436 to inform the compiler that it should not do sanitization of any option
3437 mentioned in @var{sanitize_option}. A list of values acceptable by
3438 the @option{-fsanitize} option can be provided.
3441 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3442 f () @{ /* @r{Do something.} */; @}
3443 void __attribute__ ((no_sanitize ("alignment,object-size")))
3444 g () @{ /* @r{Do something.} */; @}
3447 @item no_sanitize_address
3448 @itemx no_address_safety_analysis
3449 @cindex @code{no_sanitize_address} function attribute
3450 The @code{no_sanitize_address} attribute on functions is used
3451 to inform the compiler that it should not instrument memory accesses
3452 in the function when compiling with the @option{-fsanitize=address} option.
3453 The @code{no_address_safety_analysis} is a deprecated alias of the
3454 @code{no_sanitize_address} attribute, new code should use
3455 @code{no_sanitize_address}.
3457 @item no_sanitize_thread
3458 @cindex @code{no_sanitize_thread} function attribute
3459 The @code{no_sanitize_thread} attribute on functions is used
3460 to inform the compiler that it should not instrument memory accesses
3461 in the function when compiling with the @option{-fsanitize=thread} option.
3463 @item no_sanitize_undefined
3464 @cindex @code{no_sanitize_undefined} function attribute
3465 The @code{no_sanitize_undefined} attribute on functions is used
3466 to inform the compiler that it should not check for undefined behavior
3467 in the function when compiling with the @option{-fsanitize=undefined} option.
3469 @item no_sanitize_coverage
3470 @cindex @code{no_sanitize_coverage} function attribute
3471 The @code{no_sanitize_coverage} attribute on functions is used
3472 to inform the compiler that it should not do coverage-guided
3473 fuzzing code instrumentation (@option{-fsanitize-coverage}).
3475 @item no_split_stack
3476 @cindex @code{no_split_stack} function attribute
3477 @opindex fsplit-stack
3478 If @option{-fsplit-stack} is given, functions have a small
3479 prologue which decides whether to split the stack. Functions with the
3480 @code{no_split_stack} attribute do not have that prologue, and thus
3481 may run with only a small amount of stack space available.
3483 @item no_stack_limit
3484 @cindex @code{no_stack_limit} function attribute
3485 This attribute locally overrides the @option{-fstack-limit-register}
3486 and @option{-fstack-limit-symbol} command-line options; it has the effect
3487 of disabling stack limit checking in the function it applies to.
3490 @cindex @code{noclone} function attribute
3491 This function attribute prevents a function from being considered for
3492 cloning---a mechanism that produces specialized copies of functions
3493 and which is (currently) performed by interprocedural constant
3497 @cindex @code{noinline} function attribute
3498 This function attribute prevents a function from being considered for
3500 @c Don't enumerate the optimizations by name here; we try to be
3501 @c future-compatible with this mechanism.
3502 If the function does not have side effects, there are optimizations
3503 other than inlining that cause function calls to be optimized away,
3504 although the function call is live. To keep such calls from being
3511 (@pxref{Extended Asm}) in the called function, to serve as a special
3515 @cindex @code{noipa} function attribute
3516 Disable interprocedural optimizations between the function with this
3517 attribute and its callers, as if the body of the function is not available
3518 when optimizing callers and the callers are unavailable when optimizing
3519 the body. This attribute implies @code{noinline}, @code{noclone} and
3520 @code{no_icf} attributes. However, this attribute is not equivalent
3521 to a combination of other attributes, because its purpose is to suppress
3522 existing and future optimizations employing interprocedural analysis,
3523 including those that do not have an attribute suitable for disabling
3524 them individually. This attribute is supported mainly for the purpose
3525 of testing the compiler.
3528 @itemx nonnull (@var{arg-index}, @dots{})
3529 @cindex @code{nonnull} function attribute
3530 @cindex functions with non-null pointer arguments
3531 The @code{nonnull} attribute may be applied to a function that takes at
3532 least one argument of a pointer type. It indicates that the referenced
3533 arguments must be non-null pointers. For instance, the declaration:
3537 my_memcpy (void *dest, const void *src, size_t len)
3538 __attribute__((nonnull (1, 2)));
3542 informs the compiler that, in calls to @code{my_memcpy}, arguments
3543 @var{dest} and @var{src} must be non-null.
3545 The attribute has an effect both on functions calls and function definitions.
3549 @item If the compiler determines that a null pointer is
3550 passed in an argument slot marked as non-null, and the
3551 @option{-Wnonnull} option is enabled, a warning is issued.
3552 @xref{Warning Options}.
3553 @item The @option{-fisolate-erroneous-paths-attribute} option can be
3554 specified to have GCC transform calls with null arguments to non-null
3555 functions into traps. @xref{Optimize Options}.
3556 @item The compiler may also perform optimizations based on the
3557 knowledge that certain function arguments cannot be null. These
3558 optimizations can be disabled by the
3559 @option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}.
3562 For function definitions:
3564 @item If the compiler determines that a function parameter that is
3565 marked with nonnull is compared with null, and
3566 @option{-Wnonnull-compare} option is enabled, a warning is issued.
3567 @xref{Warning Options}.
3568 @item The compiler may also perform optimizations based on the
3569 knowledge that @code{nonnul} parameters cannot be null. This can
3570 currently not be disabled other than by removing the nonnull
3574 If no @var{arg-index} is given to the @code{nonnull} attribute,
3575 all pointer arguments are marked as non-null. To illustrate, the
3576 following declaration is equivalent to the previous example:
3580 my_memcpy (void *dest, const void *src, size_t len)
3581 __attribute__((nonnull));
3585 @cindex @code{noplt} function attribute
3586 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3587 Calls to functions marked with this attribute in position-independent code
3592 /* Externally defined function foo. */
3593 int foo () __attribute__ ((noplt));
3596 main (/* @r{@dots{}} */)
3605 The @code{noplt} attribute on function @code{foo}
3606 tells the compiler to assume that
3607 the function @code{foo} is externally defined and that the call to
3608 @code{foo} must avoid the PLT
3609 in position-independent code.
3611 In position-dependent code, a few targets also convert calls to
3612 functions that are marked to not use the PLT to use the GOT instead.
3615 @cindex @code{noreturn} function attribute
3616 @cindex functions that never return
3617 A few standard library functions, such as @code{abort} and @code{exit},
3618 cannot return. GCC knows this automatically. Some programs define
3619 their own functions that never return. You can declare them
3620 @code{noreturn} to tell the compiler this fact. For example,
3624 void fatal () __attribute__ ((noreturn));
3627 fatal (/* @r{@dots{}} */)
3629 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3635 The @code{noreturn} keyword tells the compiler to assume that
3636 @code{fatal} cannot return. It can then optimize without regard to what
3637 would happen if @code{fatal} ever did return. This makes slightly
3638 better code. More importantly, it helps avoid spurious warnings of
3639 uninitialized variables.
3641 The @code{noreturn} keyword does not affect the exceptional path when that
3642 applies: a @code{noreturn}-marked function may still return to the caller
3643 by throwing an exception or calling @code{longjmp}.
3645 In order to preserve backtraces, GCC will never turn calls to
3646 @code{noreturn} functions into tail calls.
3648 Do not assume that registers saved by the calling function are
3649 restored before calling the @code{noreturn} function.
3651 It does not make sense for a @code{noreturn} function to have a return
3652 type other than @code{void}.
3655 @cindex @code{nothrow} function attribute
3656 The @code{nothrow} attribute is used to inform the compiler that a
3657 function cannot throw an exception. For example, most functions in
3658 the standard C library can be guaranteed not to throw an exception
3659 with the notable exceptions of @code{qsort} and @code{bsearch} that
3660 take function pointer arguments.
3662 @item optimize (@var{level}, @dots{})
3663 @item optimize (@var{string}, @dots{})
3664 @cindex @code{optimize} function attribute
3665 The @code{optimize} attribute is used to specify that a function is to
3666 be compiled with different optimization options than specified on the
3667 command line. The optimize attribute arguments of a function behave
3668 behave as if appended to the command-line.
3670 Valid arguments are constant non-negative integers and
3671 strings. Each numeric argument specifies an optimization @var{level}.
3672 Each @var{string} argument consists of one or more comma-separated
3673 substrings. Each substring that begins with the letter @code{O} refers
3674 to an optimization option such as @option{-O0} or @option{-Os}. Other
3675 substrings are taken as suffixes to the @code{-f} prefix jointly
3676 forming the name of an optimization option. @xref{Optimize Options}.
3678 @samp{#pragma GCC optimize} can be used to set optimization options
3679 for more than one function. @xref{Function Specific Option Pragmas},
3680 for details about the pragma.
3682 Providing multiple strings as arguments separated by commas to specify
3683 multiple options is equivalent to separating the option suffixes with
3684 a comma (@samp{,}) within a single string. Spaces are not permitted
3687 Not every optimization option that starts with the @var{-f} prefix
3688 specified by the attribute necessarily has an effect on the function.
3689 The @code{optimize} attribute should be used for debugging purposes only.
3690 It is not suitable in production code.
3692 @item patchable_function_entry
3693 @cindex @code{patchable_function_entry} function attribute
3694 @cindex extra NOP instructions at the function entry point
3695 In case the target's text segment can be made writable at run time by
3696 any means, padding the function entry with a number of NOPs can be
3697 used to provide a universal tool for instrumentation.
3699 The @code{patchable_function_entry} function attribute can be used to
3700 change the number of NOPs to any desired value. The two-value syntax
3701 is the same as for the command-line switch
3702 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3703 the function entry point before the @var{M}th NOP instruction.
3704 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3707 If patchable function entries are enabled globally using the command-line
3708 option @option{-fpatchable-function-entry=N,M}, then you must disable
3709 instrumentation on all functions that are part of the instrumentation
3710 framework with the attribute @code{patchable_function_entry (0)}
3711 to prevent recursion.
3714 @cindex @code{pure} function attribute
3715 @cindex functions that have no side effects
3717 Calls to functions that have no observable effects on the state of
3718 the program other than to return a value may lend themselves to optimizations
3719 such as common subexpression elimination. Declaring such functions with
3720 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3721 invocations of the function with the same argument values.
3723 The @code{pure} attribute prohibits a function from modifying the state
3724 of the program that is observable by means other than inspecting
3725 the function's return value. However, functions declared with the @code{pure}
3726 attribute can safely read any non-volatile objects, and modify the value of
3727 objects in a way that does not affect their return value or the observable
3728 state of the program.
3733 int hash (char *) __attribute__ ((pure));
3737 tells GCC that subsequent calls to the function @code{hash} with the same
3738 string can be replaced by the result of the first call provided the state
3739 of the program observable by @code{hash}, including the contents of the array
3740 itself, does not change in between. Even though @code{hash} takes a non-const
3741 pointer argument it must not modify the array it points to, or any other object
3742 whose value the rest of the program may depend on. However, the caller may
3743 safely change the contents of the array between successive calls to
3744 the function (doing so disables the optimization). The restriction also
3745 applies to member objects referenced by the @code{this} pointer in C++
3746 non-static member functions.
3748 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3749 Interesting non-pure functions are functions with infinite loops or those
3750 depending on volatile memory or other system resource, that may change between
3751 consecutive calls (such as the standard C @code{feof} function in
3752 a multithreading environment).
3754 The @code{pure} attribute imposes similar but looser restrictions on
3755 a function's definition than the @code{const} attribute: @code{pure}
3756 allows the function to read any non-volatile memory, even if it changes
3757 in between successive invocations of the function. Declaring the same
3758 function with both the @code{pure} and the @code{const} attribute is
3759 diagnosed. Because a pure function cannot have any observable side
3760 effects it does not make sense for such a function to return @code{void}.
3761 Declaring such a function is diagnosed.
3763 @item returns_nonnull
3764 @cindex @code{returns_nonnull} function attribute
3765 The @code{returns_nonnull} attribute specifies that the function
3766 return value should be a non-null pointer. For instance, the declaration:
3770 mymalloc (size_t len) __attribute__((returns_nonnull));
3774 lets the compiler optimize callers based on the knowledge
3775 that the return value will never be null.
3778 @cindex @code{returns_twice} function attribute
3779 @cindex functions that return more than once
3780 The @code{returns_twice} attribute tells the compiler that a function may
3781 return more than one time. The compiler ensures that all registers
3782 are dead before calling such a function and emits a warning about
3783 the variables that may be clobbered after the second return from the
3784 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3785 The @code{longjmp}-like counterpart of such function, if any, might need
3786 to be marked with the @code{noreturn} attribute.
3788 @item section ("@var{section-name}")
3789 @cindex @code{section} function attribute
3790 @cindex functions in arbitrary sections
3791 Normally, the compiler places the code it generates in the @code{text} section.
3792 Sometimes, however, you need additional sections, or you need certain
3793 particular functions to appear in special sections. The @code{section}
3794 attribute specifies that a function lives in a particular section.
3795 For example, the declaration:
3798 extern void foobar (void) __attribute__ ((section ("bar")));
3802 puts the function @code{foobar} in the @code{bar} section.
3804 Some file formats do not support arbitrary sections so the @code{section}
3805 attribute is not available on all platforms.
3806 If you need to map the entire contents of a module to a particular
3807 section, consider using the facilities of the linker instead.
3810 @itemx sentinel (@var{position})
3811 @cindex @code{sentinel} function attribute
3812 This function attribute indicates that an argument in a call to the function
3813 is expected to be an explicit @code{NULL}. The attribute is only valid on
3814 variadic functions. By default, the sentinel is expected to be the last
3815 argument of the function call. If the optional @var{position} argument
3816 is specified to the attribute, the sentinel must be located at
3817 @var{position} counting backwards from the end of the argument list.
3820 __attribute__ ((sentinel))
3822 __attribute__ ((sentinel(0)))
3825 The attribute is automatically set with a position of 0 for the built-in
3826 functions @code{execl} and @code{execlp}. The built-in function
3827 @code{execle} has the attribute set with a position of 1.
3829 A valid @code{NULL} in this context is defined as zero with any object
3830 pointer type. If your system defines the @code{NULL} macro with
3831 an integer type then you need to add an explicit cast. During
3832 installation GCC replaces the system @code{<stddef.h>} header with
3833 a copy that redefines NULL appropriately.
3835 The warnings for missing or incorrect sentinels are enabled with
3839 @itemx simd("@var{mask}")
3840 @cindex @code{simd} function attribute
3841 This attribute enables creation of one or more function versions that
3842 can process multiple arguments using SIMD instructions from a
3843 single invocation. Specifying this attribute allows compiler to
3844 assume that such versions are available at link time (provided
3845 in the same or another translation unit). Generated versions are
3846 target-dependent and described in the corresponding Vector ABI document. For
3847 x86_64 target this document can be found
3848 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3850 The optional argument @var{mask} may have the value
3851 @code{notinbranch} or @code{inbranch},
3852 and instructs the compiler to generate non-masked or masked
3853 clones correspondingly. By default, all clones are generated.
3855 If the attribute is specified and @code{#pragma omp declare simd} is
3856 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3857 switch is specified, then the attribute is ignored.
3860 @cindex @code{stack_protect} function attribute
3861 This attribute adds stack protection code to the function if
3862 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3863 or @option{-fstack-protector-explicit} are set.
3865 @item no_stack_protector
3866 @cindex @code{no_stack_protector} function attribute
3867 This attribute prevents stack protection code for the function.
3869 @item target (@var{string}, @dots{})
3870 @cindex @code{target} function attribute
3871 Multiple target back ends implement the @code{target} attribute
3872 to specify that a function is to
3873 be compiled with different target options than specified on the
3874 command line. The original target command-line options are ignored.
3875 One or more strings can be provided as arguments.
3876 Each string consists of one or more comma-separated suffixes to
3877 the @code{-m} prefix jointly forming the name of a machine-dependent
3878 option. @xref{Submodel Options,,Machine-Dependent Options}.
3880 The @code{target} attribute can be used for instance to have a function
3881 compiled with a different ISA (instruction set architecture) than the
3882 default. @samp{#pragma GCC target} can be used to specify target-specific
3883 options for more than one function. @xref{Function Specific Option Pragmas},
3884 for details about the pragma.
3886 For instance, on an x86, you could declare one function with the
3887 @code{target("sse4.1,arch=core2")} attribute and another with
3888 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3889 compiling the first function with @option{-msse4.1} and
3890 @option{-march=core2} options, and the second function with
3891 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3892 to make sure that a function is only invoked on a machine that
3893 supports the particular ISA it is compiled for (for example by using
3894 @code{cpuid} on x86 to determine what feature bits and architecture
3898 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3899 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3902 Providing multiple strings as arguments separated by commas to specify
3903 multiple options is equivalent to separating the option suffixes with
3904 a comma (@samp{,}) within a single string. Spaces are not permitted
3907 The options supported are specific to each target; refer to @ref{x86
3908 Function Attributes}, @ref{PowerPC Function Attributes},
3909 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
3910 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
3913 @item symver ("@var{name2}@@@var{nodename}")
3914 @cindex @code{symver} function attribute
3915 On ELF targets this attribute creates a symbol version. The @var{name2} part
3916 of the parameter is the actual name of the symbol by which it will be
3917 externally referenced. The @code{nodename} portion should be the name of a
3918 node specified in the version script supplied to the linker when building a
3919 shared library. Versioned symbol must be defined and must be exported with
3923 __attribute__ ((__symver__ ("foo@@VERS_1"))) int
3929 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
3932 One can also define multiple version for a given symbol
3933 (starting from binutils 2.35).
3936 __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
3937 int symver_foo_v1 (void)
3942 This example creates a symbol name @code{symver_foo_v1}
3943 which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
3945 If you have an older release of binutils, then symbol alias needs to
3949 __attribute__ ((__symver__ ("foo@@VERS_2")))
3955 __attribute__ ((__symver__ ("foo@@VERS_3")))
3956 __attribute__ ((alias ("foo_v1")))
3957 int symver_foo_v1 (void);
3960 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
3961 addition to creating a symbol version (as if
3962 @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
3963 to resolve @var{name2} by the linker.
3965 @item target_clones (@var{options})
3966 @cindex @code{target_clones} function attribute
3967 The @code{target_clones} attribute is used to specify that a function
3968 be cloned into multiple versions compiled with different target options
3969 than specified on the command line. The supported options and restrictions
3970 are the same as for @code{target} attribute.
3972 For instance, on an x86, you could compile a function with
3973 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
3974 one compiled with @option{-msse4.1} and another with @option{-mavx}.
3976 On a PowerPC, you can compile a function with
3977 @code{target_clones("cpu=power9,default")}. GCC will create two
3978 function clones, one compiled with @option{-mcpu=power9} and another
3979 with the default options. GCC must be configured to use GLIBC 2.23 or
3980 newer in order to use the @code{target_clones} attribute.
3982 It also creates a resolver function (see
3983 the @code{ifunc} attribute above) that dynamically selects a clone
3984 suitable for current architecture. The resolver is created only if there
3985 is a usage of a function with @code{target_clones} attribute.
3987 Note that any subsequent call of a function without @code{target_clone}
3988 from a @code{target_clone} caller will not lead to copying
3989 (target clone) of the called function.
3990 If you want to enforce such behaviour,
3991 we recommend declaring the calling function with the @code{flatten} attribute?
3994 @cindex @code{unused} function attribute
3995 This attribute, attached to a function, means that the function is meant
3996 to be possibly unused. GCC does not produce a warning for this
4000 @cindex @code{used} function attribute
4001 This attribute, attached to a function, means that code must be emitted
4002 for the function even if it appears that the function is not referenced.
4003 This is useful, for example, when the function is referenced only in
4006 When applied to a member function of a C++ class template, the
4007 attribute also means that the function is instantiated if the
4008 class itself is instantiated.
4011 @cindex @code{retain} function attribute
4012 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
4013 will save the function from linker garbage collection. To support
4014 this behavior, functions that have not been placed in specific sections
4015 (e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
4016 option), will be placed in new, unique sections.
4018 This additional functionality requires Binutils version 2.36 or later.
4020 @item visibility ("@var{visibility_type}")
4021 @cindex @code{visibility} function attribute
4022 This attribute affects the linkage of the declaration to which it is attached.
4023 It can be applied to variables (@pxref{Common Variable Attributes}) and types
4024 (@pxref{Common Type Attributes}) as well as functions.
4026 There are four supported @var{visibility_type} values: default,
4027 hidden, protected or internal visibility.
4030 void __attribute__ ((visibility ("protected")))
4031 f () @{ /* @r{Do something.} */; @}
4032 int i __attribute__ ((visibility ("hidden")));
4035 The possible values of @var{visibility_type} correspond to the
4036 visibility settings in the ELF gABI.
4039 @c keep this list of visibilities in alphabetical order.
4042 Default visibility is the normal case for the object file format.
4043 This value is available for the visibility attribute to override other
4044 options that may change the assumed visibility of entities.
4046 On ELF, default visibility means that the declaration is visible to other
4047 modules and, in shared libraries, means that the declared entity may be
4050 On Darwin, default visibility means that the declaration is visible to
4053 Default visibility corresponds to ``external linkage'' in the language.
4056 Hidden visibility indicates that the entity declared has a new
4057 form of linkage, which we call ``hidden linkage''. Two
4058 declarations of an object with hidden linkage refer to the same object
4059 if they are in the same shared object.
4062 Internal visibility is like hidden visibility, but with additional
4063 processor specific semantics. Unless otherwise specified by the
4064 psABI, GCC defines internal visibility to mean that a function is
4065 @emph{never} called from another module. Compare this with hidden
4066 functions which, while they cannot be referenced directly by other
4067 modules, can be referenced indirectly via function pointers. By
4068 indicating that a function cannot be called from outside the module,
4069 GCC may for instance omit the load of a PIC register since it is known
4070 that the calling function loaded the correct value.
4073 Protected visibility is like default visibility except that it
4074 indicates that references within the defining module bind to the
4075 definition in that module. That is, the declared entity cannot be
4076 overridden by another module.
4080 All visibilities are supported on many, but not all, ELF targets
4081 (supported when the assembler supports the @samp{.visibility}
4082 pseudo-op). Default visibility is supported everywhere. Hidden
4083 visibility is supported on Darwin targets.
4085 The visibility attribute should be applied only to declarations that
4086 would otherwise have external linkage. The attribute should be applied
4087 consistently, so that the same entity should not be declared with
4088 different settings of the attribute.
4090 In C++, the visibility attribute applies to types as well as functions
4091 and objects, because in C++ types have linkage. A class must not have
4092 greater visibility than its non-static data member types and bases,
4093 and class members default to the visibility of their class. Also, a
4094 declaration without explicit visibility is limited to the visibility
4097 In C++, you can mark member functions and static member variables of a
4098 class with the visibility attribute. This is useful if you know a
4099 particular method or static member variable should only be used from
4100 one shared object; then you can mark it hidden while the rest of the
4101 class has default visibility. Care must be taken to avoid breaking
4102 the One Definition Rule; for example, it is usually not useful to mark
4103 an inline method as hidden without marking the whole class as hidden.
4105 A C++ namespace declaration can also have the visibility attribute.
4108 namespace nspace1 __attribute__ ((visibility ("protected")))
4109 @{ /* @r{Do something.} */; @}
4112 This attribute applies only to the particular namespace body, not to
4113 other definitions of the same namespace; it is equivalent to using
4114 @samp{#pragma GCC visibility} before and after the namespace
4115 definition (@pxref{Visibility Pragmas}).
4117 In C++, if a template argument has limited visibility, this
4118 restriction is implicitly propagated to the template instantiation.
4119 Otherwise, template instantiations and specializations default to the
4120 visibility of their template.
4122 If both the template and enclosing class have explicit visibility, the
4123 visibility from the template is used.
4125 @item warn_unused_result
4126 @cindex @code{warn_unused_result} function attribute
4127 The @code{warn_unused_result} attribute causes a warning to be emitted
4128 if a caller of the function with this attribute does not use its
4129 return value. This is useful for functions where not checking
4130 the result is either a security problem or always a bug, such as
4134 int fn () __attribute__ ((warn_unused_result));
4137 if (fn () < 0) return -1;
4144 results in warning on line 5.
4147 @cindex @code{weak} function attribute
4148 The @code{weak} attribute causes a declaration of an external symbol
4149 to be emitted as a weak symbol rather than a global. This is primarily
4150 useful in defining library functions that can be overridden in user code,
4151 though it can also be used with non-function declarations. The overriding
4152 symbol must have the same type as the weak symbol. In addition, if it
4153 designates a variable it must also have the same size and alignment as
4154 the weak symbol. Weak symbols are supported for ELF targets, and also
4155 for a.out targets when using the GNU assembler and linker.
4158 @itemx weakref ("@var{target}")
4159 @cindex @code{weakref} function attribute
4160 The @code{weakref} attribute marks a declaration as a weak reference.
4161 Without arguments, it should be accompanied by an @code{alias} attribute
4162 naming the target symbol. Alternatively, @var{target} may be given as
4163 an argument to @code{weakref} itself, naming the target definition of
4164 the alias. The @var{target} must have the same type as the declaration.
4165 In addition, if it designates a variable it must also have the same size
4166 and alignment as the declaration. In either form of the declaration
4167 @code{weakref} implicitly marks the declared symbol as @code{weak}. Without
4168 a @var{target} given as an argument to @code{weakref} or to @code{alias},
4169 @code{weakref} is equivalent to @code{weak} (in that case the declaration
4170 may be @code{extern}).
4173 /* Given the declaration: */
4174 extern int y (void);
4176 /* the following... */
4177 static int x (void) __attribute__ ((weakref ("y")));
4179 /* is equivalent to... */
4180 static int x (void) __attribute__ ((weakref, alias ("y")));
4182 /* or, alternatively, to... */
4183 static int x (void) __attribute__ ((weakref));
4184 static int x (void) __attribute__ ((alias ("y")));
4187 A weak reference is an alias that does not by itself require a
4188 definition to be given for the target symbol. If the target symbol is
4189 only referenced through weak references, then it becomes a @code{weak}
4190 undefined symbol. If it is directly referenced, however, then such
4191 strong references prevail, and a definition is required for the
4192 symbol, not necessarily in the same translation unit.
4194 The effect is equivalent to moving all references to the alias to a
4195 separate translation unit, renaming the alias to the aliased symbol,
4196 declaring it as weak, compiling the two separate translation units and
4197 performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
4199 A declaration to which @code{weakref} is attached and that is associated
4200 with a named @code{target} must be @code{static}.
4202 @item zero_call_used_regs ("@var{choice}")
4203 @cindex @code{zero_call_used_regs} function attribute
4205 The @code{zero_call_used_regs} attribute causes the compiler to zero
4206 a subset of all call-used registers@footnote{A ``call-used'' register
4207 is a register whose contents can be changed by a function call;
4208 therefore, a caller cannot assume that the register has the same contents
4209 on return from the function as it had before calling the function. Such
4210 registers are also called ``call-clobbered'', ``caller-saved'', or
4211 ``volatile''.} at function return.
4212 This is used to increase program security by either mitigating
4213 Return-Oriented Programming (ROP) attacks or preventing information leakage
4216 In order to satisfy users with different security needs and control the
4217 run-time overhead at the same time, the @var{choice} parameter provides a
4218 flexible way to choose the subset of the call-used registers to be zeroed.
4219 The three basic values of @var{choice} are:
4223 @samp{skip} doesn't zero any call-used registers.
4226 @samp{used} only zeros call-used registers that are used in the function.
4227 A ``used'' register is one whose content has been set or referenced in
4231 @samp{all} zeros all call-used registers.
4234 In addition to these three basic choices, it is possible to modify
4235 @samp{used} or @samp{all} as follows:
4239 Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
4242 Adding @samp{-arg} restricts the zeroing to registers that can sometimes
4243 be used to pass function arguments. This includes all argument registers
4244 defined by the platform's calling conversion, regardless of whether the
4245 function uses those registers for function arguments or not.
4248 The modifiers can be used individually or together. If they are used
4249 together, they must appear in the order above.
4251 The full list of @var{choice}s is therefore:
4255 doesn't zero any call-used register.
4258 only zeros call-used registers that are used in the function.
4261 only zeros call-used general purpose registers that are used in the function.
4264 only zeros call-used registers that are used in the function and pass arguments.
4267 only zeros call-used general purpose registers that are used in the function
4271 zeros all call-used registers.
4274 zeros all call-used general purpose registers.
4277 zeros all call-used registers that pass arguments.
4280 zeros all call-used general purpose registers that pass
4284 Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
4285 and @samp{all-gpr-arg} are mainly used for ROP mitigation.
4287 The default for the attribute is controlled by @option{-fzero-call-used-regs}.
4290 @c This is the end of the target-independent attribute table
4292 @node AArch64 Function Attributes
4293 @subsection AArch64 Function Attributes
4295 The following target-specific function attributes are available for the
4296 AArch64 target. For the most part, these options mirror the behavior of
4297 similar command-line options (@pxref{AArch64 Options}), but on a
4301 @item general-regs-only
4302 @cindex @code{general-regs-only} function attribute, AArch64
4303 Indicates that no floating-point or Advanced SIMD registers should be
4304 used when generating code for this function. If the function explicitly
4305 uses floating-point code, then the compiler gives an error. This is
4306 the same behavior as that of the command-line option
4307 @option{-mgeneral-regs-only}.
4309 @item fix-cortex-a53-835769
4310 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
4311 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
4312 applied to this function. To explicitly disable the workaround for this
4313 function specify the negated form: @code{no-fix-cortex-a53-835769}.
4314 This corresponds to the behavior of the command line options
4315 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
4318 @cindex @code{cmodel=} function attribute, AArch64
4319 Indicates that code should be generated for a particular code model for
4320 this function. The behavior and permissible arguments are the same as
4321 for the command line option @option{-mcmodel=}.
4324 @itemx no-strict-align
4325 @cindex @code{strict-align} function attribute, AArch64
4326 @code{strict-align} indicates that the compiler should not assume that unaligned
4327 memory references are handled by the system. To allow the compiler to assume
4328 that aligned memory references are handled by the system, the inverse attribute
4329 @code{no-strict-align} can be specified. The behavior is same as for the
4330 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
4332 @item omit-leaf-frame-pointer
4333 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
4334 Indicates that the frame pointer should be omitted for a leaf function call.
4335 To keep the frame pointer, the inverse attribute
4336 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
4337 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
4338 and @option{-mno-omit-leaf-frame-pointer}.
4341 @cindex @code{tls-dialect=} function attribute, AArch64
4342 Specifies the TLS dialect to use for this function. The behavior and
4343 permissible arguments are the same as for the command-line option
4344 @option{-mtls-dialect=}.
4347 @cindex @code{arch=} function attribute, AArch64
4348 Specifies the architecture version and architectural extensions to use
4349 for this function. The behavior and permissible arguments are the same as
4350 for the @option{-march=} command-line option.
4353 @cindex @code{tune=} function attribute, AArch64
4354 Specifies the core for which to tune the performance of this function.
4355 The behavior and permissible arguments are the same as for the @option{-mtune=}
4356 command-line option.
4359 @cindex @code{cpu=} function attribute, AArch64
4360 Specifies the core for which to tune the performance of this function and also
4361 whose architectural features to use. The behavior and valid arguments are the
4362 same as for the @option{-mcpu=} command-line option.
4364 @item sign-return-address
4365 @cindex @code{sign-return-address} function attribute, AArch64
4366 Select the function scope on which return address signing will be applied. The
4367 behavior and permissible arguments are the same as for the command-line option
4368 @option{-msign-return-address=}. The default value is @code{none}. This
4369 attribute is deprecated. The @code{branch-protection} attribute should
4372 @item branch-protection
4373 @cindex @code{branch-protection} function attribute, AArch64
4374 Select the function scope on which branch protection will be applied. The
4375 behavior and permissible arguments are the same as for the command-line option
4376 @option{-mbranch-protection=}. The default value is @code{none}.
4378 @item outline-atomics
4379 @cindex @code{outline-atomics} function attribute, AArch64
4380 Enable or disable calls to out-of-line helpers to implement atomic operations.
4381 This corresponds to the behavior of the command line options
4382 @option{-moutline-atomics} and @option{-mno-outline-atomics}.
4386 The above target attributes can be specified as follows:
4389 __attribute__((target("@var{attr-string}")))
4397 where @code{@var{attr-string}} is one of the attribute strings specified above.
4399 Additionally, the architectural extension string may be specified on its
4400 own. This can be used to turn on and off particular architectural extensions
4401 without having to specify a particular architecture version or core. Example:
4404 __attribute__((target("+crc+nocrypto")))
4412 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4413 extension and disables the @code{crypto} extension for the function @code{foo}
4414 without modifying an existing @option{-march=} or @option{-mcpu} option.
4416 Multiple target function attributes can be specified by separating them with
4417 a comma. For example:
4419 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
4427 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
4428 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
4430 @subsubsection Inlining rules
4431 Specifying target attributes on individual functions or performing link-time
4432 optimization across translation units compiled with different target options
4433 can affect function inlining rules:
4435 In particular, a caller function can inline a callee function only if the
4436 architectural features available to the callee are a subset of the features
4437 available to the caller.
4438 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
4439 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
4440 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
4441 because the all the architectural features that function @code{bar} requires
4442 are available to function @code{foo}. Conversely, function @code{bar} cannot
4443 inline function @code{foo}.
4445 Additionally inlining a function compiled with @option{-mstrict-align} into a
4446 function compiled without @code{-mstrict-align} is not allowed.
4447 However, inlining a function compiled without @option{-mstrict-align} into a
4448 function compiled with @option{-mstrict-align} is allowed.
4450 Note that CPU tuning options and attributes such as the @option{-mcpu=},
4451 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
4452 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
4453 architectural feature rules specified above.
4455 @node AMD GCN Function Attributes
4456 @subsection AMD GCN Function Attributes
4458 These function attributes are supported by the AMD GCN back end:
4461 @item amdgpu_hsa_kernel
4462 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
4463 This attribute indicates that the corresponding function should be compiled as
4464 a kernel function, that is an entry point that can be invoked from the host
4465 via the HSA runtime library. By default functions are only callable only from
4466 other GCN functions.
4468 This attribute is implicitly applied to any function named @code{main}, using
4471 Kernel functions may return an integer value, which will be written to a
4472 conventional place within the HSA "kernargs" region.
4474 The attribute parameters configure what values are passed into the kernel
4475 function by the GPU drivers, via the initial register state. Some values are
4476 used by the compiler, and therefore forced on. Enabling other options may
4477 break assumptions in the compiler and/or run-time libraries.
4480 @item private_segment_buffer
4481 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4485 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4489 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4492 @item kernarg_segment_ptr
4493 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4494 locate the kernel arguments, "kernargs").
4497 Set @code{enable_sgpr_dispatch_id} flag.
4499 @item flat_scratch_init
4500 Set @code{enable_sgpr_flat_scratch_init} flag.
4502 @item private_segment_size
4503 Set @code{enable_sgpr_private_segment_size} flag.
4505 @item grid_workgroup_count_X
4506 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4507 use OpenACC/OpenMP).
4509 @item grid_workgroup_count_Y
4510 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4512 @item grid_workgroup_count_Z
4513 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4515 @item workgroup_id_X
4516 Set @code{enable_sgpr_workgroup_id_x} flag.
4518 @item workgroup_id_Y
4519 Set @code{enable_sgpr_workgroup_id_y} flag.
4521 @item workgroup_id_Z
4522 Set @code{enable_sgpr_workgroup_id_z} flag.
4524 @item workgroup_info
4525 Set @code{enable_sgpr_workgroup_info} flag.
4527 @item private_segment_wave_offset
4528 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4529 (required to locate the stack).
4531 @item work_item_id_X
4532 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4534 @item work_item_id_Y
4535 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4538 @item work_item_id_Z
4539 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4545 @node ARC Function Attributes
4546 @subsection ARC Function Attributes
4548 These function attributes are supported by the ARC back end:
4552 @cindex @code{interrupt} function attribute, ARC
4553 Use this attribute to indicate
4554 that the specified function is an interrupt handler. The compiler generates
4555 function entry and exit sequences suitable for use in an interrupt handler
4556 when this attribute is present.
4558 On the ARC, you must specify the kind of interrupt to be handled
4559 in a parameter to the interrupt attribute like this:
4562 void f () __attribute__ ((interrupt ("ilink1")));
4565 Permissible values for this parameter are: @w{@code{ilink1}} and
4566 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
4567 @w{@code{firq}} for ARCv2 architecture.
4572 @cindex @code{long_call} function attribute, ARC
4573 @cindex @code{medium_call} function attribute, ARC
4574 @cindex @code{short_call} function attribute, ARC
4575 @cindex indirect calls, ARC
4576 These attributes specify how a particular function is called.
4577 These attributes override the
4578 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4579 command-line switches and @code{#pragma long_calls} settings.
4581 For ARC, a function marked with the @code{long_call} attribute is
4582 always called using register-indirect jump-and-link instructions,
4583 thereby enabling the called function to be placed anywhere within the
4584 32-bit address space. A function marked with the @code{medium_call}
4585 attribute will always be close enough to be called with an unconditional
4586 branch-and-link instruction, which has a 25-bit offset from
4587 the call site. A function marked with the @code{short_call}
4588 attribute will always be close enough to be called with a conditional
4589 branch-and-link instruction, which has a 21-bit offset from
4593 @cindex @code{jli_always} function attribute, ARC
4594 Forces a particular function to be called using @code{jli}
4595 instruction. The @code{jli} instruction makes use of a table stored
4596 into @code{.jlitab} section, which holds the location of the functions
4597 which are addressed using this instruction.
4600 @cindex @code{jli_fixed} function attribute, ARC
4601 Identical like the above one, but the location of the function in the
4602 @code{jli} table is known and given as an attribute parameter.
4605 @cindex @code{secure_call} function attribute, ARC
4606 This attribute allows one to mark secure-code functions that are
4607 callable from normal mode. The location of the secure call function
4608 into the @code{sjli} table needs to be passed as argument.
4611 @cindex @code{naked} function attribute, ARC
4612 This attribute allows the compiler to construct the requisite function
4613 declaration, while allowing the body of the function to be assembly
4614 code. The specified function will not have prologue/epilogue
4615 sequences generated by the compiler. Only basic @code{asm} statements
4616 can safely be included in naked functions (@pxref{Basic Asm}). While
4617 using extended @code{asm} or a mixture of basic @code{asm} and C code
4618 may appear to work, they cannot be depended upon to work reliably and
4623 @node ARM Function Attributes
4624 @subsection ARM Function Attributes
4626 These function attributes are supported for ARM targets:
4630 @item general-regs-only
4631 @cindex @code{general-regs-only} function attribute, ARM
4632 Indicates that no floating-point or Advanced SIMD registers should be
4633 used when generating code for this function. If the function explicitly
4634 uses floating-point code, then the compiler gives an error. This is
4635 the same behavior as that of the command-line option
4636 @option{-mgeneral-regs-only}.
4639 @cindex @code{interrupt} function attribute, ARM
4640 Use this attribute to indicate
4641 that the specified function is an interrupt handler. The compiler generates
4642 function entry and exit sequences suitable for use in an interrupt handler
4643 when this attribute is present.
4645 You can specify the kind of interrupt to be handled by
4646 adding an optional parameter to the interrupt attribute like this:
4649 void f () __attribute__ ((interrupt ("IRQ")));
4653 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4654 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4656 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4657 may be called with a word-aligned stack pointer.
4660 @cindex @code{isr} function attribute, ARM
4661 Use this attribute on ARM to write Interrupt Service Routines. This is an
4662 alias to the @code{interrupt} attribute above.
4666 @cindex @code{long_call} function attribute, ARM
4667 @cindex @code{short_call} function attribute, ARM
4668 @cindex indirect calls, ARM
4669 These attributes specify how a particular function is called.
4670 These attributes override the
4671 @option{-mlong-calls} (@pxref{ARM Options})
4672 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4673 @code{long_call} attribute indicates that the function might be far
4674 away from the call site and require a different (more expensive)
4675 calling sequence. The @code{short_call} attribute always places
4676 the offset to the function from the call site into the @samp{BL}
4677 instruction directly.
4680 @cindex @code{naked} function attribute, ARM
4681 This attribute allows the compiler to construct the
4682 requisite function declaration, while allowing the body of the
4683 function to be assembly code. The specified function will not have
4684 prologue/epilogue sequences generated by the compiler. Only basic
4685 @code{asm} statements can safely be included in naked functions
4686 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4687 basic @code{asm} and C code may appear to work, they cannot be
4688 depended upon to work reliably and are not supported.
4691 @cindex @code{pcs} function attribute, ARM
4693 The @code{pcs} attribute can be used to control the calling convention
4694 used for a function on ARM. The attribute takes an argument that specifies
4695 the calling convention to use.
4697 When compiling using the AAPCS ABI (or a variant of it) then valid
4698 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4699 order to use a variant other than @code{"aapcs"} then the compiler must
4700 be permitted to use the appropriate co-processor registers (i.e., the
4701 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4705 /* Argument passed in r0, and result returned in r0+r1. */
4706 double f2d (float) __attribute__((pcs("aapcs")));
4709 Variadic functions always use the @code{"aapcs"} calling convention and
4710 the compiler rejects attempts to specify an alternative.
4712 @item target (@var{options})
4713 @cindex @code{target} function attribute
4714 As discussed in @ref{Common Function Attributes}, this attribute
4715 allows specification of target-specific compilation options.
4717 On ARM, the following options are allowed:
4721 @cindex @code{target("thumb")} function attribute, ARM
4722 Force code generation in the Thumb (T16/T32) ISA, depending on the
4726 @cindex @code{target("arm")} function attribute, ARM
4727 Force code generation in the ARM (A32) ISA.
4729 Functions from different modes can be inlined in the caller's mode.
4732 @cindex @code{target("fpu=")} function attribute, ARM
4733 Specifies the fpu for which to tune the performance of this function.
4734 The behavior and permissible arguments are the same as for the @option{-mfpu=}
4735 command-line option.
4738 @cindex @code{arch=} function attribute, ARM
4739 Specifies the architecture version and architectural extensions to use
4740 for this function. The behavior and permissible arguments are the same as
4741 for the @option{-march=} command-line option.
4743 The above target attributes can be specified as follows:
4746 __attribute__((target("arch=armv8-a+crc")))
4754 Additionally, the architectural extension string may be specified on its
4755 own. This can be used to turn on and off particular architectural extensions
4756 without having to specify a particular architecture version or core. Example:
4759 __attribute__((target("+crc+nocrypto")))
4767 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4768 extension and disables the @code{crypto} extension for the function @code{foo}
4769 without modifying an existing @option{-march=} or @option{-mcpu} option.
4775 @node AVR Function Attributes
4776 @subsection AVR Function Attributes
4778 These function attributes are supported by the AVR back end:
4782 @cindex @code{interrupt} function attribute, AVR
4783 Use this attribute to indicate
4784 that the specified function is an interrupt handler. The compiler generates
4785 function entry and exit sequences suitable for use in an interrupt handler
4786 when this attribute is present.
4788 On the AVR, the hardware globally disables interrupts when an
4789 interrupt is executed. The first instruction of an interrupt handler
4790 declared with this attribute is a @code{SEI} instruction to
4791 re-enable interrupts. See also the @code{signal} function attribute
4792 that does not insert a @code{SEI} instruction. If both @code{signal} and
4793 @code{interrupt} are specified for the same function, @code{signal}
4794 is silently ignored.
4797 @cindex @code{naked} function attribute, AVR
4798 This attribute allows the compiler to construct the
4799 requisite function declaration, while allowing the body of the
4800 function to be assembly code. The specified function will not have
4801 prologue/epilogue sequences generated by the compiler. Only basic
4802 @code{asm} statements can safely be included in naked functions
4803 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4804 basic @code{asm} and C code may appear to work, they cannot be
4805 depended upon to work reliably and are not supported.
4808 @cindex @code{no_gccisr} function attribute, AVR
4809 Do not use @code{__gcc_isr} pseudo instructions in a function with
4810 the @code{interrupt} or @code{signal} attribute aka. interrupt
4811 service routine (ISR).
4812 Use this attribute if the preamble of the ISR prologue should always read
4816 in __tmp_reg__, __SREG__
4820 and accordingly for the postamble of the epilogue --- no matter whether
4821 the mentioned registers are actually used in the ISR or not.
4822 Situations where you might want to use this attribute include:
4825 Code that (effectively) clobbers bits of @code{SREG} other than the
4826 @code{I}-flag by writing to the memory location of @code{SREG}.
4828 Code that uses inline assembler to jump to a different function which
4829 expects (parts of) the prologue code as outlined above to be present.
4831 To disable @code{__gcc_isr} generation for the whole compilation unit,
4832 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
4836 @cindex @code{OS_main} function attribute, AVR
4837 @cindex @code{OS_task} function attribute, AVR
4838 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
4839 do not save/restore any call-saved register in their prologue/epilogue.
4841 The @code{OS_main} attribute can be used when there @emph{is
4842 guarantee} that interrupts are disabled at the time when the function
4843 is entered. This saves resources when the stack pointer has to be
4844 changed to set up a frame for local variables.
4846 The @code{OS_task} attribute can be used when there is @emph{no
4847 guarantee} that interrupts are disabled at that time when the function
4848 is entered like for, e@.g@. task functions in a multi-threading operating
4849 system. In that case, changing the stack pointer register is
4850 guarded by save/clear/restore of the global interrupt enable flag.
4852 The differences to the @code{naked} function attribute are:
4854 @item @code{naked} functions do not have a return instruction whereas
4855 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
4856 @code{RETI} return instruction.
4857 @item @code{naked} functions do not set up a frame for local variables
4858 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
4863 @cindex @code{signal} function attribute, AVR
4864 Use this attribute on the AVR to indicate that the specified
4865 function is an interrupt handler. The compiler generates function
4866 entry and exit sequences suitable for use in an interrupt handler when this
4867 attribute is present.
4869 See also the @code{interrupt} function attribute.
4871 The AVR hardware globally disables interrupts when an interrupt is executed.
4872 Interrupt handler functions defined with the @code{signal} attribute
4873 do not re-enable interrupts. It is save to enable interrupts in a
4874 @code{signal} handler. This ``save'' only applies to the code
4875 generated by the compiler and not to the IRQ layout of the
4876 application which is responsibility of the application.
4878 If both @code{signal} and @code{interrupt} are specified for the same
4879 function, @code{signal} is silently ignored.
4882 @node Blackfin Function Attributes
4883 @subsection Blackfin Function Attributes
4885 These function attributes are supported by the Blackfin back end:
4889 @item exception_handler
4890 @cindex @code{exception_handler} function attribute
4891 @cindex exception handler functions, Blackfin
4892 Use this attribute on the Blackfin to indicate that the specified function
4893 is an exception handler. The compiler generates function entry and
4894 exit sequences suitable for use in an exception handler when this
4895 attribute is present.
4897 @item interrupt_handler
4898 @cindex @code{interrupt_handler} function attribute, Blackfin
4899 Use this attribute to
4900 indicate that the specified function is an interrupt handler. The compiler
4901 generates function entry and exit sequences suitable for use in an
4902 interrupt handler when this attribute is present.
4905 @cindex @code{kspisusp} function attribute, Blackfin
4906 @cindex User stack pointer in interrupts on the Blackfin
4907 When used together with @code{interrupt_handler}, @code{exception_handler}
4908 or @code{nmi_handler}, code is generated to load the stack pointer
4909 from the USP register in the function prologue.
4912 @cindex @code{l1_text} function attribute, Blackfin
4913 This attribute specifies a function to be placed into L1 Instruction
4914 SRAM@. The function is put into a specific section named @code{.l1.text}.
4915 With @option{-mfdpic}, function calls with a such function as the callee
4916 or caller uses inlined PLT.
4919 @cindex @code{l2} function attribute, Blackfin
4920 This attribute specifies a function to be placed into L2
4921 SRAM. The function is put into a specific section named
4922 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
4927 @cindex indirect calls, Blackfin
4928 @cindex @code{longcall} function attribute, Blackfin
4929 @cindex @code{shortcall} function attribute, Blackfin
4930 The @code{longcall} attribute
4931 indicates that the function might be far away from the call site and
4932 require a different (more expensive) calling sequence. The
4933 @code{shortcall} attribute indicates that the function is always close
4934 enough for the shorter calling sequence to be used. These attributes
4935 override the @option{-mlongcall} switch.
4938 @cindex @code{nesting} function attribute, Blackfin
4939 @cindex Allow nesting in an interrupt handler on the Blackfin processor
4940 Use this attribute together with @code{interrupt_handler},
4941 @code{exception_handler} or @code{nmi_handler} to indicate that the function
4942 entry code should enable nested interrupts or exceptions.
4945 @cindex @code{nmi_handler} function attribute, Blackfin
4946 @cindex NMI handler functions on the Blackfin processor
4947 Use this attribute on the Blackfin to indicate that the specified function
4948 is an NMI handler. The compiler generates function entry and
4949 exit sequences suitable for use in an NMI handler when this
4950 attribute is present.
4953 @cindex @code{saveall} function attribute, Blackfin
4954 @cindex save all registers on the Blackfin
4955 Use this attribute to indicate that
4956 all registers except the stack pointer should be saved in the prologue
4957 regardless of whether they are used or not.
4960 @node BPF Function Attributes
4961 @subsection BPF Function Attributes
4963 These function attributes are supported by the BPF back end:
4967 @cindex @code{kernel helper}, function attribute, BPF
4968 use this attribute to indicate the specified function declaration is a
4969 kernel helper. The helper function is passed as an argument to the
4973 int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
4974 __attribute__ ((kernel_helper (4)));
4978 @node CR16 Function Attributes
4979 @subsection CR16 Function Attributes
4981 These function attributes are supported by the CR16 back end:
4985 @cindex @code{interrupt} function attribute, CR16
4986 Use this attribute to indicate
4987 that the specified function is an interrupt handler. The compiler generates
4988 function entry and exit sequences suitable for use in an interrupt handler
4989 when this attribute is present.
4992 @node C-SKY Function Attributes
4993 @subsection C-SKY Function Attributes
4995 These function attributes are supported by the C-SKY back end:
5000 @cindex @code{interrupt} function attribute, C-SKY
5001 @cindex @code{isr} function attribute, C-SKY
5002 Use these attributes to indicate that the specified function
5003 is an interrupt handler.
5004 The compiler generates function entry and exit sequences suitable for
5005 use in an interrupt handler when either of these attributes are present.
5007 Use of these options requires the @option{-mistack} command-line option
5008 to enable support for the necessary interrupt stack instructions. They
5009 are ignored with a warning otherwise. @xref{C-SKY Options}.
5012 @cindex @code{naked} function attribute, C-SKY
5013 This attribute allows the compiler to construct the
5014 requisite function declaration, while allowing the body of the
5015 function to be assembly code. The specified function will not have
5016 prologue/epilogue sequences generated by the compiler. Only basic
5017 @code{asm} statements can safely be included in naked functions
5018 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5019 basic @code{asm} and C code may appear to work, they cannot be
5020 depended upon to work reliably and are not supported.
5024 @node Epiphany Function Attributes
5025 @subsection Epiphany Function Attributes
5027 These function attributes are supported by the Epiphany back end:
5031 @cindex @code{disinterrupt} function attribute, Epiphany
5032 This attribute causes the compiler to emit
5033 instructions to disable interrupts for the duration of the given
5036 @item forwarder_section
5037 @cindex @code{forwarder_section} function attribute, Epiphany
5038 This attribute modifies the behavior of an interrupt handler.
5039 The interrupt handler may be in external memory which cannot be
5040 reached by a branch instruction, so generate a local memory trampoline
5041 to transfer control. The single parameter identifies the section where
5042 the trampoline is placed.
5045 @cindex @code{interrupt} function attribute, Epiphany
5046 Use this attribute to indicate
5047 that the specified function is an interrupt handler. The compiler generates
5048 function entry and exit sequences suitable for use in an interrupt handler
5049 when this attribute is present. It may also generate
5050 a special section with code to initialize the interrupt vector table.
5052 On Epiphany targets one or more optional parameters can be added like this:
5055 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
5058 Permissible values for these parameters are: @w{@code{reset}},
5059 @w{@code{software_exception}}, @w{@code{page_miss}},
5060 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
5061 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
5062 Multiple parameters indicate that multiple entries in the interrupt
5063 vector table should be initialized for this function, i.e.@: for each
5064 parameter @w{@var{name}}, a jump to the function is emitted in
5065 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
5066 entirely, in which case no interrupt vector table entry is provided.
5068 Note that interrupts are enabled inside the function
5069 unless the @code{disinterrupt} attribute is also specified.
5071 The following examples are all valid uses of these attributes on
5074 void __attribute__ ((interrupt)) universal_handler ();
5075 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
5076 void __attribute__ ((interrupt ("dma0, dma1")))
5077 universal_dma_handler ();
5078 void __attribute__ ((interrupt ("timer0"), disinterrupt))
5079 fast_timer_handler ();
5080 void __attribute__ ((interrupt ("dma0, dma1"),
5081 forwarder_section ("tramp")))
5082 external_dma_handler ();
5087 @cindex @code{long_call} function attribute, Epiphany
5088 @cindex @code{short_call} function attribute, Epiphany
5089 @cindex indirect calls, Epiphany
5090 These attributes specify how a particular function is called.
5091 These attributes override the
5092 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
5093 command-line switch and @code{#pragma long_calls} settings.
5097 @node H8/300 Function Attributes
5098 @subsection H8/300 Function Attributes
5100 These function attributes are available for H8/300 targets:
5103 @item function_vector
5104 @cindex @code{function_vector} function attribute, H8/300
5105 Use this attribute on the H8/300, H8/300H, and H8S to indicate
5106 that the specified function should be called through the function vector.
5107 Calling a function through the function vector reduces code size; however,
5108 the function vector has a limited size (maximum 128 entries on the H8/300
5109 and 64 entries on the H8/300H and H8S)
5110 and shares space with the interrupt vector.
5112 @item interrupt_handler
5113 @cindex @code{interrupt_handler} function attribute, H8/300
5114 Use this attribute on the H8/300, H8/300H, and H8S to
5115 indicate that the specified function is an interrupt handler. The compiler
5116 generates function entry and exit sequences suitable for use in an
5117 interrupt handler when this attribute is present.
5120 @cindex @code{saveall} function attribute, H8/300
5121 @cindex save all registers on the H8/300, H8/300H, and H8S
5122 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
5123 all registers except the stack pointer should be saved in the prologue
5124 regardless of whether they are used or not.
5127 @node IA-64 Function Attributes
5128 @subsection IA-64 Function Attributes
5130 These function attributes are supported on IA-64 targets:
5133 @item syscall_linkage
5134 @cindex @code{syscall_linkage} function attribute, IA-64
5135 This attribute is used to modify the IA-64 calling convention by marking
5136 all input registers as live at all function exits. This makes it possible
5137 to restart a system call after an interrupt without having to save/restore
5138 the input registers. This also prevents kernel data from leaking into
5142 @cindex @code{version_id} function attribute, IA-64
5143 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
5144 symbol to contain a version string, thus allowing for function level
5145 versioning. HP-UX system header files may use function level versioning
5146 for some system calls.
5149 extern int foo () __attribute__((version_id ("20040821")));
5153 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
5156 @node M32C Function Attributes
5157 @subsection M32C Function Attributes
5159 These function attributes are supported by the M32C back end:
5163 @cindex @code{bank_switch} function attribute, M32C
5164 When added to an interrupt handler with the M32C port, causes the
5165 prologue and epilogue to use bank switching to preserve the registers
5166 rather than saving them on the stack.
5168 @item fast_interrupt
5169 @cindex @code{fast_interrupt} function attribute, M32C
5170 Use this attribute on the M32C port to indicate that the specified
5171 function is a fast interrupt handler. This is just like the
5172 @code{interrupt} attribute, except that @code{freit} is used to return
5173 instead of @code{reit}.
5175 @item function_vector
5176 @cindex @code{function_vector} function attribute, M16C/M32C
5177 On M16C/M32C targets, the @code{function_vector} attribute declares a
5178 special page subroutine call function. Use of this attribute reduces
5179 the code size by 2 bytes for each call generated to the
5180 subroutine. The argument to the attribute is the vector number entry
5181 from the special page vector table which contains the 16 low-order
5182 bits of the subroutine's entry address. Each vector table has special
5183 page number (18 to 255) that is used in @code{jsrs} instructions.
5184 Jump addresses of the routines are generated by adding 0x0F0000 (in
5185 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
5186 2-byte addresses set in the vector table. Therefore you need to ensure
5187 that all the special page vector routines should get mapped within the
5188 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
5191 In the following example 2 bytes are saved for each call to
5192 function @code{foo}.
5195 void foo (void) __attribute__((function_vector(0x18)));
5206 If functions are defined in one file and are called in another file,
5207 then be sure to write this declaration in both files.
5209 This attribute is ignored for R8C target.
5212 @cindex @code{interrupt} function attribute, M32C
5213 Use this attribute to indicate
5214 that the specified function is an interrupt handler. The compiler generates
5215 function entry and exit sequences suitable for use in an interrupt handler
5216 when this attribute is present.
5219 @node M32R/D Function Attributes
5220 @subsection M32R/D Function Attributes
5222 These function attributes are supported by the M32R/D back end:
5226 @cindex @code{interrupt} function attribute, M32R/D
5227 Use this attribute to indicate
5228 that the specified function is an interrupt handler. The compiler generates
5229 function entry and exit sequences suitable for use in an interrupt handler
5230 when this attribute is present.
5232 @item model (@var{model-name})
5233 @cindex @code{model} function attribute, M32R/D
5234 @cindex function addressability on the M32R/D
5236 On the M32R/D, use this attribute to set the addressability of an
5237 object, and of the code generated for a function. The identifier
5238 @var{model-name} is one of @code{small}, @code{medium}, or
5239 @code{large}, representing each of the code models.
5241 Small model objects live in the lower 16MB of memory (so that their
5242 addresses can be loaded with the @code{ld24} instruction), and are
5243 callable with the @code{bl} instruction.
5245 Medium model objects may live anywhere in the 32-bit address space (the
5246 compiler generates @code{seth/add3} instructions to load their addresses),
5247 and are callable with the @code{bl} instruction.
5249 Large model objects may live anywhere in the 32-bit address space (the
5250 compiler generates @code{seth/add3} instructions to load their addresses),
5251 and may not be reachable with the @code{bl} instruction (the compiler
5252 generates the much slower @code{seth/add3/jl} instruction sequence).
5255 @node m68k Function Attributes
5256 @subsection m68k Function Attributes
5258 These function attributes are supported by the m68k back end:
5262 @itemx interrupt_handler
5263 @cindex @code{interrupt} function attribute, m68k
5264 @cindex @code{interrupt_handler} function attribute, m68k
5265 Use this attribute to
5266 indicate that the specified function is an interrupt handler. The compiler
5267 generates function entry and exit sequences suitable for use in an
5268 interrupt handler when this attribute is present. Either name may be used.
5270 @item interrupt_thread
5271 @cindex @code{interrupt_thread} function attribute, fido
5272 Use this attribute on fido, a subarchitecture of the m68k, to indicate
5273 that the specified function is an interrupt handler that is designed
5274 to run as a thread. The compiler omits generate prologue/epilogue
5275 sequences and replaces the return instruction with a @code{sleep}
5276 instruction. This attribute is available only on fido.
5279 @node MCORE Function Attributes
5280 @subsection MCORE Function Attributes
5282 These function attributes are supported by the MCORE back end:
5286 @cindex @code{naked} function attribute, MCORE
5287 This attribute allows the compiler to construct the
5288 requisite function declaration, while allowing the body of the
5289 function to be assembly code. The specified function will not have
5290 prologue/epilogue sequences generated by the compiler. Only basic
5291 @code{asm} statements can safely be included in naked functions
5292 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5293 basic @code{asm} and C code may appear to work, they cannot be
5294 depended upon to work reliably and are not supported.
5297 @node MeP Function Attributes
5298 @subsection MeP Function Attributes
5300 These function attributes are supported by the MeP back end:
5304 @cindex @code{disinterrupt} function attribute, MeP
5305 On MeP targets, this attribute causes the compiler to emit
5306 instructions to disable interrupts for the duration of the given
5310 @cindex @code{interrupt} function attribute, MeP
5311 Use this attribute to indicate
5312 that the specified function is an interrupt handler. The compiler generates
5313 function entry and exit sequences suitable for use in an interrupt handler
5314 when this attribute is present.
5317 @cindex @code{near} function attribute, MeP
5318 This attribute causes the compiler to assume the called
5319 function is close enough to use the normal calling convention,
5320 overriding the @option{-mtf} command-line option.
5323 @cindex @code{far} function attribute, MeP
5324 On MeP targets this causes the compiler to use a calling convention
5325 that assumes the called function is too far away for the built-in
5329 @cindex @code{vliw} function attribute, MeP
5330 The @code{vliw} attribute tells the compiler to emit
5331 instructions in VLIW mode instead of core mode. Note that this
5332 attribute is not allowed unless a VLIW coprocessor has been configured
5333 and enabled through command-line options.
5336 @node MicroBlaze Function Attributes
5337 @subsection MicroBlaze Function Attributes
5339 These function attributes are supported on MicroBlaze targets:
5342 @item save_volatiles
5343 @cindex @code{save_volatiles} function attribute, MicroBlaze
5344 Use this attribute to indicate that the function is
5345 an interrupt handler. All volatile registers (in addition to non-volatile
5346 registers) are saved in the function prologue. If the function is a leaf
5347 function, only volatiles used by the function are saved. A normal function
5348 return is generated instead of a return from interrupt.
5351 @cindex @code{break_handler} function attribute, MicroBlaze
5352 @cindex break handler functions
5353 Use this attribute to indicate that
5354 the specified function is a break handler. The compiler generates function
5355 entry and exit sequences suitable for use in an break handler when this
5356 attribute is present. The return from @code{break_handler} is done through
5357 the @code{rtbd} instead of @code{rtsd}.
5360 void f () __attribute__ ((break_handler));
5363 @item interrupt_handler
5364 @itemx fast_interrupt
5365 @cindex @code{interrupt_handler} function attribute, MicroBlaze
5366 @cindex @code{fast_interrupt} function attribute, MicroBlaze
5367 These attributes indicate that the specified function is an interrupt
5368 handler. Use the @code{fast_interrupt} attribute to indicate handlers
5369 used in low-latency interrupt mode, and @code{interrupt_handler} for
5370 interrupts that do not use low-latency handlers. In both cases, GCC
5371 emits appropriate prologue code and generates a return from the handler
5372 using @code{rtid} instead of @code{rtsd}.
5375 @node Microsoft Windows Function Attributes
5376 @subsection Microsoft Windows Function Attributes
5378 The following attributes are available on Microsoft Windows and Symbian OS
5383 @cindex @code{dllexport} function attribute
5384 @cindex @code{__declspec(dllexport)}
5385 On Microsoft Windows targets and Symbian OS targets the
5386 @code{dllexport} attribute causes the compiler to provide a global
5387 pointer to a pointer in a DLL, so that it can be referenced with the
5388 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
5389 name is formed by combining @code{_imp__} and the function or variable
5392 You can use @code{__declspec(dllexport)} as a synonym for
5393 @code{__attribute__ ((dllexport))} for compatibility with other
5396 On systems that support the @code{visibility} attribute, this
5397 attribute also implies ``default'' visibility. It is an error to
5398 explicitly specify any other visibility.
5400 GCC's default behavior is to emit all inline functions with the
5401 @code{dllexport} attribute. Since this can cause object file-size bloat,
5402 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
5403 ignore the attribute for inlined functions unless the
5404 @option{-fkeep-inline-functions} flag is used instead.
5406 The attribute is ignored for undefined symbols.
5408 When applied to C++ classes, the attribute marks defined non-inlined
5409 member functions and static data members as exports. Static consts
5410 initialized in-class are not marked unless they are also defined
5413 For Microsoft Windows targets there are alternative methods for
5414 including the symbol in the DLL's export table such as using a
5415 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
5416 the @option{--export-all} linker flag.
5419 @cindex @code{dllimport} function attribute
5420 @cindex @code{__declspec(dllimport)}
5421 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
5422 attribute causes the compiler to reference a function or variable via
5423 a global pointer to a pointer that is set up by the DLL exporting the
5424 symbol. The attribute implies @code{extern}. On Microsoft Windows
5425 targets, the pointer name is formed by combining @code{_imp__} and the
5426 function or variable name.
5428 You can use @code{__declspec(dllimport)} as a synonym for
5429 @code{__attribute__ ((dllimport))} for compatibility with other
5432 On systems that support the @code{visibility} attribute, this
5433 attribute also implies ``default'' visibility. It is an error to
5434 explicitly specify any other visibility.
5436 Currently, the attribute is ignored for inlined functions. If the
5437 attribute is applied to a symbol @emph{definition}, an error is reported.
5438 If a symbol previously declared @code{dllimport} is later defined, the
5439 attribute is ignored in subsequent references, and a warning is emitted.
5440 The attribute is also overridden by a subsequent declaration as
5443 When applied to C++ classes, the attribute marks non-inlined
5444 member functions and static data members as imports. However, the
5445 attribute is ignored for virtual methods to allow creation of vtables
5448 On the SH Symbian OS target the @code{dllimport} attribute also has
5449 another affect---it can cause the vtable and run-time type information
5450 for a class to be exported. This happens when the class has a
5451 dllimported constructor or a non-inline, non-pure virtual function
5452 and, for either of those two conditions, the class also has an inline
5453 constructor or destructor and has a key function that is defined in
5454 the current translation unit.
5456 For Microsoft Windows targets the use of the @code{dllimport}
5457 attribute on functions is not necessary, but provides a small
5458 performance benefit by eliminating a thunk in the DLL@. The use of the
5459 @code{dllimport} attribute on imported variables can be avoided by passing the
5460 @option{--enable-auto-import} switch to the GNU linker. As with
5461 functions, using the attribute for a variable eliminates a thunk in
5464 One drawback to using this attribute is that a pointer to a
5465 @emph{variable} marked as @code{dllimport} cannot be used as a constant
5466 address. However, a pointer to a @emph{function} with the
5467 @code{dllimport} attribute can be used as a constant initializer; in
5468 this case, the address of a stub function in the import lib is
5469 referenced. On Microsoft Windows targets, the attribute can be disabled
5470 for functions by setting the @option{-mnop-fun-dllimport} flag.
5473 @node MIPS Function Attributes
5474 @subsection MIPS Function Attributes
5476 These function attributes are supported by the MIPS back end:
5480 @cindex @code{interrupt} function attribute, MIPS
5481 Use this attribute to indicate that the specified function is an interrupt
5482 handler. The compiler generates function entry and exit sequences suitable
5483 for use in an interrupt handler when this attribute is present.
5484 An optional argument is supported for the interrupt attribute which allows
5485 the interrupt mode to be described. By default GCC assumes the external
5486 interrupt controller (EIC) mode is in use, this can be explicitly set using
5487 @code{eic}. When interrupts are non-masked then the requested Interrupt
5488 Priority Level (IPL) is copied to the current IPL which has the effect of only
5489 enabling higher priority interrupts. To use vectored interrupt mode use
5490 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
5491 the behavior of the non-masked interrupt support and GCC will arrange to mask
5492 all interrupts from sw0 up to and including the specified interrupt vector.
5494 You can use the following attributes to modify the behavior
5495 of an interrupt handler:
5497 @item use_shadow_register_set
5498 @cindex @code{use_shadow_register_set} function attribute, MIPS
5499 Assume that the handler uses a shadow register set, instead of
5500 the main general-purpose registers. An optional argument @code{intstack} is
5501 supported to indicate that the shadow register set contains a valid stack
5504 @item keep_interrupts_masked
5505 @cindex @code{keep_interrupts_masked} function attribute, MIPS
5506 Keep interrupts masked for the whole function. Without this attribute,
5507 GCC tries to reenable interrupts for as much of the function as it can.
5509 @item use_debug_exception_return
5510 @cindex @code{use_debug_exception_return} function attribute, MIPS
5511 Return using the @code{deret} instruction. Interrupt handlers that don't
5512 have this attribute return using @code{eret} instead.
5515 You can use any combination of these attributes, as shown below:
5517 void __attribute__ ((interrupt)) v0 ();
5518 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5519 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5520 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5521 void __attribute__ ((interrupt, use_shadow_register_set,
5522 keep_interrupts_masked)) v4 ();
5523 void __attribute__ ((interrupt, use_shadow_register_set,
5524 use_debug_exception_return)) v5 ();
5525 void __attribute__ ((interrupt, keep_interrupts_masked,
5526 use_debug_exception_return)) v6 ();
5527 void __attribute__ ((interrupt, use_shadow_register_set,
5528 keep_interrupts_masked,
5529 use_debug_exception_return)) v7 ();
5530 void __attribute__ ((interrupt("eic"))) v8 ();
5531 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5538 @cindex indirect calls, MIPS
5539 @cindex @code{long_call} function attribute, MIPS
5540 @cindex @code{short_call} function attribute, MIPS
5541 @cindex @code{near} function attribute, MIPS
5542 @cindex @code{far} function attribute, MIPS
5543 These attributes specify how a particular function is called on MIPS@.
5544 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5545 command-line switch. The @code{long_call} and @code{far} attributes are
5546 synonyms, and cause the compiler to always call
5547 the function by first loading its address into a register, and then using
5548 the contents of that register. The @code{short_call} and @code{near}
5549 attributes are synonyms, and have the opposite
5550 effect; they specify that non-PIC calls should be made using the more
5551 efficient @code{jal} instruction.
5555 @cindex @code{mips16} function attribute, MIPS
5556 @cindex @code{nomips16} function attribute, MIPS
5558 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5559 function attributes to locally select or turn off MIPS16 code generation.
5560 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5561 while MIPS16 code generation is disabled for functions with the
5562 @code{nomips16} attribute. These attributes override the
5563 @option{-mips16} and @option{-mno-mips16} options on the command line
5564 (@pxref{MIPS Options}).
5566 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5567 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5568 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5569 may interact badly with some GCC extensions such as @code{__builtin_apply}
5570 (@pxref{Constructing Calls}).
5572 @item micromips, MIPS
5573 @itemx nomicromips, MIPS
5574 @cindex @code{micromips} function attribute
5575 @cindex @code{nomicromips} function attribute
5577 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5578 function attributes to locally select or turn off microMIPS code generation.
5579 A function with the @code{micromips} attribute is emitted as microMIPS code,
5580 while microMIPS code generation is disabled for functions with the
5581 @code{nomicromips} attribute. These attributes override the
5582 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5583 (@pxref{MIPS Options}).
5585 When compiling files containing mixed microMIPS and non-microMIPS code, the
5586 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5588 not that within individual functions. Mixed microMIPS and non-microMIPS code
5589 may interact badly with some GCC extensions such as @code{__builtin_apply}
5590 (@pxref{Constructing Calls}).
5593 @cindex @code{nocompression} function attribute, MIPS
5594 On MIPS targets, you can use the @code{nocompression} function attribute
5595 to locally turn off MIPS16 and microMIPS code generation. This attribute
5596 overrides the @option{-mips16} and @option{-mmicromips} options on the
5597 command line (@pxref{MIPS Options}).
5600 @node MSP430 Function Attributes
5601 @subsection MSP430 Function Attributes
5603 These function attributes are supported by the MSP430 back end:
5607 @cindex @code{critical} function attribute, MSP430
5608 Critical functions disable interrupts upon entry and restore the
5609 previous interrupt state upon exit. Critical functions cannot also
5610 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5612 The MSP430 hardware ensures that interrupts are disabled on entry to
5613 @code{interrupt} functions, and restores the previous interrupt state
5614 on exit. The @code{critical} attribute is therefore redundant on
5615 @code{interrupt} functions.
5618 @cindex @code{interrupt} function attribute, MSP430
5619 Use this attribute to indicate
5620 that the specified function is an interrupt handler. The compiler generates
5621 function entry and exit sequences suitable for use in an interrupt handler
5622 when this attribute is present.
5624 You can provide an argument to the interrupt
5625 attribute which specifies a name or number. If the argument is a
5626 number it indicates the slot in the interrupt vector table (0 - 31) to
5627 which this handler should be assigned. If the argument is a name it
5628 is treated as a symbolic name for the vector slot. These names should
5629 match up with appropriate entries in the linker script. By default
5630 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5631 @code{reset} for vector 31 are recognized.
5634 @cindex @code{naked} function attribute, MSP430
5635 This attribute allows the compiler to construct the
5636 requisite function declaration, while allowing the body of the
5637 function to be assembly code. The specified function will not have
5638 prologue/epilogue sequences generated by the compiler. Only basic
5639 @code{asm} statements can safely be included in naked functions
5640 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5641 basic @code{asm} and C code may appear to work, they cannot be
5642 depended upon to work reliably and are not supported.
5645 @cindex @code{reentrant} function attribute, MSP430
5646 Reentrant functions disable interrupts upon entry and enable them
5647 upon exit. Reentrant functions cannot also have the @code{naked}
5648 or @code{critical} attributes. They can have the @code{interrupt}
5652 @cindex @code{wakeup} function attribute, MSP430
5653 This attribute only applies to interrupt functions. It is silently
5654 ignored if applied to a non-interrupt function. A wakeup interrupt
5655 function will rouse the processor from any low-power state that it
5656 might be in when the function exits.
5661 @cindex @code{lower} function attribute, MSP430
5662 @cindex @code{upper} function attribute, MSP430
5663 @cindex @code{either} function attribute, MSP430
5664 On the MSP430 target these attributes can be used to specify whether
5665 the function or variable should be placed into low memory, high
5666 memory, or the placement should be left to the linker to decide. The
5667 attributes are only significant if compiling for the MSP430X
5668 architecture in the large memory model.
5670 The attributes work in conjunction with a linker script that has been
5671 augmented to specify where to place sections with a @code{.lower} and
5672 a @code{.upper} prefix. So, for example, as well as placing the
5673 @code{.data} section, the script also specifies the placement of a
5674 @code{.lower.data} and a @code{.upper.data} section. The intention
5675 is that @code{lower} sections are placed into a small but easier to
5676 access memory region and the upper sections are placed into a larger, but
5677 slower to access, region.
5679 The @code{either} attribute is special. It tells the linker to place
5680 the object into the corresponding @code{lower} section if there is
5681 room for it. If there is insufficient room then the object is placed
5682 into the corresponding @code{upper} section instead. Note that the
5683 placement algorithm is not very sophisticated. It does not attempt to
5684 find an optimal packing of the @code{lower} sections. It just makes
5685 one pass over the objects and does the best that it can. Using the
5686 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5687 options can help the packing, however, since they produce smaller,
5688 easier to pack regions.
5691 @node NDS32 Function Attributes
5692 @subsection NDS32 Function Attributes
5694 These function attributes are supported by the NDS32 back end:
5698 @cindex @code{exception} function attribute
5699 @cindex exception handler functions, NDS32
5700 Use this attribute on the NDS32 target to indicate that the specified function
5701 is an exception handler. The compiler will generate corresponding sections
5702 for use in an exception handler.
5705 @cindex @code{interrupt} function attribute, NDS32
5706 On NDS32 target, this attribute indicates that the specified function
5707 is an interrupt handler. The compiler generates corresponding sections
5708 for use in an interrupt handler. You can use the following attributes
5709 to modify the behavior:
5712 @cindex @code{nested} function attribute, NDS32
5713 This interrupt service routine is interruptible.
5715 @cindex @code{not_nested} function attribute, NDS32
5716 This interrupt service routine is not interruptible.
5718 @cindex @code{nested_ready} function attribute, NDS32
5719 This interrupt service routine is interruptible after @code{PSW.GIE}
5720 (global interrupt enable) is set. This allows interrupt service routine to
5721 finish some short critical code before enabling interrupts.
5723 @cindex @code{save_all} function attribute, NDS32
5724 The system will help save all registers into stack before entering
5727 @cindex @code{partial_save} function attribute, NDS32
5728 The system will help save caller registers into stack before entering
5733 @cindex @code{naked} function attribute, NDS32
5734 This attribute allows the compiler to construct the
5735 requisite function declaration, while allowing the body of the
5736 function to be assembly code. The specified function will not have
5737 prologue/epilogue sequences generated by the compiler. Only basic
5738 @code{asm} statements can safely be included in naked functions
5739 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5740 basic @code{asm} and C code may appear to work, they cannot be
5741 depended upon to work reliably and are not supported.
5744 @cindex @code{reset} function attribute, NDS32
5745 @cindex reset handler functions
5746 Use this attribute on the NDS32 target to indicate that the specified function
5747 is a reset handler. The compiler will generate corresponding sections
5748 for use in a reset handler. You can use the following attributes
5749 to provide extra exception handling:
5752 @cindex @code{nmi} function attribute, NDS32
5753 Provide a user-defined function to handle NMI exception.
5755 @cindex @code{warm} function attribute, NDS32
5756 Provide a user-defined function to handle warm reset exception.
5760 @node Nios II Function Attributes
5761 @subsection Nios II Function Attributes
5763 These function attributes are supported by the Nios II back end:
5766 @item target (@var{options})
5767 @cindex @code{target} function attribute
5768 As discussed in @ref{Common Function Attributes}, this attribute
5769 allows specification of target-specific compilation options.
5771 When compiling for Nios II, the following options are allowed:
5774 @item custom-@var{insn}=@var{N}
5775 @itemx no-custom-@var{insn}
5776 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
5777 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
5778 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
5779 custom instruction with encoding @var{N} when generating code that uses
5780 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
5781 the custom instruction @var{insn}.
5782 These target attributes correspond to the
5783 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
5784 command-line options, and support the same set of @var{insn} keywords.
5785 @xref{Nios II Options}, for more information.
5787 @item custom-fpu-cfg=@var{name}
5788 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
5789 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
5790 command-line option, to select a predefined set of custom instructions
5792 @xref{Nios II Options}, for more information.
5796 @node Nvidia PTX Function Attributes
5797 @subsection Nvidia PTX Function Attributes
5799 These function attributes are supported by the Nvidia PTX back end:
5803 @cindex @code{kernel} attribute, Nvidia PTX
5804 This attribute indicates that the corresponding function should be compiled
5805 as a kernel function, which can be invoked from the host via the CUDA RT
5807 By default functions are only callable only from other PTX functions.
5809 Kernel functions must have @code{void} return type.
5812 @node PowerPC Function Attributes
5813 @subsection PowerPC Function Attributes
5815 These function attributes are supported by the PowerPC back end:
5820 @cindex indirect calls, PowerPC
5821 @cindex @code{longcall} function attribute, PowerPC
5822 @cindex @code{shortcall} function attribute, PowerPC
5823 The @code{longcall} attribute
5824 indicates that the function might be far away from the call site and
5825 require a different (more expensive) calling sequence. The
5826 @code{shortcall} attribute indicates that the function is always close
5827 enough for the shorter calling sequence to be used. These attributes
5828 override both the @option{-mlongcall} switch and
5829 the @code{#pragma longcall} setting.
5831 @xref{RS/6000 and PowerPC Options}, for more information on whether long
5832 calls are necessary.
5834 @item target (@var{options})
5835 @cindex @code{target} function attribute
5836 As discussed in @ref{Common Function Attributes}, this attribute
5837 allows specification of target-specific compilation options.
5839 On the PowerPC, the following options are allowed:
5844 @cindex @code{target("altivec")} function attribute, PowerPC
5845 Generate code that uses (does not use) AltiVec instructions. In
5846 32-bit code, you cannot enable AltiVec instructions unless
5847 @option{-mabi=altivec} is used on the command line.
5851 @cindex @code{target("cmpb")} function attribute, PowerPC
5852 Generate code that uses (does not use) the compare bytes instruction
5853 implemented on the POWER6 processor and other processors that support
5854 the PowerPC V2.05 architecture.
5858 @cindex @code{target("dlmzb")} function attribute, PowerPC
5859 Generate code that uses (does not use) the string-search @samp{dlmzb}
5860 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
5861 generated by default when targeting those processors.
5865 @cindex @code{target("fprnd")} function attribute, PowerPC
5866 Generate code that uses (does not use) the FP round to integer
5867 instructions implemented on the POWER5+ processor and other processors
5868 that support the PowerPC V2.03 architecture.
5872 @cindex @code{target("hard-dfp")} function attribute, PowerPC
5873 Generate code that uses (does not use) the decimal floating-point
5874 instructions implemented on some POWER processors.
5878 @cindex @code{target("isel")} function attribute, PowerPC
5879 Generate code that uses (does not use) ISEL instruction.
5883 @cindex @code{target("mfcrf")} function attribute, PowerPC
5884 Generate code that uses (does not use) the move from condition
5885 register field instruction implemented on the POWER4 processor and
5886 other processors that support the PowerPC V2.01 architecture.
5890 @cindex @code{target("mulhw")} function attribute, PowerPC
5891 Generate code that uses (does not use) the half-word multiply and
5892 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
5893 These instructions are generated by default when targeting those
5898 @cindex @code{target("multiple")} function attribute, PowerPC
5899 Generate code that uses (does not use) the load multiple word
5900 instructions and the store multiple word instructions.
5904 @cindex @code{target("update")} function attribute, PowerPC
5905 Generate code that uses (does not use) the load or store instructions
5906 that update the base register to the address of the calculated memory
5911 @cindex @code{target("popcntb")} function attribute, PowerPC
5912 Generate code that uses (does not use) the popcount and double-precision
5913 FP reciprocal estimate instruction implemented on the POWER5
5914 processor and other processors that support the PowerPC V2.02
5919 @cindex @code{target("popcntd")} function attribute, PowerPC
5920 Generate code that uses (does not use) the popcount instruction
5921 implemented on the POWER7 processor and other processors that support
5922 the PowerPC V2.06 architecture.
5924 @item powerpc-gfxopt
5925 @itemx no-powerpc-gfxopt
5926 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
5927 Generate code that uses (does not use) the optional PowerPC
5928 architecture instructions in the Graphics group, including
5929 floating-point select.
5932 @itemx no-powerpc-gpopt
5933 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
5934 Generate code that uses (does not use) the optional PowerPC
5935 architecture instructions in the General Purpose group, including
5936 floating-point square root.
5938 @item recip-precision
5939 @itemx no-recip-precision
5940 @cindex @code{target("recip-precision")} function attribute, PowerPC
5941 Assume (do not assume) that the reciprocal estimate instructions
5942 provide higher-precision estimates than is mandated by the PowerPC
5947 @cindex @code{target("string")} function attribute, PowerPC
5948 Generate code that uses (does not use) the load string instructions
5949 and the store string word instructions to save multiple registers and
5950 do small block moves.
5954 @cindex @code{target("vsx")} function attribute, PowerPC
5955 Generate code that uses (does not use) vector/scalar (VSX)
5956 instructions, and also enable the use of built-in functions that allow
5957 more direct access to the VSX instruction set. In 32-bit code, you
5958 cannot enable VSX or AltiVec instructions unless
5959 @option{-mabi=altivec} is used on the command line.
5963 @cindex @code{target("friz")} function attribute, PowerPC
5964 Generate (do not generate) the @code{friz} instruction when the
5965 @option{-funsafe-math-optimizations} option is used to optimize
5966 rounding a floating-point value to 64-bit integer and back to floating
5967 point. The @code{friz} instruction does not return the same value if
5968 the floating-point number is too large to fit in an integer.
5970 @item avoid-indexed-addresses
5971 @itemx no-avoid-indexed-addresses
5972 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
5973 Generate code that tries to avoid (not avoid) the use of indexed load
5974 or store instructions.
5978 @cindex @code{target("paired")} function attribute, PowerPC
5979 Generate code that uses (does not use) the generation of PAIRED simd
5984 @cindex @code{target("longcall")} function attribute, PowerPC
5985 Generate code that assumes (does not assume) that all calls are far
5986 away so that a longer more expensive calling sequence is required.
5989 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
5990 Specify the architecture to generate code for when compiling the
5991 function. If you select the @code{target("cpu=power7")} attribute when
5992 generating 32-bit code, VSX and AltiVec instructions are not generated
5993 unless you use the @option{-mabi=altivec} option on the command line.
5995 @item tune=@var{TUNE}
5996 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
5997 Specify the architecture to tune for when compiling the function. If
5998 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
5999 you do specify the @code{target("cpu=@var{CPU}")} attribute,
6000 compilation tunes for the @var{CPU} architecture, and not the
6001 default tuning specified on the command line.
6004 On the PowerPC, the inliner does not inline a
6005 function that has different target options than the caller, unless the
6006 callee has a subset of the target options of the caller.
6009 @node RISC-V Function Attributes
6010 @subsection RISC-V Function Attributes
6012 These function attributes are supported by the RISC-V back end:
6016 @cindex @code{naked} function attribute, RISC-V
6017 This attribute allows the compiler to construct the
6018 requisite function declaration, while allowing the body of the
6019 function to be assembly code. The specified function will not have
6020 prologue/epilogue sequences generated by the compiler. Only basic
6021 @code{asm} statements can safely be included in naked functions
6022 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6023 basic @code{asm} and C code may appear to work, they cannot be
6024 depended upon to work reliably and are not supported.
6027 @cindex @code{interrupt} function attribute, RISC-V
6028 Use this attribute to indicate that the specified function is an interrupt
6029 handler. The compiler generates function entry and exit sequences suitable
6030 for use in an interrupt handler when this attribute is present.
6032 You can specify the kind of interrupt to be handled by adding an optional
6033 parameter to the interrupt attribute like this:
6036 void f (void) __attribute__ ((interrupt ("user")));
6039 Permissible values for this parameter are @code{user}, @code{supervisor},
6040 and @code{machine}. If there is no parameter, then it defaults to
6044 @node RL78 Function Attributes
6045 @subsection RL78 Function Attributes
6047 These function attributes are supported by the RL78 back end:
6051 @itemx brk_interrupt
6052 @cindex @code{interrupt} function attribute, RL78
6053 @cindex @code{brk_interrupt} function attribute, RL78
6054 These attributes indicate
6055 that the specified function is an interrupt handler. The compiler generates
6056 function entry and exit sequences suitable for use in an interrupt handler
6057 when this attribute is present.
6059 Use @code{brk_interrupt} instead of @code{interrupt} for
6060 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
6061 that must end with @code{RETB} instead of @code{RETI}).
6064 @cindex @code{naked} function attribute, RL78
6065 This attribute allows the compiler to construct the
6066 requisite function declaration, while allowing the body of the
6067 function to be assembly code. The specified function will not have
6068 prologue/epilogue sequences generated by the compiler. Only basic
6069 @code{asm} statements can safely be included in naked functions
6070 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6071 basic @code{asm} and C code may appear to work, they cannot be
6072 depended upon to work reliably and are not supported.
6075 @node RX Function Attributes
6076 @subsection RX Function Attributes
6078 These function attributes are supported by the RX back end:
6081 @item fast_interrupt
6082 @cindex @code{fast_interrupt} function attribute, RX
6083 Use this attribute on the RX port to indicate that the specified
6084 function is a fast interrupt handler. This is just like the
6085 @code{interrupt} attribute, except that @code{freit} is used to return
6086 instead of @code{reit}.
6089 @cindex @code{interrupt} function attribute, RX
6090 Use this attribute to indicate
6091 that the specified function is an interrupt handler. The compiler generates
6092 function entry and exit sequences suitable for use in an interrupt handler
6093 when this attribute is present.
6095 On RX and RL78 targets, you may specify one or more vector numbers as arguments
6096 to the attribute, as well as naming an alternate table name.
6097 Parameters are handled sequentially, so one handler can be assigned to
6098 multiple entries in multiple tables. One may also pass the magic
6099 string @code{"$default"} which causes the function to be used for any
6100 unfilled slots in the current table.
6102 This example shows a simple assignment of a function to one vector in
6103 the default table (note that preprocessor macros may be used for
6104 chip-specific symbolic vector names):
6106 void __attribute__ ((interrupt (5))) txd1_handler ();
6109 This example assigns a function to two slots in the default table
6110 (using preprocessor macros defined elsewhere) and makes it the default
6111 for the @code{dct} table:
6113 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
6118 @cindex @code{naked} function attribute, RX
6119 This attribute allows the compiler to construct the
6120 requisite function declaration, while allowing the body of the
6121 function to be assembly code. The specified function will not have
6122 prologue/epilogue sequences generated by the compiler. Only basic
6123 @code{asm} statements can safely be included in naked functions
6124 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6125 basic @code{asm} and C code may appear to work, they cannot be
6126 depended upon to work reliably and are not supported.
6129 @cindex @code{vector} function attribute, RX
6130 This RX attribute is similar to the @code{interrupt} attribute, including its
6131 parameters, but does not make the function an interrupt-handler type
6132 function (i.e.@: it retains the normal C function calling ABI). See the
6133 @code{interrupt} attribute for a description of its arguments.
6136 @node S/390 Function Attributes
6137 @subsection S/390 Function Attributes
6139 These function attributes are supported on the S/390:
6142 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
6143 @cindex @code{hotpatch} function attribute, S/390
6145 On S/390 System z targets, you can use this function attribute to
6146 make GCC generate a ``hot-patching'' function prologue. If the
6147 @option{-mhotpatch=} command-line option is used at the same time,
6148 the @code{hotpatch} attribute takes precedence. The first of the
6149 two arguments specifies the number of halfwords to be added before
6150 the function label. A second argument can be used to specify the
6151 number of halfwords to be added after the function label. For
6152 both arguments the maximum allowed value is 1000000.
6154 If both arguments are zero, hotpatching is disabled.
6156 @item target (@var{options})
6157 @cindex @code{target} function attribute
6158 As discussed in @ref{Common Function Attributes}, this attribute
6159 allows specification of target-specific compilation options.
6161 On S/390, the following options are supported:
6169 @item warn-framesize=
6181 @itemx no-packed-stack
6183 @itemx no-small-exec
6186 @item warn-dynamicstack
6187 @itemx no-warn-dynamicstack
6190 The options work exactly like the S/390 specific command line
6191 options (without the prefix @option{-m}) except that they do not
6192 change any feature macros. For example,
6195 @code{target("no-vx")}
6198 does not undefine the @code{__VEC__} macro.
6201 @node SH Function Attributes
6202 @subsection SH Function Attributes
6204 These function attributes are supported on the SH family of processors:
6207 @item function_vector
6208 @cindex @code{function_vector} function attribute, SH
6209 @cindex calling functions through the function vector on SH2A
6210 On SH2A targets, this attribute declares a function to be called using the
6211 TBR relative addressing mode. The argument to this attribute is the entry
6212 number of the same function in a vector table containing all the TBR
6213 relative addressable functions. For correct operation the TBR must be setup
6214 accordingly to point to the start of the vector table before any functions with
6215 this attribute are invoked. Usually a good place to do the initialization is
6216 the startup routine. The TBR relative vector table can have at max 256 function
6217 entries. The jumps to these functions are generated using a SH2A specific,
6218 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
6219 from GNU binutils version 2.7 or later for this attribute to work correctly.
6221 In an application, for a function being called once, this attribute
6222 saves at least 8 bytes of code; and if other successive calls are being
6223 made to the same function, it saves 2 bytes of code per each of these
6226 @item interrupt_handler
6227 @cindex @code{interrupt_handler} function attribute, SH
6228 Use this attribute to
6229 indicate that the specified function is an interrupt handler. The compiler
6230 generates function entry and exit sequences suitable for use in an
6231 interrupt handler when this attribute is present.
6233 @item nosave_low_regs
6234 @cindex @code{nosave_low_regs} function attribute, SH
6235 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
6236 function should not save and restore registers R0..R7. This can be used on SH3*
6237 and SH4* targets that have a second R0..R7 register bank for non-reentrant
6241 @cindex @code{renesas} function attribute, SH
6242 On SH targets this attribute specifies that the function or struct follows the
6246 @cindex @code{resbank} function attribute, SH
6247 On the SH2A target, this attribute enables the high-speed register
6248 saving and restoration using a register bank for @code{interrupt_handler}
6249 routines. Saving to the bank is performed automatically after the CPU
6250 accepts an interrupt that uses a register bank.
6252 The nineteen 32-bit registers comprising general register R0 to R14,
6253 control register GBR, and system registers MACH, MACL, and PR and the
6254 vector table address offset are saved into a register bank. Register
6255 banks are stacked in first-in last-out (FILO) sequence. Restoration
6256 from the bank is executed by issuing a RESBANK instruction.
6259 @cindex @code{sp_switch} function attribute, SH
6260 Use this attribute on the SH to indicate an @code{interrupt_handler}
6261 function should switch to an alternate stack. It expects a string
6262 argument that names a global variable holding the address of the
6267 void f () __attribute__ ((interrupt_handler,
6268 sp_switch ("alt_stack")));
6272 @cindex @code{trap_exit} function attribute, SH
6273 Use this attribute on the SH for an @code{interrupt_handler} to return using
6274 @code{trapa} instead of @code{rte}. This attribute expects an integer
6275 argument specifying the trap number to be used.
6278 @cindex @code{trapa_handler} function attribute, SH
6279 On SH targets this function attribute is similar to @code{interrupt_handler}
6280 but it does not save and restore all registers.
6283 @node Symbian OS Function Attributes
6284 @subsection Symbian OS Function Attributes
6286 @xref{Microsoft Windows Function Attributes}, for discussion of the
6287 @code{dllexport} and @code{dllimport} attributes.
6289 @node V850 Function Attributes
6290 @subsection V850 Function Attributes
6292 The V850 back end supports these function attributes:
6296 @itemx interrupt_handler
6297 @cindex @code{interrupt} function attribute, V850
6298 @cindex @code{interrupt_handler} function attribute, V850
6299 Use these attributes to indicate
6300 that the specified function is an interrupt handler. The compiler generates
6301 function entry and exit sequences suitable for use in an interrupt handler
6302 when either attribute is present.
6305 @node Visium Function Attributes
6306 @subsection Visium Function Attributes
6308 These function attributes are supported by the Visium back end:
6312 @cindex @code{interrupt} function attribute, Visium
6313 Use this attribute to indicate
6314 that the specified function is an interrupt handler. The compiler generates
6315 function entry and exit sequences suitable for use in an interrupt handler
6316 when this attribute is present.
6319 @node x86 Function Attributes
6320 @subsection x86 Function Attributes
6322 These function attributes are supported by the x86 back end:
6326 @cindex @code{cdecl} function attribute, x86-32
6327 @cindex functions that pop the argument stack on x86-32
6329 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
6330 assume that the calling function pops off the stack space used to
6331 pass arguments. This is
6332 useful to override the effects of the @option{-mrtd} switch.
6335 @cindex @code{fastcall} function attribute, x86-32
6336 @cindex functions that pop the argument stack on x86-32
6337 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
6338 pass the first argument (if of integral type) in the register ECX and
6339 the second argument (if of integral type) in the register EDX@. Subsequent
6340 and other typed arguments are passed on the stack. The called function
6341 pops the arguments off the stack. If the number of arguments is variable all
6342 arguments are pushed on the stack.
6345 @cindex @code{thiscall} function attribute, x86-32
6346 @cindex functions that pop the argument stack on x86-32
6347 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
6348 pass the first argument (if of integral type) in the register ECX.
6349 Subsequent and other typed arguments are passed on the stack. The called
6350 function pops the arguments off the stack.
6351 If the number of arguments is variable all arguments are pushed on the
6353 The @code{thiscall} attribute is intended for C++ non-static member functions.
6354 As a GCC extension, this calling convention can be used for C functions
6355 and for static member methods.
6359 @cindex @code{ms_abi} function attribute, x86
6360 @cindex @code{sysv_abi} function attribute, x86
6362 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
6363 to indicate which calling convention should be used for a function. The
6364 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
6365 while the @code{sysv_abi} attribute tells the compiler to use the System V
6366 ELF ABI, which is used on GNU/Linux and other systems. The default is to use
6367 the Microsoft ABI when targeting Windows. On all other systems, the default
6368 is the System V ELF ABI.
6370 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
6371 requires the @option{-maccumulate-outgoing-args} option.
6373 @item callee_pop_aggregate_return (@var{number})
6374 @cindex @code{callee_pop_aggregate_return} function attribute, x86
6376 On x86-32 targets, you can use this attribute to control how
6377 aggregates are returned in memory. If the caller is responsible for
6378 popping the hidden pointer together with the rest of the arguments, specify
6379 @var{number} equal to zero. If callee is responsible for popping the
6380 hidden pointer, specify @var{number} equal to one.
6382 The default x86-32 ABI assumes that the callee pops the
6383 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
6384 the compiler assumes that the
6385 caller pops the stack for hidden pointer.
6387 @item ms_hook_prologue
6388 @cindex @code{ms_hook_prologue} function attribute, x86
6390 On 32-bit and 64-bit x86 targets, you can use
6391 this function attribute to make GCC generate the ``hot-patching'' function
6392 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
6396 @cindex @code{naked} function attribute, x86
6397 This attribute allows the compiler to construct the
6398 requisite function declaration, while allowing the body of the
6399 function to be assembly code. The specified function will not have
6400 prologue/epilogue sequences generated by the compiler. Only basic
6401 @code{asm} statements can safely be included in naked functions
6402 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6403 basic @code{asm} and C code may appear to work, they cannot be
6404 depended upon to work reliably and are not supported.
6406 @item regparm (@var{number})
6407 @cindex @code{regparm} function attribute, x86
6408 @cindex functions that are passed arguments in registers on x86-32
6409 On x86-32 targets, the @code{regparm} attribute causes the compiler to
6410 pass arguments number one to @var{number} if they are of integral type
6411 in registers EAX, EDX, and ECX instead of on the stack. Functions that
6412 take a variable number of arguments continue to be passed all of their
6413 arguments on the stack.
6415 Beware that on some ELF systems this attribute is unsuitable for
6416 global functions in shared libraries with lazy binding (which is the
6417 default). Lazy binding sends the first call via resolving code in
6418 the loader, which might assume EAX, EDX and ECX can be clobbered, as
6419 per the standard calling conventions. Solaris 8 is affected by this.
6420 Systems with the GNU C Library version 2.1 or higher
6421 and FreeBSD are believed to be
6422 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
6423 disabled with the linker or the loader if desired, to avoid the
6427 @cindex @code{sseregparm} function attribute, x86
6428 On x86-32 targets with SSE support, the @code{sseregparm} attribute
6429 causes the compiler to pass up to 3 floating-point arguments in
6430 SSE registers instead of on the stack. Functions that take a
6431 variable number of arguments continue to pass all of their
6432 floating-point arguments on the stack.
6434 @item force_align_arg_pointer
6435 @cindex @code{force_align_arg_pointer} function attribute, x86
6436 On x86 targets, the @code{force_align_arg_pointer} attribute may be
6437 applied to individual function definitions, generating an alternate
6438 prologue and epilogue that realigns the run-time stack if necessary.
6439 This supports mixing legacy codes that run with a 4-byte aligned stack
6440 with modern codes that keep a 16-byte stack for SSE compatibility.
6443 @cindex @code{stdcall} function attribute, x86-32
6444 @cindex functions that pop the argument stack on x86-32
6445 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
6446 assume that the called function pops off the stack space used to
6447 pass arguments, unless it takes a variable number of arguments.
6449 @item no_caller_saved_registers
6450 @cindex @code{no_caller_saved_registers} function attribute, x86
6451 Use this attribute to indicate that the specified function has no
6452 caller-saved registers. That is, all registers are callee-saved. For
6453 example, this attribute can be used for a function called from an
6454 interrupt handler. The compiler generates proper function entry and
6455 exit sequences to save and restore any modified registers, except for
6456 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
6457 states, the GCC option @option{-mgeneral-regs-only} should be used to
6458 compile functions with @code{no_caller_saved_registers} attribute.
6461 @cindex @code{interrupt} function attribute, x86
6462 Use this attribute to indicate that the specified function is an
6463 interrupt handler or an exception handler (depending on parameters passed
6464 to the function, explained further). The compiler generates function
6465 entry and exit sequences suitable for use in an interrupt handler when
6466 this attribute is present. The @code{IRET} instruction, instead of the
6467 @code{RET} instruction, is used to return from interrupt handlers. All
6468 registers, except for the EFLAGS register which is restored by the
6469 @code{IRET} instruction, are preserved by the compiler. Since GCC
6470 doesn't preserve SSE, MMX nor x87 states, the GCC option
6471 @option{-mgeneral-regs-only} should be used to compile interrupt and
6474 Any interruptible-without-stack-switch code must be compiled with
6475 @option{-mno-red-zone} since interrupt handlers can and will, because
6476 of the hardware design, touch the red zone.
6478 An interrupt handler must be declared with a mandatory pointer
6482 struct interrupt_frame;
6484 __attribute__ ((interrupt))
6486 f (struct interrupt_frame *frame)
6492 and you must define @code{struct interrupt_frame} as described in the
6495 Exception handlers differ from interrupt handlers because the system
6496 pushes an error code on the stack. An exception handler declaration is
6497 similar to that for an interrupt handler, but with a different mandatory
6498 function signature. The compiler arranges to pop the error code off the
6499 stack before the @code{IRET} instruction.
6503 typedef unsigned long long int uword_t;
6505 typedef unsigned int uword_t;
6508 struct interrupt_frame;
6510 __attribute__ ((interrupt))
6512 f (struct interrupt_frame *frame, uword_t error_code)
6518 Exception handlers should only be used for exceptions that push an error
6519 code; you should use an interrupt handler in other cases. The system
6520 will crash if the wrong kind of handler is used.
6522 @item target (@var{options})
6523 @cindex @code{target} function attribute
6524 As discussed in @ref{Common Function Attributes}, this attribute
6525 allows specification of target-specific compilation options.
6527 On the x86, the following options are allowed:
6531 @cindex @code{target("3dnow")} function attribute, x86
6532 Enable/disable the generation of the 3DNow!@: instructions.
6536 @cindex @code{target("3dnowa")} function attribute, x86
6537 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6541 @cindex @code{target("abm")} function attribute, x86
6542 Enable/disable the generation of the advanced bit instructions.
6546 @cindex @code{target("adx")} function attribute, x86
6547 Enable/disable the generation of the ADX instructions.
6551 @cindex @code{target("aes")} function attribute, x86
6552 Enable/disable the generation of the AES instructions.
6556 @cindex @code{target("avx")} function attribute, x86
6557 Enable/disable the generation of the AVX instructions.
6561 @cindex @code{target("avx2")} function attribute, x86
6562 Enable/disable the generation of the AVX2 instructions.
6565 @itemx no-avx5124fmaps
6566 @cindex @code{target("avx5124fmaps")} function attribute, x86
6567 Enable/disable the generation of the AVX5124FMAPS instructions.
6570 @itemx no-avx5124vnniw
6571 @cindex @code{target("avx5124vnniw")} function attribute, x86
6572 Enable/disable the generation of the AVX5124VNNIW instructions.
6575 @itemx no-avx512bitalg
6576 @cindex @code{target("avx512bitalg")} function attribute, x86
6577 Enable/disable the generation of the AVX512BITALG instructions.
6581 @cindex @code{target("avx512bw")} function attribute, x86
6582 Enable/disable the generation of the AVX512BW instructions.
6586 @cindex @code{target("avx512cd")} function attribute, x86
6587 Enable/disable the generation of the AVX512CD instructions.
6591 @cindex @code{target("avx512dq")} function attribute, x86
6592 Enable/disable the generation of the AVX512DQ instructions.
6596 @cindex @code{target("avx512er")} function attribute, x86
6597 Enable/disable the generation of the AVX512ER instructions.
6601 @cindex @code{target("avx512f")} function attribute, x86
6602 Enable/disable the generation of the AVX512F instructions.
6605 @itemx no-avx512ifma
6606 @cindex @code{target("avx512ifma")} function attribute, x86
6607 Enable/disable the generation of the AVX512IFMA instructions.
6611 @cindex @code{target("avx512pf")} function attribute, x86
6612 Enable/disable the generation of the AVX512PF instructions.
6615 @itemx no-avx512vbmi
6616 @cindex @code{target("avx512vbmi")} function attribute, x86
6617 Enable/disable the generation of the AVX512VBMI instructions.
6620 @itemx no-avx512vbmi2
6621 @cindex @code{target("avx512vbmi2")} function attribute, x86
6622 Enable/disable the generation of the AVX512VBMI2 instructions.
6626 @cindex @code{target("avx512vl")} function attribute, x86
6627 Enable/disable the generation of the AVX512VL instructions.
6630 @itemx no-avx512vnni
6631 @cindex @code{target("avx512vnni")} function attribute, x86
6632 Enable/disable the generation of the AVX512VNNI instructions.
6634 @item avx512vpopcntdq
6635 @itemx no-avx512vpopcntdq
6636 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6637 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6641 @cindex @code{target("bmi")} function attribute, x86
6642 Enable/disable the generation of the BMI instructions.
6646 @cindex @code{target("bmi2")} function attribute, x86
6647 Enable/disable the generation of the BMI2 instructions.
6651 @cindex @code{target("cldemote")} function attribute, x86
6652 Enable/disable the generation of the CLDEMOTE instructions.
6655 @itemx no-clflushopt
6656 @cindex @code{target("clflushopt")} function attribute, x86
6657 Enable/disable the generation of the CLFLUSHOPT instructions.
6661 @cindex @code{target("clwb")} function attribute, x86
6662 Enable/disable the generation of the CLWB instructions.
6666 @cindex @code{target("clzero")} function attribute, x86
6667 Enable/disable the generation of the CLZERO instructions.
6671 @cindex @code{target("crc32")} function attribute, x86
6672 Enable/disable the generation of the CRC32 instructions.
6676 @cindex @code{target("cx16")} function attribute, x86
6677 Enable/disable the generation of the CMPXCHG16B instructions.
6680 @cindex @code{target("default")} function attribute, x86
6681 @xref{Function Multiversioning}, where it is used to specify the
6682 default function version.
6686 @cindex @code{target("f16c")} function attribute, x86
6687 Enable/disable the generation of the F16C instructions.
6691 @cindex @code{target("fma")} function attribute, x86
6692 Enable/disable the generation of the FMA instructions.
6696 @cindex @code{target("fma4")} function attribute, x86
6697 Enable/disable the generation of the FMA4 instructions.
6701 @cindex @code{target("fsgsbase")} function attribute, x86
6702 Enable/disable the generation of the FSGSBASE instructions.
6706 @cindex @code{target("fxsr")} function attribute, x86
6707 Enable/disable the generation of the FXSR instructions.
6711 @cindex @code{target("gfni")} function attribute, x86
6712 Enable/disable the generation of the GFNI instructions.
6716 @cindex @code{target("hle")} function attribute, x86
6717 Enable/disable the generation of the HLE instruction prefixes.
6721 @cindex @code{target("lwp")} function attribute, x86
6722 Enable/disable the generation of the LWP instructions.
6726 @cindex @code{target("lzcnt")} function attribute, x86
6727 Enable/disable the generation of the LZCNT instructions.
6731 @cindex @code{target("mmx")} function attribute, x86
6732 Enable/disable the generation of the MMX instructions.
6736 @cindex @code{target("movbe")} function attribute, x86
6737 Enable/disable the generation of the MOVBE instructions.
6741 @cindex @code{target("movdir64b")} function attribute, x86
6742 Enable/disable the generation of the MOVDIR64B instructions.
6746 @cindex @code{target("movdiri")} function attribute, x86
6747 Enable/disable the generation of the MOVDIRI instructions.
6751 @cindex @code{target("mwait")} function attribute, x86
6752 Enable/disable the generation of the MWAIT and MONITOR instructions.
6756 @cindex @code{target("mwaitx")} function attribute, x86
6757 Enable/disable the generation of the MWAITX instructions.
6761 @cindex @code{target("pclmul")} function attribute, x86
6762 Enable/disable the generation of the PCLMUL instructions.
6766 @cindex @code{target("pconfig")} function attribute, x86
6767 Enable/disable the generation of the PCONFIG instructions.
6771 @cindex @code{target("pku")} function attribute, x86
6772 Enable/disable the generation of the PKU instructions.
6776 @cindex @code{target("popcnt")} function attribute, x86
6777 Enable/disable the generation of the POPCNT instruction.
6780 @itemx no-prefetchwt1
6781 @cindex @code{target("prefetchwt1")} function attribute, x86
6782 Enable/disable the generation of the PREFETCHWT1 instructions.
6786 @cindex @code{target("prfchw")} function attribute, x86
6787 Enable/disable the generation of the PREFETCHW instruction.
6791 @cindex @code{target("ptwrite")} function attribute, x86
6792 Enable/disable the generation of the PTWRITE instructions.
6796 @cindex @code{target("rdpid")} function attribute, x86
6797 Enable/disable the generation of the RDPID instructions.
6801 @cindex @code{target("rdrnd")} function attribute, x86
6802 Enable/disable the generation of the RDRND instructions.
6806 @cindex @code{target("rdseed")} function attribute, x86
6807 Enable/disable the generation of the RDSEED instructions.
6811 @cindex @code{target("rtm")} function attribute, x86
6812 Enable/disable the generation of the RTM instructions.
6816 @cindex @code{target("sahf")} function attribute, x86
6817 Enable/disable the generation of the SAHF instructions.
6821 @cindex @code{target("sgx")} function attribute, x86
6822 Enable/disable the generation of the SGX instructions.
6826 @cindex @code{target("sha")} function attribute, x86
6827 Enable/disable the generation of the SHA instructions.
6831 @cindex @code{target("shstk")} function attribute, x86
6832 Enable/disable the shadow stack built-in functions from CET.
6836 @cindex @code{target("sse")} function attribute, x86
6837 Enable/disable the generation of the SSE instructions.
6841 @cindex @code{target("sse2")} function attribute, x86
6842 Enable/disable the generation of the SSE2 instructions.
6846 @cindex @code{target("sse3")} function attribute, x86
6847 Enable/disable the generation of the SSE3 instructions.
6851 @cindex @code{target("sse4")} function attribute, x86
6852 Enable/disable the generation of the SSE4 instructions (both SSE4.1
6857 @cindex @code{target("sse4.1")} function attribute, x86
6858 Enable/disable the generation of the SSE4.1 instructions.
6862 @cindex @code{target("sse4.2")} function attribute, x86
6863 Enable/disable the generation of the SSE4.2 instructions.
6867 @cindex @code{target("sse4a")} function attribute, x86
6868 Enable/disable the generation of the SSE4A instructions.
6872 @cindex @code{target("ssse3")} function attribute, x86
6873 Enable/disable the generation of the SSSE3 instructions.
6877 @cindex @code{target("tbm")} function attribute, x86
6878 Enable/disable the generation of the TBM instructions.
6882 @cindex @code{target("vaes")} function attribute, x86
6883 Enable/disable the generation of the VAES instructions.
6886 @itemx no-vpclmulqdq
6887 @cindex @code{target("vpclmulqdq")} function attribute, x86
6888 Enable/disable the generation of the VPCLMULQDQ instructions.
6892 @cindex @code{target("waitpkg")} function attribute, x86
6893 Enable/disable the generation of the WAITPKG instructions.
6897 @cindex @code{target("wbnoinvd")} function attribute, x86
6898 Enable/disable the generation of the WBNOINVD instructions.
6902 @cindex @code{target("xop")} function attribute, x86
6903 Enable/disable the generation of the XOP instructions.
6907 @cindex @code{target("xsave")} function attribute, x86
6908 Enable/disable the generation of the XSAVE instructions.
6912 @cindex @code{target("xsavec")} function attribute, x86
6913 Enable/disable the generation of the XSAVEC instructions.
6917 @cindex @code{target("xsaveopt")} function attribute, x86
6918 Enable/disable the generation of the XSAVEOPT instructions.
6922 @cindex @code{target("xsaves")} function attribute, x86
6923 Enable/disable the generation of the XSAVES instructions.
6927 @cindex @code{target("amx-tile")} function attribute, x86
6928 Enable/disable the generation of the AMX-TILE instructions.
6932 @cindex @code{target("amx-int8")} function attribute, x86
6933 Enable/disable the generation of the AMX-INT8 instructions.
6937 @cindex @code{target("amx-bf16")} function attribute, x86
6938 Enable/disable the generation of the AMX-BF16 instructions.
6942 @cindex @code{target("uintr")} function attribute, x86
6943 Enable/disable the generation of the UINTR instructions.
6947 @cindex @code{target("hreset")} function attribute, x86
6948 Enable/disable the generation of the HRESET instruction.
6952 @cindex @code{target("kl")} function attribute, x86
6953 Enable/disable the generation of the KEYLOCKER instructions.
6957 @cindex @code{target("widekl")} function attribute, x86
6958 Enable/disable the generation of the WIDEKL instructions.
6962 @cindex @code{target("avxvnni")} function attribute, x86
6963 Enable/disable the generation of the AVXVNNI instructions.
6967 @cindex @code{target("cld")} function attribute, x86
6968 Enable/disable the generation of the CLD before string moves.
6970 @item fancy-math-387
6971 @itemx no-fancy-math-387
6972 @cindex @code{target("fancy-math-387")} function attribute, x86
6973 Enable/disable the generation of the @code{sin}, @code{cos}, and
6974 @code{sqrt} instructions on the 387 floating-point unit.
6978 @cindex @code{target("ieee-fp")} function attribute, x86
6979 Enable/disable the generation of floating point that depends on IEEE arithmetic.
6981 @item inline-all-stringops
6982 @itemx no-inline-all-stringops
6983 @cindex @code{target("inline-all-stringops")} function attribute, x86
6984 Enable/disable inlining of string operations.
6986 @item inline-stringops-dynamically
6987 @itemx no-inline-stringops-dynamically
6988 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
6989 Enable/disable the generation of the inline code to do small string
6990 operations and calling the library routines for large operations.
6992 @item align-stringops
6993 @itemx no-align-stringops
6994 @cindex @code{target("align-stringops")} function attribute, x86
6995 Do/do not align destination of inlined string operations.
6999 @cindex @code{target("recip")} function attribute, x86
7000 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
7001 instructions followed an additional Newton-Raphson step instead of
7002 doing a floating-point division.
7004 @item general-regs-only
7005 @cindex @code{target("general-regs-only")} function attribute, x86
7006 Generate code which uses only the general registers.
7008 @item arch=@var{ARCH}
7009 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
7010 Specify the architecture to generate code for in compiling the function.
7012 @item tune=@var{TUNE}
7013 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
7014 Specify the architecture to tune for in compiling the function.
7016 @item fpmath=@var{FPMATH}
7017 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
7018 Specify which floating-point unit to use. You must specify the
7019 @code{target("fpmath=sse,387")} option as
7020 @code{target("fpmath=sse+387")} because the comma would separate
7023 @item prefer-vector-width=@var{OPT}
7024 @cindex @code{prefer-vector-width} function attribute, x86
7025 On x86 targets, the @code{prefer-vector-width} attribute informs the
7026 compiler to use @var{OPT}-bit vector width in instructions
7027 instead of the default on the selected platform.
7029 Valid @var{OPT} values are:
7033 No extra limitations applied to GCC other than defined by the selected platform.
7036 Prefer 128-bit vector width for instructions.
7039 Prefer 256-bit vector width for instructions.
7042 Prefer 512-bit vector width for instructions.
7045 On the x86, the inliner does not inline a
7046 function that has different target options than the caller, unless the
7047 callee has a subset of the target options of the caller. For example
7048 a function declared with @code{target("sse3")} can inline a function
7049 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
7052 @item indirect_branch("@var{choice}")
7053 @cindex @code{indirect_branch} function attribute, x86
7054 On x86 targets, the @code{indirect_branch} attribute causes the compiler
7055 to convert indirect call and jump with @var{choice}. @samp{keep}
7056 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
7057 call and jump to call and return thunk. @samp{thunk-inline} converts
7058 indirect call and jump to inlined call and return thunk.
7059 @samp{thunk-extern} converts indirect call and jump to external call
7060 and return thunk provided in a separate object file.
7062 @item function_return("@var{choice}")
7063 @cindex @code{function_return} function attribute, x86
7064 On x86 targets, the @code{function_return} attribute causes the compiler
7065 to convert function return with @var{choice}. @samp{keep} keeps function
7066 return unmodified. @samp{thunk} converts function return to call and
7067 return thunk. @samp{thunk-inline} converts function return to inlined
7068 call and return thunk. @samp{thunk-extern} converts function return to
7069 external call and return thunk provided in a separate object file.
7072 @cindex @code{nocf_check} function attribute
7073 The @code{nocf_check} attribute on a function is used to inform the
7074 compiler that the function's prologue should not be instrumented when
7075 compiled with the @option{-fcf-protection=branch} option. The
7076 compiler assumes that the function's address is a valid target for a
7077 control-flow transfer.
7079 The @code{nocf_check} attribute on a type of pointer to function is
7080 used to inform the compiler that a call through the pointer should
7081 not be instrumented when compiled with the
7082 @option{-fcf-protection=branch} option. The compiler assumes
7083 that the function's address from the pointer is a valid target for
7084 a control-flow transfer. A direct function call through a function
7085 name is assumed to be a safe call thus direct calls are not
7086 instrumented by the compiler.
7088 The @code{nocf_check} attribute is applied to an object's type.
7089 In case of assignment of a function address or a function pointer to
7090 another pointer, the attribute is not carried over from the right-hand
7091 object's type; the type of left-hand object stays unchanged. The
7092 compiler checks for @code{nocf_check} attribute mismatch and reports
7093 a warning in case of mismatch.
7097 int foo (void) __attribute__(nocf_check);
7098 void (*foo1)(void) __attribute__(nocf_check);
7101 /* foo's address is assumed to be valid. */
7105 /* This call site is not checked for control-flow
7109 /* A warning is issued about attribute mismatch. */
7112 /* This call site is still not checked. */
7115 /* This call site is checked. */
7118 /* A warning is issued about attribute mismatch. */
7121 /* This call site is still checked. */
7129 @cindex @code{cf_check} function attribute, x86
7131 The @code{cf_check} attribute on a function is used to inform the
7132 compiler that ENDBR instruction should be placed at the function
7133 entry when @option{-fcf-protection=branch} is enabled.
7135 @item indirect_return
7136 @cindex @code{indirect_return} function attribute, x86
7138 The @code{indirect_return} attribute can be applied to a function,
7139 as well as variable or type of function pointer to inform the
7140 compiler that the function may return via indirect branch.
7142 @item fentry_name("@var{name}")
7143 @cindex @code{fentry_name} function attribute, x86
7144 On x86 targets, the @code{fentry_name} attribute sets the function to
7145 call on function entry when function instrumentation is enabled
7146 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
7147 nop sequence is generated.
7149 @item fentry_section("@var{name}")
7150 @cindex @code{fentry_section} function attribute, x86
7151 On x86 targets, the @code{fentry_section} attribute sets the name
7152 of the section to record function entry instrumentation calls in when
7153 enabled with @option{-pg -mrecord-mcount}
7157 @node Xstormy16 Function Attributes
7158 @subsection Xstormy16 Function Attributes
7160 These function attributes are supported by the Xstormy16 back end:
7164 @cindex @code{interrupt} function attribute, Xstormy16
7165 Use this attribute to indicate
7166 that the specified function is an interrupt handler. The compiler generates
7167 function entry and exit sequences suitable for use in an interrupt handler
7168 when this attribute is present.
7171 @node Variable Attributes
7172 @section Specifying Attributes of Variables
7173 @cindex attribute of variables
7174 @cindex variable attributes
7176 The keyword @code{__attribute__} allows you to specify special properties
7177 of variables, function parameters, or structure, union, and, in C++, class
7178 members. This @code{__attribute__} keyword is followed by an attribute
7179 specification enclosed in double parentheses. Some attributes are currently
7180 defined generically for variables. Other attributes are defined for
7181 variables on particular target systems. Other attributes are available
7182 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
7183 enumerators (@pxref{Enumerator Attributes}), statements
7184 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
7185 Other front ends might define more attributes
7186 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
7188 @xref{Attribute Syntax}, for details of the exact syntax for using
7192 * Common Variable Attributes::
7193 * ARC Variable Attributes::
7194 * AVR Variable Attributes::
7195 * Blackfin Variable Attributes::
7196 * H8/300 Variable Attributes::
7197 * IA-64 Variable Attributes::
7198 * M32R/D Variable Attributes::
7199 * MeP Variable Attributes::
7200 * Microsoft Windows Variable Attributes::
7201 * MSP430 Variable Attributes::
7202 * Nvidia PTX Variable Attributes::
7203 * PowerPC Variable Attributes::
7204 * RL78 Variable Attributes::
7205 * V850 Variable Attributes::
7206 * x86 Variable Attributes::
7207 * Xstormy16 Variable Attributes::
7210 @node Common Variable Attributes
7211 @subsection Common Variable Attributes
7213 The following attributes are supported on most targets.
7217 @item alias ("@var{target}")
7218 @cindex @code{alias} variable attribute
7219 The @code{alias} variable attribute causes the declaration to be emitted
7220 as an alias for another symbol known as an @dfn{alias target}. Except
7221 for top-level qualifiers the alias target must have the same type as
7222 the alias. For instance, the following
7226 extern int __attribute__ ((alias ("var_target"))) var_alias;
7230 defines @code{var_alias} to be an alias for the @code{var_target} variable.
7232 It is an error if the alias target is not defined in the same translation
7235 Note that in the absence of the attribute GCC assumes that distinct
7236 declarations with external linkage denote distinct objects. Using both
7237 the alias and the alias target to access the same object is undefined
7238 in a translation unit without a declaration of the alias with the attribute.
7240 This attribute requires assembler and object file support, and may not be
7241 available on all targets.
7243 @cindex @code{aligned} variable attribute
7245 @itemx aligned (@var{alignment})
7246 The @code{aligned} attribute specifies a minimum alignment for the variable
7247 or structure field, measured in bytes. When specified, @var{alignment} must
7248 be an integer constant power of 2. Specifying no @var{alignment} argument
7249 implies the maximum alignment for the target, which is often, but by no
7250 means always, 8 or 16 bytes.
7252 For example, the declaration:
7255 int x __attribute__ ((aligned (16))) = 0;
7259 causes the compiler to allocate the global variable @code{x} on a
7260 16-byte boundary. On a 68040, this could be used in conjunction with
7261 an @code{asm} expression to access the @code{move16} instruction which
7262 requires 16-byte aligned operands.
7264 You can also specify the alignment of structure fields. For example, to
7265 create a double-word aligned @code{int} pair, you could write:
7268 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
7272 This is an alternative to creating a union with a @code{double} member,
7273 which forces the union to be double-word aligned.
7275 As in the preceding examples, you can explicitly specify the alignment
7276 (in bytes) that you wish the compiler to use for a given variable or
7277 structure field. Alternatively, you can leave out the alignment factor
7278 and just ask the compiler to align a variable or field to the
7279 default alignment for the target architecture you are compiling for.
7280 The default alignment is sufficient for all scalar types, but may not be
7281 enough for all vector types on a target that supports vector operations.
7282 The default alignment is fixed for a particular target ABI.
7284 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
7285 which is the largest alignment ever used for any data type on the
7286 target machine you are compiling for. For example, you could write:
7289 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
7292 The compiler automatically sets the alignment for the declared
7293 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
7294 often make copy operations more efficient, because the compiler can
7295 use whatever instructions copy the biggest chunks of memory when
7296 performing copies to or from the variables or fields that you have
7297 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
7298 may change depending on command-line options.
7300 When used on a struct, or struct member, the @code{aligned} attribute can
7301 only increase the alignment; in order to decrease it, the @code{packed}
7302 attribute must be specified as well. When used as part of a typedef, the
7303 @code{aligned} attribute can both increase and decrease alignment, and
7304 specifying the @code{packed} attribute generates a warning.
7306 Note that the effectiveness of @code{aligned} attributes for static
7307 variables may be limited by inherent limitations in the system linker
7308 and/or object file format. On some systems, the linker is
7309 only able to arrange for variables to be aligned up to a certain maximum
7310 alignment. (For some linkers, the maximum supported alignment may
7311 be very very small.) If your linker is only able to align variables
7312 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
7313 in an @code{__attribute__} still only provides you with 8-byte
7314 alignment. See your linker documentation for further information.
7316 Stack variables are not affected by linker restrictions; GCC can properly
7317 align them on any target.
7319 The @code{aligned} attribute can also be used for functions
7320 (@pxref{Common Function Attributes}.)
7322 @cindex @code{warn_if_not_aligned} variable attribute
7323 @item warn_if_not_aligned (@var{alignment})
7324 This attribute specifies a threshold for the structure field, measured
7325 in bytes. If the structure field is aligned below the threshold, a
7326 warning will be issued. For example, the declaration:
7333 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
7338 causes the compiler to issue an warning on @code{struct foo}, like
7339 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
7340 The compiler also issues a warning, like @samp{warning: 'x' offset
7341 8 in 'struct foo' isn't aligned to 16}, when the structure field has
7342 the misaligned offset:
7345 struct __attribute__ ((aligned (16))) foo
7349 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
7353 This warning can be disabled by @option{-Wno-if-not-aligned}.
7354 The @code{warn_if_not_aligned} attribute can also be used for types
7355 (@pxref{Common Type Attributes}.)
7357 @item alloc_size (@var{position})
7358 @itemx alloc_size (@var{position-1}, @var{position-2})
7359 @cindex @code{alloc_size} variable attribute
7360 The @code{alloc_size} variable attribute may be applied to the declaration
7361 of a pointer to a function that returns a pointer and takes at least one
7362 argument of an integer type. It indicates that the returned pointer points
7363 to an object whose size is given by the function argument at @var{position},
7364 or by the product of the arguments at @var{position-1} and @var{position-2}.
7365 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
7366 sizes are diagnosed when detected. GCC uses this information to improve
7367 the results of @code{__builtin_object_size}.
7369 For instance, the following declarations
7372 typedef __attribute__ ((alloc_size (1, 2))) void*
7373 (*calloc_ptr) (size_t, size_t);
7374 typedef __attribute__ ((alloc_size (1))) void*
7375 (*malloc_ptr) (size_t);
7379 specify that @code{calloc_ptr} is a pointer of a function that, like
7380 the standard C function @code{calloc}, returns an object whose size
7381 is given by the product of arguments 1 and 2, and similarly, that
7382 @code{malloc_ptr}, like the standard C function @code{malloc},
7383 returns an object whose size is given by argument 1 to the function.
7385 @item cleanup (@var{cleanup_function})
7386 @cindex @code{cleanup} variable attribute
7387 The @code{cleanup} attribute runs a function when the variable goes
7388 out of scope. This attribute can only be applied to auto function
7389 scope variables; it may not be applied to parameters or variables
7390 with static storage duration. The function must take one parameter,
7391 a pointer to a type compatible with the variable. The return value
7392 of the function (if any) is ignored.
7394 If @option{-fexceptions} is enabled, then @var{cleanup_function}
7395 is run during the stack unwinding that happens during the
7396 processing of the exception. Note that the @code{cleanup} attribute
7397 does not allow the exception to be caught, only to perform an action.
7398 It is undefined what happens if @var{cleanup_function} does not
7403 @cindex @code{common} variable attribute
7404 @cindex @code{nocommon} variable attribute
7407 The @code{common} attribute requests GCC to place a variable in
7408 ``common'' storage. The @code{nocommon} attribute requests the
7409 opposite---to allocate space for it directly.
7411 These attributes override the default chosen by the
7412 @option{-fno-common} and @option{-fcommon} flags respectively.
7415 @itemx copy (@var{variable})
7416 @cindex @code{copy} variable attribute
7417 The @code{copy} attribute applies the set of attributes with which
7418 @var{variable} has been declared to the declaration of the variable
7419 to which the attribute is applied. The attribute is designed for
7420 libraries that define aliases that are expected to specify the same
7421 set of attributes as the aliased symbols. The @code{copy} attribute
7422 can be used with variables, functions or types. However, the kind
7423 of symbol to which the attribute is applied (either varible or
7424 function) must match the kind of symbol to which the argument refers.
7425 The @code{copy} attribute copies only syntactic and semantic attributes
7426 but not attributes that affect a symbol's linkage or visibility such as
7427 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7428 attribute is also not copied. @xref{Common Function Attributes}.
7429 @xref{Common Type Attributes}.
7432 @itemx deprecated (@var{msg})
7433 @cindex @code{deprecated} variable attribute
7434 The @code{deprecated} attribute results in a warning if the variable
7435 is used anywhere in the source file. This is useful when identifying
7436 variables that are expected to be removed in a future version of a
7437 program. The warning also includes the location of the declaration
7438 of the deprecated variable, to enable users to easily find further
7439 information about why the variable is deprecated, or what they should
7440 do instead. Note that the warning only occurs for uses:
7443 extern int old_var __attribute__ ((deprecated));
7445 int new_fn () @{ return old_var; @}
7449 results in a warning on line 3 but not line 2. The optional @var{msg}
7450 argument, which must be a string, is printed in the warning if
7453 The @code{deprecated} attribute can also be used for functions and
7454 types (@pxref{Common Function Attributes},
7455 @pxref{Common Type Attributes}).
7457 The message attached to the attribute is affected by the setting of
7458 the @option{-fmessage-length} option.
7461 @itemx unavailable (@var{msg})
7462 @cindex @code{unavailable} variable attribute
7463 The @code{unavailable} attribute indicates that the variable so marked
7464 is not available, if it is used anywhere in the source file. It behaves
7465 in the same manner as the @code{deprecated} attribute except that the
7466 compiler will emit an error rather than a warning.
7468 It is expected that items marked as @code{deprecated} will eventually be
7469 withdrawn from interfaces, and then become unavailable. This attribute
7470 allows for marking them appropriately.
7472 The @code{unavailable} attribute can also be used for functions and
7473 types (@pxref{Common Function Attributes},
7474 @pxref{Common Type Attributes}).
7476 @item mode (@var{mode})
7477 @cindex @code{mode} variable attribute
7478 This attribute specifies the data type for the declaration---whichever
7479 type corresponds to the mode @var{mode}. This in effect lets you
7480 request an integer or floating-point type according to its width.
7482 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
7483 for a list of the possible keywords for @var{mode}.
7484 You may also specify a mode of @code{byte} or @code{__byte__} to
7485 indicate the mode corresponding to a one-byte integer, @code{word} or
7486 @code{__word__} for the mode of a one-word integer, and @code{pointer}
7487 or @code{__pointer__} for the mode used to represent pointers.
7490 @cindex @code{nonstring} variable attribute
7491 The @code{nonstring} variable attribute specifies that an object or member
7492 declaration with type array of @code{char}, @code{signed char}, or
7493 @code{unsigned char}, or pointer to such a type is intended to store
7494 character arrays that do not necessarily contain a terminating @code{NUL}.
7495 This is useful in detecting uses of such arrays or pointers with functions
7496 that expect @code{NUL}-terminated strings, and to avoid warnings when such
7497 an array or pointer is used as an argument to a bounded string manipulation
7498 function such as @code{strncpy}. For example, without the attribute, GCC
7499 will issue a warning for the @code{strncpy} call below because it may
7500 truncate the copy without appending the terminating @code{NUL} character.
7501 Using the attribute makes it possible to suppress the warning. However,
7502 when the array is declared with the attribute the call to @code{strlen} is
7503 diagnosed because when the array doesn't contain a @code{NUL}-terminated
7504 string the call is undefined. To copy, compare, of search non-string
7505 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
7506 and other functions that operate on arrays of bytes. In addition,
7507 calling @code{strnlen} and @code{strndup} with such arrays is safe
7508 provided a suitable bound is specified, and not diagnosed.
7513 char name [32] __attribute__ ((nonstring));
7516 int f (struct Data *pd, const char *s)
7518 strncpy (pd->name, s, sizeof pd->name);
7520 return strlen (pd->name); // unsafe, gets a warning
7525 @cindex @code{packed} variable attribute
7526 The @code{packed} attribute specifies that a structure member should have
7527 the smallest possible alignment---one bit for a bit-field and one byte
7528 otherwise, unless a larger value is specified with the @code{aligned}
7529 attribute. The attribute does not apply to non-member objects.
7531 For example in the structure below, the member array @code{x} is packed
7532 so that it immediately follows @code{a} with no intervening padding:
7538 int x[2] __attribute__ ((packed));
7542 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
7543 @code{packed} attribute on bit-fields of type @code{char}. This has
7544 been fixed in GCC 4.4 but the change can lead to differences in the
7545 structure layout. See the documentation of
7546 @option{-Wpacked-bitfield-compat} for more information.
7548 @item section ("@var{section-name}")
7549 @cindex @code{section} variable attribute
7550 Normally, the compiler places the objects it generates in sections like
7551 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
7552 or you need certain particular variables to appear in special sections,
7553 for example to map to special hardware. The @code{section}
7554 attribute specifies that a variable (or function) lives in a particular
7555 section. For example, this small program uses several specific section names:
7558 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
7559 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
7560 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
7561 int init_data __attribute__ ((section ("INITDATA")));
7565 /* @r{Initialize stack pointer} */
7566 init_sp (stack + sizeof (stack));
7568 /* @r{Initialize initialized data} */
7569 memcpy (&init_data, &data, &edata - &data);
7571 /* @r{Turn on the serial ports} */
7578 Use the @code{section} attribute with
7579 @emph{global} variables and not @emph{local} variables,
7580 as shown in the example.
7582 You may use the @code{section} attribute with initialized or
7583 uninitialized global variables but the linker requires
7584 each object be defined once, with the exception that uninitialized
7585 variables tentatively go in the @code{common} (or @code{bss}) section
7586 and can be multiply ``defined''. Using the @code{section} attribute
7587 changes what section the variable goes into and may cause the
7588 linker to issue an error if an uninitialized variable has multiple
7589 definitions. You can force a variable to be initialized with the
7590 @option{-fno-common} flag or the @code{nocommon} attribute.
7592 Some file formats do not support arbitrary sections so the @code{section}
7593 attribute is not available on all platforms.
7594 If you need to map the entire contents of a module to a particular
7595 section, consider using the facilities of the linker instead.
7597 @item tls_model ("@var{tls_model}")
7598 @cindex @code{tls_model} variable attribute
7599 The @code{tls_model} attribute sets thread-local storage model
7600 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
7601 overriding @option{-ftls-model=} command-line switch on a per-variable
7603 The @var{tls_model} argument should be one of @code{global-dynamic},
7604 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
7606 Not all targets support this attribute.
7609 @cindex @code{unused} variable attribute
7610 This attribute, attached to a variable or structure field, means that
7611 the variable or field is meant to be possibly unused. GCC does not
7612 produce a warning for this variable or field.
7615 @cindex @code{used} variable attribute
7616 This attribute, attached to a variable with static storage, means that
7617 the variable must be emitted even if it appears that the variable is not
7620 When applied to a static data member of a C++ class template, the
7621 attribute also means that the member is instantiated if the
7622 class itself is instantiated.
7625 @cindex @code{retain} variable attribute
7626 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
7627 will save the variable from linker garbage collection. To support
7628 this behavior, variables that have not been placed in specific sections
7629 (e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
7630 will be placed in new, unique sections.
7632 This additional functionality requires Binutils version 2.36 or later.
7635 @cindex @code{uninitialized} variable attribute
7636 This attribute, attached to a variable with automatic storage, means that
7637 the variable should not be automatically initialized by the compiler when
7638 the option @code{-ftrivial-auto-var-init} presents.
7640 With the option @code{-ftrivial-auto-var-init}, all the automatic variables
7641 that do not have explicit initializers will be initialized by the compiler.
7642 These additional compiler initializations might incur run-time overhead,
7643 sometimes dramatically. This attribute can be used to mark some variables
7644 to be excluded from such automatical initialization in order to reduce runtime
7647 This attribute has no effect when the option @code{-ftrivial-auto-var-init}
7650 @item vector_size (@var{bytes})
7651 @cindex @code{vector_size} variable attribute
7652 This attribute specifies the vector size for the type of the declared
7653 variable, measured in bytes. The type to which it applies is known as
7654 the @dfn{base type}. The @var{bytes} argument must be a positive
7655 power-of-two multiple of the base type size. For example, the declaration:
7658 int foo __attribute__ ((vector_size (16)));
7662 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
7663 divided into @code{int} sized units. Assuming a 32-bit @code{int},
7664 @code{foo}'s type is a vector of four units of four bytes each, and
7665 the corresponding mode of @code{foo} is @code{V4SI}.
7666 @xref{Vector Extensions}, for details of manipulating vector variables.
7668 This attribute is only applicable to integral and floating scalars,
7669 although arrays, pointers, and function return values are allowed in
7670 conjunction with this construct.
7672 Aggregates with this attribute are invalid, even if they are of the same
7673 size as a corresponding scalar. For example, the declaration:
7676 struct S @{ int a; @};
7677 struct S __attribute__ ((vector_size (16))) foo;
7681 is invalid even if the size of the structure is the same as the size of
7684 @item visibility ("@var{visibility_type}")
7685 @cindex @code{visibility} variable attribute
7686 This attribute affects the linkage of the declaration to which it is attached.
7687 The @code{visibility} attribute is described in
7688 @ref{Common Function Attributes}.
7691 @cindex @code{weak} variable attribute
7692 The @code{weak} attribute is described in
7693 @ref{Common Function Attributes}.
7696 @cindex @code{noinit} variable attribute
7697 Any data with the @code{noinit} attribute will not be initialized by
7698 the C runtime startup code, or the program loader. Not initializing
7699 data in this way can reduce program startup times.
7701 This attribute is specific to ELF targets and relies on the linker
7702 script to place sections with the @code{.noinit} prefix in the right
7706 @cindex @code{persistent} variable attribute
7707 Any data with the @code{persistent} attribute will not be initialized by
7708 the C runtime startup code, but will be initialized by the program
7709 loader. This enables the value of the variable to @samp{persist}
7710 between processor resets.
7712 This attribute is specific to ELF targets and relies on the linker
7713 script to place the sections with the @code{.persistent} prefix in the
7714 right location. Specifically, some type of non-volatile, writeable
7717 @item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
7718 @cindex @code{objc_nullability} variable attribute
7719 This attribute applies to pointer variables only. It allows marking the
7720 pointer with one of four possible values describing the conditions under
7721 which the pointer might have a @code{nil} value. In most cases, the
7722 attribute is intended to be an internal representation for property and
7723 method nullability (specified by language keywords); it is not recommended
7726 When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
7727 known about the conditions in which the pointer might be @code{nil}. Making
7728 this state specific serves to avoid false positives in diagnostics.
7730 When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
7731 no meaning if it is @code{nil} and thus the compiler is free to emit
7732 diagnostics if it can be determined that the value will be @code{nil}.
7734 When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
7735 be @code{nil} and carry meaning as such.
7737 When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
7738 the context of property attribute lists) this describes the case in which a
7739 property setter may take the value @code{nil} (which perhaps causes the
7740 property to be reset in some manner to a default) but for which the property
7741 getter will never validly return @code{nil}.
7745 @node ARC Variable Attributes
7746 @subsection ARC Variable Attributes
7750 @cindex @code{aux} variable attribute, ARC
7751 The @code{aux} attribute is used to directly access the ARC's
7752 auxiliary register space from C. The auxilirary register number is
7753 given via attribute argument.
7757 @node AVR Variable Attributes
7758 @subsection AVR Variable Attributes
7762 @cindex @code{progmem} variable attribute, AVR
7763 The @code{progmem} attribute is used on the AVR to place read-only
7764 data in the non-volatile program memory (flash). The @code{progmem}
7765 attribute accomplishes this by putting respective variables into a
7766 section whose name starts with @code{.progmem}.
7768 This attribute works similar to the @code{section} attribute
7769 but adds additional checking.
7772 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers:
7773 @code{progmem} affects the location
7774 of the data but not how this data is accessed.
7775 In order to read data located with the @code{progmem} attribute
7776 (inline) assembler must be used.
7778 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
7779 #include <avr/pgmspace.h>
7781 /* Locate var in flash memory */
7782 const int var[2] PROGMEM = @{ 1, 2 @};
7784 int read_var (int i)
7786 /* Access var[] by accessor macro from avr/pgmspace.h */
7787 return (int) pgm_read_word (& var[i]);
7791 AVR is a Harvard architecture processor and data and read-only data
7792 normally resides in the data memory (RAM).
7794 See also the @ref{AVR Named Address Spaces} section for
7795 an alternate way to locate and access data in flash memory.
7797 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range:
7798 On such devices, there is no need for attribute @code{progmem} or
7799 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
7800 Just use standard C / C++. The compiler will generate @code{LD*}
7801 instructions. As flash memory is visible in the RAM address range,
7802 and the default linker script does @emph{not} locate @code{.rodata} in
7803 RAM, no special features are needed in order not to waste RAM for
7804 read-only data or to read from flash. You might even get slightly better
7806 avoiding @code{progmem} and @code{__flash}. This applies to devices from
7807 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
7810 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40:
7811 The compiler adds @code{0x4000}
7812 to the addresses of objects and declarations in @code{progmem} and locates
7813 the objects in flash memory, namely in section @code{.progmem.data}.
7814 The offset is needed because the flash memory is visible in the RAM
7815 address space starting at address @code{0x4000}.
7817 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
7818 no special functions or macros are needed.
7821 /* var is located in flash memory */
7822 extern const int var[2] __attribute__((progmem));
7824 int read_var (int i)
7830 Please notice that on these devices, there is no need for @code{progmem}
7836 @itemx io (@var{addr})
7837 @cindex @code{io} variable attribute, AVR
7838 Variables with the @code{io} attribute are used to address
7839 memory-mapped peripherals in the io address range.
7840 If an address is specified, the variable
7841 is assigned that address, and the value is interpreted as an
7842 address in the data address space.
7846 volatile int porta __attribute__((io (0x22)));
7849 The address specified in the address in the data address range.
7851 Otherwise, the variable it is not assigned an address, but the
7852 compiler will still use in/out instructions where applicable,
7853 assuming some other module assigns an address in the io address range.
7857 extern volatile int porta __attribute__((io));
7861 @itemx io_low (@var{addr})
7862 @cindex @code{io_low} variable attribute, AVR
7863 This is like the @code{io} attribute, but additionally it informs the
7864 compiler that the object lies in the lower half of the I/O area,
7865 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
7869 @itemx address (@var{addr})
7870 @cindex @code{address} variable attribute, AVR
7871 Variables with the @code{address} attribute are used to address
7872 memory-mapped peripherals that may lie outside the io address range.
7875 volatile int porta __attribute__((address (0x600)));
7879 @cindex @code{absdata} variable attribute, AVR
7880 Variables in static storage and with the @code{absdata} attribute can
7881 be accessed by the @code{LDS} and @code{STS} instructions which take
7886 This attribute is only supported for the reduced AVR Tiny core
7890 You must make sure that respective data is located in the
7891 address range @code{0x40}@dots{}@code{0xbf} accessible by
7892 @code{LDS} and @code{STS}. One way to achieve this as an
7893 appropriate linker description file.
7896 If the location does not fit the address range of @code{LDS}
7897 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
7900 @code{module.c:(.text+0x1c): warning: internal error: out of range error}
7905 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
7909 @node Blackfin Variable Attributes
7910 @subsection Blackfin Variable Attributes
7912 Three attributes are currently defined for the Blackfin.
7918 @cindex @code{l1_data} variable attribute, Blackfin
7919 @cindex @code{l1_data_A} variable attribute, Blackfin
7920 @cindex @code{l1_data_B} variable attribute, Blackfin
7921 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
7922 Variables with @code{l1_data} attribute are put into the specific section
7923 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
7924 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
7925 attribute are put into the specific section named @code{.l1.data.B}.
7928 @cindex @code{l2} variable attribute, Blackfin
7929 Use this attribute on the Blackfin to place the variable into L2 SRAM.
7930 Variables with @code{l2} attribute are put into the specific section
7931 named @code{.l2.data}.
7934 @node H8/300 Variable Attributes
7935 @subsection H8/300 Variable Attributes
7937 These variable attributes are available for H8/300 targets:
7941 @cindex @code{eightbit_data} variable attribute, H8/300
7942 @cindex eight-bit data on the H8/300, H8/300H, and H8S
7943 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
7944 variable should be placed into the eight-bit data section.
7945 The compiler generates more efficient code for certain operations
7946 on data in the eight-bit data area. Note the eight-bit data area is limited to
7949 You must use GAS and GLD from GNU binutils version 2.7 or later for
7950 this attribute to work correctly.
7953 @cindex @code{tiny_data} variable attribute, H8/300
7954 @cindex tiny data section on the H8/300H and H8S
7955 Use this attribute on the H8/300H and H8S to indicate that the specified
7956 variable should be placed into the tiny data section.
7957 The compiler generates more efficient code for loads and stores
7958 on data in the tiny data section. Note the tiny data area is limited to
7959 slightly under 32KB of data.
7963 @node IA-64 Variable Attributes
7964 @subsection IA-64 Variable Attributes
7966 The IA-64 back end supports the following variable attribute:
7969 @item model (@var{model-name})
7970 @cindex @code{model} variable attribute, IA-64
7972 On IA-64, use this attribute to set the addressability of an object.
7973 At present, the only supported identifier for @var{model-name} is
7974 @code{small}, indicating addressability via ``small'' (22-bit)
7975 addresses (so that their addresses can be loaded with the @code{addl}
7976 instruction). Caveat: such addressing is by definition not position
7977 independent and hence this attribute must not be used for objects
7978 defined by shared libraries.
7982 @node M32R/D Variable Attributes
7983 @subsection M32R/D Variable Attributes
7985 One attribute is currently defined for the M32R/D@.
7988 @item model (@var{model-name})
7989 @cindex @code{model-name} variable attribute, M32R/D
7990 @cindex variable addressability on the M32R/D
7991 Use this attribute on the M32R/D to set the addressability of an object.
7992 The identifier @var{model-name} is one of @code{small}, @code{medium},
7993 or @code{large}, representing each of the code models.
7995 Small model objects live in the lower 16MB of memory (so that their
7996 addresses can be loaded with the @code{ld24} instruction).
7998 Medium and large model objects may live anywhere in the 32-bit address space
7999 (the compiler generates @code{seth/add3} instructions to load their
8003 @node MeP Variable Attributes
8004 @subsection MeP Variable Attributes
8006 The MeP target has a number of addressing modes and busses. The
8007 @code{near} space spans the standard memory space's first 16 megabytes
8008 (24 bits). The @code{far} space spans the entire 32-bit memory space.
8009 The @code{based} space is a 128-byte region in the memory space that
8010 is addressed relative to the @code{$tp} register. The @code{tiny}
8011 space is a 65536-byte region relative to the @code{$gp} register. In
8012 addition to these memory regions, the MeP target has a separate 16-bit
8013 control bus which is specified with @code{cb} attributes.
8018 @cindex @code{based} variable attribute, MeP
8019 Any variable with the @code{based} attribute is assigned to the
8020 @code{.based} section, and is accessed with relative to the
8021 @code{$tp} register.
8024 @cindex @code{tiny} variable attribute, MeP
8025 Likewise, the @code{tiny} attribute assigned variables to the
8026 @code{.tiny} section, relative to the @code{$gp} register.
8029 @cindex @code{near} variable attribute, MeP
8030 Variables with the @code{near} attribute are assumed to have addresses
8031 that fit in a 24-bit addressing mode. This is the default for large
8032 variables (@code{-mtiny=4} is the default) but this attribute can
8033 override @code{-mtiny=} for small variables, or override @code{-ml}.
8036 @cindex @code{far} variable attribute, MeP
8037 Variables with the @code{far} attribute are addressed using a full
8038 32-bit address. Since this covers the entire memory space, this
8039 allows modules to make no assumptions about where variables might be
8043 @cindex @code{io} variable attribute, MeP
8044 @itemx io (@var{addr})
8045 Variables with the @code{io} attribute are used to address
8046 memory-mapped peripherals. If an address is specified, the variable
8047 is assigned that address, else it is not assigned an address (it is
8048 assumed some other module assigns an address). Example:
8051 int timer_count __attribute__((io(0x123)));
8055 @itemx cb (@var{addr})
8056 @cindex @code{cb} variable attribute, MeP
8057 Variables with the @code{cb} attribute are used to access the control
8058 bus, using special instructions. @code{addr} indicates the control bus
8062 int cpu_clock __attribute__((cb(0x123)));
8067 @node Microsoft Windows Variable Attributes
8068 @subsection Microsoft Windows Variable Attributes
8070 You can use these attributes on Microsoft Windows targets.
8071 @ref{x86 Variable Attributes} for additional Windows compatibility
8072 attributes available on all x86 targets.
8077 @cindex @code{dllimport} variable attribute
8078 @cindex @code{dllexport} variable attribute
8079 The @code{dllimport} and @code{dllexport} attributes are described in
8080 @ref{Microsoft Windows Function Attributes}.
8083 @cindex @code{selectany} variable attribute
8084 The @code{selectany} attribute causes an initialized global variable to
8085 have link-once semantics. When multiple definitions of the variable are
8086 encountered by the linker, the first is selected and the remainder are
8087 discarded. Following usage by the Microsoft compiler, the linker is told
8088 @emph{not} to warn about size or content differences of the multiple
8091 Although the primary usage of this attribute is for POD types, the
8092 attribute can also be applied to global C++ objects that are initialized
8093 by a constructor. In this case, the static initialization and destruction
8094 code for the object is emitted in each translation defining the object,
8095 but the calls to the constructor and destructor are protected by a
8096 link-once guard variable.
8098 The @code{selectany} attribute is only available on Microsoft Windows
8099 targets. You can use @code{__declspec (selectany)} as a synonym for
8100 @code{__attribute__ ((selectany))} for compatibility with other
8104 @cindex @code{shared} variable attribute
8105 On Microsoft Windows, in addition to putting variable definitions in a named
8106 section, the section can also be shared among all running copies of an
8107 executable or DLL@. For example, this small program defines shared data
8108 by putting it in a named section @code{shared} and marking the section
8112 int foo __attribute__((section ("shared"), shared)) = 0;
8117 /* @r{Read and write foo. All running
8118 copies see the same value.} */
8124 You may only use the @code{shared} attribute along with @code{section}
8125 attribute with a fully-initialized global definition because of the way
8126 linkers work. See @code{section} attribute for more information.
8128 The @code{shared} attribute is only available on Microsoft Windows@.
8132 @node MSP430 Variable Attributes
8133 @subsection MSP430 Variable Attributes
8138 @cindex @code{upper} variable attribute, MSP430
8139 @cindex @code{either} variable attribute, MSP430
8140 These attributes are the same as the MSP430 function attributes of the
8141 same name (@pxref{MSP430 Function Attributes}).
8144 @cindex @code{lower} variable attribute, MSP430
8145 This option behaves mostly the same as the MSP430 function attribute of the
8146 same name (@pxref{MSP430 Function Attributes}), but it has some additional
8149 If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
8150 the @code{section} attribute is applied to a variable, the compiler will
8151 generate 430X instructions to handle it. This is because the compiler has
8152 to assume that the variable could get placed in the upper memory region
8153 (above address 0xFFFF). Marking the variable with the @code{lower} attribute
8154 informs the compiler that the variable will be placed in lower memory so it
8155 is safe to use 430 instructions to handle it.
8157 In the case of the @code{section} attribute, the section name given
8158 will be used, and the @code{.lower} prefix will not be added.
8162 @node Nvidia PTX Variable Attributes
8163 @subsection Nvidia PTX Variable Attributes
8165 These variable attributes are supported by the Nvidia PTX back end:
8169 @cindex @code{shared} attribute, Nvidia PTX
8170 Use this attribute to place a variable in the @code{.shared} memory space.
8171 This memory space is private to each cooperative thread array; only threads
8172 within one thread block refer to the same instance of the variable.
8173 The runtime does not initialize variables in this memory space.
8176 @node PowerPC Variable Attributes
8177 @subsection PowerPC Variable Attributes
8179 Three attributes currently are defined for PowerPC configurations:
8180 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8182 @cindex @code{ms_struct} variable attribute, PowerPC
8183 @cindex @code{gcc_struct} variable attribute, PowerPC
8184 For full documentation of the struct attributes please see the
8185 documentation in @ref{x86 Variable Attributes}.
8187 @cindex @code{altivec} variable attribute, PowerPC
8188 For documentation of @code{altivec} attribute please see the
8189 documentation in @ref{PowerPC Type Attributes}.
8191 @node RL78 Variable Attributes
8192 @subsection RL78 Variable Attributes
8194 @cindex @code{saddr} variable attribute, RL78
8195 The RL78 back end supports the @code{saddr} variable attribute. This
8196 specifies placement of the corresponding variable in the SADDR area,
8197 which can be accessed more efficiently than the default memory region.
8199 @node V850 Variable Attributes
8200 @subsection V850 Variable Attributes
8202 These variable attributes are supported by the V850 back end:
8207 @cindex @code{sda} variable attribute, V850
8208 Use this attribute to explicitly place a variable in the small data area,
8209 which can hold up to 64 kilobytes.
8212 @cindex @code{tda} variable attribute, V850
8213 Use this attribute to explicitly place a variable in the tiny data area,
8214 which can hold up to 256 bytes in total.
8217 @cindex @code{zda} variable attribute, V850
8218 Use this attribute to explicitly place a variable in the first 32 kilobytes
8222 @node x86 Variable Attributes
8223 @subsection x86 Variable Attributes
8225 Two attributes are currently defined for x86 configurations:
8226 @code{ms_struct} and @code{gcc_struct}.
8231 @cindex @code{ms_struct} variable attribute, x86
8232 @cindex @code{gcc_struct} variable attribute, x86
8234 If @code{packed} is used on a structure, or if bit-fields are used,
8235 it may be that the Microsoft ABI lays out the structure differently
8236 than the way GCC normally does. Particularly when moving packed
8237 data between functions compiled with GCC and the native Microsoft compiler
8238 (either via function call or as data in a file), it may be necessary to access
8241 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8242 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8243 command-line options, respectively;
8244 see @ref{x86 Options}, for details of how structure layout is affected.
8245 @xref{x86 Type Attributes}, for information about the corresponding
8246 attributes on types.
8250 @node Xstormy16 Variable Attributes
8251 @subsection Xstormy16 Variable Attributes
8253 One attribute is currently defined for xstormy16 configurations:
8258 @cindex @code{below100} variable attribute, Xstormy16
8260 If a variable has the @code{below100} attribute (@code{BELOW100} is
8261 allowed also), GCC places the variable in the first 0x100 bytes of
8262 memory and use special opcodes to access it. Such variables are
8263 placed in either the @code{.bss_below100} section or the
8264 @code{.data_below100} section.
8268 @node Type Attributes
8269 @section Specifying Attributes of Types
8270 @cindex attribute of types
8271 @cindex type attributes
8273 The keyword @code{__attribute__} allows you to specify various special
8274 properties of types. Some type attributes apply only to structure and
8275 union types, and in C++, also class types, while others can apply to
8276 any type defined via a @code{typedef} declaration. Unless otherwise
8277 specified, the same restrictions and effects apply to attributes regardless
8278 of whether a type is a trivial structure or a C++ class with user-defined
8279 constructors, destructors, or a copy assignment.
8281 Other attributes are defined for functions (@pxref{Function Attributes}),
8282 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
8283 Attributes}), statements (@pxref{Statement Attributes}), and for variables
8284 (@pxref{Variable Attributes}).
8286 The @code{__attribute__} keyword is followed by an attribute specification
8287 enclosed in double parentheses.
8289 You may specify type attributes in an enum, struct or union type
8290 declaration or definition by placing them immediately after the
8291 @code{struct}, @code{union} or @code{enum} keyword. You can also place
8292 them just past the closing curly brace of the definition, but this is less
8293 preferred because logically the type should be fully defined at
8296 You can also include type attributes in a @code{typedef} declaration.
8297 @xref{Attribute Syntax}, for details of the exact syntax for using
8301 * Common Type Attributes::
8302 * ARC Type Attributes::
8303 * ARM Type Attributes::
8304 * BPF Type Attributes::
8305 * MeP Type Attributes::
8306 * PowerPC Type Attributes::
8307 * x86 Type Attributes::
8310 @node Common Type Attributes
8311 @subsection Common Type Attributes
8313 The following type attributes are supported on most targets.
8316 @cindex @code{aligned} type attribute
8318 @itemx aligned (@var{alignment})
8319 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
8320 variables of the specified type. When specified, @var{alignment} must be
8321 a power of 2. Specifying no @var{alignment} argument implies the maximum
8322 alignment for the target, which is often, but by no means always, 8 or 16
8323 bytes. For example, the declarations:
8326 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
8327 typedef int more_aligned_int __attribute__ ((aligned (8)));
8331 force the compiler to ensure (as far as it can) that each variable whose
8332 type is @code{struct S} or @code{more_aligned_int} is allocated and
8333 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
8334 variables of type @code{struct S} aligned to 8-byte boundaries allows
8335 the compiler to use the @code{ldd} and @code{std} (doubleword load and
8336 store) instructions when copying one variable of type @code{struct S} to
8337 another, thus improving run-time efficiency.
8339 Note that the alignment of any given @code{struct} or @code{union} type
8340 is required by the ISO C standard to be at least a perfect multiple of
8341 the lowest common multiple of the alignments of all of the members of
8342 the @code{struct} or @code{union} in question. This means that you @emph{can}
8343 effectively adjust the alignment of a @code{struct} or @code{union}
8344 type by attaching an @code{aligned} attribute to any one of the members
8345 of such a type, but the notation illustrated in the example above is a
8346 more obvious, intuitive, and readable way to request the compiler to
8347 adjust the alignment of an entire @code{struct} or @code{union} type.
8349 As in the preceding example, you can explicitly specify the alignment
8350 (in bytes) that you wish the compiler to use for a given @code{struct}
8351 or @code{union} type. Alternatively, you can leave out the alignment factor
8352 and just ask the compiler to align a type to the maximum
8353 useful alignment for the target machine you are compiling for. For
8354 example, you could write:
8357 struct __attribute__ ((aligned)) S @{ short f[3]; @};
8360 Whenever you leave out the alignment factor in an @code{aligned}
8361 attribute specification, the compiler automatically sets the alignment
8362 for the type to the largest alignment that is ever used for any data
8363 type on the target machine you are compiling for. Doing this can often
8364 make copy operations more efficient, because the compiler can use
8365 whatever instructions copy the biggest chunks of memory when performing
8366 copies to or from the variables that have types that you have aligned
8369 In the example above, if the size of each @code{short} is 2 bytes, then
8370 the size of the entire @code{struct S} type is 6 bytes. The smallest
8371 power of two that is greater than or equal to that is 8, so the
8372 compiler sets the alignment for the entire @code{struct S} type to 8
8375 Note that although you can ask the compiler to select a time-efficient
8376 alignment for a given type and then declare only individual stand-alone
8377 objects of that type, the compiler's ability to select a time-efficient
8378 alignment is primarily useful only when you plan to create arrays of
8379 variables having the relevant (efficiently aligned) type. If you
8380 declare or use arrays of variables of an efficiently-aligned type, then
8381 it is likely that your program also does pointer arithmetic (or
8382 subscripting, which amounts to the same thing) on pointers to the
8383 relevant type, and the code that the compiler generates for these
8384 pointer arithmetic operations is often more efficient for
8385 efficiently-aligned types than for other types.
8387 Note that the effectiveness of @code{aligned} attributes may be limited
8388 by inherent limitations in your linker. On many systems, the linker is
8389 only able to arrange for variables to be aligned up to a certain maximum
8390 alignment. (For some linkers, the maximum supported alignment may
8391 be very very small.) If your linker is only able to align variables
8392 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
8393 in an @code{__attribute__} still only provides you with 8-byte
8394 alignment. See your linker documentation for further information.
8396 When used on a struct, or struct member, the @code{aligned} attribute can
8397 only increase the alignment; in order to decrease it, the @code{packed}
8398 attribute must be specified as well. When used as part of a typedef, the
8399 @code{aligned} attribute can both increase and decrease alignment, and
8400 specifying the @code{packed} attribute generates a warning.
8402 @cindex @code{warn_if_not_aligned} type attribute
8403 @item warn_if_not_aligned (@var{alignment})
8404 This attribute specifies a threshold for the structure field, measured
8405 in bytes. If the structure field is aligned below the threshold, a
8406 warning will be issued. For example, the declaration:
8409 typedef unsigned long long __u64
8410 __attribute__((aligned (4), warn_if_not_aligned (8)));
8421 causes the compiler to issue an warning on @code{struct foo}, like
8422 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
8423 It is used to define @code{struct foo} in such a way that
8424 @code{struct foo} has the same layout and the structure field @code{x}
8425 has the same alignment when @code{__u64} is aligned at either 4 or
8426 8 bytes. Align @code{struct foo} to 8 bytes:
8429 struct __attribute__ ((aligned (8))) foo
8438 silences the warning. The compiler also issues a warning, like
8439 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
8440 when the structure field has the misaligned offset:
8443 struct __attribute__ ((aligned (8))) foo
8452 This warning can be disabled by @option{-Wno-if-not-aligned}.
8454 @item alloc_size (@var{position})
8455 @itemx alloc_size (@var{position-1}, @var{position-2})
8456 @cindex @code{alloc_size} type attribute
8457 The @code{alloc_size} type attribute may be applied to the definition
8458 of a type of a function that returns a pointer and takes at least one
8459 argument of an integer type. It indicates that the returned pointer
8460 points to an object whose size is given by the function argument at
8461 @var{position-1}, or by the product of the arguments at @var{position-1}
8462 and @var{position-2}. Meaningful sizes are positive values less than
8463 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
8464 this information to improve the results of @code{__builtin_object_size}.
8466 For instance, the following declarations
8469 typedef __attribute__ ((alloc_size (1, 2))) void*
8470 calloc_type (size_t, size_t);
8471 typedef __attribute__ ((alloc_size (1))) void*
8472 malloc_type (size_t);
8476 specify that @code{calloc_type} is a type of a function that, like
8477 the standard C function @code{calloc}, returns an object whose size
8478 is given by the product of arguments 1 and 2, and that
8479 @code{malloc_type}, like the standard C function @code{malloc},
8480 returns an object whose size is given by argument 1 to the function.
8483 @itemx copy (@var{expression})
8484 @cindex @code{copy} type attribute
8485 The @code{copy} attribute applies the set of attributes with which
8486 the type of the @var{expression} has been declared to the declaration
8487 of the type to which the attribute is applied. The attribute is
8488 designed for libraries that define aliases that are expected to
8489 specify the same set of attributes as the aliased symbols.
8490 The @code{copy} attribute can be used with types, variables, or
8491 functions. However, the kind of symbol to which the attribute is
8492 applied (either varible or function) must match the kind of symbol
8493 to which the argument refers.
8494 The @code{copy} attribute copies only syntactic and semantic attributes
8495 but not attributes that affect a symbol's linkage or visibility such as
8496 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
8497 attribute is also not copied. @xref{Common Function Attributes}.
8498 @xref{Common Variable Attributes}.
8500 For example, suppose @code{struct A} below is defined in some third
8501 party library header to have the alignment requirement @code{N} and
8502 to force a warning whenever a variable of the type is not so aligned
8503 due to attribute @code{packed}. Specifying the @code{copy} attribute
8504 on the definition on the unrelated @code{struct B} has the effect of
8505 copying all relevant attributes from the type referenced by the pointer
8506 expression to @code{struct B}.
8509 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
8510 A @{ /* @r{@dots{}} */ @};
8511 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
8515 @itemx deprecated (@var{msg})
8516 @cindex @code{deprecated} type attribute
8517 The @code{deprecated} attribute results in a warning if the type
8518 is used anywhere in the source file. This is useful when identifying
8519 types that are expected to be removed in a future version of a program.
8520 If possible, the warning also includes the location of the declaration
8521 of the deprecated type, to enable users to easily find further
8522 information about why the type is deprecated, or what they should do
8523 instead. Note that the warnings only occur for uses and then only
8524 if the type is being applied to an identifier that itself is not being
8525 declared as deprecated.
8528 typedef int T1 __attribute__ ((deprecated));
8532 typedef T1 T3 __attribute__ ((deprecated));
8533 T3 z __attribute__ ((deprecated));
8537 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
8538 warning is issued for line 4 because T2 is not explicitly
8539 deprecated. Line 5 has no warning because T3 is explicitly
8540 deprecated. Similarly for line 6. The optional @var{msg}
8541 argument, which must be a string, is printed in the warning if
8542 present. Control characters in the string will be replaced with
8543 escape sequences, and if the @option{-fmessage-length} option is set
8544 to 0 (its default value) then any newline characters will be ignored.
8546 The @code{deprecated} attribute can also be used for functions and
8547 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8549 The message attached to the attribute is affected by the setting of
8550 the @option{-fmessage-length} option.
8553 @itemx unavailable (@var{msg})
8554 @cindex @code{unavailable} type attribute
8555 The @code{unavailable} attribute behaves in the same manner as the
8556 @code{deprecated} one, but emits an error rather than a warning. It is
8557 used to indicate that a (perhaps previously @code{deprecated}) type is
8560 The @code{unavailable} attribute can also be used for functions and
8561 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8563 @item designated_init
8564 @cindex @code{designated_init} type attribute
8565 This attribute may only be applied to structure types. It indicates
8566 that any initialization of an object of this type must use designated
8567 initializers rather than positional initializers. The intent of this
8568 attribute is to allow the programmer to indicate that a structure's
8569 layout may change, and that therefore relying on positional
8570 initialization will result in future breakage.
8572 GCC emits warnings based on this attribute by default; use
8573 @option{-Wno-designated-init} to suppress them.
8576 @cindex @code{may_alias} type attribute
8577 Accesses through pointers to types with this attribute are not subject
8578 to type-based alias analysis, but are instead assumed to be able to alias
8579 any other type of objects.
8580 In the context of section 6.5 paragraph 7 of the C99 standard,
8581 an lvalue expression
8582 dereferencing such a pointer is treated like having a character type.
8583 See @option{-fstrict-aliasing} for more information on aliasing issues.
8584 This extension exists to support some vector APIs, in which pointers to
8585 one vector type are permitted to alias pointers to a different vector type.
8587 Note that an object of a type with this attribute does not have any
8593 typedef short __attribute__ ((__may_alias__)) short_a;
8599 short_a *b = (short_a *) &a;
8603 if (a == 0x12345678)
8611 If you replaced @code{short_a} with @code{short} in the variable
8612 declaration, the above program would abort when compiled with
8613 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
8616 @item mode (@var{mode})
8617 @cindex @code{mode} type attribute
8618 This attribute specifies the data type for the declaration---whichever
8619 type corresponds to the mode @var{mode}. This in effect lets you
8620 request an integer or floating-point type according to its width.
8622 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
8623 for a list of the possible keywords for @var{mode}.
8624 You may also specify a mode of @code{byte} or @code{__byte__} to
8625 indicate the mode corresponding to a one-byte integer, @code{word} or
8626 @code{__word__} for the mode of a one-word integer, and @code{pointer}
8627 or @code{__pointer__} for the mode used to represent pointers.
8630 @cindex @code{packed} type attribute
8631 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
8632 type definition, specifies that each of its members (other than zero-width
8633 bit-fields) is placed to minimize the memory required. This is equivalent
8634 to specifying the @code{packed} attribute on each of the members.
8636 @opindex fshort-enums
8637 When attached to an @code{enum} definition, the @code{packed} attribute
8638 indicates that the smallest integral type should be used.
8639 Specifying the @option{-fshort-enums} flag on the command line
8640 is equivalent to specifying the @code{packed}
8641 attribute on all @code{enum} definitions.
8643 In the following example @code{struct my_packed_struct}'s members are
8644 packed closely together, but the internal layout of its @code{s} member
8645 is not packed---to do that, @code{struct my_unpacked_struct} needs to
8649 struct my_unpacked_struct
8655 struct __attribute__ ((__packed__)) my_packed_struct
8659 struct my_unpacked_struct s;
8663 You may only specify the @code{packed} attribute on the definition
8664 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
8665 not on a @code{typedef} that does not also define the enumerated type,
8666 structure, union, or class.
8668 @item scalar_storage_order ("@var{endianness}")
8669 @cindex @code{scalar_storage_order} type attribute
8670 When attached to a @code{union} or a @code{struct}, this attribute sets
8671 the storage order, aka endianness, of the scalar fields of the type, as
8672 well as the array fields whose component is scalar. The supported
8673 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
8674 has no effects on fields which are themselves a @code{union}, a @code{struct}
8675 or an array whose component is a @code{union} or a @code{struct}, and it is
8676 possible for these fields to have a different scalar storage order than the
8679 Note that neither pointer nor vector fields are considered scalar fields in
8680 this context, so the attribute has no effects on these fields.
8682 This attribute is supported only for targets that use a uniform default
8683 scalar storage order (fortunately, most of them), i.e.@: targets that store
8684 the scalars either all in big-endian or all in little-endian.
8686 Additional restrictions are enforced for types with the reverse scalar
8687 storage order with regard to the scalar storage order of the target:
8690 @item Taking the address of a scalar field of a @code{union} or a
8691 @code{struct} with reverse scalar storage order is not permitted and yields
8693 @item Taking the address of an array field, whose component is scalar, of
8694 a @code{union} or a @code{struct} with reverse scalar storage order is
8695 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
8697 @item Taking the address of a @code{union} or a @code{struct} with reverse
8698 scalar storage order is permitted.
8701 These restrictions exist because the storage order attribute is lost when
8702 the address of a scalar or the address of an array with scalar component is
8703 taken, so storing indirectly through this address generally does not work.
8704 The second case is nevertheless allowed to be able to perform a block copy
8705 from or to the array.
8707 Moreover, the use of type punning or aliasing to toggle the storage order
8708 is not supported; that is to say, if a given scalar object can be accessed
8709 through distinct types that assign a different storage order to it, then the
8710 behavior is undefined.
8712 @item transparent_union
8713 @cindex @code{transparent_union} type attribute
8715 This attribute, attached to a @code{union} type definition, indicates
8716 that any function parameter having that union type causes calls to that
8717 function to be treated in a special way.
8719 First, the argument corresponding to a transparent union type can be of
8720 any type in the union; no cast is required. Also, if the union contains
8721 a pointer type, the corresponding argument can be a null pointer
8722 constant or a void pointer expression; and if the union contains a void
8723 pointer type, the corresponding argument can be any pointer expression.
8724 If the union member type is a pointer, qualifiers like @code{const} on
8725 the referenced type must be respected, just as with normal pointer
8728 Second, the argument is passed to the function using the calling
8729 conventions of the first member of the transparent union, not the calling
8730 conventions of the union itself. All members of the union must have the
8731 same machine representation; this is necessary for this argument passing
8734 Transparent unions are designed for library functions that have multiple
8735 interfaces for compatibility reasons. For example, suppose the
8736 @code{wait} function must accept either a value of type @code{int *} to
8737 comply with POSIX, or a value of type @code{union wait *} to comply with
8738 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
8739 @code{wait} would accept both kinds of arguments, but it would also
8740 accept any other pointer type and this would make argument type checking
8741 less useful. Instead, @code{<sys/wait.h>} might define the interface
8745 typedef union __attribute__ ((__transparent_union__))
8749 @} wait_status_ptr_t;
8751 pid_t wait (wait_status_ptr_t);
8755 This interface allows either @code{int *} or @code{union wait *}
8756 arguments to be passed, using the @code{int *} calling convention.
8757 The program can call @code{wait} with arguments of either type:
8760 int w1 () @{ int w; return wait (&w); @}
8761 int w2 () @{ union wait w; return wait (&w); @}
8765 With this interface, @code{wait}'s implementation might look like this:
8768 pid_t wait (wait_status_ptr_t p)
8770 return waitpid (-1, p.__ip, 0);
8775 @cindex @code{unused} type attribute
8776 When attached to a type (including a @code{union} or a @code{struct}),
8777 this attribute means that variables of that type are meant to appear
8778 possibly unused. GCC does not produce a warning for any variables of
8779 that type, even if the variable appears to do nothing. This is often
8780 the case with lock or thread classes, which are usually defined and then
8781 not referenced, but contain constructors and destructors that have
8782 nontrivial bookkeeping functions.
8784 @item vector_size (@var{bytes})
8785 @cindex @code{vector_size} type attribute
8786 This attribute specifies the vector size for the type, measured in bytes.
8787 The type to which it applies is known as the @dfn{base type}. The @var{bytes}
8788 argument must be a positive power-of-two multiple of the base type size. For
8789 example, the following declarations:
8792 typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
8793 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
8794 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
8798 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
8799 sized units. With @code{int} having a size of 4 bytes, the type defines
8800 a vector of eight units, four bytes each. The mode of variables of type
8801 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
8802 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
8803 an array of three such vectors. @xref{Vector Extensions}, for details of
8804 manipulating objects of vector types.
8806 This attribute is only applicable to integral and floating scalar types.
8807 In function declarations the attribute applies to the function return
8810 For example, the following:
8812 __attribute__ ((vector_size (16))) float get_flt_vec16 (void);
8814 declares @code{get_flt_vec16} to be a function returning a 16-byte vector
8815 with the base type @code{float}.
8818 @cindex @code{visibility} type attribute
8819 In C++, attribute visibility (@pxref{Function Attributes}) can also be
8820 applied to class, struct, union and enum types. Unlike other type
8821 attributes, the attribute must appear between the initial keyword and
8822 the name of the type; it cannot appear after the body of the type.
8824 Note that the type visibility is applied to vague linkage entities
8825 associated with the class (vtable, typeinfo node, etc.). In
8826 particular, if a class is thrown as an exception in one shared object
8827 and caught in another, the class must have default visibility.
8828 Otherwise the two shared objects are unable to use the same
8829 typeinfo node and exception handling will break.
8831 @item objc_root_class @r{(Objective-C and Objective-C++ only)}
8832 @cindex @code{objc_root_class} type attribute
8833 This attribute marks a class as being a root class, and thus allows
8834 the compiler to elide any warnings about a missing superclass and to
8835 make additional checks for mandatory methods as needed.
8839 To specify multiple attributes, separate them by commas within the
8840 double parentheses: for example, @samp{__attribute__ ((aligned (16),
8843 @node ARC Type Attributes
8844 @subsection ARC Type Attributes
8846 @cindex @code{uncached} type attribute, ARC
8847 Declaring objects with @code{uncached} allows you to exclude
8848 data-cache participation in load and store operations on those objects
8849 without involving the additional semantic implications of
8850 @code{volatile}. The @code{.di} instruction suffix is used for all
8851 loads and stores of data declared @code{uncached}.
8853 @node ARM Type Attributes
8854 @subsection ARM Type Attributes
8856 @cindex @code{notshared} type attribute, ARM
8857 On those ARM targets that support @code{dllimport} (such as Symbian
8858 OS), you can use the @code{notshared} attribute to indicate that the
8859 virtual table and other similar data for a class should not be
8860 exported from a DLL@. For example:
8863 class __declspec(notshared) C @{
8865 __declspec(dllimport) C();
8869 __declspec(dllexport)
8874 In this code, @code{C::C} is exported from the current DLL, but the
8875 virtual table for @code{C} is not exported. (You can use
8876 @code{__attribute__} instead of @code{__declspec} if you prefer, but
8877 most Symbian OS code uses @code{__declspec}.)
8879 @node BPF Type Attributes
8880 @subsection BPF Type Attributes
8882 @cindex @code{preserve_access_index} type attribute, BPF
8883 BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a
8884 @code{struct} or @code{union} type definition, indicates that CO-RE
8885 relocation information should be generated for any access to a variable
8886 of that type. The behavior is equivalent to the programmer manually
8887 wrapping every such access with @code{__builtin_preserve_access_index}.
8890 @node MeP Type Attributes
8891 @subsection MeP Type Attributes
8893 @cindex @code{based} type attribute, MeP
8894 @cindex @code{tiny} type attribute, MeP
8895 @cindex @code{near} type attribute, MeP
8896 @cindex @code{far} type attribute, MeP
8897 Many of the MeP variable attributes may be applied to types as well.
8898 Specifically, the @code{based}, @code{tiny}, @code{near}, and
8899 @code{far} attributes may be applied to either. The @code{io} and
8900 @code{cb} attributes may not be applied to types.
8902 @node PowerPC Type Attributes
8903 @subsection PowerPC Type Attributes
8905 Three attributes currently are defined for PowerPC configurations:
8906 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8908 @cindex @code{ms_struct} type attribute, PowerPC
8909 @cindex @code{gcc_struct} type attribute, PowerPC
8910 For full documentation of the @code{ms_struct} and @code{gcc_struct}
8911 attributes please see the documentation in @ref{x86 Type Attributes}.
8913 @cindex @code{altivec} type attribute, PowerPC
8914 The @code{altivec} attribute allows one to declare AltiVec vector data
8915 types supported by the AltiVec Programming Interface Manual. The
8916 attribute requires an argument to specify one of three vector types:
8917 @code{vector__}, @code{pixel__} (always followed by unsigned short),
8918 and @code{bool__} (always followed by unsigned).
8921 __attribute__((altivec(vector__)))
8922 __attribute__((altivec(pixel__))) unsigned short
8923 __attribute__((altivec(bool__))) unsigned
8926 These attributes mainly are intended to support the @code{__vector},
8927 @code{__pixel}, and @code{__bool} AltiVec keywords.
8929 @node x86 Type Attributes
8930 @subsection x86 Type Attributes
8932 Two attributes are currently defined for x86 configurations:
8933 @code{ms_struct} and @code{gcc_struct}.
8939 @cindex @code{ms_struct} type attribute, x86
8940 @cindex @code{gcc_struct} type attribute, x86
8942 If @code{packed} is used on a structure, or if bit-fields are used
8943 it may be that the Microsoft ABI packs them differently
8944 than GCC normally packs them. Particularly when moving packed
8945 data between functions compiled with GCC and the native Microsoft compiler
8946 (either via function call or as data in a file), it may be necessary to access
8949 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8950 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8951 command-line options, respectively;
8952 see @ref{x86 Options}, for details of how structure layout is affected.
8953 @xref{x86 Variable Attributes}, for information about the corresponding
8954 attributes on variables.
8958 @node Label Attributes
8959 @section Label Attributes
8960 @cindex Label Attributes
8962 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
8963 details of the exact syntax for using attributes. Other attributes are
8964 available for functions (@pxref{Function Attributes}), variables
8965 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
8966 statements (@pxref{Statement Attributes}), and for types
8967 (@pxref{Type Attributes}). A label attribute followed
8968 by a declaration appertains to the label and not the declaration.
8970 This example uses the @code{cold} label attribute to indicate the
8971 @code{ErrorHandling} branch is unlikely to be taken and that the
8972 @code{ErrorHandling} label is unused:
8976 asm goto ("some asm" : : : : NoError);
8978 /* This branch (the fall-through from the asm) is less commonly used */
8980 __attribute__((cold, unused)); /* Semi-colon is required here */
8985 printf("no error\n");
8991 @cindex @code{unused} label attribute
8992 This feature is intended for program-generated code that may contain
8993 unused labels, but which is compiled with @option{-Wall}. It is
8994 not normally appropriate to use in it human-written code, though it
8995 could be useful in cases where the code that jumps to the label is
8996 contained within an @code{#ifdef} conditional.
8999 @cindex @code{hot} label attribute
9000 The @code{hot} attribute on a label is used to inform the compiler that
9001 the path following the label is more likely than paths that are not so
9002 annotated. This attribute is used in cases where @code{__builtin_expect}
9003 cannot be used, for instance with computed goto or @code{asm goto}.
9006 @cindex @code{cold} label attribute
9007 The @code{cold} attribute on labels is used to inform the compiler that
9008 the path following the label is unlikely to be executed. This attribute
9009 is used in cases where @code{__builtin_expect} cannot be used, for instance
9010 with computed goto or @code{asm goto}.
9014 @node Enumerator Attributes
9015 @section Enumerator Attributes
9016 @cindex Enumerator Attributes
9018 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
9019 details of the exact syntax for using attributes. Other attributes are
9020 available for functions (@pxref{Function Attributes}), variables
9021 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
9022 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
9024 This example uses the @code{deprecated} enumerator attribute to indicate the
9025 @code{oldval} enumerator is deprecated:
9029 oldval __attribute__((deprecated)),
9042 @cindex @code{deprecated} enumerator attribute
9043 The @code{deprecated} attribute results in a warning if the enumerator
9044 is used anywhere in the source file. This is useful when identifying
9045 enumerators that are expected to be removed in a future version of a
9046 program. The warning also includes the location of the declaration
9047 of the deprecated enumerator, to enable users to easily find further
9048 information about why the enumerator is deprecated, or what they should
9049 do instead. Note that the warnings only occurs for uses.
9052 @cindex @code{unavailable} enumerator attribute
9053 The @code{unavailable} attribute results in an error if the enumerator
9054 is used anywhere in the source file. In other respects it behaves in the
9055 same manner as the @code{deprecated} attribute.
9059 @node Statement Attributes
9060 @section Statement Attributes
9061 @cindex Statement Attributes
9063 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
9064 for details of the exact syntax for using attributes. Other attributes are
9065 available for functions (@pxref{Function Attributes}), variables
9066 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
9067 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
9069 This example uses the @code{fallthrough} statement attribute to indicate that
9070 the @option{-Wimplicit-fallthrough} warning should not be emitted:
9077 __attribute__((fallthrough));
9085 @cindex @code{fallthrough} statement attribute
9086 The @code{fallthrough} attribute with a null statement serves as a
9087 fallthrough statement. It hints to the compiler that a statement
9088 that falls through to another case label, or user-defined label
9089 in a switch statement is intentional and thus the
9090 @option{-Wimplicit-fallthrough} warning must not trigger. The
9091 fallthrough attribute may appear at most once in each attribute
9092 list, and may not be mixed with other attributes. It can only
9093 be used in a switch statement (the compiler will issue an error
9094 otherwise), after a preceding statement and before a logically
9095 succeeding case label, or user-defined label.
9099 @node Attribute Syntax
9100 @section Attribute Syntax
9101 @cindex attribute syntax
9103 This section describes the syntax with which @code{__attribute__} may be
9104 used, and the constructs to which attribute specifiers bind, for the C
9105 language. Some details may vary for C++ and Objective-C@. Because of
9106 infelicities in the grammar for attributes, some forms described here
9107 may not be successfully parsed in all cases.
9109 There are some problems with the semantics of attributes in C++. For
9110 example, there are no manglings for attributes, although they may affect
9111 code generation, so problems may arise when attributed types are used in
9112 conjunction with templates or overloading. Similarly, @code{typeid}
9113 does not distinguish between types with different attributes. Support
9114 for attributes in C++ may be restricted in future to attributes on
9115 declarations only, but not on nested declarators.
9117 @xref{Function Attributes}, for details of the semantics of attributes
9118 applying to functions. @xref{Variable Attributes}, for details of the
9119 semantics of attributes applying to variables. @xref{Type Attributes},
9120 for details of the semantics of attributes applying to structure, union
9121 and enumerated types.
9122 @xref{Label Attributes}, for details of the semantics of attributes
9124 @xref{Enumerator Attributes}, for details of the semantics of attributes
9125 applying to enumerators.
9126 @xref{Statement Attributes}, for details of the semantics of attributes
9127 applying to statements.
9129 An @dfn{attribute specifier} is of the form
9130 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
9131 is a possibly empty comma-separated sequence of @dfn{attributes}, where
9132 each attribute is one of the following:
9136 Empty. Empty attributes are ignored.
9140 (which may be an identifier such as @code{unused}, or a reserved
9141 word such as @code{const}).
9144 An attribute name followed by a parenthesized list of
9145 parameters for the attribute.
9146 These parameters take one of the following forms:
9150 An identifier. For example, @code{mode} attributes use this form.
9153 An identifier followed by a comma and a non-empty comma-separated list
9154 of expressions. For example, @code{format} attributes use this form.
9157 A possibly empty comma-separated list of expressions. For example,
9158 @code{format_arg} attributes use this form with the list being a single
9159 integer constant expression, and @code{alias} attributes use this form
9160 with the list being a single string constant.
9164 An @dfn{attribute specifier list} is a sequence of one or more attribute
9165 specifiers, not separated by any other tokens.
9167 You may optionally specify attribute names with @samp{__}
9168 preceding and following the name.
9169 This allows you to use them in header files without
9170 being concerned about a possible macro of the same name. For example,
9171 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
9174 @subsubheading Label Attributes
9176 In GNU C, an attribute specifier list may appear after the colon following a
9177 label, other than a @code{case} or @code{default} label. GNU C++ only permits
9178 attributes on labels if the attribute specifier is immediately
9179 followed by a semicolon (i.e., the label applies to an empty
9180 statement). If the semicolon is missing, C++ label attributes are
9181 ambiguous, as it is permissible for a declaration, which could begin
9182 with an attribute list, to be labelled in C++. Declarations cannot be
9183 labelled in C90 or C99, so the ambiguity does not arise there.
9185 @subsubheading Enumerator Attributes
9187 In GNU C, an attribute specifier list may appear as part of an enumerator.
9188 The attribute goes after the enumeration constant, before @code{=}, if
9189 present. The optional attribute in the enumerator appertains to the
9190 enumeration constant. It is not possible to place the attribute after
9191 the constant expression, if present.
9193 @subsubheading Statement Attributes
9194 In GNU C, an attribute specifier list may appear as part of a null
9195 statement. The attribute goes before the semicolon.
9197 @subsubheading Type Attributes
9199 An attribute specifier list may appear as part of a @code{struct},
9200 @code{union} or @code{enum} specifier. It may go either immediately
9201 after the @code{struct}, @code{union} or @code{enum} keyword, or after
9202 the closing brace. The former syntax is preferred.
9203 Where attribute specifiers follow the closing brace, they are considered
9204 to relate to the structure, union or enumerated type defined, not to any
9205 enclosing declaration the type specifier appears in, and the type
9206 defined is not complete until after the attribute specifiers.
9207 @c Otherwise, there would be the following problems: a shift/reduce
9208 @c conflict between attributes binding the struct/union/enum and
9209 @c binding to the list of specifiers/qualifiers; and "aligned"
9210 @c attributes could use sizeof for the structure, but the size could be
9211 @c changed later by "packed" attributes.
9214 @subsubheading All other attributes
9216 Otherwise, an attribute specifier appears as part of a declaration,
9217 counting declarations of unnamed parameters and type names, and relates
9218 to that declaration (which may be nested in another declaration, for
9219 example in the case of a parameter declaration), or to a particular declarator
9220 within a declaration. Where an
9221 attribute specifier is applied to a parameter declared as a function or
9222 an array, it should apply to the function or array rather than the
9223 pointer to which the parameter is implicitly converted, but this is not
9224 yet correctly implemented.
9226 Any list of specifiers and qualifiers at the start of a declaration may
9227 contain attribute specifiers, whether or not such a list may in that
9228 context contain storage class specifiers. (Some attributes, however,
9229 are essentially in the nature of storage class specifiers, and only make
9230 sense where storage class specifiers may be used; for example,
9231 @code{section}.) There is one necessary limitation to this syntax: the
9232 first old-style parameter declaration in a function definition cannot
9233 begin with an attribute specifier, because such an attribute applies to
9234 the function instead by syntax described below (which, however, is not
9235 yet implemented in this case). In some other cases, attribute
9236 specifiers are permitted by this grammar but not yet supported by the
9237 compiler. All attribute specifiers in this place relate to the
9238 declaration as a whole. In the obsolescent usage where a type of
9239 @code{int} is implied by the absence of type specifiers, such a list of
9240 specifiers and qualifiers may be an attribute specifier list with no
9241 other specifiers or qualifiers.
9243 At present, the first parameter in a function prototype must have some
9244 type specifier that is not an attribute specifier; this resolves an
9245 ambiguity in the interpretation of @code{void f(int
9246 (__attribute__((foo)) x))}, but is subject to change. At present, if
9247 the parentheses of a function declarator contain only attributes then
9248 those attributes are ignored, rather than yielding an error or warning
9249 or implying a single parameter of type int, but this is subject to
9252 An attribute specifier list may appear immediately before a declarator
9253 (other than the first) in a comma-separated list of declarators in a
9254 declaration of more than one identifier using a single list of
9255 specifiers and qualifiers. Such attribute specifiers apply
9256 only to the identifier before whose declarator they appear. For
9260 __attribute__((noreturn)) void d0 (void),
9261 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
9266 the @code{noreturn} attribute applies to all the functions
9267 declared; the @code{format} attribute only applies to @code{d1}.
9269 An attribute specifier list may appear immediately before the comma,
9270 @code{=} or semicolon terminating the declaration of an identifier other
9271 than a function definition. Such attribute specifiers apply
9272 to the declared object or function. Where an
9273 assembler name for an object or function is specified (@pxref{Asm
9274 Labels}), the attribute must follow the @code{asm}
9277 An attribute specifier list may, in future, be permitted to appear after
9278 the declarator in a function definition (before any old-style parameter
9279 declarations or the function body).
9281 Attribute specifiers may be mixed with type qualifiers appearing inside
9282 the @code{[]} of a parameter array declarator, in the C99 construct by
9283 which such qualifiers are applied to the pointer to which the array is
9284 implicitly converted. Such attribute specifiers apply to the pointer,
9285 not to the array, but at present this is not implemented and they are
9288 An attribute specifier list may appear at the start of a nested
9289 declarator. At present, there are some limitations in this usage: the
9290 attributes correctly apply to the declarator, but for most individual
9291 attributes the semantics this implies are not implemented.
9292 When attribute specifiers follow the @code{*} of a pointer
9293 declarator, they may be mixed with any type qualifiers present.
9294 The following describes the formal semantics of this syntax. It makes the
9295 most sense if you are familiar with the formal specification of
9296 declarators in the ISO C standard.
9298 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
9299 D1}, where @code{T} contains declaration specifiers that specify a type
9300 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
9301 contains an identifier @var{ident}. The type specified for @var{ident}
9302 for derived declarators whose type does not include an attribute
9303 specifier is as in the ISO C standard.
9305 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
9306 and the declaration @code{T D} specifies the type
9307 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
9308 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
9309 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
9311 If @code{D1} has the form @code{*
9312 @var{type-qualifier-and-attribute-specifier-list} D}, and the
9313 declaration @code{T D} specifies the type
9314 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
9315 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
9316 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
9322 void (__attribute__((noreturn)) ****f) (void);
9326 specifies the type ``pointer to pointer to pointer to pointer to
9327 non-returning function returning @code{void}''. As another example,
9330 char *__attribute__((aligned(8))) *f;
9334 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
9335 Note again that this does not work with most attributes; for example,
9336 the usage of @samp{aligned} and @samp{noreturn} attributes given above
9337 is not yet supported.
9339 For compatibility with existing code written for compiler versions that
9340 did not implement attributes on nested declarators, some laxity is
9341 allowed in the placing of attributes. If an attribute that only applies
9342 to types is applied to a declaration, it is treated as applying to
9343 the type of that declaration. If an attribute that only applies to
9344 declarations is applied to the type of a declaration, it is treated
9345 as applying to that declaration; and, for compatibility with code
9346 placing the attributes immediately before the identifier declared, such
9347 an attribute applied to a function return type is treated as
9348 applying to the function type, and such an attribute applied to an array
9349 element type is treated as applying to the array type. If an
9350 attribute that only applies to function types is applied to a
9351 pointer-to-function type, it is treated as applying to the pointer
9352 target type; if such an attribute is applied to a function return type
9353 that is not a pointer-to-function type, it is treated as applying
9354 to the function type.
9356 @node Function Prototypes
9357 @section Prototypes and Old-Style Function Definitions
9358 @cindex function prototype declarations
9359 @cindex old-style function definitions
9360 @cindex promotion of formal parameters
9362 GNU C extends ISO C to allow a function prototype to override a later
9363 old-style non-prototype definition. Consider the following example:
9366 /* @r{Use prototypes unless the compiler is old-fashioned.} */
9373 /* @r{Prototype function declaration.} */
9374 int isroot P((uid_t));
9376 /* @r{Old-style function definition.} */
9378 isroot (x) /* @r{??? lossage here ???} */
9385 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
9386 not allow this example, because subword arguments in old-style
9387 non-prototype definitions are promoted. Therefore in this example the
9388 function definition's argument is really an @code{int}, which does not
9389 match the prototype argument type of @code{short}.
9391 This restriction of ISO C makes it hard to write code that is portable
9392 to traditional C compilers, because the programmer does not know
9393 whether the @code{uid_t} type is @code{short}, @code{int}, or
9394 @code{long}. Therefore, in cases like these GNU C allows a prototype
9395 to override a later old-style definition. More precisely, in GNU C, a
9396 function prototype argument type overrides the argument type specified
9397 by a later old-style definition if the former type is the same as the
9398 latter type before promotion. Thus in GNU C the above example is
9399 equivalent to the following:
9412 GNU C++ does not support old-style function definitions, so this
9413 extension is irrelevant.
9416 @section C++ Style Comments
9418 @cindex C++ comments
9419 @cindex comments, C++ style
9421 In GNU C, you may use C++ style comments, which start with @samp{//} and
9422 continue until the end of the line. Many other C implementations allow
9423 such comments, and they are included in the 1999 C standard. However,
9424 C++ style comments are not recognized if you specify an @option{-std}
9425 option specifying a version of ISO C before C99, or @option{-ansi}
9426 (equivalent to @option{-std=c90}).
9429 @section Dollar Signs in Identifier Names
9431 @cindex dollar signs in identifier names
9432 @cindex identifier names, dollar signs in
9434 In GNU C, you may normally use dollar signs in identifier names.
9435 This is because many traditional C implementations allow such identifiers.
9436 However, dollar signs in identifiers are not supported on a few target
9437 machines, typically because the target assembler does not allow them.
9439 @node Character Escapes
9440 @section The Character @key{ESC} in Constants
9442 You can use the sequence @samp{\e} in a string or character constant to
9443 stand for the ASCII character @key{ESC}.
9446 @section Determining the Alignment of Functions, Types or Variables
9448 @cindex type alignment
9449 @cindex variable alignment
9451 The keyword @code{__alignof__} determines the alignment requirement of
9452 a function, object, or a type, or the minimum alignment usually required
9453 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
9455 For example, if the target machine requires a @code{double} value to be
9456 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
9457 This is true on many RISC machines. On more traditional machine
9458 designs, @code{__alignof__ (double)} is 4 or even 2.
9460 Some machines never actually require alignment; they allow references to any
9461 data type even at an odd address. For these machines, @code{__alignof__}
9462 reports the smallest alignment that GCC gives the data type, usually as
9463 mandated by the target ABI.
9465 If the operand of @code{__alignof__} is an lvalue rather than a type,
9466 its value is the required alignment for its type, taking into account
9467 any minimum alignment specified by attribute @code{aligned}
9468 (@pxref{Common Variable Attributes}). For example, after this
9472 struct foo @{ int x; char y; @} foo1;
9476 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
9477 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
9478 It is an error to ask for the alignment of an incomplete type other
9481 If the operand of the @code{__alignof__} expression is a function,
9482 the expression evaluates to the alignment of the function which may
9483 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
9486 @section An Inline Function is As Fast As a Macro
9487 @cindex inline functions
9488 @cindex integrating function code
9490 @cindex macros, inline alternative
9492 By declaring a function inline, you can direct GCC to make
9493 calls to that function faster. One way GCC can achieve this is to
9494 integrate that function's code into the code for its callers. This
9495 makes execution faster by eliminating the function-call overhead; in
9496 addition, if any of the actual argument values are constant, their
9497 known values may permit simplifications at compile time so that not
9498 all of the inline function's code needs to be included. The effect on
9499 code size is less predictable; object code may be larger or smaller
9500 with function inlining, depending on the particular case. You can
9501 also direct GCC to try to integrate all ``simple enough'' functions
9502 into their callers with the option @option{-finline-functions}.
9504 GCC implements three different semantics of declaring a function
9505 inline. One is available with @option{-std=gnu89} or
9506 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
9507 on all inline declarations, another when
9509 @option{-std=gnu99} or an option for a later C version is used
9510 (without @option{-fgnu89-inline}), and the third
9511 is used when compiling C++.
9513 To declare a function inline, use the @code{inline} keyword in its
9514 declaration, like this:
9524 If you are writing a header file to be included in ISO C90 programs, write
9525 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
9527 The three types of inlining behave similarly in two important cases:
9528 when the @code{inline} keyword is used on a @code{static} function,
9529 like the example above, and when a function is first declared without
9530 using the @code{inline} keyword and then is defined with
9531 @code{inline}, like this:
9534 extern int inc (int *a);
9542 In both of these common cases, the program behaves the same as if you
9543 had not used the @code{inline} keyword, except for its speed.
9545 @cindex inline functions, omission of
9546 @opindex fkeep-inline-functions
9547 When a function is both inline and @code{static}, if all calls to the
9548 function are integrated into the caller, and the function's address is
9549 never used, then the function's own assembler code is never referenced.
9550 In this case, GCC does not actually output assembler code for the
9551 function, unless you specify the option @option{-fkeep-inline-functions}.
9552 If there is a nonintegrated call, then the function is compiled to
9553 assembler code as usual. The function must also be compiled as usual if
9554 the program refers to its address, because that cannot be inlined.
9557 Note that certain usages in a function definition can make it unsuitable
9558 for inline substitution. Among these usages are: variadic functions,
9559 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
9560 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
9561 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
9562 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
9563 function marked @code{inline} could not be substituted, and gives the
9564 reason for the failure.
9566 @cindex automatic @code{inline} for C++ member fns
9567 @cindex @code{inline} automatic for C++ member fns
9568 @cindex member fns, automatically @code{inline}
9569 @cindex C++ member fns, automatically @code{inline}
9570 @opindex fno-default-inline
9571 As required by ISO C++, GCC considers member functions defined within
9572 the body of a class to be marked inline even if they are
9573 not explicitly declared with the @code{inline} keyword. You can
9574 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
9575 Options,,Options Controlling C++ Dialect}.
9577 GCC does not inline any functions when not optimizing unless you specify
9578 the @samp{always_inline} attribute for the function, like this:
9581 /* @r{Prototype.} */
9582 inline void foo (const char) __attribute__((always_inline));
9585 The remainder of this section is specific to GNU C90 inlining.
9587 @cindex non-static inline function
9588 When an inline function is not @code{static}, then the compiler must assume
9589 that there may be calls from other source files; since a global symbol can
9590 be defined only once in any program, the function must not be defined in
9591 the other source files, so the calls therein cannot be integrated.
9592 Therefore, a non-@code{static} inline function is always compiled on its
9593 own in the usual fashion.
9595 If you specify both @code{inline} and @code{extern} in the function
9596 definition, then the definition is used only for inlining. In no case
9597 is the function compiled on its own, not even if you refer to its
9598 address explicitly. Such an address becomes an external reference, as
9599 if you had only declared the function, and had not defined it.
9601 This combination of @code{inline} and @code{extern} has almost the
9602 effect of a macro. The way to use it is to put a function definition in
9603 a header file with these keywords, and put another copy of the
9604 definition (lacking @code{inline} and @code{extern}) in a library file.
9605 The definition in the header file causes most calls to the function
9606 to be inlined. If any uses of the function remain, they refer to
9607 the single copy in the library.
9610 @section When is a Volatile Object Accessed?
9611 @cindex accessing volatiles
9612 @cindex volatile read
9613 @cindex volatile write
9614 @cindex volatile access
9616 C has the concept of volatile objects. These are normally accessed by
9617 pointers and used for accessing hardware or inter-thread
9618 communication. The standard encourages compilers to refrain from
9619 optimizations concerning accesses to volatile objects, but leaves it
9620 implementation defined as to what constitutes a volatile access. The
9621 minimum requirement is that at a sequence point all previous accesses
9622 to volatile objects have stabilized and no subsequent accesses have
9623 occurred. Thus an implementation is free to reorder and combine
9624 volatile accesses that occur between sequence points, but cannot do
9625 so for accesses across a sequence point. The use of volatile does
9626 not allow you to violate the restriction on updating objects multiple
9627 times between two sequence points.
9629 Accesses to non-volatile objects are not ordered with respect to
9630 volatile accesses. You cannot use a volatile object as a memory
9631 barrier to order a sequence of writes to non-volatile memory. For
9635 int *ptr = @var{something};
9637 *ptr = @var{something};
9642 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
9643 that the write to @var{*ptr} occurs by the time the update
9644 of @var{vobj} happens. If you need this guarantee, you must use
9645 a stronger memory barrier such as:
9648 int *ptr = @var{something};
9650 *ptr = @var{something};
9651 asm volatile ("" : : : "memory");
9655 A scalar volatile object is read when it is accessed in a void context:
9658 volatile int *src = @var{somevalue};
9662 Such expressions are rvalues, and GCC implements this as a
9663 read of the volatile object being pointed to.
9665 Assignments are also expressions and have an rvalue. However when
9666 assigning to a scalar volatile, the volatile object is not reread,
9667 regardless of whether the assignment expression's rvalue is used or
9668 not. If the assignment's rvalue is used, the value is that assigned
9669 to the volatile object. For instance, there is no read of @var{vobj}
9670 in all the following cases:
9675 vobj = @var{something};
9676 obj = vobj = @var{something};
9677 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
9678 obj = (@var{something}, vobj = @var{anotherthing});
9681 If you need to read the volatile object after an assignment has
9682 occurred, you must use a separate expression with an intervening
9685 As bit-fields are not individually addressable, volatile bit-fields may
9686 be implicitly read when written to, or when adjacent bit-fields are
9687 accessed. Bit-field operations may be optimized such that adjacent
9688 bit-fields are only partially accessed, if they straddle a storage unit
9689 boundary. For these reasons it is unwise to use volatile bit-fields to
9692 @node Using Assembly Language with C
9693 @section How to Use Inline Assembly Language in C Code
9694 @cindex @code{asm} keyword
9695 @cindex assembly language in C
9696 @cindex inline assembly language
9697 @cindex mixing assembly language and C
9699 The @code{asm} keyword allows you to embed assembler instructions
9700 within C code. GCC provides two forms of inline @code{asm}
9701 statements. A @dfn{basic @code{asm}} statement is one with no
9702 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
9703 statement (@pxref{Extended Asm}) includes one or more operands.
9704 The extended form is preferred for mixing C and assembly language
9705 within a function, but to include assembly language at
9706 top level you must use basic @code{asm}.
9708 You can also use the @code{asm} keyword to override the assembler name
9709 for a C symbol, or to place a C variable in a specific register.
9712 * Basic Asm:: Inline assembler without operands.
9713 * Extended Asm:: Inline assembler with operands.
9714 * Constraints:: Constraints for @code{asm} operands
9715 * Asm Labels:: Specifying the assembler name to use for a C symbol.
9716 * Explicit Register Variables:: Defining variables residing in specified
9718 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
9722 @subsection Basic Asm --- Assembler Instructions Without Operands
9723 @cindex basic @code{asm}
9724 @cindex assembly language in C, basic
9726 A basic @code{asm} statement has the following syntax:
9729 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
9732 For the C language, the @code{asm} keyword is a GNU extension.
9733 When writing C code that can be compiled with @option{-ansi} and the
9734 @option{-std} options that select C dialects without GNU extensions, use
9735 @code{__asm__} instead of @code{asm} (@pxref{Alternate Keywords}). For
9736 the C++ language, @code{asm} is a standard keyword, but @code{__asm__}
9737 can be used for code compiled with @option{-fno-asm}.
9739 @subsubheading Qualifiers
9742 The optional @code{volatile} qualifier has no effect.
9743 All basic @code{asm} blocks are implicitly volatile.
9746 If you use the @code{inline} qualifier, then for inlining purposes the size
9747 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
9751 @subsubheading Parameters
9754 @item AssemblerInstructions
9755 This is a literal string that specifies the assembler code. The string can
9756 contain any instructions recognized by the assembler, including directives.
9757 GCC does not parse the assembler instructions themselves and
9758 does not know what they mean or even whether they are valid assembler input.
9760 You may place multiple assembler instructions together in a single @code{asm}
9761 string, separated by the characters normally used in assembly code for the
9762 system. A combination that works in most places is a newline to break the
9763 line, plus a tab character (written as @samp{\n\t}).
9764 Some assemblers allow semicolons as a line separator. However,
9765 note that some assembler dialects use semicolons to start a comment.
9768 @subsubheading Remarks
9769 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
9770 smaller, safer, and more efficient code, and in most cases it is a
9771 better solution than basic @code{asm}. However, there are two
9772 situations where only basic @code{asm} can be used:
9776 Extended @code{asm} statements have to be inside a C
9777 function, so to write inline assembly language at file scope (``top-level''),
9778 outside of C functions, you must use basic @code{asm}.
9779 You can use this technique to emit assembler directives,
9780 define assembly language macros that can be invoked elsewhere in the file,
9781 or write entire functions in assembly language.
9782 Basic @code{asm} statements outside of functions may not use any
9787 with the @code{naked} attribute also require basic @code{asm}
9788 (@pxref{Function Attributes}).
9791 Safely accessing C data and calling functions from basic @code{asm} is more
9792 complex than it may appear. To access C data, it is better to use extended
9795 Do not expect a sequence of @code{asm} statements to remain perfectly
9796 consecutive after compilation. If certain instructions need to remain
9797 consecutive in the output, put them in a single multi-instruction @code{asm}
9798 statement. Note that GCC's optimizers can move @code{asm} statements
9799 relative to other code, including across jumps.
9801 @code{asm} statements may not perform jumps into other @code{asm} statements.
9802 GCC does not know about these jumps, and therefore cannot take
9803 account of them when deciding how to optimize. Jumps from @code{asm} to C
9804 labels are only supported in extended @code{asm}.
9806 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9807 assembly code when optimizing. This can lead to unexpected duplicate
9808 symbol errors during compilation if your assembly code defines symbols or
9811 @strong{Warning:} The C standards do not specify semantics for @code{asm},
9812 making it a potential source of incompatibilities between compilers. These
9813 incompatibilities may not produce compiler warnings/errors.
9815 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
9816 means there is no way to communicate to the compiler what is happening
9817 inside them. GCC has no visibility of symbols in the @code{asm} and may
9818 discard them as unreferenced. It also does not know about side effects of
9819 the assembler code, such as modifications to memory or registers. Unlike
9820 some compilers, GCC assumes that no changes to general purpose registers
9821 occur. This assumption may change in a future release.
9823 To avoid complications from future changes to the semantics and the
9824 compatibility issues between compilers, consider replacing basic @code{asm}
9825 with extended @code{asm}. See
9826 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
9827 from basic asm to extended asm} for information about how to perform this
9830 The compiler copies the assembler instructions in a basic @code{asm}
9831 verbatim to the assembly language output file, without
9832 processing dialects or any of the @samp{%} operators that are available with
9833 extended @code{asm}. This results in minor differences between basic
9834 @code{asm} strings and extended @code{asm} templates. For example, to refer to
9835 registers you might use @samp{%eax} in basic @code{asm} and
9836 @samp{%%eax} in extended @code{asm}.
9838 On targets such as x86 that support multiple assembler dialects,
9839 all basic @code{asm} blocks use the assembler dialect specified by the
9840 @option{-masm} command-line option (@pxref{x86 Options}).
9841 Basic @code{asm} provides no
9842 mechanism to provide different assembler strings for different dialects.
9844 For basic @code{asm} with non-empty assembler string GCC assumes
9845 the assembler block does not change any general purpose registers,
9846 but it may read or write any globally accessible variable.
9848 Here is an example of basic @code{asm} for i386:
9851 /* Note that this code will not compile with -masm=intel */
9852 #define DebugBreak() asm("int $3")
9856 @subsection Extended Asm - Assembler Instructions with C Expression Operands
9857 @cindex extended @code{asm}
9858 @cindex assembly language in C, extended
9860 With extended @code{asm} you can read and write C variables from
9861 assembler and perform jumps from assembler code to C labels.
9862 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
9863 the operand parameters after the assembler template:
9866 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9867 : @var{OutputOperands}
9868 @r{[} : @var{InputOperands}
9869 @r{[} : @var{Clobbers} @r{]} @r{]})
9871 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9872 : @var{OutputOperands}
9873 : @var{InputOperands}
9877 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
9880 The @code{asm} keyword is a GNU extension.
9881 When writing code that can be compiled with @option{-ansi} and the
9882 various @option{-std} options, use @code{__asm__} instead of
9883 @code{asm} (@pxref{Alternate Keywords}).
9885 @subsubheading Qualifiers
9889 The typical use of extended @code{asm} statements is to manipulate input
9890 values to produce output values. However, your @code{asm} statements may
9891 also produce side effects. If so, you may need to use the @code{volatile}
9892 qualifier to disable certain optimizations. @xref{Volatile}.
9895 If you use the @code{inline} qualifier, then for inlining purposes the size
9896 of the @code{asm} statement is taken as the smallest size possible
9897 (@pxref{Size of an asm}).
9900 This qualifier informs the compiler that the @code{asm} statement may
9901 perform a jump to one of the labels listed in the @var{GotoLabels}.
9905 @subsubheading Parameters
9907 @item AssemblerTemplate
9908 This is a literal string that is the template for the assembler code. It is a
9909 combination of fixed text and tokens that refer to the input, output,
9910 and goto parameters. @xref{AssemblerTemplate}.
9912 @item OutputOperands
9913 A comma-separated list of the C variables modified by the instructions in the
9914 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
9917 A comma-separated list of C expressions read by the instructions in the
9918 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
9921 A comma-separated list of registers or other values changed by the
9922 @var{AssemblerTemplate}, beyond those listed as outputs.
9923 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
9926 When you are using the @code{goto} form of @code{asm}, this section contains
9927 the list of all C labels to which the code in the
9928 @var{AssemblerTemplate} may jump.
9931 @code{asm} statements may not perform jumps into other @code{asm} statements,
9932 only to the listed @var{GotoLabels}.
9933 GCC's optimizers do not know about other jumps; therefore they cannot take
9934 account of them when deciding how to optimize.
9937 The total number of input + output + goto operands is limited to 30.
9939 @subsubheading Remarks
9940 The @code{asm} statement allows you to include assembly instructions directly
9941 within C code. This may help you to maximize performance in time-sensitive
9942 code or to access assembly instructions that are not readily available to C
9945 Note that extended @code{asm} statements must be inside a function. Only
9946 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
9947 Functions declared with the @code{naked} attribute also require basic
9948 @code{asm} (@pxref{Function Attributes}).
9950 While the uses of @code{asm} are many and varied, it may help to think of an
9951 @code{asm} statement as a series of low-level instructions that convert input
9952 parameters to output parameters. So a simple (if not particularly useful)
9953 example for i386 using @code{asm} might look like this:
9959 asm ("mov %1, %0\n\t"
9964 printf("%d\n", dst);
9967 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
9970 @subsubsection Volatile
9971 @cindex volatile @code{asm}
9972 @cindex @code{asm} volatile
9974 GCC's optimizers sometimes discard @code{asm} statements if they determine
9975 there is no need for the output variables. Also, the optimizers may move
9976 code out of loops if they believe that the code will always return the same
9977 result (i.e.@: none of its input values change between calls). Using the
9978 @code{volatile} qualifier disables these optimizations. @code{asm} statements
9979 that have no output operands and @code{asm goto} statements,
9980 are implicitly volatile.
9982 This i386 code demonstrates a case that does not use (or require) the
9983 @code{volatile} qualifier. If it is performing assertion checking, this code
9984 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
9985 unreferenced by any code. As a result, the optimizers can discard the
9986 @code{asm} statement, which in turn removes the need for the entire
9987 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
9988 isn't needed you allow the optimizers to produce the most efficient code
9992 void DoCheck(uint32_t dwSomeValue)
9996 // Assumes dwSomeValue is not zero.
10006 The next example shows a case where the optimizers can recognize that the input
10007 (@code{dwSomeValue}) never changes during the execution of the function and can
10008 therefore move the @code{asm} outside the loop to produce more efficient code.
10009 Again, using the @code{volatile} qualifier disables this type of optimization.
10012 void do_print(uint32_t dwSomeValue)
10016 for (uint32_t x=0; x < 5; x++)
10018 // Assumes dwSomeValue is not zero.
10021 : "r" (dwSomeValue)
10024 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
10029 The following example demonstrates a case where you need to use the
10030 @code{volatile} qualifier.
10031 It uses the x86 @code{rdtsc} instruction, which reads
10032 the computer's time-stamp counter. Without the @code{volatile} qualifier,
10033 the optimizers might assume that the @code{asm} block will always return the
10034 same value and therefore optimize away the second call.
10039 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
10040 "shl $32, %%rdx\n\t" // Shift the upper bits left.
10041 "or %%rdx, %0" // 'Or' in the lower bits.
10046 printf("msr: %llx\n", msr);
10048 // Do other work...
10050 // Reprint the timestamp
10051 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
10052 "shl $32, %%rdx\n\t" // Shift the upper bits left.
10053 "or %%rdx, %0" // 'Or' in the lower bits.
10058 printf("msr: %llx\n", msr);
10061 GCC's optimizers do not treat this code like the non-volatile code in the
10062 earlier examples. They do not move it out of loops or omit it on the
10063 assumption that the result from a previous call is still valid.
10065 Note that the compiler can move even @code{volatile asm} instructions relative
10066 to other code, including across jump instructions. For example, on many
10067 targets there is a system register that controls the rounding mode of
10068 floating-point operations. Setting it with a @code{volatile asm} statement,
10069 as in the following PowerPC example, does not work reliably.
10072 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
10076 The compiler may move the addition back before the @code{volatile asm}
10077 statement. To make it work as expected, add an artificial dependency to
10078 the @code{asm} by referencing a variable in the subsequent code, for
10082 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
10086 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
10087 assembly code when optimizing. This can lead to unexpected duplicate symbol
10088 errors during compilation if your @code{asm} code defines symbols or labels.
10090 (@pxref{AssemblerTemplate}) may help resolve this problem.
10092 @anchor{AssemblerTemplate}
10093 @subsubsection Assembler Template
10094 @cindex @code{asm} assembler template
10096 An assembler template is a literal string containing assembler instructions.
10097 The compiler replaces tokens in the template that refer
10098 to inputs, outputs, and goto labels,
10099 and then outputs the resulting string to the assembler. The
10100 string can contain any instructions recognized by the assembler, including
10101 directives. GCC does not parse the assembler instructions
10102 themselves and does not know what they mean or even whether they are valid
10103 assembler input. However, it does count the statements
10104 (@pxref{Size of an asm}).
10106 You may place multiple assembler instructions together in a single @code{asm}
10107 string, separated by the characters normally used in assembly code for the
10108 system. A combination that works in most places is a newline to break the
10109 line, plus a tab character to move to the instruction field (written as
10111 Some assemblers allow semicolons as a line separator. However, note
10112 that some assembler dialects use semicolons to start a comment.
10114 Do not expect a sequence of @code{asm} statements to remain perfectly
10115 consecutive after compilation, even when you are using the @code{volatile}
10116 qualifier. If certain instructions need to remain consecutive in the output,
10117 put them in a single multi-instruction @code{asm} statement.
10119 Accessing data from C programs without using input/output operands (such as
10120 by using global symbols directly from the assembler template) may not work as
10121 expected. Similarly, calling functions directly from an assembler template
10122 requires a detailed understanding of the target assembler and ABI.
10124 Since GCC does not parse the assembler template,
10125 it has no visibility of any
10126 symbols it references. This may result in GCC discarding those symbols as
10127 unreferenced unless they are also listed as input, output, or goto operands.
10129 @subsubheading Special format strings
10131 In addition to the tokens described by the input, output, and goto operands,
10132 these tokens have special meanings in the assembler template:
10136 Outputs a single @samp{%} into the assembler code.
10139 Outputs a number that is unique to each instance of the @code{asm}
10140 statement in the entire compilation. This option is useful when creating local
10141 labels and referring to them multiple times in a single template that
10142 generates multiple assembler instructions.
10147 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
10148 into the assembler code. When unescaped, these characters have special
10149 meaning to indicate multiple assembler dialects, as described below.
10152 @subsubheading Multiple assembler dialects in @code{asm} templates
10154 On targets such as x86, GCC supports multiple assembler dialects.
10155 The @option{-masm} option controls which dialect GCC uses as its
10156 default for inline assembler. The target-specific documentation for the
10157 @option{-masm} option contains the list of supported dialects, as well as the
10158 default dialect if the option is not specified. This information may be
10159 important to understand, since assembler code that works correctly when
10160 compiled using one dialect will likely fail if compiled using another.
10161 @xref{x86 Options}.
10163 If your code needs to support multiple assembler dialects (for example, if
10164 you are writing public headers that need to support a variety of compilation
10165 options), use constructs of this form:
10168 @{ dialect0 | dialect1 | dialect2... @}
10171 This construct outputs @code{dialect0}
10172 when using dialect #0 to compile the code,
10173 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
10174 braces than the number of dialects the compiler supports, the construct
10177 For example, if an x86 compiler supports two dialects
10178 (@samp{att}, @samp{intel}), an
10179 assembler template such as this:
10182 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
10186 is equivalent to one of
10189 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
10190 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
10193 Using that same compiler, this code:
10196 "xchg@{l@}\t@{%%@}ebx, %1"
10200 corresponds to either
10203 "xchgl\t%%ebx, %1" @r{/* att dialect */}
10204 "xchg\tebx, %1" @r{/* intel dialect */}
10207 There is no support for nesting dialect alternatives.
10209 @anchor{OutputOperands}
10210 @subsubsection Output Operands
10211 @cindex @code{asm} output operands
10213 An @code{asm} statement has zero or more output operands indicating the names
10214 of C variables modified by the assembler code.
10216 In this i386 example, @code{old} (referred to in the template string as
10217 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
10218 (@code{%2}) is an input:
10223 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
10224 "sbb %0,%0" // Use the CF to calculate old.
10225 : "=r" (old), "+rm" (*Base)
10232 Operands are separated by commas. Each operand has this format:
10235 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
10239 @item asmSymbolicName
10240 Specifies a symbolic name for the operand.
10241 Reference the name in the assembler template
10242 by enclosing it in square brackets
10243 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10244 that contains the definition. Any valid C variable name is acceptable,
10245 including names already defined in the surrounding code. No two operands
10246 within the same @code{asm} statement can use the same symbolic name.
10248 When not using an @var{asmSymbolicName}, use the (zero-based) position
10250 in the list of operands in the assembler template. For example if there are
10251 three output operands, use @samp{%0} in the template to refer to the first,
10252 @samp{%1} for the second, and @samp{%2} for the third.
10255 A string constant specifying constraints on the placement of the operand;
10256 @xref{Constraints}, for details.
10258 Output constraints must begin with either @samp{=} (a variable overwriting an
10259 existing value) or @samp{+} (when reading and writing). When using
10260 @samp{=}, do not assume the location contains the existing value
10261 on entry to the @code{asm}, except
10262 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
10264 After the prefix, there must be one or more additional constraints
10265 (@pxref{Constraints}) that describe where the value resides. Common
10266 constraints include @samp{r} for register and @samp{m} for memory.
10267 When you list more than one possible location (for example, @code{"=rm"}),
10268 the compiler chooses the most efficient one based on the current context.
10269 If you list as many alternates as the @code{asm} statement allows, you permit
10270 the optimizers to produce the best possible code.
10271 If you must use a specific register, but your Machine Constraints do not
10272 provide sufficient control to select the specific register you want,
10273 local register variables may provide a solution (@pxref{Local Register
10276 @item cvariablename
10277 Specifies a C lvalue expression to hold the output, typically a variable name.
10278 The enclosing parentheses are a required part of the syntax.
10282 When the compiler selects the registers to use to
10283 represent the output operands, it does not use any of the clobbered registers
10284 (@pxref{Clobbers and Scratch Registers}).
10286 Output operand expressions must be lvalues. The compiler cannot check whether
10287 the operands have data types that are reasonable for the instruction being
10288 executed. For output expressions that are not directly addressable (for
10289 example a bit-field), the constraint must allow a register. In that case, GCC
10290 uses the register as the output of the @code{asm}, and then stores that
10291 register into the output.
10293 Operands using the @samp{+} constraint modifier count as two operands
10294 (that is, both as input and output) towards the total maximum of 30 operands
10295 per @code{asm} statement.
10297 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
10298 operands that must not overlap an input. Otherwise,
10299 GCC may allocate the output operand in the same register as an unrelated
10300 input operand, on the assumption that the assembler code consumes its
10301 inputs before producing outputs. This assumption may be false if the assembler
10302 code actually consists of more than one instruction.
10304 The same problem can occur if one output parameter (@var{a}) allows a register
10305 constraint and another output parameter (@var{b}) allows a memory constraint.
10306 The code generated by GCC to access the memory address in @var{b} can contain
10307 registers which @emph{might} be shared by @var{a}, and GCC considers those
10308 registers to be inputs to the asm. As above, GCC assumes that such input
10309 registers are consumed before any outputs are written. This assumption may
10310 result in incorrect behavior if the @code{asm} statement writes to @var{a}
10312 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
10313 ensures that modifying @var{a} does not affect the address referenced by
10314 @var{b}. Otherwise, the location of @var{b}
10315 is undefined if @var{a} is modified before using @var{b}.
10317 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10318 instead of simply @samp{%2}). Typically these qualifiers are hardware
10319 dependent. The list of supported modifiers for x86 is found at
10320 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10322 If the C code that follows the @code{asm} makes no use of any of the output
10323 operands, use @code{volatile} for the @code{asm} statement to prevent the
10324 optimizers from discarding the @code{asm} statement as unneeded
10325 (see @ref{Volatile}).
10327 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
10328 references the first output operand as @code{%0} (were there a second, it
10329 would be @code{%1}, etc). The number of the first input operand is one greater
10330 than that of the last output operand. In this i386 example, that makes
10331 @code{Mask} referenced as @code{%1}:
10334 uint32_t Mask = 1234;
10343 That code overwrites the variable @code{Index} (@samp{=}),
10344 placing the value in a register (@samp{r}).
10345 Using the generic @samp{r} constraint instead of a constraint for a specific
10346 register allows the compiler to pick the register to use, which can result
10347 in more efficient code. This may not be possible if an assembler instruction
10348 requires a specific register.
10350 The following i386 example uses the @var{asmSymbolicName} syntax.
10352 same result as the code above, but some may consider it more readable or more
10353 maintainable since reordering index numbers is not necessary when adding or
10354 removing operands. The names @code{aIndex} and @code{aMask}
10355 are only used in this example to emphasize which
10356 names get used where.
10357 It is acceptable to reuse the names @code{Index} and @code{Mask}.
10360 uint32_t Mask = 1234;
10363 asm ("bsfl %[aMask], %[aIndex]"
10364 : [aIndex] "=r" (Index)
10365 : [aMask] "r" (Mask)
10369 Here are some more examples of output operands.
10376 asm ("mov %[e], %[d]"
10381 Here, @code{d} may either be in a register or in memory. Since the compiler
10382 might already have the current value of the @code{uint32_t} location
10383 pointed to by @code{e}
10384 in a register, you can enable it to choose the best location
10385 for @code{d} by specifying both constraints.
10387 @anchor{FlagOutputOperands}
10388 @subsubsection Flag Output Operands
10389 @cindex @code{asm} flag output operands
10391 Some targets have a special register that holds the ``flags'' for the
10392 result of an operation or comparison. Normally, the contents of that
10393 register are either unmodifed by the asm, or the @code{asm} statement is
10394 considered to clobber the contents.
10396 On some targets, a special form of output operand exists by which
10397 conditions in the flags register may be outputs of the asm. The set of
10398 conditions supported are target specific, but the general rule is that
10399 the output variable must be a scalar integer, and the value is boolean.
10400 When supported, the target defines the preprocessor symbol
10401 @code{__GCC_ASM_FLAG_OUTPUTS__}.
10403 Because of the special nature of the flag output operands, the constraint
10404 may not include alternatives.
10406 Most often, the target has only one flags register, and thus is an implied
10407 operand of many instructions. In this case, the operand should not be
10408 referenced within the assembler template via @code{%0} etc, as there's
10409 no corresponding text in the assembly language.
10414 The flag output constraints for the ARM family are of the form
10415 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
10416 conditions defined in the ARM ARM for @code{ConditionHolds}.
10420 Z flag set, or equal
10422 Z flag clear or not equal
10425 C flag set or unsigned greater than equal
10428 C flag clear or unsigned less than
10430 N flag set or ``minus''
10432 N flag clear or ``plus''
10434 V flag set or signed overflow
10438 unsigned greater than
10440 unsigned less than equal
10442 signed greater than equal
10446 signed greater than
10448 signed less than equal
10451 The flag output constraints are not supported in thumb1 mode.
10454 The flag output constraints for the x86 family are of the form
10455 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
10456 conditions defined in the ISA manual for @code{j@var{cc}} or
10457 @code{set@var{cc}}.
10461 ``above'' or unsigned greater than
10463 ``above or equal'' or unsigned greater than or equal
10465 ``below'' or unsigned less than
10467 ``below or equal'' or unsigned less than or equal
10472 ``equal'' or zero flag set
10474 signed greater than
10476 signed greater than or equal
10480 signed less than or equal
10501 ``not'' @var{flag}, or inverted versions of those above
10506 @anchor{InputOperands}
10507 @subsubsection Input Operands
10508 @cindex @code{asm} input operands
10509 @cindex @code{asm} expressions
10511 Input operands make values from C variables and expressions available to the
10514 Operands are separated by commas. Each operand has this format:
10517 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
10521 @item asmSymbolicName
10522 Specifies a symbolic name for the operand.
10523 Reference the name in the assembler template
10524 by enclosing it in square brackets
10525 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10526 that contains the definition. Any valid C variable name is acceptable,
10527 including names already defined in the surrounding code. No two operands
10528 within the same @code{asm} statement can use the same symbolic name.
10530 When not using an @var{asmSymbolicName}, use the (zero-based) position
10532 in the list of operands in the assembler template. For example if there are
10533 two output operands and three inputs,
10534 use @samp{%2} in the template to refer to the first input operand,
10535 @samp{%3} for the second, and @samp{%4} for the third.
10538 A string constant specifying constraints on the placement of the operand;
10539 @xref{Constraints}, for details.
10541 Input constraint strings may not begin with either @samp{=} or @samp{+}.
10542 When you list more than one possible location (for example, @samp{"irm"}),
10543 the compiler chooses the most efficient one based on the current context.
10544 If you must use a specific register, but your Machine Constraints do not
10545 provide sufficient control to select the specific register you want,
10546 local register variables may provide a solution (@pxref{Local Register
10549 Input constraints can also be digits (for example, @code{"0"}). This indicates
10550 that the specified input must be in the same place as the output constraint
10551 at the (zero-based) index in the output constraint list.
10552 When using @var{asmSymbolicName} syntax for the output operands,
10553 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
10556 This is the C variable or expression being passed to the @code{asm} statement
10557 as input. The enclosing parentheses are a required part of the syntax.
10561 When the compiler selects the registers to use to represent the input
10562 operands, it does not use any of the clobbered registers
10563 (@pxref{Clobbers and Scratch Registers}).
10565 If there are no output operands but there are input operands, place two
10566 consecutive colons where the output operands would go:
10569 __asm__ ("some instructions"
10570 : /* No outputs. */
10571 : "r" (Offset / 8));
10574 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
10575 (except for inputs tied to outputs). The compiler assumes that on exit from
10576 the @code{asm} statement these operands contain the same values as they
10577 had before executing the statement.
10578 It is @emph{not} possible to use clobbers
10579 to inform the compiler that the values in these inputs are changing. One
10580 common work-around is to tie the changing input variable to an output variable
10581 that never gets used. Note, however, that if the code that follows the
10582 @code{asm} statement makes no use of any of the output operands, the GCC
10583 optimizers may discard the @code{asm} statement as unneeded
10584 (see @ref{Volatile}).
10586 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10587 instead of simply @samp{%2}). Typically these qualifiers are hardware
10588 dependent. The list of supported modifiers for x86 is found at
10589 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10591 In this example using the fictitious @code{combine} instruction, the
10592 constraint @code{"0"} for input operand 1 says that it must occupy the same
10593 location as output operand 0. Only input operands may use numbers in
10594 constraints, and they must each refer to an output operand. Only a number (or
10595 the symbolic assembler name) in the constraint can guarantee that one operand
10596 is in the same place as another. The mere fact that @code{foo} is the value of
10597 both operands is not enough to guarantee that they are in the same place in
10598 the generated assembler code.
10601 asm ("combine %2, %0"
10603 : "0" (foo), "g" (bar));
10606 Here is an example using symbolic names.
10609 asm ("cmoveq %1, %2, %[result]"
10610 : [result] "=r"(result)
10611 : "r" (test), "r" (new), "[result]" (old));
10614 @anchor{Clobbers and Scratch Registers}
10615 @subsubsection Clobbers and Scratch Registers
10616 @cindex @code{asm} clobbers
10617 @cindex @code{asm} scratch registers
10619 While the compiler is aware of changes to entries listed in the output
10620 operands, the inline @code{asm} code may modify more than just the outputs. For
10621 example, calculations may require additional registers, or the processor may
10622 overwrite a register as a side effect of a particular assembler instruction.
10623 In order to inform the compiler of these changes, list them in the clobber
10624 list. Clobber list items are either register names or the special clobbers
10625 (listed below). Each clobber list item is a string constant
10626 enclosed in double quotes and separated by commas.
10628 Clobber descriptions may not in any way overlap with an input or output
10629 operand. For example, you may not have an operand describing a register class
10630 with one member when listing that register in the clobber list. Variables
10631 declared to live in specific registers (@pxref{Explicit Register
10632 Variables}) and used
10633 as @code{asm} input or output operands must have no part mentioned in the
10634 clobber description. In particular, there is no way to specify that input
10635 operands get modified without also specifying them as output operands.
10637 When the compiler selects which registers to use to represent input and output
10638 operands, it does not use any of the clobbered registers. As a result,
10639 clobbered registers are available for any use in the assembler code.
10641 Another restriction is that the clobber list should not contain the
10642 stack pointer register. This is because the compiler requires the
10643 value of the stack pointer to be the same after an @code{asm}
10644 statement as it was on entry to the statement. However, previous
10645 versions of GCC did not enforce this rule and allowed the stack
10646 pointer to appear in the list, with unclear semantics. This behavior
10647 is deprecated and listing the stack pointer may become an error in
10648 future versions of GCC@.
10650 Here is a realistic example for the VAX showing the use of clobbered
10654 asm volatile ("movc3 %0, %1, %2"
10655 : /* No outputs. */
10656 : "g" (from), "g" (to), "g" (count)
10657 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
10660 Also, there are two special clobber arguments:
10664 The @code{"cc"} clobber indicates that the assembler code modifies the flags
10665 register. On some machines, GCC represents the condition codes as a specific
10666 hardware register; @code{"cc"} serves to name this register.
10667 On other machines, condition code handling is different,
10668 and specifying @code{"cc"} has no effect. But
10669 it is valid no matter what the target.
10672 The @code{"memory"} clobber tells the compiler that the assembly code
10674 reads or writes to items other than those listed in the input and output
10675 operands (for example, accessing the memory pointed to by one of the input
10676 parameters). To ensure memory contains correct values, GCC may need to flush
10677 specific register values to memory before executing the @code{asm}. Further,
10678 the compiler does not assume that any values read from memory before an
10679 @code{asm} remain unchanged after that @code{asm}; it reloads them as
10681 Using the @code{"memory"} clobber effectively forms a read/write
10682 memory barrier for the compiler.
10684 Note that this clobber does not prevent the @emph{processor} from doing
10685 speculative reads past the @code{asm} statement. To prevent that, you need
10686 processor-specific fence instructions.
10690 Flushing registers to memory has performance implications and may be
10691 an issue for time-sensitive code. You can provide better information
10692 to GCC to avoid this, as shown in the following examples. At a
10693 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
10694 need to be flushed.
10696 Here is a fictitious sum of squares instruction, that takes two
10697 pointers to floating point values in memory and produces a floating
10698 point register output.
10699 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
10700 parameters, once to specify memory accessed, and once to specify a
10701 base register used by the @code{asm}. You won't normally be wasting a
10702 register by doing this as GCC can use the same register for both
10703 purposes. However, it would be foolish to use both @code{%1} and
10704 @code{%3} for @code{x} in this @code{asm} and expect them to be the
10705 same. In fact, @code{%3} may well not be a register. It might be a
10706 symbolic memory reference to the object pointed to by @code{x}.
10709 asm ("sumsq %0, %1, %2"
10711 : "r" (x), "r" (y), "m" (*x), "m" (*y));
10714 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
10715 Notice that the @code{x}, @code{y} and @code{z} pointer registers
10716 must be specified as input/output because the @code{asm} modifies
10720 asm ("vecmul %0, %1, %2"
10721 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
10722 : "m" (*x), "m" (*y));
10725 An x86 example where the string memory argument is of unknown length.
10729 : "=c" (count), "+D" (p)
10730 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
10733 If you know the above will only be reading a ten byte array then you
10734 could instead use a memory input like:
10735 @code{"m" (*(const char (*)[10]) p)}.
10737 Here is an example of a PowerPC vector scale implemented in assembly,
10738 complete with vector and condition code clobbers, and some initialized
10739 offset registers that are unchanged by the @code{asm}.
10743 dscal (size_t n, double *x, double alpha)
10745 asm ("/* lots of asm here */"
10746 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
10747 : "d" (alpha), "b" (32), "b" (48), "b" (64),
10748 "b" (80), "b" (96), "b" (112)
10750 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
10751 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
10755 Rather than allocating fixed registers via clobbers to provide scratch
10756 registers for an @code{asm} statement, an alternative is to define a
10757 variable and make it an early-clobber output as with @code{a2} and
10758 @code{a3} in the example below. This gives the compiler register
10759 allocator more freedom. You can also define a variable and make it an
10760 output tied to an input as with @code{a0} and @code{a1}, tied
10761 respectively to @code{ap} and @code{lda}. Of course, with tied
10762 outputs your @code{asm} can't use the input value after modifying the
10763 output register since they are one and the same register. What's
10764 more, if you omit the early-clobber on the output, it is possible that
10765 GCC might allocate the same register to another of the inputs if GCC
10766 could prove they had the same value on entry to the @code{asm}. This
10767 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
10768 might conceivably be known to have the value 16 and without an
10769 early-clobber share the same register as @code{%11}. On the other
10770 hand, @code{ap} can't be the same as any of the other inputs, so an
10771 early-clobber on @code{a0} is not needed. It is also not desirable in
10772 this case. An early-clobber on @code{a0} would cause GCC to allocate
10773 a separate register for the @code{"m" (*(const double (*)[]) ap)}
10774 input. Note that tying an input to an output is the way to set up an
10775 initialized temporary register modified by an @code{asm} statement.
10776 An input not tied to an output is assumed by GCC to be unchanged, for
10777 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
10778 use that register in following code if the value 16 happened to be
10779 needed. You can even use a normal @code{asm} output for a scratch if
10780 all inputs that might share the same register are consumed before the
10781 scratch is used. The VSX registers clobbered by the @code{asm}
10782 statement could have used this technique except for GCC's limit on the
10783 number of @code{asm} parameters.
10787 dgemv_kernel_4x4 (long n, const double *ap, long lda,
10788 const double *x, double *y, double alpha)
10797 /* lots of asm here */
10798 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
10799 "#a0=%3 a1=%4 a2=%5 a3=%6"
10801 "+m" (*(double (*)[n]) y),
10809 "m" (*(const double (*)[n]) x),
10810 "m" (*(const double (*)[]) ap),
10818 "vs32","vs33","vs34","vs35","vs36","vs37",
10819 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
10824 @anchor{GotoLabels}
10825 @subsubsection Goto Labels
10826 @cindex @code{asm} goto labels
10828 @code{asm goto} allows assembly code to jump to one or more C labels. The
10829 @var{GotoLabels} section in an @code{asm goto} statement contains
10831 list of all C labels to which the assembler code may jump. GCC assumes that
10832 @code{asm} execution falls through to the next statement (if this is not the
10833 case, consider using the @code{__builtin_unreachable} intrinsic after the
10834 @code{asm} statement). Optimization of @code{asm goto} may be improved by
10835 using the @code{hot} and @code{cold} label attributes (@pxref{Label
10838 If the assembler code does modify anything, use the @code{"memory"} clobber
10840 optimizers to flush all register values to memory and reload them if
10841 necessary after the @code{asm} statement.
10843 Also note that an @code{asm goto} statement is always implicitly
10844 considered volatile.
10846 Be careful when you set output operands inside @code{asm goto} only on
10847 some possible control flow paths. If you don't set up the output on
10848 given path and never use it on this path, it is okay. Otherwise, you
10849 should use @samp{+} constraint modifier meaning that the operand is
10850 input and output one. With this modifier you will have the correct
10851 values on all possible paths from the @code{asm goto}.
10853 To reference a label in the assembler template, prefix it with
10854 @samp{%l} (lowercase @samp{L}) followed by its (zero-based) position
10855 in @var{GotoLabels} plus the number of input and output operands.
10856 Output operand with constraint modifier @samp{+} is counted as two
10857 operands because it is considered as one output and one input operand.
10858 For example, if the @code{asm} has three inputs, one output operand
10859 with constraint modifier @samp{+} and one output operand with
10860 constraint modifier @samp{=} and references two labels, refer to the
10861 first label as @samp{%l6} and the second as @samp{%l7}).
10863 Alternately, you can reference labels using the actual C label name
10864 enclosed in brackets. For example, to reference a label named
10865 @code{carry}, you can use @samp{%l[carry]}. The label must still be
10866 listed in the @var{GotoLabels} section when using this approach. It
10867 is better to use the named references for labels as in this case you
10868 can avoid counting input and output operands and special treatment of
10869 output operands with constraint modifier @samp{+}.
10871 Here is an example of @code{asm goto} for i386:
10877 : /* No outputs. */
10878 : "r" (p1), "r" (p2)
10888 The following example shows an @code{asm goto} that uses a memory clobber.
10894 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
10895 : /* No outputs. */
10905 The following example shows an @code{asm goto} that uses an output.
10910 asm goto ("dec %0; jb %l[stop]"
10921 The following artificial example shows an @code{asm goto} that sets
10922 up an output only on one path inside the @code{asm goto}. Usage of
10923 constraint modifier @code{=} instead of @code{+} would be wrong as
10924 @code{factor} is used on all paths from the @code{asm goto}.
10930 asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0"
10936 return inp * factor; /* return 2 * inp or 0 if inp < 10 */
10940 @anchor{x86Operandmodifiers}
10941 @subsubsection x86 Operand Modifiers
10943 References to input, output, and goto operands in the assembler template
10944 of extended @code{asm} statements can use
10945 modifiers to affect the way the operands are formatted in
10946 the code output to the assembler. For example, the
10947 following code uses the @samp{h} and @samp{b} modifiers for x86:
10951 asm volatile ("xchg %h0, %b0" : "+a" (num) );
10955 These modifiers generate this assembler code:
10961 The rest of this discussion uses the following code for illustrative purposes.
10970 asm volatile goto ("some assembler instructions here"
10971 : /* No outputs. */
10972 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
10973 : /* No clobbers. */
10978 With no modifiers, this is what the output from the operands would be
10979 for the @samp{att} and @samp{intel} dialects of assembler:
10981 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
10982 @headitem Operand @tab @samp{att} @tab @samp{intel}
10991 @tab @code{OFFSET FLAT:.L3}
11003 The table below shows the list of supported modifiers and their effects.
11005 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
11006 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
11008 @tab Print an absolute memory reference.
11013 @tab Print the QImode name of the register.
11018 @tab print the opcode suffix of b.
11023 @tab Require a constant operand and print the constant expression with no punctuation.
11028 @tab print duplicated register operand for AVX instruction.
11030 @tab @code{%xmm0, %xmm0}
11031 @tab @code{xmm0, xmm0}
11033 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
11034 Otherwise mode is unspecified (VOIDmode).
11039 @tab Print the V16SFmode name of the register.
11044 @tab Print the QImode name for a ``high'' register.
11049 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
11050 high 8 bytes of SSE values. For a memref in (%rax), it generates
11052 @tab @code{8(%rax)}
11055 @tab Print the SImode name of the register.
11060 @tab Print the label name with no punctuation.
11065 @tab print the opcode suffix of l.
11075 @tab Print raw symbol name (without syntax-specific prefixes).
11080 @tab If used for a function, print the PLT suffix and generate PIC code.
11081 For example, emit @code{foo@@PLT} instead of 'foo' for the function
11082 foo(). If used for a constant, drop all syntax-specific prefixes and
11083 issue the bare constant. See @code{p} above.
11085 @tab Print the DImode name of the register.
11090 @tab print the opcode suffix of q.
11095 @tab print embedded rounding and sae.
11097 @tab @code{@{rn-sae@}, }
11098 @tab @code{, @{rn-sae@}}
11100 @tab print only sae.
11102 @tab @code{@{sae@}, }
11103 @tab @code{, @{sae@}}
11105 @tab print a shift double count, followed by the assemblers argument
11106 delimiterprint the opcode suffix of s.
11111 @tab print the opcode suffix of s.
11116 @tab print the V8SFmode name of the register.
11121 @tab print the opcode suffix of t.
11126 @tab print naked full integer register name without %.
11131 @tab Print the HImode name of the register.
11136 @tab print the opcode suffix of w.
11141 @tab print the V4SFmode name of the register.
11146 @tab print "st(0)" instead of "st" as a register.
11151 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
11156 @tab Like @code{z}, with special suffixes for x87 instructions.
11160 @anchor{x86floatingpointasmoperands}
11161 @subsubsection x86 Floating-Point @code{asm} Operands
11163 On x86 targets, there are several rules on the usage of stack-like registers
11164 in the operands of an @code{asm}. These rules apply only to the operands
11165 that are stack-like registers:
11169 Given a set of input registers that die in an @code{asm}, it is
11170 necessary to know which are implicitly popped by the @code{asm}, and
11171 which must be explicitly popped by GCC@.
11173 An input register that is implicitly popped by the @code{asm} must be
11174 explicitly clobbered, unless it is constrained to match an
11178 For any input register that is implicitly popped by an @code{asm}, it is
11179 necessary to know how to adjust the stack to compensate for the pop.
11180 If any non-popped input is closer to the top of the reg-stack than
11181 the implicitly popped register, it would not be possible to know what the
11182 stack looked like---it's not clear how the rest of the stack ``slides
11185 All implicitly popped input registers must be closer to the top of
11186 the reg-stack than any input that is not implicitly popped.
11188 It is possible that if an input dies in an @code{asm}, the compiler might
11189 use the input register for an output reload. Consider this example:
11192 asm ("foo" : "=t" (a) : "f" (b));
11196 This code says that input @code{b} is not popped by the @code{asm}, and that
11197 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
11198 deeper after the @code{asm} than it was before. But, it is possible that
11199 reload may think that it can use the same register for both the input and
11202 To prevent this from happening,
11203 if any input operand uses the @samp{f} constraint, all output register
11204 constraints must use the @samp{&} early-clobber modifier.
11206 The example above is correctly written as:
11209 asm ("foo" : "=&t" (a) : "f" (b));
11213 Some operands need to be in particular places on the stack. All
11214 output operands fall in this category---GCC has no other way to
11215 know which registers the outputs appear in unless you indicate
11216 this in the constraints.
11218 Output operands must specifically indicate which register an output
11219 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
11220 constraints must select a class with a single register.
11223 Output operands may not be ``inserted'' between existing stack registers.
11224 Since no 387 opcode uses a read/write operand, all output operands
11225 are dead before the @code{asm}, and are pushed by the @code{asm}.
11226 It makes no sense to push anywhere but the top of the reg-stack.
11228 Output operands must start at the top of the reg-stack: output
11229 operands may not ``skip'' a register.
11232 Some @code{asm} statements may need extra stack space for internal
11233 calculations. This can be guaranteed by clobbering stack registers
11234 unrelated to the inputs and outputs.
11239 takes one input, which is internally popped, and produces two outputs.
11242 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
11246 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
11247 and replaces them with one output. The @code{st(1)} clobber is necessary
11248 for the compiler to know that @code{fyl2xp1} pops both inputs.
11251 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
11254 @anchor{msp430Operandmodifiers}
11255 @subsubsection MSP430 Operand Modifiers
11257 The list below describes the supported modifiers and their effects for MSP430.
11259 @multitable @columnfractions .10 .90
11260 @headitem Modifier @tab Description
11261 @item @code{A} @tab Select low 16-bits of the constant/register/memory operand.
11262 @item @code{B} @tab Select high 16-bits of the constant/register/memory
11264 @item @code{C} @tab Select bits 32-47 of the constant/register/memory operand.
11265 @item @code{D} @tab Select bits 48-63 of the constant/register/memory operand.
11266 @item @code{H} @tab Equivalent to @code{B} (for backwards compatibility).
11267 @item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant
11269 @item @code{J} @tab Print an integer without a @code{#} prefix.
11270 @item @code{L} @tab Equivalent to @code{A} (for backwards compatibility).
11271 @item @code{O} @tab Offset of the current frame from the top of the stack.
11272 @item @code{Q} @tab Use the @code{A} instruction postfix.
11273 @item @code{R} @tab Inverse of condition code, for unsigned comparisons.
11274 @item @code{W} @tab Subtract 16 from the constant value.
11275 @item @code{X} @tab Use the @code{X} instruction postfix.
11276 @item @code{Y} @tab Subtract 4 from the constant value.
11277 @item @code{Z} @tab Subtract 1 from the constant value.
11278 @item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the
11279 instruction, depending on the mode.
11280 @item @code{d} @tab Offset 1 byte of a memory reference or constant value.
11281 @item @code{e} @tab Offset 3 bytes of a memory reference or constant value.
11282 @item @code{f} @tab Offset 5 bytes of a memory reference or constant value.
11283 @item @code{g} @tab Offset 7 bytes of a memory reference or constant value.
11284 @item @code{p} @tab Print the value of 2, raised to the power of the given
11285 constant. Used to select the specified bit position.
11286 @item @code{r} @tab Inverse of condition code, for signed comparisons.
11287 @item @code{x} @tab Equivialent to @code{X}, but only for pointers.
11295 @subsection Controlling Names Used in Assembler Code
11296 @cindex assembler names for identifiers
11297 @cindex names used in assembler code
11298 @cindex identifiers, names in assembler code
11300 You can specify the name to be used in the assembler code for a C
11301 function or variable by writing the @code{asm} (or @code{__asm__})
11302 keyword after the declarator.
11303 It is up to you to make sure that the assembler names you choose do not
11304 conflict with any other assembler symbols, or reference registers.
11306 @subsubheading Assembler names for data:
11308 This sample shows how to specify the assembler name for data:
11311 int foo asm ("myfoo") = 2;
11315 This specifies that the name to be used for the variable @code{foo} in
11316 the assembler code should be @samp{myfoo} rather than the usual
11319 On systems where an underscore is normally prepended to the name of a C
11320 variable, this feature allows you to define names for the
11321 linker that do not start with an underscore.
11323 GCC does not support using this feature with a non-static local variable
11324 since such variables do not have assembler names. If you are
11325 trying to put the variable in a particular register, see
11326 @ref{Explicit Register Variables}.
11328 @subsubheading Assembler names for functions:
11330 To specify the assembler name for functions, write a declaration for the
11331 function before its definition and put @code{asm} there, like this:
11334 int func (int x, int y) asm ("MYFUNC");
11336 int func (int x, int y)
11342 This specifies that the name to be used for the function @code{func} in
11343 the assembler code should be @code{MYFUNC}.
11345 @node Explicit Register Variables
11346 @subsection Variables in Specified Registers
11347 @anchor{Explicit Reg Vars}
11348 @cindex explicit register variables
11349 @cindex variables in specified registers
11350 @cindex specified registers
11352 GNU C allows you to associate specific hardware registers with C
11353 variables. In almost all cases, allowing the compiler to assign
11354 registers produces the best code. However under certain unusual
11355 circumstances, more precise control over the variable storage is
11358 Both global and local variables can be associated with a register. The
11359 consequences of performing this association are very different between
11360 the two, as explained in the sections below.
11363 * Global Register Variables:: Variables declared at global scope.
11364 * Local Register Variables:: Variables declared within a function.
11367 @node Global Register Variables
11368 @subsubsection Defining Global Register Variables
11369 @anchor{Global Reg Vars}
11370 @cindex global register variables
11371 @cindex registers, global variables in
11372 @cindex registers, global allocation
11374 You can define a global register variable and associate it with a specified
11375 register like this:
11378 register int *foo asm ("r12");
11382 Here @code{r12} is the name of the register that should be used. Note that
11383 this is the same syntax used for defining local register variables, but for
11384 a global variable the declaration appears outside a function. The
11385 @code{register} keyword is required, and cannot be combined with
11386 @code{static}. The register name must be a valid register name for the
11389 Do not use type qualifiers such as @code{const} and @code{volatile}, as
11390 the outcome may be contrary to expectations. In particular, using the
11391 @code{volatile} qualifier does not fully prevent the compiler from
11392 optimizing accesses to the register.
11394 Registers are a scarce resource on most systems and allowing the
11395 compiler to manage their usage usually results in the best code. However,
11396 under special circumstances it can make sense to reserve some globally.
11397 For example this may be useful in programs such as programming language
11398 interpreters that have a couple of global variables that are accessed
11401 After defining a global register variable, for the current compilation
11405 @item If the register is a call-saved register, call ABI is affected:
11406 the register will not be restored in function epilogue sequences after
11407 the variable has been assigned. Therefore, functions cannot safely
11408 return to callers that assume standard ABI.
11409 @item Conversely, if the register is a call-clobbered register, making
11410 calls to functions that use standard ABI may lose contents of the variable.
11411 Such calls may be created by the compiler even if none are evident in
11412 the original program, for example when libgcc functions are used to
11413 make up for unavailable instructions.
11414 @item Accesses to the variable may be optimized as usual and the register
11415 remains available for allocation and use in any computations, provided that
11416 observable values of the variable are not affected.
11417 @item If the variable is referenced in inline assembly, the type of access
11418 must be provided to the compiler via constraints (@pxref{Constraints}).
11419 Accesses from basic asms are not supported.
11422 Note that these points @emph{only} apply to code that is compiled with the
11423 definition. The behavior of code that is merely linked in (for example
11424 code from libraries) is not affected.
11426 If you want to recompile source files that do not actually use your global
11427 register variable so they do not use the specified register for any other
11428 purpose, you need not actually add the global register declaration to
11429 their source code. It suffices to specify the compiler option
11430 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
11433 @subsubheading Declaring the variable
11435 Global register variables cannot have initial values, because an
11436 executable file has no means to supply initial contents for a register.
11438 When selecting a register, choose one that is normally saved and
11439 restored by function calls on your machine. This ensures that code
11440 which is unaware of this reservation (such as library routines) will
11441 restore it before returning.
11443 On machines with register windows, be sure to choose a global
11444 register that is not affected magically by the function call mechanism.
11446 @subsubheading Using the variable
11448 @cindex @code{qsort}, and global register variables
11449 When calling routines that are not aware of the reservation, be
11450 cautious if those routines call back into code which uses them. As an
11451 example, if you call the system library version of @code{qsort}, it may
11452 clobber your registers during execution, but (if you have selected
11453 appropriate registers) it will restore them before returning. However
11454 it will @emph{not} restore them before calling @code{qsort}'s comparison
11455 function. As a result, global values will not reliably be available to
11456 the comparison function unless the @code{qsort} function itself is rebuilt.
11458 Similarly, it is not safe to access the global register variables from signal
11459 handlers or from more than one thread of control. Unless you recompile
11460 them specially for the task at hand, the system library routines may
11461 temporarily use the register for other things. Furthermore, since the register
11462 is not reserved exclusively for the variable, accessing it from handlers of
11463 asynchronous signals may observe unrelated temporary values residing in the
11466 @cindex register variable after @code{longjmp}
11467 @cindex global register after @code{longjmp}
11468 @cindex value after @code{longjmp}
11471 On most machines, @code{longjmp} restores to each global register
11472 variable the value it had at the time of the @code{setjmp}. On some
11473 machines, however, @code{longjmp} does not change the value of global
11474 register variables. To be portable, the function that called @code{setjmp}
11475 should make other arrangements to save the values of the global register
11476 variables, and to restore them in a @code{longjmp}. This way, the same
11477 thing happens regardless of what @code{longjmp} does.
11479 @node Local Register Variables
11480 @subsubsection Specifying Registers for Local Variables
11481 @anchor{Local Reg Vars}
11482 @cindex local variables, specifying registers
11483 @cindex specifying registers for local variables
11484 @cindex registers for local variables
11486 You can define a local register variable and associate it with a specified
11487 register like this:
11490 register int *foo asm ("r12");
11494 Here @code{r12} is the name of the register that should be used. Note
11495 that this is the same syntax used for defining global register variables,
11496 but for a local variable the declaration appears within a function. The
11497 @code{register} keyword is required, and cannot be combined with
11498 @code{static}. The register name must be a valid register name for the
11501 Do not use type qualifiers such as @code{const} and @code{volatile}, as
11502 the outcome may be contrary to expectations. In particular, when the
11503 @code{const} qualifier is used, the compiler may substitute the
11504 variable with its initializer in @code{asm} statements, which may cause
11505 the corresponding operand to appear in a different register.
11507 As with global register variables, it is recommended that you choose
11508 a register that is normally saved and restored by function calls on your
11509 machine, so that calls to library routines will not clobber it.
11511 The only supported use for this feature is to specify registers
11512 for input and output operands when calling Extended @code{asm}
11513 (@pxref{Extended Asm}). This may be necessary if the constraints for a
11514 particular machine don't provide sufficient control to select the desired
11515 register. To force an operand into a register, create a local variable
11516 and specify the register name after the variable's declaration. Then use
11517 the local variable for the @code{asm} operand and specify any constraint
11518 letter that matches the register:
11521 register int *p1 asm ("r0") = @dots{};
11522 register int *p2 asm ("r1") = @dots{};
11523 register int *result asm ("r0");
11524 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
11527 @emph{Warning:} In the above example, be aware that a register (for example
11528 @code{r0}) can be call-clobbered by subsequent code, including function
11529 calls and library calls for arithmetic operators on other variables (for
11530 example the initialization of @code{p2}). In this case, use temporary
11531 variables for expressions between the register assignments:
11535 register int *p1 asm ("r0") = @dots{};
11536 register int *p2 asm ("r1") = t1;
11537 register int *result asm ("r0");
11538 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
11541 Defining a register variable does not reserve the register. Other than
11542 when invoking the Extended @code{asm}, the contents of the specified
11543 register are not guaranteed. For this reason, the following uses
11544 are explicitly @emph{not} supported. If they appear to work, it is only
11545 happenstance, and may stop working as intended due to (seemingly)
11546 unrelated changes in surrounding code, or even minor changes in the
11547 optimization of a future version of gcc:
11550 @item Passing parameters to or from Basic @code{asm}
11551 @item Passing parameters to or from Extended @code{asm} without using input
11552 or output operands.
11553 @item Passing parameters to or from routines written in assembler (or
11554 other languages) using non-standard calling conventions.
11557 Some developers use Local Register Variables in an attempt to improve
11558 gcc's allocation of registers, especially in large functions. In this
11559 case the register name is essentially a hint to the register allocator.
11560 While in some instances this can generate better code, improvements are
11561 subject to the whims of the allocator/optimizers. Since there are no
11562 guarantees that your improvements won't be lost, this usage of Local
11563 Register Variables is discouraged.
11565 On the MIPS platform, there is related use for local register variables
11566 with slightly different characteristics (@pxref{MIPS Coprocessors,,
11567 Defining coprocessor specifics for MIPS targets, gccint,
11568 GNU Compiler Collection (GCC) Internals}).
11570 @node Size of an asm
11571 @subsection Size of an @code{asm}
11573 Some targets require that GCC track the size of each instruction used
11574 in order to generate correct code. Because the final length of the
11575 code produced by an @code{asm} statement is only known by the
11576 assembler, GCC must make an estimate as to how big it will be. It
11577 does this by counting the number of instructions in the pattern of the
11578 @code{asm} and multiplying that by the length of the longest
11579 instruction supported by that processor. (When working out the number
11580 of instructions, it assumes that any occurrence of a newline or of
11581 whatever statement separator character is supported by the assembler ---
11582 typically @samp{;} --- indicates the end of an instruction.)
11584 Normally, GCC's estimate is adequate to ensure that correct
11585 code is generated, but it is possible to confuse the compiler if you use
11586 pseudo instructions or assembler macros that expand into multiple real
11587 instructions, or if you use assembler directives that expand to more
11588 space in the object file than is needed for a single instruction.
11589 If this happens then the assembler may produce a diagnostic saying that
11590 a label is unreachable.
11592 @cindex @code{asm inline}
11593 This size is also used for inlining decisions. If you use @code{asm inline}
11594 instead of just @code{asm}, then for inlining purposes the size of the asm
11595 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
11597 @node Alternate Keywords
11598 @section Alternate Keywords
11599 @cindex alternate keywords
11600 @cindex keywords, alternate
11602 @option{-ansi} and the various @option{-std} options disable certain
11603 keywords. This causes trouble when you want to use GNU C extensions, or
11604 a general-purpose header file that should be usable by all programs,
11605 including ISO C programs. The keywords @code{asm}, @code{typeof} and
11606 @code{inline} are not available in programs compiled with
11607 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
11608 program compiled with @option{-std=c99} or a later standard). The
11610 @code{restrict} is only available when @option{-std=gnu99} (which will
11611 eventually be the default) or @option{-std=c99} (or the equivalent
11612 @option{-std=iso9899:1999}), or an option for a later standard
11615 The way to solve these problems is to put @samp{__} at the beginning and
11616 end of each problematical keyword. For example, use @code{__asm__}
11617 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
11619 Other C compilers won't accept these alternative keywords; if you want to
11620 compile with another compiler, you can define the alternate keywords as
11621 macros to replace them with the customary keywords. It looks like this:
11625 #define __asm__ asm
11629 @findex __extension__
11631 @option{-pedantic} and other options cause warnings for many GNU C extensions.
11633 prevent such warnings within one expression by writing
11634 @code{__extension__} before the expression. @code{__extension__} has no
11635 effect aside from this.
11637 @node Incomplete Enums
11638 @section Incomplete @code{enum} Types
11640 You can define an @code{enum} tag without specifying its possible values.
11641 This results in an incomplete type, much like what you get if you write
11642 @code{struct foo} without describing the elements. A later declaration
11643 that does specify the possible values completes the type.
11645 You cannot allocate variables or storage using the type while it is
11646 incomplete. However, you can work with pointers to that type.
11648 This extension may not be very useful, but it makes the handling of
11649 @code{enum} more consistent with the way @code{struct} and @code{union}
11652 This extension is not supported by GNU C++.
11654 @node Function Names
11655 @section Function Names as Strings
11656 @cindex @code{__func__} identifier
11657 @cindex @code{__FUNCTION__} identifier
11658 @cindex @code{__PRETTY_FUNCTION__} identifier
11660 GCC provides three magic constants that hold the name of the current
11661 function as a string. In C++11 and later modes, all three are treated
11662 as constant expressions and can be used in @code{constexpr} constexts.
11663 The first of these constants is @code{__func__}, which is part of
11666 The identifier @code{__func__} is implicitly declared by the translator
11667 as if, immediately following the opening brace of each function
11668 definition, the declaration
11671 static const char __func__[] = "function-name";
11675 appeared, where function-name is the name of the lexically-enclosing
11676 function. This name is the unadorned name of the function. As an
11677 extension, at file (or, in C++, namespace scope), @code{__func__}
11678 evaluates to the empty string.
11680 @code{__FUNCTION__} is another name for @code{__func__}, provided for
11681 backward compatibility with old versions of GCC.
11683 In C, @code{__PRETTY_FUNCTION__} is yet another name for
11684 @code{__func__}, except that at file scope (or, in C++, namespace scope),
11685 it evaluates to the string @code{"top level"}. In addition, in C++,
11686 @code{__PRETTY_FUNCTION__} contains the signature of the function as
11687 well as its bare name. For example, this program:
11690 extern "C" int printf (const char *, ...);
11696 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
11697 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
11715 __PRETTY_FUNCTION__ = void a::sub(int)
11718 These identifiers are variables, not preprocessor macros, and may not
11719 be used to initialize @code{char} arrays or be concatenated with string
11722 @node Return Address
11723 @section Getting the Return or Frame Address of a Function
11725 These functions may be used to get information about the callers of a
11728 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
11729 This function returns the return address of the current function, or of
11730 one of its callers. The @var{level} argument is number of frames to
11731 scan up the call stack. A value of @code{0} yields the return address
11732 of the current function, a value of @code{1} yields the return address
11733 of the caller of the current function, and so forth. When inlining
11734 the expected behavior is that the function returns the address of
11735 the function that is returned to. To work around this behavior use
11736 the @code{noinline} function attribute.
11738 The @var{level} argument must be a constant integer.
11740 On some machines it may be impossible to determine the return address of
11741 any function other than the current one; in such cases, or when the top
11742 of the stack has been reached, this function returns an unspecified
11743 value. In addition, @code{__builtin_frame_address} may be used
11744 to determine if the top of the stack has been reached.
11746 Additional post-processing of the returned value may be needed, see
11747 @code{__builtin_extract_return_addr}.
11749 The stored representation of the return address in memory may be different
11750 from the address returned by @code{__builtin_return_address}. For example,
11751 on AArch64 the stored address may be mangled with return address signing
11752 whereas the address returned by @code{__builtin_return_address} is not.
11754 Calling this function with a nonzero argument can have unpredictable
11755 effects, including crashing the calling program. As a result, calls
11756 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11757 option is in effect. Such calls should only be made in debugging
11760 On targets where code addresses are representable as @code{void *},
11762 void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
11764 gives the code address where the current function would return. For example,
11765 such an address may be used with @code{dladdr} or other interfaces that work
11766 with code addresses.
11769 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
11770 The address as returned by @code{__builtin_return_address} may have to be fed
11771 through this function to get the actual encoded address. For example, on the
11772 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
11773 platforms an offset has to be added for the true next instruction to be
11776 If no fixup is needed, this function simply passes through @var{addr}.
11779 @deftypefn {Built-in Function} {void *} __builtin_frob_return_addr (void *@var{addr})
11780 This function does the reverse of @code{__builtin_extract_return_addr}.
11783 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
11784 This function is similar to @code{__builtin_return_address}, but it
11785 returns the address of the function frame rather than the return address
11786 of the function. Calling @code{__builtin_frame_address} with a value of
11787 @code{0} yields the frame address of the current function, a value of
11788 @code{1} yields the frame address of the caller of the current function,
11791 The frame is the area on the stack that holds local variables and saved
11792 registers. The frame address is normally the address of the first word
11793 pushed on to the stack by the function. However, the exact definition
11794 depends upon the processor and the calling convention. If the processor
11795 has a dedicated frame pointer register, and the function has a frame,
11796 then @code{__builtin_frame_address} returns the value of the frame
11799 On some machines it may be impossible to determine the frame address of
11800 any function other than the current one; in such cases, or when the top
11801 of the stack has been reached, this function returns @code{0} if
11802 the first frame pointer is properly initialized by the startup code.
11804 Calling this function with a nonzero argument can have unpredictable
11805 effects, including crashing the calling program. As a result, calls
11806 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11807 option is in effect. Such calls should only be made in debugging
11811 @node Vector Extensions
11812 @section Using Vector Instructions through Built-in Functions
11814 On some targets, the instruction set contains SIMD vector instructions which
11815 operate on multiple values contained in one large register at the same time.
11816 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
11819 The first step in using these extensions is to provide the necessary data
11820 types. This should be done using an appropriate @code{typedef}:
11823 typedef int v4si __attribute__ ((vector_size (16)));
11827 The @code{int} type specifies the @dfn{base type}, while the attribute specifies
11828 the vector size for the variable, measured in bytes. For example, the
11829 declaration above causes the compiler to set the mode for the @code{v4si}
11830 type to be 16 bytes wide and divided into @code{int} sized units. For
11831 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
11832 corresponding mode of @code{foo} is @acronym{V4SI}.
11834 The @code{vector_size} attribute is only applicable to integral and
11835 floating scalars, although arrays, pointers, and function return values
11836 are allowed in conjunction with this construct. Only sizes that are
11837 positive power-of-two multiples of the base type size are currently allowed.
11839 All the basic integer types can be used as base types, both as signed
11840 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
11841 @code{long long}. In addition, @code{float} and @code{double} can be
11842 used to build floating-point vector types.
11844 Specifying a combination that is not valid for the current architecture
11845 causes GCC to synthesize the instructions using a narrower mode.
11846 For example, if you specify a variable of type @code{V4SI} and your
11847 architecture does not allow for this specific SIMD type, GCC
11848 produces code that uses 4 @code{SIs}.
11850 The types defined in this manner can be used with a subset of normal C
11851 operations. Currently, GCC allows using the following operators
11852 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
11854 The operations behave like C++ @code{valarrays}. Addition is defined as
11855 the addition of the corresponding elements of the operands. For
11856 example, in the code below, each of the 4 elements in @var{a} is
11857 added to the corresponding 4 elements in @var{b} and the resulting
11858 vector is stored in @var{c}.
11861 typedef int v4si __attribute__ ((vector_size (16)));
11868 Subtraction, multiplication, division, and the logical operations
11869 operate in a similar manner. Likewise, the result of using the unary
11870 minus or complement operators on a vector type is a vector whose
11871 elements are the negative or complemented values of the corresponding
11872 elements in the operand.
11874 It is possible to use shifting operators @code{<<}, @code{>>} on
11875 integer-type vectors. The operation is defined as following: @code{@{a0,
11876 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
11877 @dots{}, an >> bn@}}@. Vector operands must have the same number of
11880 For convenience, it is allowed to use a binary vector operation
11881 where one operand is a scalar. In that case the compiler transforms
11882 the scalar operand into a vector where each element is the scalar from
11883 the operation. The transformation happens only if the scalar could be
11884 safely converted to the vector-element type.
11885 Consider the following code.
11888 typedef int v4si __attribute__ ((vector_size (16)));
11893 a = b + 1; /* a = b + @{1,1,1,1@}; */
11894 a = 2 * b; /* a = @{2,2,2,2@} * b; */
11896 a = l + a; /* Error, cannot convert long to int. */
11899 Vectors can be subscripted as if the vector were an array with
11900 the same number of elements and base type. Out of bound accesses
11901 invoke undefined behavior at run time. Warnings for out of bound
11902 accesses for vector subscription can be enabled with
11903 @option{-Warray-bounds}.
11905 Vector comparison is supported with standard comparison
11906 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
11907 vector expressions of integer-type or real-type. Comparison between
11908 integer-type vectors and real-type vectors are not supported. The
11909 result of the comparison is a vector of the same width and number of
11910 elements as the comparison operands with a signed integral element
11913 Vectors are compared element-wise producing 0 when comparison is false
11914 and -1 (constant of the appropriate type where all bits are set)
11915 otherwise. Consider the following example.
11918 typedef int v4si __attribute__ ((vector_size (16)));
11920 v4si a = @{1,2,3,4@};
11921 v4si b = @{3,2,1,4@};
11924 c = a > b; /* The result would be @{0, 0,-1, 0@} */
11925 c = a == b; /* The result would be @{0,-1, 0,-1@} */
11928 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
11929 @code{b} and @code{c} are vectors of the same type and @code{a} is an
11930 integer vector with the same number of elements of the same size as @code{b}
11931 and @code{c}, computes all three arguments and creates a vector
11932 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
11933 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
11934 As in the case of binary operations, this syntax is also accepted when
11935 one of @code{b} or @code{c} is a scalar that is then transformed into a
11936 vector. If both @code{b} and @code{c} are scalars and the type of
11937 @code{true?b:c} has the same size as the element type of @code{a}, then
11938 @code{b} and @code{c} are converted to a vector type whose elements have
11939 this type and with the same number of elements as @code{a}.
11941 In C++, the logic operators @code{!, &&, ||} are available for vectors.
11942 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
11943 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
11944 For mixed operations between a scalar @code{s} and a vector @code{v},
11945 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
11946 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
11948 @findex __builtin_shuffle
11949 Vector shuffling is available using functions
11950 @code{__builtin_shuffle (vec, mask)} and
11951 @code{__builtin_shuffle (vec0, vec1, mask)}.
11952 Both functions construct a permutation of elements from one or two
11953 vectors and return a vector of the same type as the input vector(s).
11954 The @var{mask} is an integral vector with the same width (@var{W})
11955 and element count (@var{N}) as the output vector.
11957 The elements of the input vectors are numbered in memory ordering of
11958 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
11959 elements of @var{mask} are considered modulo @var{N} in the single-operand
11960 case and modulo @math{2*@var{N}} in the two-operand case.
11962 Consider the following example,
11965 typedef int v4si __attribute__ ((vector_size (16)));
11967 v4si a = @{1,2,3,4@};
11968 v4si b = @{5,6,7,8@};
11969 v4si mask1 = @{0,1,1,3@};
11970 v4si mask2 = @{0,4,2,5@};
11973 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
11974 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
11977 Note that @code{__builtin_shuffle} is intentionally semantically
11978 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
11980 You can declare variables and use them in function calls and returns, as
11981 well as in assignments and some casts. You can specify a vector type as
11982 a return type for a function. Vector types can also be used as function
11983 arguments. It is possible to cast from one vector type to another,
11984 provided they are of the same size (in fact, you can also cast vectors
11985 to and from other datatypes of the same size).
11987 You cannot operate between vectors of different lengths or different
11988 signedness without a cast.
11990 @findex __builtin_shufflevector
11991 Vector shuffling is available using the
11992 @code{__builtin_shufflevector (vec1, vec2, index...)}
11993 function. @var{vec1} and @var{vec2} must be expressions with
11994 vector type with a compatible element type. The result of
11995 @code{__builtin_shufflevector} is a vector with the same element type
11996 as @var{vec1} and @var{vec2} but that has an element count equal to
11997 the number of indices specified.
11999 The @var{index} arguments are a list of integers that specify the
12000 elements indices of the first two vectors that should be extracted and
12001 returned in a new vector. These element indices are numbered sequentially
12002 starting with the first vector, continuing into the second vector.
12003 An index of -1 can be used to indicate that the corresponding element in
12004 the returned vector is a don't care and can be freely chosen to optimized
12005 the generated code sequence performing the shuffle operation.
12007 Consider the following example,
12009 typedef int v4si __attribute__ ((vector_size (16)));
12010 typedef int v8si __attribute__ ((vector_size (32)));
12012 v8si a = @{1,-2,3,-4,5,-6,7,-8@};
12013 v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */
12014 v4si c = @{-2,-4,-6,-8@};
12015 v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */
12018 @findex __builtin_convertvector
12019 Vector conversion is available using the
12020 @code{__builtin_convertvector (vec, vectype)}
12021 function. @var{vec} must be an expression with integral or floating
12022 vector type and @var{vectype} an integral or floating vector type with the
12023 same number of elements. The result has @var{vectype} type and value of
12024 a C cast of every element of @var{vec} to the element type of @var{vectype}.
12026 Consider the following example,
12028 typedef int v4si __attribute__ ((vector_size (16)));
12029 typedef float v4sf __attribute__ ((vector_size (16)));
12030 typedef double v4df __attribute__ ((vector_size (32)));
12031 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
12033 v4si a = @{1,-2,3,-4@};
12034 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
12035 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
12036 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
12038 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
12039 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
12040 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
12041 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
12042 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
12045 @cindex vector types, using with x86 intrinsics
12046 Sometimes it is desirable to write code using a mix of generic vector
12047 operations (for clarity) and machine-specific vector intrinsics (to
12048 access vector instructions that are not exposed via generic built-ins).
12049 On x86, intrinsic functions for integer vectors typically use the same
12050 vector type @code{__m128i} irrespective of how they interpret the vector,
12051 making it necessary to cast their arguments and return values from/to
12052 other vector types. In C, you can make use of a @code{union} type:
12053 @c In C++ such type punning via a union is not allowed by the language
12055 #include <immintrin.h>
12057 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
12058 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
12068 for variables that can be used with both built-in operators and x86
12072 v128 x, y = @{ 0 @};
12073 memcpy (&x, ptr, sizeof x);
12075 x.mm = _mm_adds_epu8 (x.mm, y.mm);
12078 /* Instead of a variable, a compound literal may be used to pass the
12079 return value of an intrinsic call to a function expecting the union: */
12081 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
12082 @c This could be done implicitly with __attribute__((transparent_union)),
12083 @c but GCC does not accept it for unions of vector types (PR 88955).
12087 @section Support for @code{offsetof}
12088 @findex __builtin_offsetof
12090 GCC implements for both C and C++ a syntactic extension to implement
12091 the @code{offsetof} macro.
12095 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
12097 offsetof_member_designator:
12099 | offsetof_member_designator "." @code{identifier}
12100 | offsetof_member_designator "[" @code{expr} "]"
12103 This extension is sufficient such that
12106 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
12110 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
12111 may be dependent. In either case, @var{member} may consist of a single
12112 identifier, or a sequence of member accesses and array references.
12114 @node __sync Builtins
12115 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
12117 The following built-in functions
12118 are intended to be compatible with those described
12119 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
12120 section 7.4. As such, they depart from normal GCC practice by not using
12121 the @samp{__builtin_} prefix and also by being overloaded so that they
12122 work on multiple types.
12124 The definition given in the Intel documentation allows only for the use of
12125 the types @code{int}, @code{long}, @code{long long} or their unsigned
12126 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
12127 size other than the C type @code{_Bool} or the C++ type @code{bool}.
12128 Operations on pointer arguments are performed as if the operands were
12129 of the @code{uintptr_t} type. That is, they are not scaled by the size
12130 of the type to which the pointer points.
12132 These functions are implemented in terms of the @samp{__atomic}
12133 builtins (@pxref{__atomic Builtins}). They should not be used for new
12134 code which should use the @samp{__atomic} builtins instead.
12136 Not all operations are supported by all target processors. If a particular
12137 operation cannot be implemented on the target processor, a warning is
12138 generated and a call to an external function is generated. The external
12139 function carries the same name as the built-in version,
12140 with an additional suffix
12141 @samp{_@var{n}} where @var{n} is the size of the data type.
12143 @c ??? Should we have a mechanism to suppress this warning? This is almost
12144 @c useful for implementing the operation under the control of an external
12147 In most cases, these built-in functions are considered a @dfn{full barrier}.
12149 no memory operand is moved across the operation, either forward or
12150 backward. Further, instructions are issued as necessary to prevent the
12151 processor from speculating loads across the operation and from queuing stores
12152 after the operation.
12154 All of the routines are described in the Intel documentation to take
12155 ``an optional list of variables protected by the memory barrier''. It's
12156 not clear what is meant by that; it could mean that @emph{only} the
12157 listed variables are protected, or it could mean a list of additional
12158 variables to be protected. The list is ignored by GCC which treats it as
12159 empty. GCC interprets an empty list as meaning that all globally
12160 accessible variables should be protected.
12163 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
12164 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
12165 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
12166 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
12167 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
12168 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
12169 @findex __sync_fetch_and_add
12170 @findex __sync_fetch_and_sub
12171 @findex __sync_fetch_and_or
12172 @findex __sync_fetch_and_and
12173 @findex __sync_fetch_and_xor
12174 @findex __sync_fetch_and_nand
12175 These built-in functions perform the operation suggested by the name, and
12176 returns the value that had previously been in memory. That is, operations
12177 on integer operands have the following semantics. Operations on pointer
12178 arguments are performed as if the operands were of the @code{uintptr_t}
12179 type. That is, they are not scaled by the size of the type to which
12180 the pointer points.
12183 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
12184 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
12187 The object pointed to by the first argument must be of integer or pointer
12188 type. It must not be a boolean type.
12190 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
12191 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
12193 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
12194 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
12195 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
12196 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
12197 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
12198 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
12199 @findex __sync_add_and_fetch
12200 @findex __sync_sub_and_fetch
12201 @findex __sync_or_and_fetch
12202 @findex __sync_and_and_fetch
12203 @findex __sync_xor_and_fetch
12204 @findex __sync_nand_and_fetch
12205 These built-in functions perform the operation suggested by the name, and
12206 return the new value. That is, operations on integer operands have
12207 the following semantics. Operations on pointer operands are performed as
12208 if the operand's type were @code{uintptr_t}.
12211 @{ *ptr @var{op}= value; return *ptr; @}
12212 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
12215 The same constraints on arguments apply as for the corresponding
12216 @code{__sync_op_and_fetch} built-in functions.
12218 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
12219 as @code{*ptr = ~(*ptr & value)} instead of
12220 @code{*ptr = ~*ptr & value}.
12222 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
12223 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
12224 @findex __sync_bool_compare_and_swap
12225 @findex __sync_val_compare_and_swap
12226 These built-in functions perform an atomic compare and swap.
12227 That is, if the current
12228 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
12231 The ``bool'' version returns @code{true} if the comparison is successful and
12232 @var{newval} is written. The ``val'' version returns the contents
12233 of @code{*@var{ptr}} before the operation.
12235 @item __sync_synchronize (...)
12236 @findex __sync_synchronize
12237 This built-in function issues a full memory barrier.
12239 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
12240 @findex __sync_lock_test_and_set
12241 This built-in function, as described by Intel, is not a traditional test-and-set
12242 operation, but rather an atomic exchange operation. It writes @var{value}
12243 into @code{*@var{ptr}}, and returns the previous contents of
12246 Many targets have only minimal support for such locks, and do not support
12247 a full exchange operation. In this case, a target may support reduced
12248 functionality here by which the @emph{only} valid value to store is the
12249 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
12250 is implementation defined.
12252 This built-in function is not a full barrier,
12253 but rather an @dfn{acquire barrier}.
12254 This means that references after the operation cannot move to (or be
12255 speculated to) before the operation, but previous memory stores may not
12256 be globally visible yet, and previous memory loads may not yet be
12259 @item void __sync_lock_release (@var{type} *ptr, ...)
12260 @findex __sync_lock_release
12261 This built-in function releases the lock acquired by
12262 @code{__sync_lock_test_and_set}.
12263 Normally this means writing the constant 0 to @code{*@var{ptr}}.
12265 This built-in function is not a full barrier,
12266 but rather a @dfn{release barrier}.
12267 This means that all previous memory stores are globally visible, and all
12268 previous memory loads have been satisfied, but following memory reads
12269 are not prevented from being speculated to before the barrier.
12272 @node __atomic Builtins
12273 @section Built-in Functions for Memory Model Aware Atomic Operations
12275 The following built-in functions approximately match the requirements
12276 for the C++11 memory model. They are all
12277 identified by being prefixed with @samp{__atomic} and most are
12278 overloaded so that they work with multiple types.
12280 These functions are intended to replace the legacy @samp{__sync}
12281 builtins. The main difference is that the memory order that is requested
12282 is a parameter to the functions. New code should always use the
12283 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
12285 Note that the @samp{__atomic} builtins assume that programs will
12286 conform to the C++11 memory model. In particular, they assume
12287 that programs are free of data races. See the C++11 standard for
12288 detailed requirements.
12290 The @samp{__atomic} builtins can be used with any integral scalar or
12291 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
12292 types are also allowed if @samp{__int128} (@pxref{__int128}) is
12293 supported by the architecture.
12295 The four non-arithmetic functions (load, store, exchange, and
12296 compare_exchange) all have a generic version as well. This generic
12297 version works on any data type. It uses the lock-free built-in function
12298 if the specific data type size makes that possible; otherwise, an
12299 external call is left to be resolved at run time. This external call is
12300 the same format with the addition of a @samp{size_t} parameter inserted
12301 as the first parameter indicating the size of the object being pointed to.
12302 All objects must be the same size.
12304 There are 6 different memory orders that can be specified. These map
12305 to the C++11 memory orders with the same names, see the C++11 standard
12306 or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
12307 on atomic synchronization} for detailed definitions. Individual
12308 targets may also support additional memory orders for use on specific
12309 architectures. Refer to the target documentation for details of
12312 An atomic operation can both constrain code motion and
12313 be mapped to hardware instructions for synchronization between threads
12314 (e.g., a fence). To which extent this happens is controlled by the
12315 memory orders, which are listed here in approximately ascending order of
12316 strength. The description of each memory order is only meant to roughly
12317 illustrate the effects and is not a specification; see the C++11
12318 memory model for precise semantics.
12321 @item __ATOMIC_RELAXED
12322 Implies no inter-thread ordering constraints.
12323 @item __ATOMIC_CONSUME
12324 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
12325 memory order because of a deficiency in C++11's semantics for
12326 @code{memory_order_consume}.
12327 @item __ATOMIC_ACQUIRE
12328 Creates an inter-thread happens-before constraint from the release (or
12329 stronger) semantic store to this acquire load. Can prevent hoisting
12330 of code to before the operation.
12331 @item __ATOMIC_RELEASE
12332 Creates an inter-thread happens-before constraint to acquire (or stronger)
12333 semantic loads that read from this release store. Can prevent sinking
12334 of code to after the operation.
12335 @item __ATOMIC_ACQ_REL
12336 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
12337 @code{__ATOMIC_RELEASE}.
12338 @item __ATOMIC_SEQ_CST
12339 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
12342 Note that in the C++11 memory model, @emph{fences} (e.g.,
12343 @samp{__atomic_thread_fence}) take effect in combination with other
12344 atomic operations on specific memory locations (e.g., atomic loads);
12345 operations on specific memory locations do not necessarily affect other
12346 operations in the same way.
12348 Target architectures are encouraged to provide their own patterns for
12349 each of the atomic built-in functions. If no target is provided, the original
12350 non-memory model set of @samp{__sync} atomic built-in functions are
12351 used, along with any required synchronization fences surrounding it in
12352 order to achieve the proper behavior. Execution in this case is subject
12353 to the same restrictions as those built-in functions.
12355 If there is no pattern or mechanism to provide a lock-free instruction
12356 sequence, a call is made to an external routine with the same parameters
12357 to be resolved at run time.
12359 When implementing patterns for these built-in functions, the memory order
12360 parameter can be ignored as long as the pattern implements the most
12361 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
12362 orders execute correctly with this memory order but they may not execute as
12363 efficiently as they could with a more appropriate implementation of the
12364 relaxed requirements.
12366 Note that the C++11 standard allows for the memory order parameter to be
12367 determined at run time rather than at compile time. These built-in
12368 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
12369 than invoke a runtime library call or inline a switch statement. This is
12370 standard compliant, safe, and the simplest approach for now.
12372 The memory order parameter is a signed int, but only the lower 16 bits are
12373 reserved for the memory order. The remainder of the signed int is reserved
12374 for target use and should be 0. Use of the predefined atomic values
12375 ensures proper usage.
12377 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
12378 This built-in function implements an atomic load operation. It returns the
12379 contents of @code{*@var{ptr}}.
12381 The valid memory order variants are
12382 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
12383 and @code{__ATOMIC_CONSUME}.
12387 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
12388 This is the generic version of an atomic load. It returns the
12389 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
12393 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
12394 This built-in function implements an atomic store operation. It writes
12395 @code{@var{val}} into @code{*@var{ptr}}.
12397 The valid memory order variants are
12398 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
12402 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
12403 This is the generic version of an atomic store. It stores the value
12404 of @code{*@var{val}} into @code{*@var{ptr}}.
12408 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
12409 This built-in function implements an atomic exchange operation. It writes
12410 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
12413 The valid memory order variants are
12414 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
12415 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
12419 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
12420 This is the generic version of an atomic exchange. It stores the
12421 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
12422 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
12426 @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)
12427 This built-in function implements an atomic compare and exchange operation.
12428 This compares the contents of @code{*@var{ptr}} with the contents of
12429 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
12430 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
12431 equal, the operation is a @emph{read} and the current contents of
12432 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
12433 for weak compare_exchange, which may fail spuriously, and @code{false} for
12434 the strong variation, which never fails spuriously. Many targets
12435 only offer the strong variation and ignore the parameter. When in doubt, use
12436 the strong variation.
12438 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
12439 and memory is affected according to the
12440 memory order specified by @var{success_memorder}. There are no
12441 restrictions on what memory order can be used here.
12443 Otherwise, @code{false} is returned and memory is affected according
12444 to @var{failure_memorder}. This memory order cannot be
12445 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
12446 stronger order than that specified by @var{success_memorder}.
12450 @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)
12451 This built-in function implements the generic version of
12452 @code{__atomic_compare_exchange}. The function is virtually identical to
12453 @code{__atomic_compare_exchange_n}, except the desired value is also a
12458 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
12459 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
12460 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
12461 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
12462 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
12463 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
12464 These built-in functions perform the operation suggested by the name, and
12465 return the result of the operation. Operations on pointer arguments are
12466 performed as if the operands were of the @code{uintptr_t} type. That is,
12467 they are not scaled by the size of the type to which the pointer points.
12470 @{ *ptr @var{op}= val; return *ptr; @}
12471 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
12474 The object pointed to by the first argument must be of integer or pointer
12475 type. It must not be a boolean type. All memory orders are valid.
12479 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
12480 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
12481 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
12482 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
12483 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
12484 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
12485 These built-in functions perform the operation suggested by the name, and
12486 return the value that had previously been in @code{*@var{ptr}}. Operations
12487 on pointer arguments are performed as if the operands were of
12488 the @code{uintptr_t} type. That is, they are not scaled by the size of
12489 the type to which the pointer points.
12492 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
12493 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
12496 The same constraints on arguments apply as for the corresponding
12497 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
12501 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
12503 This built-in function performs an atomic test-and-set operation on
12504 the byte at @code{*@var{ptr}}. The byte is set to some implementation
12505 defined nonzero ``set'' value and the return value is @code{true} if and only
12506 if the previous contents were ``set''.
12507 It should be only used for operands of type @code{bool} or @code{char}. For
12508 other types only part of the value may be set.
12510 All memory orders are valid.
12514 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
12516 This built-in function performs an atomic clear operation on
12517 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
12518 It should be only used for operands of type @code{bool} or @code{char} and
12519 in conjunction with @code{__atomic_test_and_set}.
12520 For other types it may only clear partially. If the type is not @code{bool}
12521 prefer using @code{__atomic_store}.
12523 The valid memory order variants are
12524 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
12525 @code{__ATOMIC_RELEASE}.
12529 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
12531 This built-in function acts as a synchronization fence between threads
12532 based on the specified memory order.
12534 All memory orders are valid.
12538 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
12540 This built-in function acts as a synchronization fence between a thread
12541 and signal handlers based in the same thread.
12543 All memory orders are valid.
12547 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
12549 This built-in function returns @code{true} if objects of @var{size} bytes always
12550 generate lock-free atomic instructions for the target architecture.
12551 @var{size} must resolve to a compile-time constant and the result also
12552 resolves to a compile-time constant.
12554 @var{ptr} is an optional pointer to the object that may be used to determine
12555 alignment. A value of 0 indicates typical alignment should be used. The
12556 compiler may also ignore this parameter.
12559 if (__atomic_always_lock_free (sizeof (long long), 0))
12564 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
12566 This built-in function returns @code{true} if objects of @var{size} bytes always
12567 generate lock-free atomic instructions for the target architecture. If
12568 the built-in function is not known to be lock-free, a call is made to a
12569 runtime routine named @code{__atomic_is_lock_free}.
12571 @var{ptr} is an optional pointer to the object that may be used to determine
12572 alignment. A value of 0 indicates typical alignment should be used. The
12573 compiler may also ignore this parameter.
12576 @node Integer Overflow Builtins
12577 @section Built-in Functions to Perform Arithmetic with Overflow Checking
12579 The following built-in functions allow performing simple arithmetic operations
12580 together with checking whether the operations overflowed.
12582 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12583 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
12584 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
12585 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
12586 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
12587 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12588 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12590 These built-in functions promote the first two operands into infinite precision signed
12591 type and perform addition on those promoted operands. The result is then
12592 cast to the type the third pointer argument points to and stored there.
12593 If the stored result is equal to the infinite precision result, the built-in
12594 functions return @code{false}, otherwise they return @code{true}. As the addition is
12595 performed in infinite signed precision, these built-in functions have fully defined
12596 behavior for all argument values.
12598 The first built-in function allows arbitrary integral types for operands and
12599 the result type must be pointer to some integral type other than enumerated or
12600 boolean type, the rest of the built-in functions have explicit integer types.
12602 The compiler will attempt to use hardware instructions to implement
12603 these built-in functions where possible, like conditional jump on overflow
12604 after addition, conditional jump on carry etc.
12608 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12609 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
12610 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
12611 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
12612 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
12613 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12614 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12616 These built-in functions are similar to the add overflow checking built-in
12617 functions above, except they perform subtraction, subtract the second argument
12618 from the first one, instead of addition.
12622 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12623 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
12624 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
12625 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
12626 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
12627 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12628 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12630 These built-in functions are similar to the add overflow checking built-in
12631 functions above, except they perform multiplication, instead of addition.
12635 The following built-in functions allow checking if simple arithmetic operation
12638 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12639 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12640 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12642 These built-in functions are similar to @code{__builtin_add_overflow},
12643 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
12644 they don't store the result of the arithmetic operation anywhere and the
12645 last argument is not a pointer, but some expression with integral type other
12646 than enumerated or boolean type.
12648 The built-in functions promote the first two operands into infinite precision signed type
12649 and perform addition on those promoted operands. The result is then
12650 cast to the type of the third argument. If the cast result is equal to the infinite
12651 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
12652 The value of the third argument is ignored, just the side effects in the third argument
12653 are evaluated, and no integral argument promotions are performed on the last argument.
12654 If the third argument is a bit-field, the type used for the result cast has the
12655 precision and signedness of the given bit-field, rather than precision and signedness
12656 of the underlying type.
12658 For example, the following macro can be used to portably check, at
12659 compile-time, whether or not adding two constant integers will overflow,
12660 and perform the addition only when it is known to be safe and not to trigger
12661 a @option{-Woverflow} warning.
12664 #define INT_ADD_OVERFLOW_P(a, b) \
12665 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
12668 A = INT_MAX, B = 3,
12669 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
12670 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
12674 The compiler will attempt to use hardware instructions to implement
12675 these built-in functions where possible, like conditional jump on overflow
12676 after addition, conditional jump on carry etc.
12680 @node x86 specific memory model extensions for transactional memory
12681 @section x86-Specific Memory Model Extensions for Transactional Memory
12683 The x86 architecture supports additional memory ordering flags
12684 to mark critical sections for hardware lock elision.
12685 These must be specified in addition to an existing memory order to
12689 @item __ATOMIC_HLE_ACQUIRE
12690 Start lock elision on a lock variable.
12691 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
12692 @item __ATOMIC_HLE_RELEASE
12693 End lock elision on a lock variable.
12694 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
12697 When a lock acquire fails, it is required for good performance to abort
12698 the transaction quickly. This can be done with a @code{_mm_pause}.
12701 #include <immintrin.h> // For _mm_pause
12705 /* Acquire lock with lock elision */
12706 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
12707 _mm_pause(); /* Abort failed transaction */
12709 /* Free lock with lock elision */
12710 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
12713 @node Object Size Checking
12714 @section Object Size Checking Built-in Functions
12715 @findex __builtin_object_size
12716 @findex __builtin_dynamic_object_size
12717 @findex __builtin___memcpy_chk
12718 @findex __builtin___mempcpy_chk
12719 @findex __builtin___memmove_chk
12720 @findex __builtin___memset_chk
12721 @findex __builtin___strcpy_chk
12722 @findex __builtin___stpcpy_chk
12723 @findex __builtin___strncpy_chk
12724 @findex __builtin___strcat_chk
12725 @findex __builtin___strncat_chk
12726 @findex __builtin___sprintf_chk
12727 @findex __builtin___snprintf_chk
12728 @findex __builtin___vsprintf_chk
12729 @findex __builtin___vsnprintf_chk
12730 @findex __builtin___printf_chk
12731 @findex __builtin___vprintf_chk
12732 @findex __builtin___fprintf_chk
12733 @findex __builtin___vfprintf_chk
12735 GCC implements a limited buffer overflow protection mechanism that can
12736 prevent some buffer overflow attacks by determining the sizes of objects
12737 into which data is about to be written and preventing the writes when
12738 the size isn't sufficient. The built-in functions described below yield
12739 the best results when used together and when optimization is enabled.
12740 For example, to detect object sizes across function boundaries or to
12741 follow pointer assignments through non-trivial control flow they rely
12742 on various optimization passes enabled with @option{-O2}. However, to
12743 a limited extent, they can be used without optimization as well.
12745 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
12746 is a built-in construct that returns a constant number of bytes from
12747 @var{ptr} to the end of the object @var{ptr} pointer points to
12748 (if known at compile time). To determine the sizes of dynamically allocated
12749 objects the function relies on the allocation functions called to obtain
12750 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
12751 Function Attributes}). @code{__builtin_object_size} never evaluates
12752 its arguments for side effects. If there are any side effects in them, it
12753 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12754 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
12755 point to and all of them are known at compile time, the returned number
12756 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
12757 0 and minimum if nonzero. If it is not possible to determine which objects
12758 @var{ptr} points to at compile time, @code{__builtin_object_size} should
12759 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12760 for @var{type} 2 or 3.
12762 @var{type} is an integer constant from 0 to 3. If the least significant
12763 bit is clear, objects are whole variables, if it is set, a closest
12764 surrounding subobject is considered the object a pointer points to.
12765 The second bit determines if maximum or minimum of remaining bytes
12769 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
12770 char *p = &var.buf1[1], *q = &var.b;
12772 /* Here the object p points to is var. */
12773 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
12774 /* The subobject p points to is var.buf1. */
12775 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
12776 /* The object q points to is var. */
12777 assert (__builtin_object_size (q, 0)
12778 == (char *) (&var + 1) - (char *) &var.b);
12779 /* The subobject q points to is var.b. */
12780 assert (__builtin_object_size (q, 1) == sizeof (var.b));
12784 @deftypefn {Built-in Function} {size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})
12785 is similar to @code{__builtin_object_size} in that it returns a number of bytes
12786 from @var{ptr} to the end of the object @var{ptr} pointer points to, except
12787 that the size returned may not be a constant. This results in successful
12788 evaluation of object size estimates in a wider range of use cases and can be
12789 more precise than @code{__builtin_object_size}, but it incurs a performance
12790 penalty since it may add a runtime overhead on size computation. Semantics of
12791 @var{type} as well as return values in case it is not possible to determine
12792 which objects @var{ptr} points to at compile time are the same as in the case
12793 of @code{__builtin_object_size}.
12796 There are built-in functions added for many common string operation
12797 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
12798 built-in is provided. This built-in has an additional last argument,
12799 which is the number of bytes remaining in the object the @var{dest}
12800 argument points to or @code{(size_t) -1} if the size is not known.
12802 The built-in functions are optimized into the normal string functions
12803 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
12804 it is known at compile time that the destination object will not
12805 be overflowed. If the compiler can determine at compile time that the
12806 object will always be overflowed, it issues a warning.
12808 The intended use can be e.g.@:
12812 #define bos0(dest) __builtin_object_size (dest, 0)
12813 #define memcpy(dest, src, n) \
12814 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
12818 /* It is unknown what object p points to, so this is optimized
12819 into plain memcpy - no checking is possible. */
12820 memcpy (p, "abcde", n);
12821 /* Destination is known and length too. It is known at compile
12822 time there will be no overflow. */
12823 memcpy (&buf[5], "abcde", 5);
12824 /* Destination is known, but the length is not known at compile time.
12825 This will result in __memcpy_chk call that can check for overflow
12827 memcpy (&buf[5], "abcde", n);
12828 /* Destination is known and it is known at compile time there will
12829 be overflow. There will be a warning and __memcpy_chk call that
12830 will abort the program at run time. */
12831 memcpy (&buf[6], "abcde", 5);
12834 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
12835 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
12836 @code{strcat} and @code{strncat}.
12838 There are also checking built-in functions for formatted output functions.
12840 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
12841 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12842 const char *fmt, ...);
12843 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
12845 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12846 const char *fmt, va_list ap);
12849 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
12850 etc.@: functions and can contain implementation specific flags on what
12851 additional security measures the checking function might take, such as
12852 handling @code{%n} differently.
12854 The @var{os} argument is the object size @var{s} points to, like in the
12855 other built-in functions. There is a small difference in the behavior
12856 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
12857 optimized into the non-checking functions only if @var{flag} is 0, otherwise
12858 the checking function is called with @var{os} argument set to
12859 @code{(size_t) -1}.
12861 In addition to this, there are checking built-in functions
12862 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
12863 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
12864 These have just one additional argument, @var{flag}, right before
12865 format string @var{fmt}. If the compiler is able to optimize them to
12866 @code{fputc} etc.@: functions, it does, otherwise the checking function
12867 is called and the @var{flag} argument passed to it.
12869 @node Other Builtins
12870 @section Other Built-in Functions Provided by GCC
12871 @cindex built-in functions
12872 @findex __builtin_alloca
12873 @findex __builtin_alloca_with_align
12874 @findex __builtin_alloca_with_align_and_max
12875 @findex __builtin_call_with_static_chain
12876 @findex __builtin_extend_pointer
12877 @findex __builtin_fpclassify
12878 @findex __builtin_has_attribute
12879 @findex __builtin_isfinite
12880 @findex __builtin_isnormal
12881 @findex __builtin_isgreater
12882 @findex __builtin_isgreaterequal
12883 @findex __builtin_isinf_sign
12884 @findex __builtin_isless
12885 @findex __builtin_islessequal
12886 @findex __builtin_islessgreater
12887 @findex __builtin_isunordered
12888 @findex __builtin_object_size
12889 @findex __builtin_powi
12890 @findex __builtin_powif
12891 @findex __builtin_powil
12892 @findex __builtin_speculation_safe_value
13053 @findex fprintf_unlocked
13055 @findex fputs_unlocked
13164 @findex nexttowardf
13165 @findex nexttowardl
13173 @findex printf_unlocked
13204 @findex signbitd128
13205 @findex significand
13206 @findex significandf
13207 @findex significandl
13235 @findex strncasecmp
13279 GCC provides a large number of built-in functions other than the ones
13280 mentioned above. Some of these are for internal use in the processing
13281 of exceptions or variable-length argument lists and are not
13282 documented here because they may change from time to time; we do not
13283 recommend general use of these functions.
13285 The remaining functions are provided for optimization purposes.
13287 With the exception of built-ins that have library equivalents such as
13288 the standard C library functions discussed below, or that expand to
13289 library calls, GCC built-in functions are always expanded inline and
13290 thus do not have corresponding entry points and their address cannot
13291 be obtained. Attempting to use them in an expression other than
13292 a function call results in a compile-time error.
13294 @opindex fno-builtin
13295 GCC includes built-in versions of many of the functions in the standard
13296 C library. These functions come in two forms: one whose names start with
13297 the @code{__builtin_} prefix, and the other without. Both forms have the
13298 same type (including prototype), the same address (when their address is
13299 taken), and the same meaning as the C library functions even if you specify
13300 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
13301 functions are only optimized in certain cases; if they are not optimized in
13302 a particular case, a call to the library function is emitted.
13306 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
13307 @option{-std=c99} or @option{-std=c11}), the functions
13308 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
13309 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
13310 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
13311 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
13312 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
13313 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
13314 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
13315 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
13316 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
13317 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
13318 @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl},
13319 @code{scalbf}, @code{scalbl}, @code{scalb},
13320 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
13321 @code{signbitd64}, @code{signbitd128}, @code{significandf},
13322 @code{significandl}, @code{significand}, @code{sincosf},
13323 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
13324 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
13325 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
13326 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
13328 may be handled as built-in functions.
13329 All these functions have corresponding versions
13330 prefixed with @code{__builtin_}, which may be used even in strict C90
13333 The ISO C99 functions
13334 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
13335 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
13336 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
13337 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
13338 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
13339 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
13340 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
13341 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
13342 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
13343 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
13344 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
13345 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
13346 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
13347 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
13348 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
13349 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
13350 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
13351 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
13352 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
13353 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
13354 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
13355 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
13356 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
13357 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
13358 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
13359 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
13360 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
13361 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
13362 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
13363 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
13364 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
13365 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
13366 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
13367 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
13368 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
13369 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
13370 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
13371 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
13372 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
13373 are handled as built-in functions
13374 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
13376 There are also built-in versions of the ISO C99 functions
13377 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
13378 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
13379 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
13380 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
13381 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
13382 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
13383 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
13384 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
13385 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
13386 that are recognized in any mode since ISO C90 reserves these names for
13387 the purpose to which ISO C99 puts them. All these functions have
13388 corresponding versions prefixed with @code{__builtin_}.
13390 There are also built-in functions @code{__builtin_fabsf@var{n}},
13391 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
13392 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
13393 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
13394 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
13395 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
13397 There are also GNU extension functions @code{clog10}, @code{clog10f} and
13398 @code{clog10l} which names are reserved by ISO C99 for future use.
13399 All these functions have versions prefixed with @code{__builtin_}.
13401 The ISO C94 functions
13402 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
13403 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
13404 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
13406 are handled as built-in functions
13407 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
13409 The ISO C90 functions
13410 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
13411 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
13412 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
13413 @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf},
13414 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
13415 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
13416 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
13417 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
13418 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
13419 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
13420 @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin},
13421 @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
13422 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
13423 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
13424 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
13425 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
13426 are all recognized as built-in functions unless
13427 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
13428 is specified for an individual function). All of these functions have
13429 corresponding versions prefixed with @code{__builtin_}.
13431 GCC provides built-in versions of the ISO C99 floating-point comparison
13432 macros that avoid raising exceptions for unordered operands. They have
13433 the same names as the standard macros ( @code{isgreater},
13434 @code{isgreaterequal}, @code{isless}, @code{islessequal},
13435 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
13436 prefixed. We intend for a library implementor to be able to simply
13437 @code{#define} each standard macro to its built-in equivalent.
13438 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
13439 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
13440 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
13441 built-in functions appear both with and without the @code{__builtin_} prefix.
13443 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
13444 The @code{__builtin_alloca} function must be called at block scope.
13445 The function allocates an object @var{size} bytes large on the stack
13446 of the calling function. The object is aligned on the default stack
13447 alignment boundary for the target determined by the
13448 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
13449 function returns a pointer to the first byte of the allocated object.
13450 The lifetime of the allocated object ends just before the calling
13451 function returns to its caller. This is so even when
13452 @code{__builtin_alloca} is called within a nested block.
13454 For example, the following function allocates eight objects of @code{n}
13455 bytes each on the stack, storing a pointer to each in consecutive elements
13456 of the array @code{a}. It then passes the array to function @code{g}
13457 which can safely use the storage pointed to by each of the array elements.
13460 void f (unsigned n)
13463 for (int i = 0; i != 8; ++i)
13464 a [i] = __builtin_alloca (n);
13466 g (a, n); // @r{safe}
13470 Since the @code{__builtin_alloca} function doesn't validate its argument
13471 it is the responsibility of its caller to make sure the argument doesn't
13472 cause it to exceed the stack size limit.
13473 The @code{__builtin_alloca} function is provided to make it possible to
13474 allocate on the stack arrays of bytes with an upper bound that may be
13475 computed at run time. Since C99 Variable Length Arrays offer
13476 similar functionality under a portable, more convenient, and safer
13477 interface they are recommended instead, in both C99 and C++ programs
13478 where GCC provides them as an extension.
13479 @xref{Variable Length}, for details.
13483 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
13484 The @code{__builtin_alloca_with_align} function must be called at block
13485 scope. The function allocates an object @var{size} bytes large on
13486 the stack of the calling function. The allocated object is aligned on
13487 the boundary specified by the argument @var{alignment} whose unit is given
13488 in bits (not bytes). The @var{size} argument must be positive and not
13489 exceed the stack size limit. The @var{alignment} argument must be a constant
13490 integer expression that evaluates to a power of 2 greater than or equal to
13491 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
13492 with other values are rejected with an error indicating the valid bounds.
13493 The function returns a pointer to the first byte of the allocated object.
13494 The lifetime of the allocated object ends at the end of the block in which
13495 the function was called. The allocated storage is released no later than
13496 just before the calling function returns to its caller, but may be released
13497 at the end of the block in which the function was called.
13499 For example, in the following function the call to @code{g} is unsafe
13500 because when @code{overalign} is non-zero, the space allocated by
13501 @code{__builtin_alloca_with_align} may have been released at the end
13502 of the @code{if} statement in which it was called.
13505 void f (unsigned n, bool overalign)
13509 p = __builtin_alloca_with_align (n, 64 /* bits */);
13511 p = __builtin_alloc (n);
13513 g (p, n); // @r{unsafe}
13517 Since the @code{__builtin_alloca_with_align} function doesn't validate its
13518 @var{size} argument it is the responsibility of its caller to make sure
13519 the argument doesn't cause it to exceed the stack size limit.
13520 The @code{__builtin_alloca_with_align} function is provided to make
13521 it possible to allocate on the stack overaligned arrays of bytes with
13522 an upper bound that may be computed at run time. Since C99
13523 Variable Length Arrays offer the same functionality under
13524 a portable, more convenient, and safer interface they are recommended
13525 instead, in both C99 and C++ programs where GCC provides them as
13526 an extension. @xref{Variable Length}, for details.
13530 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
13531 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
13532 specifying an upper bound for @var{size} in case its value cannot be computed
13533 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
13534 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
13535 expression, it has no effect on code generation and no attempt is made to
13536 check its compatibility with @var{size}.
13540 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
13541 The @code{__builtin_has_attribute} function evaluates to an integer constant
13542 expression equal to @code{true} if the symbol or type referenced by
13543 the @var{type-or-expression} argument has been declared with
13544 the @var{attribute} referenced by the second argument. For
13545 an @var{type-or-expression} argument that does not reference a symbol,
13546 since attributes do not apply to expressions the built-in consider
13547 the type of the argument. Neither argument is evaluated.
13548 The @var{type-or-expression} argument is subject to the same
13549 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
13550 @var{attribute} argument is an attribute name optionally followed by
13551 a comma-separated list of arguments enclosed in parentheses. Both forms
13552 of attribute names---with and without double leading and trailing
13553 underscores---are recognized. @xref{Attribute Syntax}, for details.
13554 When no attribute arguments are specified for an attribute that expects
13555 one or more arguments the function returns @code{true} if
13556 @var{type-or-expression} has been declared with the attribute regardless
13557 of the attribute argument values. Arguments provided for an attribute
13558 that expects some are validated and matched up to the provided number.
13559 The function returns @code{true} if all provided arguments match. For
13560 example, the first call to the function below evaluates to @code{true}
13561 because @code{x} is declared with the @code{aligned} attribute but
13562 the second call evaluates to @code{false} because @code{x} is declared
13563 @code{aligned (8)} and not @code{aligned (4)}.
13566 __attribute__ ((aligned (8))) int x;
13567 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
13568 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
13571 Due to a limitation the @code{__builtin_has_attribute} function returns
13572 @code{false} for the @code{mode} attribute even if the type or variable
13573 referenced by the @var{type-or-expression} argument was declared with one.
13574 The function is also not supported with labels, and in C with enumerators.
13576 Note that unlike the @code{__has_attribute} preprocessor operator which
13577 is suitable for use in @code{#if} preprocessing directives
13578 @code{__builtin_has_attribute} is an intrinsic function that is not
13579 recognized in such contexts.
13583 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
13585 This built-in function can be used to help mitigate against unsafe
13586 speculative execution. @var{type} may be any integral type or any
13591 If the CPU is not speculatively executing the code, then @var{val}
13594 If the CPU is executing speculatively then either:
13597 The function may cause execution to pause until it is known that the
13598 code is no-longer being executed speculatively (in which case
13599 @var{val} can be returned, as above); or
13601 The function may use target-dependent speculation tracking state to cause
13602 @var{failval} to be returned when it is known that speculative
13603 execution has incorrectly predicted a conditional branch operation.
13607 The second argument, @var{failval}, is optional and defaults to zero
13610 GCC defines the preprocessor macro
13611 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
13612 updated to support this builtin.
13614 The built-in function can be used where a variable appears to be used in a
13615 safe way, but the CPU, due to speculative execution may temporarily ignore
13616 the bounds checks. Consider, for example, the following function:
13620 int f (unsigned untrusted_index)
13622 if (untrusted_index < 500)
13623 return array[untrusted_index];
13628 If the function is called repeatedly with @code{untrusted_index} less
13629 than the limit of 500, then a branch predictor will learn that the
13630 block of code that returns a value stored in @code{array} will be
13631 executed. If the function is subsequently called with an
13632 out-of-range value it will still try to execute that block of code
13633 first until the CPU determines that the prediction was incorrect
13634 (the CPU will unwind any incorrect operations at that point).
13635 However, depending on how the result of the function is used, it might be
13636 possible to leave traces in the cache that can reveal what was stored
13637 at the out-of-bounds location. The built-in function can be used to
13638 provide some protection against leaking data in this way by changing
13643 int f (unsigned untrusted_index)
13645 if (untrusted_index < 500)
13646 return array[__builtin_speculation_safe_value (untrusted_index)];
13651 The built-in function will either cause execution to stall until the
13652 conditional branch has been fully resolved, or it may permit
13653 speculative execution to continue, but using 0 instead of
13654 @code{untrusted_value} if that exceeds the limit.
13656 If accessing any memory location is potentially unsafe when speculative
13657 execution is incorrect, then the code can be rewritten as
13661 int f (unsigned untrusted_index)
13663 if (untrusted_index < 500)
13664 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
13669 which will cause a @code{NULL} pointer to be used for the unsafe case.
13673 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
13675 You can use the built-in function @code{__builtin_types_compatible_p} to
13676 determine whether two types are the same.
13678 This built-in function returns 1 if the unqualified versions of the
13679 types @var{type1} and @var{type2} (which are types, not expressions) are
13680 compatible, 0 otherwise. The result of this built-in function can be
13681 used in integer constant expressions.
13683 This built-in function ignores top level qualifiers (e.g., @code{const},
13684 @code{volatile}). For example, @code{int} is equivalent to @code{const
13687 The type @code{int[]} and @code{int[5]} are compatible. On the other
13688 hand, @code{int} and @code{char *} are not compatible, even if the size
13689 of their types, on the particular architecture are the same. Also, the
13690 amount of pointer indirection is taken into account when determining
13691 similarity. Consequently, @code{short *} is not similar to
13692 @code{short **}. Furthermore, two types that are typedefed are
13693 considered compatible if their underlying types are compatible.
13695 An @code{enum} type is not considered to be compatible with another
13696 @code{enum} type even if both are compatible with the same integer
13697 type; this is what the C standard specifies.
13698 For example, @code{enum @{foo, bar@}} is not similar to
13699 @code{enum @{hot, dog@}}.
13701 You typically use this function in code whose execution varies
13702 depending on the arguments' types. For example:
13707 typeof (x) tmp = (x); \
13708 if (__builtin_types_compatible_p (typeof (x), long double)) \
13709 tmp = foo_long_double (tmp); \
13710 else if (__builtin_types_compatible_p (typeof (x), double)) \
13711 tmp = foo_double (tmp); \
13712 else if (__builtin_types_compatible_p (typeof (x), float)) \
13713 tmp = foo_float (tmp); \
13720 @emph{Note:} This construct is only available for C@.
13724 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
13726 The @var{call_exp} expression must be a function call, and the
13727 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
13728 is passed to the function call in the target's static chain location.
13729 The result of builtin is the result of the function call.
13731 @emph{Note:} This builtin is only available for C@.
13732 This builtin can be used to call Go closures from C.
13736 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
13738 You can use the built-in function @code{__builtin_choose_expr} to
13739 evaluate code depending on the value of a constant expression. This
13740 built-in function returns @var{exp1} if @var{const_exp}, which is an
13741 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
13743 This built-in function is analogous to the @samp{? :} operator in C,
13744 except that the expression returned has its type unaltered by promotion
13745 rules. Also, the built-in function does not evaluate the expression
13746 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
13747 @var{exp2} is not evaluated even if it has side effects.
13749 This built-in function can return an lvalue if the chosen argument is an
13752 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
13753 type. Similarly, if @var{exp2} is returned, its return type is the same
13760 __builtin_choose_expr ( \
13761 __builtin_types_compatible_p (typeof (x), double), \
13763 __builtin_choose_expr ( \
13764 __builtin_types_compatible_p (typeof (x), float), \
13766 /* @r{The void expression results in a compile-time error} \
13767 @r{when assigning the result to something.} */ \
13771 @emph{Note:} This construct is only available for C@. Furthermore, the
13772 unused expression (@var{exp1} or @var{exp2} depending on the value of
13773 @var{const_exp}) may still generate syntax errors. This may change in
13778 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
13780 The built-in function @code{__builtin_tgmath}, available only for C
13781 and Objective-C, calls a function determined according to the rules of
13782 @code{<tgmath.h>} macros. It is intended to be used in
13783 implementations of that header, so that expansions of macros from that
13784 header only expand each of their arguments once, to avoid problems
13785 when calls to such macros are nested inside the arguments of other
13786 calls to such macros; in addition, it results in better diagnostics
13787 for invalid calls to @code{<tgmath.h>} macros than implementations
13788 using other GNU C language features. For example, the @code{pow}
13789 type-generic macro might be defined as:
13792 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
13793 cpowf, cpow, cpowl, a, b)
13796 The arguments to @code{__builtin_tgmath} are at least two pointers to
13797 functions, followed by the arguments to the type-generic macro (which
13798 will be passed as arguments to the selected function). All the
13799 pointers to functions must be pointers to prototyped functions, none
13800 of which may have variable arguments, and all of which must have the
13801 same number of parameters; the number of parameters of the first
13802 function determines how many arguments to @code{__builtin_tgmath} are
13803 interpreted as function pointers, and how many as the arguments to the
13806 The types of the specified functions must all be different, but
13807 related to each other in the same way as a set of functions that may
13808 be selected between by a macro in @code{<tgmath.h>}. This means that
13809 the functions are parameterized by a floating-point type @var{t},
13810 different for each such function. The function return types may all
13811 be the same type, or they may be @var{t} for each function, or they
13812 may be the real type corresponding to @var{t} for each function (if
13813 some of the types @var{t} are complex). Likewise, for each parameter
13814 position, the type of the parameter in that position may always be the
13815 same type, or may be @var{t} for each function (this case must apply
13816 for at least one parameter position), or may be the real type
13817 corresponding to @var{t} for each function.
13819 The standard rules for @code{<tgmath.h>} macros are used to find a
13820 common type @var{u} from the types of the arguments for parameters
13821 whose types vary between the functions; complex integer types (a GNU
13822 extension) are treated like @code{_Complex double} for this purpose
13823 (or @code{_Complex _Float64} if all the function return types are the
13824 same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
13825 If the function return types vary, or are all the same integer type,
13826 the function called is the one for which @var{t} is @var{u}, and it is
13827 an error if there is no such function. If the function return types
13828 are all the same floating-point type, the type-generic macro is taken
13829 to be one of those from TS 18661 that rounds the result to a narrower
13830 type; if there is a function for which @var{t} is @var{u}, it is
13831 called, and otherwise the first function, if any, for which @var{t}
13832 has at least the range and precision of @var{u} is called, and it is
13833 an error if there is no such function.
13837 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
13839 The built-in function @code{__builtin_complex} is provided for use in
13840 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
13841 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
13842 real binary floating-point type, and the result has the corresponding
13843 complex type with real and imaginary parts @var{real} and @var{imag}.
13844 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
13845 infinities, NaNs and negative zeros are involved.
13849 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
13850 You can use the built-in function @code{__builtin_constant_p} to
13851 determine if a value is known to be constant at compile time and hence
13852 that GCC can perform constant-folding on expressions involving that
13853 value. The argument of the function is the value to test. The function
13854 returns the integer 1 if the argument is known to be a compile-time
13855 constant and 0 if it is not known to be a compile-time constant. A
13856 return of 0 does not indicate that the value is @emph{not} a constant,
13857 but merely that GCC cannot prove it is a constant with the specified
13858 value of the @option{-O} option.
13860 You typically use this function in an embedded application where
13861 memory is a critical resource. If you have some complex calculation,
13862 you may want it to be folded if it involves constants, but need to call
13863 a function if it does not. For example:
13866 #define Scale_Value(X) \
13867 (__builtin_constant_p (X) \
13868 ? ((X) * SCALE + OFFSET) : Scale (X))
13871 You may use this built-in function in either a macro or an inline
13872 function. However, if you use it in an inlined function and pass an
13873 argument of the function as the argument to the built-in, GCC
13874 never returns 1 when you call the inline function with a string constant
13875 or compound literal (@pxref{Compound Literals}) and does not return 1
13876 when you pass a constant numeric value to the inline function unless you
13877 specify the @option{-O} option.
13879 You may also use @code{__builtin_constant_p} in initializers for static
13880 data. For instance, you can write
13883 static const int table[] = @{
13884 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
13890 This is an acceptable initializer even if @var{EXPRESSION} is not a
13891 constant expression, including the case where
13892 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
13893 folded to a constant but @var{EXPRESSION} contains operands that are
13894 not otherwise permitted in a static initializer (for example,
13895 @code{0 && foo ()}). GCC must be more conservative about evaluating the
13896 built-in in this case, because it has no opportunity to perform
13900 @deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void)
13901 The @code{__builtin_is_constant_evaluated} function is available only
13902 in C++. The built-in is intended to be used by implementations of
13903 the @code{std::is_constant_evaluated} C++ function. Programs should make
13904 use of the latter function rather than invoking the built-in directly.
13906 The main use case of the built-in is to determine whether a @code{constexpr}
13907 function is being called in a @code{constexpr} context. A call to
13908 the function evaluates to a core constant expression with the value
13909 @code{true} if and only if it occurs within the evaluation of an expression
13910 or conversion that is manifestly constant-evaluated as defined in the C++
13911 standard. Manifestly constant-evaluated contexts include constant-expressions,
13912 the conditions of @code{constexpr if} statements, constraint-expressions, and
13913 initializers of variables usable in constant expressions. For more details
13914 refer to the latest revision of the C++ standard.
13917 @deftypefn {Built-in Function} void __builtin_clear_padding (@var{ptr})
13918 The built-in function @code{__builtin_clear_padding} function clears
13919 padding bits inside of the object representation of object pointed by
13920 @var{ptr}, which has to be a pointer. The value representation of the
13921 object is not affected. The type of the object is assumed to be the type
13922 the pointer points to. Inside of a union, the only cleared bits are
13923 bits that are padding bits for all the union members.
13925 This built-in-function is useful if the padding bits of an object might
13926 have intederminate values and the object representation needs to be
13927 bitwise compared to some other object, for example for atomic operations.
13930 @deftypefn {Built-in Function} @var{type} __builtin_bit_cast (@var{type}, @var{arg})
13931 The @code{__builtin_bit_cast} function is available only
13932 in C++. The built-in is intended to be used by implementations of
13933 the @code{std::bit_cast} C++ template function. Programs should make
13934 use of the latter function rather than invoking the built-in directly.
13936 This built-in function allows reinterpreting the bits of the @var{arg}
13937 argument as if it had type @var{type}. @var{type} and the type of the
13938 @var{arg} argument need to be trivially copyable types with the same size.
13939 When manifestly constant-evaluated, it performs extra diagnostics required
13940 for @code{std::bit_cast} and returns a constant expression if @var{arg}
13941 is a constant expression. For more details
13942 refer to the latest revision of the C++ standard.
13945 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
13946 @opindex fprofile-arcs
13947 You may use @code{__builtin_expect} to provide the compiler with
13948 branch prediction information. In general, you should prefer to
13949 use actual profile feedback for this (@option{-fprofile-arcs}), as
13950 programmers are notoriously bad at predicting how their programs
13951 actually perform. However, there are applications in which this
13952 data is hard to collect.
13954 The return value is the value of @var{exp}, which should be an integral
13955 expression. The semantics of the built-in are that it is expected that
13956 @var{exp} == @var{c}. For example:
13959 if (__builtin_expect (x, 0))
13964 indicates that we do not expect to call @code{foo}, since
13965 we expect @code{x} to be zero. Since you are limited to integral
13966 expressions for @var{exp}, you should use constructions such as
13969 if (__builtin_expect (ptr != NULL, 1))
13974 when testing pointer or floating-point values.
13976 For the purposes of branch prediction optimizations, the probability that
13977 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
13978 @code{builtin-expect-probability} parameter, which defaults to 90%.
13980 You can also use @code{__builtin_expect_with_probability} to explicitly
13981 assign a probability value to individual expressions. If the built-in
13982 is used in a loop construct, the provided probability will influence
13983 the expected number of iterations made by loop optimizations.
13986 @deftypefn {Built-in Function} long __builtin_expect_with_probability
13987 (long @var{exp}, long @var{c}, double @var{probability})
13989 This function has the same semantics as @code{__builtin_expect},
13990 but the caller provides the expected probability that @var{exp} == @var{c}.
13991 The last argument, @var{probability}, is a floating-point value in the
13992 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
13993 constant floating-point expression.
13996 @deftypefn {Built-in Function} void __builtin_trap (void)
13997 This function causes the program to exit abnormally. GCC implements
13998 this function by using a target-dependent mechanism (such as
13999 intentionally executing an illegal instruction) or by calling
14000 @code{abort}. The mechanism used may vary from release to release so
14001 you should not rely on any particular implementation.
14004 @deftypefn {Built-in Function} void __builtin_unreachable (void)
14005 If control flow reaches the point of the @code{__builtin_unreachable},
14006 the program is undefined. It is useful in situations where the
14007 compiler cannot deduce the unreachability of the code.
14009 One such case is immediately following an @code{asm} statement that
14010 either never terminates, or one that transfers control elsewhere
14011 and never returns. In this example, without the
14012 @code{__builtin_unreachable}, GCC issues a warning that control
14013 reaches the end of a non-void function. It also generates code
14014 to return after the @code{asm}.
14017 int f (int c, int v)
14025 asm("jmp error_handler");
14026 __builtin_unreachable ();
14032 Because the @code{asm} statement unconditionally transfers control out
14033 of the function, control never reaches the end of the function
14034 body. The @code{__builtin_unreachable} is in fact unreachable and
14035 communicates this fact to the compiler.
14037 Another use for @code{__builtin_unreachable} is following a call a
14038 function that never returns but that is not declared
14039 @code{__attribute__((noreturn))}, as in this example:
14042 void function_that_never_returns (void);
14052 function_that_never_returns ();
14053 __builtin_unreachable ();
14060 @deftypefn {Built-in Function} @var{type} __builtin_assoc_barrier (@var{type} @var{expr})
14061 This built-in inhibits re-association of the floating-point expression
14062 @var{expr} with expressions consuming the return value of the built-in. The
14063 expression @var{expr} itself can be reordered, and the whole expression
14064 @var{expr} can be reordered with operands after the barrier. The barrier is
14065 only relevant when @code{-fassociative-math} is active, since otherwise
14066 floating-point is not treated as associative.
14069 float x0 = a + b - b;
14070 float x1 = __builtin_assoc_barrier(a + b) - b;
14074 means that, with @code{-fassociative-math}, @code{x0} can be optimized to
14075 @code{x0 = a} but @code{x1} cannot.
14078 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
14079 This function returns its first argument, and allows the compiler
14080 to assume that the returned pointer is at least @var{align} bytes
14081 aligned. This built-in can have either two or three arguments,
14082 if it has three, the third argument should have integer type, and
14083 if it is nonzero means misalignment offset. For example:
14086 void *x = __builtin_assume_aligned (arg, 16);
14090 means that the compiler can assume @code{x}, set to @code{arg}, is at least
14091 16-byte aligned, while:
14094 void *x = __builtin_assume_aligned (arg, 32, 8);
14098 means that the compiler can assume for @code{x}, set to @code{arg}, that
14099 @code{(char *) x - 8} is 32-byte aligned.
14102 @deftypefn {Built-in Function} int __builtin_LINE ()
14103 This function is the equivalent of the preprocessor @code{__LINE__}
14104 macro and returns a constant integer expression that evaluates to
14105 the line number of the invocation of the built-in. When used as a C++
14106 default argument for a function @var{F}, it returns the line number
14107 of the call to @var{F}.
14110 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
14111 This function is the equivalent of the @code{__FUNCTION__} symbol
14112 and returns an address constant pointing to the name of the function
14113 from which the built-in was invoked, or the empty string if
14114 the invocation is not at function scope. When used as a C++ default
14115 argument for a function @var{F}, it returns the name of @var{F}'s
14116 caller or the empty string if the call was not made at function
14120 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
14121 This function is the equivalent of the preprocessor @code{__FILE__}
14122 macro and returns an address constant pointing to the file name
14123 containing the invocation of the built-in, or the empty string if
14124 the invocation is not at function scope. When used as a C++ default
14125 argument for a function @var{F}, it returns the file name of the call
14126 to @var{F} or the empty string if the call was not made at function
14129 For example, in the following, each call to function @code{foo} will
14130 print a line similar to @code{"file.c:123: foo: message"} with the name
14131 of the file and the line number of the @code{printf} call, the name of
14132 the function @code{foo}, followed by the word @code{message}.
14136 function (const char *func = __builtin_FUNCTION ())
14143 printf ("%s:%i: %s: message\n", file (), line (), function ());
14149 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
14150 This function is used to flush the processor's instruction cache for
14151 the region of memory between @var{begin} inclusive and @var{end}
14152 exclusive. Some targets require that the instruction cache be
14153 flushed, after modifying memory containing code, in order to obtain
14154 deterministic behavior.
14156 If the target does not require instruction cache flushes,
14157 @code{__builtin___clear_cache} has no effect. Otherwise either
14158 instructions are emitted in-line to clear the instruction cache or a
14159 call to the @code{__clear_cache} function in libgcc is made.
14162 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
14163 This function is used to minimize cache-miss latency by moving data into
14164 a cache before it is accessed.
14165 You can insert calls to @code{__builtin_prefetch} into code for which
14166 you know addresses of data in memory that is likely to be accessed soon.
14167 If the target supports them, data prefetch instructions are generated.
14168 If the prefetch is done early enough before the access then the data will
14169 be in the cache by the time it is accessed.
14171 The value of @var{addr} is the address of the memory to prefetch.
14172 There are two optional arguments, @var{rw} and @var{locality}.
14173 The value of @var{rw} is a compile-time constant one or zero; one
14174 means that the prefetch is preparing for a write to the memory address
14175 and zero, the default, means that the prefetch is preparing for a read.
14176 The value @var{locality} must be a compile-time constant integer between
14177 zero and three. A value of zero means that the data has no temporal
14178 locality, so it need not be left in the cache after the access. A value
14179 of three means that the data has a high degree of temporal locality and
14180 should be left in all levels of cache possible. Values of one and two
14181 mean, respectively, a low or moderate degree of temporal locality. The
14185 for (i = 0; i < n; i++)
14187 a[i] = a[i] + b[i];
14188 __builtin_prefetch (&a[i+j], 1, 1);
14189 __builtin_prefetch (&b[i+j], 0, 1);
14194 Data prefetch does not generate faults if @var{addr} is invalid, but
14195 the address expression itself must be valid. For example, a prefetch
14196 of @code{p->next} does not fault if @code{p->next} is not a valid
14197 address, but evaluation faults if @code{p} is not a valid address.
14199 If the target does not support data prefetch, the address expression
14200 is evaluated if it includes side effects but no other code is generated
14201 and GCC does not issue a warning.
14204 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
14205 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size
14206 Checking}, for a detailed description of the function.
14209 @deftypefn {Built-in Function} double __builtin_huge_val (void)
14210 Returns a positive infinity, if supported by the floating-point format,
14211 else @code{DBL_MAX}. This function is suitable for implementing the
14212 ISO C macro @code{HUGE_VAL}.
14215 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
14216 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
14219 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
14220 Similar to @code{__builtin_huge_val}, except the return
14221 type is @code{long double}.
14224 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
14225 Similar to @code{__builtin_huge_val}, except the return type is
14226 @code{_Float@var{n}}.
14229 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
14230 Similar to @code{__builtin_huge_val}, except the return type is
14231 @code{_Float@var{n}x}.
14234 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
14235 This built-in implements the C99 fpclassify functionality. The first
14236 five int arguments should be the target library's notion of the
14237 possible FP classes and are used for return values. They must be
14238 constant values and they must appear in this order: @code{FP_NAN},
14239 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
14240 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
14241 to classify. GCC treats the last argument as type-generic, which
14242 means it does not do default promotion from float to double.
14245 @deftypefn {Built-in Function} double __builtin_inf (void)
14246 Similar to @code{__builtin_huge_val}, except a warning is generated
14247 if the target floating-point format does not support infinities.
14250 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
14251 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
14254 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
14255 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
14258 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
14259 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
14262 @deftypefn {Built-in Function} float __builtin_inff (void)
14263 Similar to @code{__builtin_inf}, except the return type is @code{float}.
14264 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
14267 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
14268 Similar to @code{__builtin_inf}, except the return
14269 type is @code{long double}.
14272 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
14273 Similar to @code{__builtin_inf}, except the return
14274 type is @code{_Float@var{n}}.
14277 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
14278 Similar to @code{__builtin_inf}, except the return
14279 type is @code{_Float@var{n}x}.
14282 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
14283 Similar to @code{isinf}, except the return value is -1 for
14284 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
14285 Note while the parameter list is an
14286 ellipsis, this function only accepts exactly one floating-point
14287 argument. GCC treats this parameter as type-generic, which means it
14288 does not do default promotion from float to double.
14291 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
14292 This is an implementation of the ISO C99 function @code{nan}.
14294 Since ISO C99 defines this function in terms of @code{strtod}, which we
14295 do not implement, a description of the parsing is in order. The string
14296 is parsed as by @code{strtol}; that is, the base is recognized by
14297 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
14298 in the significand such that the least significant bit of the number
14299 is at the least significant bit of the significand. The number is
14300 truncated to fit the significand field provided. The significand is
14301 forced to be a quiet NaN@.
14303 This function, if given a string literal all of which would have been
14304 consumed by @code{strtol}, is evaluated early enough that it is considered a
14305 compile-time constant.
14308 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
14309 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
14312 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
14313 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
14316 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
14317 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
14320 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
14321 Similar to @code{__builtin_nan}, except the return type is @code{float}.
14324 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
14325 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
14328 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
14329 Similar to @code{__builtin_nan}, except the return type is
14330 @code{_Float@var{n}}.
14333 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
14334 Similar to @code{__builtin_nan}, except the return type is
14335 @code{_Float@var{n}x}.
14338 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
14339 Similar to @code{__builtin_nan}, except the significand is forced
14340 to be a signaling NaN@. The @code{nans} function is proposed by
14341 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
14344 @deftypefn {Built-in Function} _Decimal32 __builtin_nansd32 (const char *str)
14345 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}.
14348 @deftypefn {Built-in Function} _Decimal64 __builtin_nansd64 (const char *str)
14349 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}.
14352 @deftypefn {Built-in Function} _Decimal128 __builtin_nansd128 (const char *str)
14353 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}.
14356 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
14357 Similar to @code{__builtin_nans}, except the return type is @code{float}.
14360 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
14361 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
14364 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
14365 Similar to @code{__builtin_nans}, except the return type is
14366 @code{_Float@var{n}}.
14369 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
14370 Similar to @code{__builtin_nans}, except the return type is
14371 @code{_Float@var{n}x}.
14374 @deftypefn {Built-in Function} int __builtin_ffs (int x)
14375 Returns one plus the index of the least significant 1-bit of @var{x}, or
14376 if @var{x} is zero, returns zero.
14379 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
14380 Returns the number of leading 0-bits in @var{x}, starting at the most
14381 significant bit position. If @var{x} is 0, the result is undefined.
14384 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
14385 Returns the number of trailing 0-bits in @var{x}, starting at the least
14386 significant bit position. If @var{x} is 0, the result is undefined.
14389 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
14390 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
14391 number of bits following the most significant bit that are identical
14392 to it. There are no special cases for 0 or other values.
14395 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
14396 Returns the number of 1-bits in @var{x}.
14399 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
14400 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
14404 @deftypefn {Built-in Function} int __builtin_ffsl (long)
14405 Similar to @code{__builtin_ffs}, except the argument type is
14409 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
14410 Similar to @code{__builtin_clz}, except the argument type is
14411 @code{unsigned long}.
14414 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
14415 Similar to @code{__builtin_ctz}, except the argument type is
14416 @code{unsigned long}.
14419 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
14420 Similar to @code{__builtin_clrsb}, except the argument type is
14424 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
14425 Similar to @code{__builtin_popcount}, except the argument type is
14426 @code{unsigned long}.
14429 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
14430 Similar to @code{__builtin_parity}, except the argument type is
14431 @code{unsigned long}.
14434 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
14435 Similar to @code{__builtin_ffs}, except the argument type is
14439 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
14440 Similar to @code{__builtin_clz}, except the argument type is
14441 @code{unsigned long long}.
14444 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
14445 Similar to @code{__builtin_ctz}, except the argument type is
14446 @code{unsigned long long}.
14449 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
14450 Similar to @code{__builtin_clrsb}, except the argument type is
14454 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
14455 Similar to @code{__builtin_popcount}, except the argument type is
14456 @code{unsigned long long}.
14459 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
14460 Similar to @code{__builtin_parity}, except the argument type is
14461 @code{unsigned long long}.
14464 @deftypefn {Built-in Function} double __builtin_powi (double, int)
14465 Returns the first argument raised to the power of the second. Unlike the
14466 @code{pow} function no guarantees about precision and rounding are made.
14469 @deftypefn {Built-in Function} float __builtin_powif (float, int)
14470 Similar to @code{__builtin_powi}, except the argument and return types
14474 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
14475 Similar to @code{__builtin_powi}, except the argument and return types
14476 are @code{long double}.
14479 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
14480 Returns @var{x} with the order of the bytes reversed; for example,
14481 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
14485 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
14486 Similar to @code{__builtin_bswap16}, except the argument and return types
14490 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
14491 Similar to @code{__builtin_bswap32}, except the argument and return types
14495 @deftypefn {Built-in Function} uint128_t __builtin_bswap128 (uint128_t x)
14496 Similar to @code{__builtin_bswap64}, except the argument and return types
14497 are 128-bit. Only supported on targets when 128-bit types are supported.
14501 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
14502 On targets where the user visible pointer size is smaller than the size
14503 of an actual hardware address this function returns the extended user
14504 pointer. Targets where this is true included ILP32 mode on x86_64 or
14505 Aarch64. This function is mainly useful when writing inline assembly
14509 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
14510 Returns the openacc gang, worker or vector id depending on whether @var{x} is
14514 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
14515 Returns the openacc gang, worker or vector size depending on whether @var{x} is
14519 @node Target Builtins
14520 @section Built-in Functions Specific to Particular Target Machines
14522 On some target machines, GCC supports many built-in functions specific
14523 to those machines. Generally these generate calls to specific machine
14524 instructions, but allow the compiler to schedule those calls.
14527 * AArch64 Built-in Functions::
14528 * Alpha Built-in Functions::
14529 * Altera Nios II Built-in Functions::
14530 * ARC Built-in Functions::
14531 * ARC SIMD Built-in Functions::
14532 * ARM iWMMXt Built-in Functions::
14533 * ARM C Language Extensions (ACLE)::
14534 * ARM Floating Point Status and Control Intrinsics::
14535 * ARM ARMv8-M Security Extensions::
14536 * AVR Built-in Functions::
14537 * Blackfin Built-in Functions::
14538 * BPF Built-in Functions::
14539 * FR-V Built-in Functions::
14540 * MIPS DSP Built-in Functions::
14541 * MIPS Paired-Single Support::
14542 * MIPS Loongson Built-in Functions::
14543 * MIPS SIMD Architecture (MSA) Support::
14544 * Other MIPS Built-in Functions::
14545 * MSP430 Built-in Functions::
14546 * NDS32 Built-in Functions::
14547 * picoChip Built-in Functions::
14548 * Basic PowerPC Built-in Functions::
14549 * PowerPC AltiVec/VSX Built-in Functions::
14550 * PowerPC Hardware Transactional Memory Built-in Functions::
14551 * PowerPC Atomic Memory Operation Functions::
14552 * PowerPC Matrix-Multiply Assist Built-in Functions::
14553 * PRU Built-in Functions::
14554 * RISC-V Built-in Functions::
14555 * RX Built-in Functions::
14556 * S/390 System z Built-in Functions::
14557 * SH Built-in Functions::
14558 * SPARC VIS Built-in Functions::
14559 * TI C6X Built-in Functions::
14560 * TILE-Gx Built-in Functions::
14561 * TILEPro Built-in Functions::
14562 * x86 Built-in Functions::
14563 * x86 transactional memory intrinsics::
14564 * x86 control-flow protection intrinsics::
14567 @node AArch64 Built-in Functions
14568 @subsection AArch64 Built-in Functions
14570 These built-in functions are available for the AArch64 family of
14573 unsigned int __builtin_aarch64_get_fpcr ();
14574 void __builtin_aarch64_set_fpcr (unsigned int);
14575 unsigned int __builtin_aarch64_get_fpsr ();
14576 void __builtin_aarch64_set_fpsr (unsigned int);
14578 unsigned long long __builtin_aarch64_get_fpcr64 ();
14579 void __builtin_aarch64_set_fpcr64 (unsigned long long);
14580 unsigned long long __builtin_aarch64_get_fpsr64 ();
14581 void __builtin_aarch64_set_fpsr64 (unsigned long long);
14584 @node Alpha Built-in Functions
14585 @subsection Alpha Built-in Functions
14587 These built-in functions are available for the Alpha family of
14588 processors, depending on the command-line switches used.
14590 The following built-in functions are always available. They
14591 all generate the machine instruction that is part of the name.
14594 long __builtin_alpha_implver (void);
14595 long __builtin_alpha_rpcc (void);
14596 long __builtin_alpha_amask (long);
14597 long __builtin_alpha_cmpbge (long, long);
14598 long __builtin_alpha_extbl (long, long);
14599 long __builtin_alpha_extwl (long, long);
14600 long __builtin_alpha_extll (long, long);
14601 long __builtin_alpha_extql (long, long);
14602 long __builtin_alpha_extwh (long, long);
14603 long __builtin_alpha_extlh (long, long);
14604 long __builtin_alpha_extqh (long, long);
14605 long __builtin_alpha_insbl (long, long);
14606 long __builtin_alpha_inswl (long, long);
14607 long __builtin_alpha_insll (long, long);
14608 long __builtin_alpha_insql (long, long);
14609 long __builtin_alpha_inswh (long, long);
14610 long __builtin_alpha_inslh (long, long);
14611 long __builtin_alpha_insqh (long, long);
14612 long __builtin_alpha_mskbl (long, long);
14613 long __builtin_alpha_mskwl (long, long);
14614 long __builtin_alpha_mskll (long, long);
14615 long __builtin_alpha_mskql (long, long);
14616 long __builtin_alpha_mskwh (long, long);
14617 long __builtin_alpha_msklh (long, long);
14618 long __builtin_alpha_mskqh (long, long);
14619 long __builtin_alpha_umulh (long, long);
14620 long __builtin_alpha_zap (long, long);
14621 long __builtin_alpha_zapnot (long, long);
14624 The following built-in functions are always with @option{-mmax}
14625 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
14626 later. They all generate the machine instruction that is part
14630 long __builtin_alpha_pklb (long);
14631 long __builtin_alpha_pkwb (long);
14632 long __builtin_alpha_unpkbl (long);
14633 long __builtin_alpha_unpkbw (long);
14634 long __builtin_alpha_minub8 (long, long);
14635 long __builtin_alpha_minsb8 (long, long);
14636 long __builtin_alpha_minuw4 (long, long);
14637 long __builtin_alpha_minsw4 (long, long);
14638 long __builtin_alpha_maxub8 (long, long);
14639 long __builtin_alpha_maxsb8 (long, long);
14640 long __builtin_alpha_maxuw4 (long, long);
14641 long __builtin_alpha_maxsw4 (long, long);
14642 long __builtin_alpha_perr (long, long);
14645 The following built-in functions are always with @option{-mcix}
14646 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
14647 later. They all generate the machine instruction that is part
14651 long __builtin_alpha_cttz (long);
14652 long __builtin_alpha_ctlz (long);
14653 long __builtin_alpha_ctpop (long);
14656 The following built-in functions are available on systems that use the OSF/1
14657 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
14658 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
14659 @code{rdval} and @code{wrval}.
14662 void *__builtin_thread_pointer (void);
14663 void __builtin_set_thread_pointer (void *);
14666 @node Altera Nios II Built-in Functions
14667 @subsection Altera Nios II Built-in Functions
14669 These built-in functions are available for the Altera Nios II
14670 family of processors.
14672 The following built-in functions are always available. They
14673 all generate the machine instruction that is part of the name.
14676 int __builtin_ldbio (volatile const void *);
14677 int __builtin_ldbuio (volatile const void *);
14678 int __builtin_ldhio (volatile const void *);
14679 int __builtin_ldhuio (volatile const void *);
14680 int __builtin_ldwio (volatile const void *);
14681 void __builtin_stbio (volatile void *, int);
14682 void __builtin_sthio (volatile void *, int);
14683 void __builtin_stwio (volatile void *, int);
14684 void __builtin_sync (void);
14685 int __builtin_rdctl (int);
14686 int __builtin_rdprs (int, int);
14687 void __builtin_wrctl (int, int);
14688 void __builtin_flushd (volatile void *);
14689 void __builtin_flushda (volatile void *);
14690 int __builtin_wrpie (int);
14691 void __builtin_eni (int);
14692 int __builtin_ldex (volatile const void *);
14693 int __builtin_stex (volatile void *, int);
14694 int __builtin_ldsex (volatile const void *);
14695 int __builtin_stsex (volatile void *, int);
14698 The following built-in functions are always available. They
14699 all generate a Nios II Custom Instruction. The name of the
14700 function represents the types that the function takes and
14701 returns. The letter before the @code{n} is the return type
14702 or void if absent. The @code{n} represents the first parameter
14703 to all the custom instructions, the custom instruction number.
14704 The two letters after the @code{n} represent the up to two
14705 parameters to the function.
14707 The letters represent the following data types:
14710 @code{void} for return type and no parameter for parameter types.
14713 @code{int} for return type and parameter type
14716 @code{float} for return type and parameter type
14719 @code{void *} for return type and parameter type
14723 And the function names are:
14725 void __builtin_custom_n (void);
14726 void __builtin_custom_ni (int);
14727 void __builtin_custom_nf (float);
14728 void __builtin_custom_np (void *);
14729 void __builtin_custom_nii (int, int);
14730 void __builtin_custom_nif (int, float);
14731 void __builtin_custom_nip (int, void *);
14732 void __builtin_custom_nfi (float, int);
14733 void __builtin_custom_nff (float, float);
14734 void __builtin_custom_nfp (float, void *);
14735 void __builtin_custom_npi (void *, int);
14736 void __builtin_custom_npf (void *, float);
14737 void __builtin_custom_npp (void *, void *);
14738 int __builtin_custom_in (void);
14739 int __builtin_custom_ini (int);
14740 int __builtin_custom_inf (float);
14741 int __builtin_custom_inp (void *);
14742 int __builtin_custom_inii (int, int);
14743 int __builtin_custom_inif (int, float);
14744 int __builtin_custom_inip (int, void *);
14745 int __builtin_custom_infi (float, int);
14746 int __builtin_custom_inff (float, float);
14747 int __builtin_custom_infp (float, void *);
14748 int __builtin_custom_inpi (void *, int);
14749 int __builtin_custom_inpf (void *, float);
14750 int __builtin_custom_inpp (void *, void *);
14751 float __builtin_custom_fn (void);
14752 float __builtin_custom_fni (int);
14753 float __builtin_custom_fnf (float);
14754 float __builtin_custom_fnp (void *);
14755 float __builtin_custom_fnii (int, int);
14756 float __builtin_custom_fnif (int, float);
14757 float __builtin_custom_fnip (int, void *);
14758 float __builtin_custom_fnfi (float, int);
14759 float __builtin_custom_fnff (float, float);
14760 float __builtin_custom_fnfp (float, void *);
14761 float __builtin_custom_fnpi (void *, int);
14762 float __builtin_custom_fnpf (void *, float);
14763 float __builtin_custom_fnpp (void *, void *);
14764 void * __builtin_custom_pn (void);
14765 void * __builtin_custom_pni (int);
14766 void * __builtin_custom_pnf (float);
14767 void * __builtin_custom_pnp (void *);
14768 void * __builtin_custom_pnii (int, int);
14769 void * __builtin_custom_pnif (int, float);
14770 void * __builtin_custom_pnip (int, void *);
14771 void * __builtin_custom_pnfi (float, int);
14772 void * __builtin_custom_pnff (float, float);
14773 void * __builtin_custom_pnfp (float, void *);
14774 void * __builtin_custom_pnpi (void *, int);
14775 void * __builtin_custom_pnpf (void *, float);
14776 void * __builtin_custom_pnpp (void *, void *);
14779 @node ARC Built-in Functions
14780 @subsection ARC Built-in Functions
14782 The following built-in functions are provided for ARC targets. The
14783 built-ins generate the corresponding assembly instructions. In the
14784 examples given below, the generated code often requires an operand or
14785 result to be in a register. Where necessary further code will be
14786 generated to ensure this is true, but for brevity this is not
14787 described in each case.
14789 @emph{Note:} Using a built-in to generate an instruction not supported
14790 by a target may cause problems. At present the compiler is not
14791 guaranteed to detect such misuse, and as a result an internal compiler
14792 error may be generated.
14794 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
14795 Return 1 if @var{val} is known to have the byte alignment given
14796 by @var{alignval}, otherwise return 0.
14797 Note that this is different from
14799 __alignof__(*(char *)@var{val}) >= alignval
14801 because __alignof__ sees only the type of the dereference, whereas
14802 __builtin_arc_align uses alignment information from the pointer
14803 as well as from the pointed-to type.
14804 The information available will depend on optimization level.
14807 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
14814 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
14815 The operand is the number of a register to be read. Generates:
14817 mov @var{dest}, r@var{regno}
14819 where the value in @var{dest} will be the result returned from the
14823 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
14824 The first operand is the number of a register to be written, the
14825 second operand is a compile time constant to write into that
14826 register. Generates:
14828 mov r@var{regno}, @var{val}
14832 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
14833 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
14836 divaw @var{dest}, @var{a}, @var{b}
14838 where the value in @var{dest} will be the result returned from the
14842 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
14849 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
14850 The operand, @var{auxv}, is the address of an auxiliary register and
14851 must be a compile time constant. Generates:
14853 lr @var{dest}, [@var{auxr}]
14855 Where the value in @var{dest} will be the result returned from the
14859 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
14860 Only available with @option{-mmul64}. Generates:
14862 mul64 @var{a}, @var{b}
14866 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
14867 Only available with @option{-mmul64}. Generates:
14869 mulu64 @var{a}, @var{b}
14873 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
14880 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
14881 Only valid if the @samp{norm} instruction is available through the
14882 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14885 norm @var{dest}, @var{src}
14887 Where the value in @var{dest} will be the result returned from the
14891 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
14892 Only valid if the @samp{normw} instruction is available through the
14893 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14896 normw @var{dest}, @var{src}
14898 Where the value in @var{dest} will be the result returned from the
14902 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
14909 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
14916 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{val}, unsigned int @var{auxr})
14917 The first argument, @var{val}, is a compile time constant to be
14918 written to the register, the second argument, @var{auxr}, is the
14919 address of an auxiliary register. Generates:
14921 sr @var{val}, [@var{auxr}]
14925 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
14926 Only valid with @option{-mswap}. Generates:
14928 swap @var{dest}, @var{src}
14930 Where the value in @var{dest} will be the result returned from the
14934 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
14941 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
14942 Only available with @option{-mcpu=ARC700}. Generates:
14948 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
14949 Only available with @option{-mcpu=ARC700}. Generates:
14955 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
14956 Only available with @option{-mcpu=ARC700}. Generates:
14962 The instructions generated by the following builtins are not
14963 considered as candidates for scheduling. They are not moved around by
14964 the compiler during scheduling, and thus can be expected to appear
14965 where they are put in the C code:
14967 __builtin_arc_brk()
14968 __builtin_arc_core_read()
14969 __builtin_arc_core_write()
14970 __builtin_arc_flag()
14972 __builtin_arc_sleep()
14974 __builtin_arc_swi()
14977 @node ARC SIMD Built-in Functions
14978 @subsection ARC SIMD Built-in Functions
14980 SIMD builtins provided by the compiler can be used to generate the
14981 vector instructions. This section describes the available builtins
14982 and their usage in programs. With the @option{-msimd} option, the
14983 compiler provides 128-bit vector types, which can be specified using
14984 the @code{vector_size} attribute. The header file @file{arc-simd.h}
14985 can be included to use the following predefined types:
14987 typedef int __v4si __attribute__((vector_size(16)));
14988 typedef short __v8hi __attribute__((vector_size(16)));
14991 These types can be used to define 128-bit variables. The built-in
14992 functions listed in the following section can be used on these
14993 variables to generate the vector operations.
14995 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
14996 @file{arc-simd.h} also provides equivalent macros called
14997 @code{_@var{someinsn}} that can be used for programming ease and
14998 improved readability. The following macros for DMA control are also
15001 #define _setup_dma_in_channel_reg _vdiwr
15002 #define _setup_dma_out_channel_reg _vdowr
15005 The following is a complete list of all the SIMD built-ins provided
15006 for ARC, grouped by calling signature.
15008 The following take two @code{__v8hi} arguments and return a
15009 @code{__v8hi} result:
15011 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi);
15012 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi);
15013 __v8hi __builtin_arc_vand (__v8hi, __v8hi);
15014 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi);
15015 __v8hi __builtin_arc_vavb (__v8hi, __v8hi);
15016 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi);
15017 __v8hi __builtin_arc_vbic (__v8hi, __v8hi);
15018 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi);
15019 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi);
15020 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi);
15021 __v8hi __builtin_arc_veqw (__v8hi, __v8hi);
15022 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi);
15023 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi);
15024 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi);
15025 __v8hi __builtin_arc_vlew (__v8hi, __v8hi);
15026 __v8hi __builtin_arc_vltw (__v8hi, __v8hi);
15027 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi);
15028 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi);
15029 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi);
15030 __v8hi __builtin_arc_vminw (__v8hi, __v8hi);
15031 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi);
15032 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi);
15033 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi);
15034 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi);
15035 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi);
15036 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi);
15037 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi);
15038 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi);
15039 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi);
15040 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi);
15041 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi);
15042 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi);
15043 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi);
15044 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi);
15045 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi);
15046 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi);
15047 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi);
15048 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi);
15049 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi);
15050 __v8hi __builtin_arc_vnew (__v8hi, __v8hi);
15051 __v8hi __builtin_arc_vor (__v8hi, __v8hi);
15052 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi);
15053 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi);
15054 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi);
15055 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi);
15056 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi);
15057 __v8hi __builtin_arc_vxor (__v8hi, __v8hi);
15058 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi);
15061 The following take one @code{__v8hi} and one @code{int} argument and return a
15062 @code{__v8hi} result:
15065 __v8hi __builtin_arc_vbaddw (__v8hi, int);
15066 __v8hi __builtin_arc_vbmaxw (__v8hi, int);
15067 __v8hi __builtin_arc_vbminw (__v8hi, int);
15068 __v8hi __builtin_arc_vbmulaw (__v8hi, int);
15069 __v8hi __builtin_arc_vbmulfw (__v8hi, int);
15070 __v8hi __builtin_arc_vbmulw (__v8hi, int);
15071 __v8hi __builtin_arc_vbrsubw (__v8hi, int);
15072 __v8hi __builtin_arc_vbsubw (__v8hi, int);
15075 The following take one @code{__v8hi} argument and one @code{int} argument which
15076 must be a 3-bit compile time constant indicating a register number
15077 I0-I7. They return a @code{__v8hi} result.
15079 __v8hi __builtin_arc_vasrw (__v8hi, const int);
15080 __v8hi __builtin_arc_vsr8 (__v8hi, const int);
15081 __v8hi __builtin_arc_vsr8aw (__v8hi, const int);
15084 The following take one @code{__v8hi} argument and one @code{int}
15085 argument which must be a 6-bit compile time constant. They return a
15086 @code{__v8hi} result.
15088 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int);
15089 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int);
15090 __v8hi __builtin_arc_vasrrwi (__v8hi, const int);
15091 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int);
15092 __v8hi __builtin_arc_vasrwi (__v8hi, const int);
15093 __v8hi __builtin_arc_vsr8awi (__v8hi, const int);
15094 __v8hi __builtin_arc_vsr8i (__v8hi, const int);
15097 The following take one @code{__v8hi} argument and one @code{int} argument which
15098 must be a 8-bit compile time constant. They return a @code{__v8hi}
15101 __v8hi __builtin_arc_vd6tapf (__v8hi, const int);
15102 __v8hi __builtin_arc_vmvaw (__v8hi, const int);
15103 __v8hi __builtin_arc_vmvw (__v8hi, const int);
15104 __v8hi __builtin_arc_vmvzw (__v8hi, const int);
15107 The following take two @code{int} arguments, the second of which which
15108 must be a 8-bit compile time constant. They return a @code{__v8hi}
15111 __v8hi __builtin_arc_vmovaw (int, const int);
15112 __v8hi __builtin_arc_vmovw (int, const int);
15113 __v8hi __builtin_arc_vmovzw (int, const int);
15116 The following take a single @code{__v8hi} argument and return a
15117 @code{__v8hi} result:
15119 __v8hi __builtin_arc_vabsaw (__v8hi);
15120 __v8hi __builtin_arc_vabsw (__v8hi);
15121 __v8hi __builtin_arc_vaddsuw (__v8hi);
15122 __v8hi __builtin_arc_vexch1 (__v8hi);
15123 __v8hi __builtin_arc_vexch2 (__v8hi);
15124 __v8hi __builtin_arc_vexch4 (__v8hi);
15125 __v8hi __builtin_arc_vsignw (__v8hi);
15126 __v8hi __builtin_arc_vupbaw (__v8hi);
15127 __v8hi __builtin_arc_vupbw (__v8hi);
15128 __v8hi __builtin_arc_vupsbaw (__v8hi);
15129 __v8hi __builtin_arc_vupsbw (__v8hi);
15132 The following take two @code{int} arguments and return no result:
15134 void __builtin_arc_vdirun (int, int);
15135 void __builtin_arc_vdorun (int, int);
15138 The following take two @code{int} arguments and return no result. The
15139 first argument must a 3-bit compile time constant indicating one of
15140 the DR0-DR7 DMA setup channels:
15142 void __builtin_arc_vdiwr (const int, int);
15143 void __builtin_arc_vdowr (const int, int);
15146 The following take an @code{int} argument and return no result:
15148 void __builtin_arc_vendrec (int);
15149 void __builtin_arc_vrec (int);
15150 void __builtin_arc_vrecrun (int);
15151 void __builtin_arc_vrun (int);
15154 The following take a @code{__v8hi} argument and two @code{int}
15155 arguments and return a @code{__v8hi} result. The second argument must
15156 be a 3-bit compile time constants, indicating one the registers I0-I7,
15157 and the third argument must be an 8-bit compile time constant.
15159 @emph{Note:} Although the equivalent hardware instructions do not take
15160 an SIMD register as an operand, these builtins overwrite the relevant
15161 bits of the @code{__v8hi} register provided as the first argument with
15162 the value loaded from the @code{[Ib, u8]} location in the SDM.
15165 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int);
15166 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int);
15167 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int);
15168 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int);
15171 The following take two @code{int} arguments and return a @code{__v8hi}
15172 result. The first argument must be a 3-bit compile time constants,
15173 indicating one the registers I0-I7, and the second argument must be an
15174 8-bit compile time constant.
15177 __v8hi __builtin_arc_vld128 (const int, const int);
15178 __v8hi __builtin_arc_vld64w (const int, const int);
15181 The following take a @code{__v8hi} argument and two @code{int}
15182 arguments and return no result. The second argument must be a 3-bit
15183 compile time constants, indicating one the registers I0-I7, and the
15184 third argument must be an 8-bit compile time constant.
15187 void __builtin_arc_vst128 (__v8hi, const int, const int);
15188 void __builtin_arc_vst64 (__v8hi, const int, const int);
15191 The following take a @code{__v8hi} argument and three @code{int}
15192 arguments and return no result. The second argument must be a 3-bit
15193 compile-time constant, identifying the 16-bit sub-register to be
15194 stored, the third argument must be a 3-bit compile time constants,
15195 indicating one the registers I0-I7, and the fourth argument must be an
15196 8-bit compile time constant.
15199 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int);
15200 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int);
15203 @node ARM iWMMXt Built-in Functions
15204 @subsection ARM iWMMXt Built-in Functions
15206 These built-in functions are available for the ARM family of
15207 processors when the @option{-mcpu=iwmmxt} switch is used:
15210 typedef int v2si __attribute__ ((vector_size (8)));
15211 typedef short v4hi __attribute__ ((vector_size (8)));
15212 typedef char v8qi __attribute__ ((vector_size (8)));
15214 int __builtin_arm_getwcgr0 (void);
15215 void __builtin_arm_setwcgr0 (int);
15216 int __builtin_arm_getwcgr1 (void);
15217 void __builtin_arm_setwcgr1 (int);
15218 int __builtin_arm_getwcgr2 (void);
15219 void __builtin_arm_setwcgr2 (int);
15220 int __builtin_arm_getwcgr3 (void);
15221 void __builtin_arm_setwcgr3 (int);
15222 int __builtin_arm_textrmsb (v8qi, int);
15223 int __builtin_arm_textrmsh (v4hi, int);
15224 int __builtin_arm_textrmsw (v2si, int);
15225 int __builtin_arm_textrmub (v8qi, int);
15226 int __builtin_arm_textrmuh (v4hi, int);
15227 int __builtin_arm_textrmuw (v2si, int);
15228 v8qi __builtin_arm_tinsrb (v8qi, int, int);
15229 v4hi __builtin_arm_tinsrh (v4hi, int, int);
15230 v2si __builtin_arm_tinsrw (v2si, int, int);
15231 long long __builtin_arm_tmia (long long, int, int);
15232 long long __builtin_arm_tmiabb (long long, int, int);
15233 long long __builtin_arm_tmiabt (long long, int, int);
15234 long long __builtin_arm_tmiaph (long long, int, int);
15235 long long __builtin_arm_tmiatb (long long, int, int);
15236 long long __builtin_arm_tmiatt (long long, int, int);
15237 int __builtin_arm_tmovmskb (v8qi);
15238 int __builtin_arm_tmovmskh (v4hi);
15239 int __builtin_arm_tmovmskw (v2si);
15240 long long __builtin_arm_waccb (v8qi);
15241 long long __builtin_arm_wacch (v4hi);
15242 long long __builtin_arm_waccw (v2si);
15243 v8qi __builtin_arm_waddb (v8qi, v8qi);
15244 v8qi __builtin_arm_waddbss (v8qi, v8qi);
15245 v8qi __builtin_arm_waddbus (v8qi, v8qi);
15246 v4hi __builtin_arm_waddh (v4hi, v4hi);
15247 v4hi __builtin_arm_waddhss (v4hi, v4hi);
15248 v4hi __builtin_arm_waddhus (v4hi, v4hi);
15249 v2si __builtin_arm_waddw (v2si, v2si);
15250 v2si __builtin_arm_waddwss (v2si, v2si);
15251 v2si __builtin_arm_waddwus (v2si, v2si);
15252 v8qi __builtin_arm_walign (v8qi, v8qi, int);
15253 long long __builtin_arm_wand(long long, long long);
15254 long long __builtin_arm_wandn (long long, long long);
15255 v8qi __builtin_arm_wavg2b (v8qi, v8qi);
15256 v8qi __builtin_arm_wavg2br (v8qi, v8qi);
15257 v4hi __builtin_arm_wavg2h (v4hi, v4hi);
15258 v4hi __builtin_arm_wavg2hr (v4hi, v4hi);
15259 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi);
15260 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi);
15261 v2si __builtin_arm_wcmpeqw (v2si, v2si);
15262 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi);
15263 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi);
15264 v2si __builtin_arm_wcmpgtsw (v2si, v2si);
15265 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi);
15266 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi);
15267 v2si __builtin_arm_wcmpgtuw (v2si, v2si);
15268 long long __builtin_arm_wmacs (long long, v4hi, v4hi);
15269 long long __builtin_arm_wmacsz (v4hi, v4hi);
15270 long long __builtin_arm_wmacu (long long, v4hi, v4hi);
15271 long long __builtin_arm_wmacuz (v4hi, v4hi);
15272 v4hi __builtin_arm_wmadds (v4hi, v4hi);
15273 v4hi __builtin_arm_wmaddu (v4hi, v4hi);
15274 v8qi __builtin_arm_wmaxsb (v8qi, v8qi);
15275 v4hi __builtin_arm_wmaxsh (v4hi, v4hi);
15276 v2si __builtin_arm_wmaxsw (v2si, v2si);
15277 v8qi __builtin_arm_wmaxub (v8qi, v8qi);
15278 v4hi __builtin_arm_wmaxuh (v4hi, v4hi);
15279 v2si __builtin_arm_wmaxuw (v2si, v2si);
15280 v8qi __builtin_arm_wminsb (v8qi, v8qi);
15281 v4hi __builtin_arm_wminsh (v4hi, v4hi);
15282 v2si __builtin_arm_wminsw (v2si, v2si);
15283 v8qi __builtin_arm_wminub (v8qi, v8qi);
15284 v4hi __builtin_arm_wminuh (v4hi, v4hi);
15285 v2si __builtin_arm_wminuw (v2si, v2si);
15286 v4hi __builtin_arm_wmulsm (v4hi, v4hi);
15287 v4hi __builtin_arm_wmulul (v4hi, v4hi);
15288 v4hi __builtin_arm_wmulum (v4hi, v4hi);
15289 long long __builtin_arm_wor (long long, long long);
15290 v2si __builtin_arm_wpackdss (long long, long long);
15291 v2si __builtin_arm_wpackdus (long long, long long);
15292 v8qi __builtin_arm_wpackhss (v4hi, v4hi);
15293 v8qi __builtin_arm_wpackhus (v4hi, v4hi);
15294 v4hi __builtin_arm_wpackwss (v2si, v2si);
15295 v4hi __builtin_arm_wpackwus (v2si, v2si);
15296 long long __builtin_arm_wrord (long long, long long);
15297 long long __builtin_arm_wrordi (long long, int);
15298 v4hi __builtin_arm_wrorh (v4hi, long long);
15299 v4hi __builtin_arm_wrorhi (v4hi, int);
15300 v2si __builtin_arm_wrorw (v2si, long long);
15301 v2si __builtin_arm_wrorwi (v2si, int);
15302 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi);
15303 v2si __builtin_arm_wsadbz (v8qi, v8qi);
15304 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi);
15305 v2si __builtin_arm_wsadhz (v4hi, v4hi);
15306 v4hi __builtin_arm_wshufh (v4hi, int);
15307 long long __builtin_arm_wslld (long long, long long);
15308 long long __builtin_arm_wslldi (long long, int);
15309 v4hi __builtin_arm_wsllh (v4hi, long long);
15310 v4hi __builtin_arm_wsllhi (v4hi, int);
15311 v2si __builtin_arm_wsllw (v2si, long long);
15312 v2si __builtin_arm_wsllwi (v2si, int);
15313 long long __builtin_arm_wsrad (long long, long long);
15314 long long __builtin_arm_wsradi (long long, int);
15315 v4hi __builtin_arm_wsrah (v4hi, long long);
15316 v4hi __builtin_arm_wsrahi (v4hi, int);
15317 v2si __builtin_arm_wsraw (v2si, long long);
15318 v2si __builtin_arm_wsrawi (v2si, int);
15319 long long __builtin_arm_wsrld (long long, long long);
15320 long long __builtin_arm_wsrldi (long long, int);
15321 v4hi __builtin_arm_wsrlh (v4hi, long long);
15322 v4hi __builtin_arm_wsrlhi (v4hi, int);
15323 v2si __builtin_arm_wsrlw (v2si, long long);
15324 v2si __builtin_arm_wsrlwi (v2si, int);
15325 v8qi __builtin_arm_wsubb (v8qi, v8qi);
15326 v8qi __builtin_arm_wsubbss (v8qi, v8qi);
15327 v8qi __builtin_arm_wsubbus (v8qi, v8qi);
15328 v4hi __builtin_arm_wsubh (v4hi, v4hi);
15329 v4hi __builtin_arm_wsubhss (v4hi, v4hi);
15330 v4hi __builtin_arm_wsubhus (v4hi, v4hi);
15331 v2si __builtin_arm_wsubw (v2si, v2si);
15332 v2si __builtin_arm_wsubwss (v2si, v2si);
15333 v2si __builtin_arm_wsubwus (v2si, v2si);
15334 v4hi __builtin_arm_wunpckehsb (v8qi);
15335 v2si __builtin_arm_wunpckehsh (v4hi);
15336 long long __builtin_arm_wunpckehsw (v2si);
15337 v4hi __builtin_arm_wunpckehub (v8qi);
15338 v2si __builtin_arm_wunpckehuh (v4hi);
15339 long long __builtin_arm_wunpckehuw (v2si);
15340 v4hi __builtin_arm_wunpckelsb (v8qi);
15341 v2si __builtin_arm_wunpckelsh (v4hi);
15342 long long __builtin_arm_wunpckelsw (v2si);
15343 v4hi __builtin_arm_wunpckelub (v8qi);
15344 v2si __builtin_arm_wunpckeluh (v4hi);
15345 long long __builtin_arm_wunpckeluw (v2si);
15346 v8qi __builtin_arm_wunpckihb (v8qi, v8qi);
15347 v4hi __builtin_arm_wunpckihh (v4hi, v4hi);
15348 v2si __builtin_arm_wunpckihw (v2si, v2si);
15349 v8qi __builtin_arm_wunpckilb (v8qi, v8qi);
15350 v4hi __builtin_arm_wunpckilh (v4hi, v4hi);
15351 v2si __builtin_arm_wunpckilw (v2si, v2si);
15352 long long __builtin_arm_wxor (long long, long long);
15353 long long __builtin_arm_wzero ();
15357 @node ARM C Language Extensions (ACLE)
15358 @subsection ARM C Language Extensions (ACLE)
15360 GCC implements extensions for C as described in the ARM C Language
15361 Extensions (ACLE) specification, which can be found at
15362 @uref{https://developer.arm.com/documentation/ihi0053/latest/}.
15364 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
15365 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
15366 intrinsics can be found at
15367 @uref{https://developer.arm.com/documentation/ihi0073/latest/}.
15368 The built-in intrinsics for the Advanced SIMD extension are available when
15371 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
15372 back ends support CRC32 intrinsics and the ARM back end supports the
15373 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
15374 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
15375 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
15378 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
15379 availability of extensions.
15381 @node ARM Floating Point Status and Control Intrinsics
15382 @subsection ARM Floating Point Status and Control Intrinsics
15384 These built-in functions are available for the ARM family of
15385 processors with floating-point unit.
15388 unsigned int __builtin_arm_get_fpscr ()
15389 void __builtin_arm_set_fpscr (unsigned int)
15392 @node ARM ARMv8-M Security Extensions
15393 @subsection ARM ARMv8-M Security Extensions
15395 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
15396 Security Extensions: Requirements on Development Tools Engineering
15397 Specification, which can be found at
15398 @uref{https://developer.arm.com/documentation/ecm0359818/latest/}.
15400 As part of the Security Extensions GCC implements two new function attributes:
15401 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
15403 As part of the Security Extensions GCC implements the intrinsics below. FPTR
15404 is used here to mean any function pointer type.
15407 cmse_address_info_t cmse_TT (void *);
15408 cmse_address_info_t cmse_TT_fptr (FPTR);
15409 cmse_address_info_t cmse_TTT (void *);
15410 cmse_address_info_t cmse_TTT_fptr (FPTR);
15411 cmse_address_info_t cmse_TTA (void *);
15412 cmse_address_info_t cmse_TTA_fptr (FPTR);
15413 cmse_address_info_t cmse_TTAT (void *);
15414 cmse_address_info_t cmse_TTAT_fptr (FPTR);
15415 void * cmse_check_address_range (void *, size_t, int);
15416 typeof(p) cmse_nsfptr_create (FPTR p);
15417 intptr_t cmse_is_nsfptr (FPTR);
15418 int cmse_nonsecure_caller (void);
15421 @node AVR Built-in Functions
15422 @subsection AVR Built-in Functions
15424 For each built-in function for AVR, there is an equally named,
15425 uppercase built-in macro defined. That way users can easily query if
15426 or if not a specific built-in is implemented or not. For example, if
15427 @code{__builtin_avr_nop} is available the macro
15428 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
15432 @item void __builtin_avr_nop (void)
15433 @itemx void __builtin_avr_sei (void)
15434 @itemx void __builtin_avr_cli (void)
15435 @itemx void __builtin_avr_sleep (void)
15436 @itemx void __builtin_avr_wdr (void)
15437 @itemx unsigned char __builtin_avr_swap (unsigned char)
15438 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
15439 @itemx int __builtin_avr_fmuls (char, char)
15440 @itemx int __builtin_avr_fmulsu (char, unsigned char)
15441 These built-in functions map to the respective machine
15442 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
15443 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
15444 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
15445 as library call if no hardware multiplier is available.
15447 @item void __builtin_avr_delay_cycles (unsigned long ticks)
15448 Delay execution for @var{ticks} cycles. Note that this
15449 built-in does not take into account the effect of interrupts that
15450 might increase delay time. @var{ticks} must be a compile-time
15451 integer constant; delays with a variable number of cycles are not supported.
15453 @item char __builtin_avr_flash_segment (const __memx void*)
15454 This built-in takes a byte address to the 24-bit
15455 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
15456 the number of the flash segment (the 64 KiB chunk) where the address
15457 points to. Counting starts at @code{0}.
15458 If the address does not point to flash memory, return @code{-1}.
15460 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
15461 Insert bits from @var{bits} into @var{val} and return the resulting
15462 value. The nibbles of @var{map} determine how the insertion is
15463 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
15465 @item If @var{X} is @code{0xf},
15466 then the @var{n}-th bit of @var{val} is returned unaltered.
15468 @item If X is in the range 0@dots{}7,
15469 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
15471 @item If X is in the range 8@dots{}@code{0xe},
15472 then the @var{n}-th result bit is undefined.
15476 One typical use case for this built-in is adjusting input and
15477 output values to non-contiguous port layouts. Some examples:
15480 // same as val, bits is unused
15481 __builtin_avr_insert_bits (0xffffffff, bits, val);
15485 // same as bits, val is unused
15486 __builtin_avr_insert_bits (0x76543210, bits, val);
15490 // same as rotating bits by 4
15491 __builtin_avr_insert_bits (0x32107654, bits, 0);
15495 // high nibble of result is the high nibble of val
15496 // low nibble of result is the low nibble of bits
15497 __builtin_avr_insert_bits (0xffff3210, bits, val);
15501 // reverse the bit order of bits
15502 __builtin_avr_insert_bits (0x01234567, bits, 0);
15505 @item void __builtin_avr_nops (unsigned count)
15506 Insert @var{count} @code{NOP} instructions.
15507 The number of instructions must be a compile-time integer constant.
15512 There are many more AVR-specific built-in functions that are used to
15513 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
15514 section 7.18a.6. You don't need to use these built-ins directly.
15515 Instead, use the declarations as supplied by the @code{stdfix.h} header
15519 #include <stdfix.h>
15521 // Re-interpret the bit representation of unsigned 16-bit
15522 // integer @var{uval} as Q-format 0.16 value.
15523 unsigned fract get_bits (uint_ur_t uval)
15525 return urbits (uval);
15529 @node Blackfin Built-in Functions
15530 @subsection Blackfin Built-in Functions
15532 Currently, there are two Blackfin-specific built-in functions. These are
15533 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
15534 using inline assembly; by using these built-in functions the compiler can
15535 automatically add workarounds for hardware errata involving these
15536 instructions. These functions are named as follows:
15539 void __builtin_bfin_csync (void);
15540 void __builtin_bfin_ssync (void);
15543 @node BPF Built-in Functions
15544 @subsection BPF Built-in Functions
15546 The following built-in functions are available for eBPF targets.
15548 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset})
15549 Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15552 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset})
15553 Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15556 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset})
15557 Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15560 @deftypefn {Built-in Function} void * __builtin_preserve_access_index (@var{expr})
15561 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).
15564 @node FR-V Built-in Functions
15565 @subsection FR-V Built-in Functions
15567 GCC provides many FR-V-specific built-in functions. In general,
15568 these functions are intended to be compatible with those described
15569 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
15570 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
15571 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
15572 pointer rather than by value.
15574 Most of the functions are named after specific FR-V instructions.
15575 Such functions are said to be ``directly mapped'' and are summarized
15576 here in tabular form.
15580 * Directly-mapped Integer Functions::
15581 * Directly-mapped Media Functions::
15582 * Raw read/write Functions::
15583 * Other Built-in Functions::
15586 @node Argument Types
15587 @subsubsection Argument Types
15589 The arguments to the built-in functions can be divided into three groups:
15590 register numbers, compile-time constants and run-time values. In order
15591 to make this classification clear at a glance, the arguments and return
15592 values are given the following pseudo types:
15594 @multitable @columnfractions .20 .30 .15 .35
15595 @headitem Pseudo type @tab Real C type @tab Constant? @tab Description
15596 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
15597 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
15598 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
15599 @item @code{uw2} @tab @code{unsigned long long} @tab No
15600 @tab an unsigned doubleword
15601 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
15602 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
15603 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
15604 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
15607 These pseudo types are not defined by GCC, they are simply a notational
15608 convenience used in this manual.
15610 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
15611 and @code{sw2} are evaluated at run time. They correspond to
15612 register operands in the underlying FR-V instructions.
15614 @code{const} arguments represent immediate operands in the underlying
15615 FR-V instructions. They must be compile-time constants.
15617 @code{acc} arguments are evaluated at compile time and specify the number
15618 of an accumulator register. For example, an @code{acc} argument of 2
15619 selects the ACC2 register.
15621 @code{iacc} arguments are similar to @code{acc} arguments but specify the
15622 number of an IACC register. See @pxref{Other Built-in Functions}
15625 @node Directly-mapped Integer Functions
15626 @subsubsection Directly-Mapped Integer Functions
15628 The functions listed below map directly to FR-V I-type instructions.
15630 @multitable @columnfractions .45 .32 .23
15631 @headitem Function prototype @tab Example usage @tab Assembly output
15632 @item @code{sw1 __ADDSS (sw1, sw1)}
15633 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
15634 @tab @code{ADDSS @var{a},@var{b},@var{c}}
15635 @item @code{sw1 __SCAN (sw1, sw1)}
15636 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
15637 @tab @code{SCAN @var{a},@var{b},@var{c}}
15638 @item @code{sw1 __SCUTSS (sw1)}
15639 @tab @code{@var{b} = __SCUTSS (@var{a})}
15640 @tab @code{SCUTSS @var{a},@var{b}}
15641 @item @code{sw1 __SLASS (sw1, sw1)}
15642 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
15643 @tab @code{SLASS @var{a},@var{b},@var{c}}
15644 @item @code{void __SMASS (sw1, sw1)}
15645 @tab @code{__SMASS (@var{a}, @var{b})}
15646 @tab @code{SMASS @var{a},@var{b}}
15647 @item @code{void __SMSSS (sw1, sw1)}
15648 @tab @code{__SMSSS (@var{a}, @var{b})}
15649 @tab @code{SMSSS @var{a},@var{b}}
15650 @item @code{void __SMU (sw1, sw1)}
15651 @tab @code{__SMU (@var{a}, @var{b})}
15652 @tab @code{SMU @var{a},@var{b}}
15653 @item @code{sw2 __SMUL (sw1, sw1)}
15654 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
15655 @tab @code{SMUL @var{a},@var{b},@var{c}}
15656 @item @code{sw1 __SUBSS (sw1, sw1)}
15657 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
15658 @tab @code{SUBSS @var{a},@var{b},@var{c}}
15659 @item @code{uw2 __UMUL (uw1, uw1)}
15660 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
15661 @tab @code{UMUL @var{a},@var{b},@var{c}}
15664 @node Directly-mapped Media Functions
15665 @subsubsection Directly-Mapped Media Functions
15667 The functions listed below map directly to FR-V M-type instructions.
15669 @multitable @columnfractions .45 .32 .23
15670 @headitem Function prototype @tab Example usage @tab Assembly output
15671 @item @code{uw1 __MABSHS (sw1)}
15672 @tab @code{@var{b} = __MABSHS (@var{a})}
15673 @tab @code{MABSHS @var{a},@var{b}}
15674 @item @code{void __MADDACCS (acc, acc)}
15675 @tab @code{__MADDACCS (@var{b}, @var{a})}
15676 @tab @code{MADDACCS @var{a},@var{b}}
15677 @item @code{sw1 __MADDHSS (sw1, sw1)}
15678 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
15679 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
15680 @item @code{uw1 __MADDHUS (uw1, uw1)}
15681 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
15682 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
15683 @item @code{uw1 __MAND (uw1, uw1)}
15684 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
15685 @tab @code{MAND @var{a},@var{b},@var{c}}
15686 @item @code{void __MASACCS (acc, acc)}
15687 @tab @code{__MASACCS (@var{b}, @var{a})}
15688 @tab @code{MASACCS @var{a},@var{b}}
15689 @item @code{uw1 __MAVEH (uw1, uw1)}
15690 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
15691 @tab @code{MAVEH @var{a},@var{b},@var{c}}
15692 @item @code{uw2 __MBTOH (uw1)}
15693 @tab @code{@var{b} = __MBTOH (@var{a})}
15694 @tab @code{MBTOH @var{a},@var{b}}
15695 @item @code{void __MBTOHE (uw1 *, uw1)}
15696 @tab @code{__MBTOHE (&@var{b}, @var{a})}
15697 @tab @code{MBTOHE @var{a},@var{b}}
15698 @item @code{void __MCLRACC (acc)}
15699 @tab @code{__MCLRACC (@var{a})}
15700 @tab @code{MCLRACC @var{a}}
15701 @item @code{void __MCLRACCA (void)}
15702 @tab @code{__MCLRACCA ()}
15703 @tab @code{MCLRACCA}
15704 @item @code{uw1 __Mcop1 (uw1, uw1)}
15705 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
15706 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
15707 @item @code{uw1 __Mcop2 (uw1, uw1)}
15708 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
15709 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
15710 @item @code{uw1 __MCPLHI (uw2, const)}
15711 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
15712 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
15713 @item @code{uw1 __MCPLI (uw2, const)}
15714 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
15715 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
15716 @item @code{void __MCPXIS (acc, sw1, sw1)}
15717 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
15718 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
15719 @item @code{void __MCPXIU (acc, uw1, uw1)}
15720 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
15721 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
15722 @item @code{void __MCPXRS (acc, sw1, sw1)}
15723 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
15724 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
15725 @item @code{void __MCPXRU (acc, uw1, uw1)}
15726 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
15727 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
15728 @item @code{uw1 __MCUT (acc, uw1)}
15729 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
15730 @tab @code{MCUT @var{a},@var{b},@var{c}}
15731 @item @code{uw1 __MCUTSS (acc, sw1)}
15732 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
15733 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
15734 @item @code{void __MDADDACCS (acc, acc)}
15735 @tab @code{__MDADDACCS (@var{b}, @var{a})}
15736 @tab @code{MDADDACCS @var{a},@var{b}}
15737 @item @code{void __MDASACCS (acc, acc)}
15738 @tab @code{__MDASACCS (@var{b}, @var{a})}
15739 @tab @code{MDASACCS @var{a},@var{b}}
15740 @item @code{uw2 __MDCUTSSI (acc, const)}
15741 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
15742 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
15743 @item @code{uw2 __MDPACKH (uw2, uw2)}
15744 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
15745 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
15746 @item @code{uw2 __MDROTLI (uw2, const)}
15747 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
15748 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
15749 @item @code{void __MDSUBACCS (acc, acc)}
15750 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
15751 @tab @code{MDSUBACCS @var{a},@var{b}}
15752 @item @code{void __MDUNPACKH (uw1 *, uw2)}
15753 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
15754 @tab @code{MDUNPACKH @var{a},@var{b}}
15755 @item @code{uw2 __MEXPDHD (uw1, const)}
15756 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
15757 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
15758 @item @code{uw1 __MEXPDHW (uw1, const)}
15759 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
15760 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
15761 @item @code{uw1 __MHDSETH (uw1, const)}
15762 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
15763 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
15764 @item @code{sw1 __MHDSETS (const)}
15765 @tab @code{@var{b} = __MHDSETS (@var{a})}
15766 @tab @code{MHDSETS #@var{a},@var{b}}
15767 @item @code{uw1 __MHSETHIH (uw1, const)}
15768 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
15769 @tab @code{MHSETHIH #@var{a},@var{b}}
15770 @item @code{sw1 __MHSETHIS (sw1, const)}
15771 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
15772 @tab @code{MHSETHIS #@var{a},@var{b}}
15773 @item @code{uw1 __MHSETLOH (uw1, const)}
15774 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
15775 @tab @code{MHSETLOH #@var{a},@var{b}}
15776 @item @code{sw1 __MHSETLOS (sw1, const)}
15777 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
15778 @tab @code{MHSETLOS #@var{a},@var{b}}
15779 @item @code{uw1 __MHTOB (uw2)}
15780 @tab @code{@var{b} = __MHTOB (@var{a})}
15781 @tab @code{MHTOB @var{a},@var{b}}
15782 @item @code{void __MMACHS (acc, sw1, sw1)}
15783 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
15784 @tab @code{MMACHS @var{a},@var{b},@var{c}}
15785 @item @code{void __MMACHU (acc, uw1, uw1)}
15786 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
15787 @tab @code{MMACHU @var{a},@var{b},@var{c}}
15788 @item @code{void __MMRDHS (acc, sw1, sw1)}
15789 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
15790 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
15791 @item @code{void __MMRDHU (acc, uw1, uw1)}
15792 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
15793 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
15794 @item @code{void __MMULHS (acc, sw1, sw1)}
15795 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
15796 @tab @code{MMULHS @var{a},@var{b},@var{c}}
15797 @item @code{void __MMULHU (acc, uw1, uw1)}
15798 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
15799 @tab @code{MMULHU @var{a},@var{b},@var{c}}
15800 @item @code{void __MMULXHS (acc, sw1, sw1)}
15801 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
15802 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
15803 @item @code{void __MMULXHU (acc, uw1, uw1)}
15804 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
15805 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
15806 @item @code{uw1 __MNOT (uw1)}
15807 @tab @code{@var{b} = __MNOT (@var{a})}
15808 @tab @code{MNOT @var{a},@var{b}}
15809 @item @code{uw1 __MOR (uw1, uw1)}
15810 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
15811 @tab @code{MOR @var{a},@var{b},@var{c}}
15812 @item @code{uw1 __MPACKH (uh, uh)}
15813 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
15814 @tab @code{MPACKH @var{a},@var{b},@var{c}}
15815 @item @code{sw2 __MQADDHSS (sw2, sw2)}
15816 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
15817 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
15818 @item @code{uw2 __MQADDHUS (uw2, uw2)}
15819 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
15820 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
15821 @item @code{void __MQCPXIS (acc, sw2, sw2)}
15822 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
15823 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
15824 @item @code{void __MQCPXIU (acc, uw2, uw2)}
15825 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
15826 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
15827 @item @code{void __MQCPXRS (acc, sw2, sw2)}
15828 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
15829 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
15830 @item @code{void __MQCPXRU (acc, uw2, uw2)}
15831 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
15832 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
15833 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
15834 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
15835 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
15836 @item @code{sw2 __MQLMTHS (sw2, sw2)}
15837 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
15838 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
15839 @item @code{void __MQMACHS (acc, sw2, sw2)}
15840 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
15841 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
15842 @item @code{void __MQMACHU (acc, uw2, uw2)}
15843 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
15844 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
15845 @item @code{void __MQMACXHS (acc, sw2, sw2)}
15846 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
15847 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
15848 @item @code{void __MQMULHS (acc, sw2, sw2)}
15849 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
15850 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
15851 @item @code{void __MQMULHU (acc, uw2, uw2)}
15852 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
15853 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
15854 @item @code{void __MQMULXHS (acc, sw2, sw2)}
15855 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
15856 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
15857 @item @code{void __MQMULXHU (acc, uw2, uw2)}
15858 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
15859 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
15860 @item @code{sw2 __MQSATHS (sw2, sw2)}
15861 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
15862 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
15863 @item @code{uw2 __MQSLLHI (uw2, int)}
15864 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
15865 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
15866 @item @code{sw2 __MQSRAHI (sw2, int)}
15867 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
15868 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
15869 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
15870 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
15871 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
15872 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
15873 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
15874 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
15875 @item @code{void __MQXMACHS (acc, sw2, sw2)}
15876 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
15877 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
15878 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
15879 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
15880 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
15881 @item @code{uw1 __MRDACC (acc)}
15882 @tab @code{@var{b} = __MRDACC (@var{a})}
15883 @tab @code{MRDACC @var{a},@var{b}}
15884 @item @code{uw1 __MRDACCG (acc)}
15885 @tab @code{@var{b} = __MRDACCG (@var{a})}
15886 @tab @code{MRDACCG @var{a},@var{b}}
15887 @item @code{uw1 __MROTLI (uw1, const)}
15888 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
15889 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
15890 @item @code{uw1 __MROTRI (uw1, const)}
15891 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
15892 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
15893 @item @code{sw1 __MSATHS (sw1, sw1)}
15894 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
15895 @tab @code{MSATHS @var{a},@var{b},@var{c}}
15896 @item @code{uw1 __MSATHU (uw1, uw1)}
15897 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
15898 @tab @code{MSATHU @var{a},@var{b},@var{c}}
15899 @item @code{uw1 __MSLLHI (uw1, const)}
15900 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
15901 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
15902 @item @code{sw1 __MSRAHI (sw1, const)}
15903 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
15904 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
15905 @item @code{uw1 __MSRLHI (uw1, const)}
15906 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
15907 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
15908 @item @code{void __MSUBACCS (acc, acc)}
15909 @tab @code{__MSUBACCS (@var{b}, @var{a})}
15910 @tab @code{MSUBACCS @var{a},@var{b}}
15911 @item @code{sw1 __MSUBHSS (sw1, sw1)}
15912 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
15913 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
15914 @item @code{uw1 __MSUBHUS (uw1, uw1)}
15915 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
15916 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
15917 @item @code{void __MTRAP (void)}
15918 @tab @code{__MTRAP ()}
15920 @item @code{uw2 __MUNPACKH (uw1)}
15921 @tab @code{@var{b} = __MUNPACKH (@var{a})}
15922 @tab @code{MUNPACKH @var{a},@var{b}}
15923 @item @code{uw1 __MWCUT (uw2, uw1)}
15924 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
15925 @tab @code{MWCUT @var{a},@var{b},@var{c}}
15926 @item @code{void __MWTACC (acc, uw1)}
15927 @tab @code{__MWTACC (@var{b}, @var{a})}
15928 @tab @code{MWTACC @var{a},@var{b}}
15929 @item @code{void __MWTACCG (acc, uw1)}
15930 @tab @code{__MWTACCG (@var{b}, @var{a})}
15931 @tab @code{MWTACCG @var{a},@var{b}}
15932 @item @code{uw1 __MXOR (uw1, uw1)}
15933 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
15934 @tab @code{MXOR @var{a},@var{b},@var{c}}
15937 @node Raw read/write Functions
15938 @subsubsection Raw Read/Write Functions
15940 This sections describes built-in functions related to read and write
15941 instructions to access memory. These functions generate
15942 @code{membar} instructions to flush the I/O load and stores where
15943 appropriate, as described in Fujitsu's manual described above.
15947 @item unsigned char __builtin_read8 (void *@var{data})
15948 @item unsigned short __builtin_read16 (void *@var{data})
15949 @item unsigned long __builtin_read32 (void *@var{data})
15950 @item unsigned long long __builtin_read64 (void *@var{data})
15952 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
15953 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
15954 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
15955 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
15958 @node Other Built-in Functions
15959 @subsubsection Other Built-in Functions
15961 This section describes built-in functions that are not named after
15962 a specific FR-V instruction.
15965 @item sw2 __IACCreadll (iacc @var{reg})
15966 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
15967 for future expansion and must be 0.
15969 @item sw1 __IACCreadl (iacc @var{reg})
15970 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
15971 Other values of @var{reg} are rejected as invalid.
15973 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
15974 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
15975 is reserved for future expansion and must be 0.
15977 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
15978 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
15979 is 1. Other values of @var{reg} are rejected as invalid.
15981 @item void __data_prefetch0 (const void *@var{x})
15982 Use the @code{dcpl} instruction to load the contents of address @var{x}
15983 into the data cache.
15985 @item void __data_prefetch (const void *@var{x})
15986 Use the @code{nldub} instruction to load the contents of address @var{x}
15987 into the data cache. The instruction is issued in slot I1@.
15990 @node MIPS DSP Built-in Functions
15991 @subsection MIPS DSP Built-in Functions
15993 The MIPS DSP Application-Specific Extension (ASE) includes new
15994 instructions that are designed to improve the performance of DSP and
15995 media applications. It provides instructions that operate on packed
15996 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
15998 GCC supports MIPS DSP operations using both the generic
15999 vector extensions (@pxref{Vector Extensions}) and a collection of
16000 MIPS-specific built-in functions. Both kinds of support are
16001 enabled by the @option{-mdsp} command-line option.
16003 Revision 2 of the ASE was introduced in the second half of 2006.
16004 This revision adds extra instructions to the original ASE, but is
16005 otherwise backwards-compatible with it. You can select revision 2
16006 using the command-line option @option{-mdspr2}; this option implies
16009 The SCOUNT and POS bits of the DSP control register are global. The
16010 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
16011 POS bits. During optimization, the compiler does not delete these
16012 instructions and it does not delete calls to functions containing
16013 these instructions.
16015 At present, GCC only provides support for operations on 32-bit
16016 vectors. The vector type associated with 8-bit integer data is
16017 usually called @code{v4i8}, the vector type associated with Q7
16018 is usually called @code{v4q7}, the vector type associated with 16-bit
16019 integer data is usually called @code{v2i16}, and the vector type
16020 associated with Q15 is usually called @code{v2q15}. They can be
16021 defined in C as follows:
16024 typedef signed char v4i8 __attribute__ ((vector_size(4)));
16025 typedef signed char v4q7 __attribute__ ((vector_size(4)));
16026 typedef short v2i16 __attribute__ ((vector_size(4)));
16027 typedef short v2q15 __attribute__ ((vector_size(4)));
16030 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
16031 initialized in the same way as aggregates. For example:
16034 v4i8 a = @{1, 2, 3, 4@};
16036 b = (v4i8) @{5, 6, 7, 8@};
16038 v2q15 c = @{0x0fcb, 0x3a75@};
16040 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
16043 @emph{Note:} The CPU's endianness determines the order in which values
16044 are packed. On little-endian targets, the first value is the least
16045 significant and the last value is the most significant. The opposite
16046 order applies to big-endian targets. For example, the code above
16047 sets the lowest byte of @code{a} to @code{1} on little-endian targets
16048 and @code{4} on big-endian targets.
16050 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
16051 representation. As shown in this example, the integer representation
16052 of a Q7 value can be obtained by multiplying the fractional value by
16053 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
16054 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
16057 The table below lists the @code{v4i8} and @code{v2q15} operations for which
16058 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
16059 and @code{c} and @code{d} are @code{v2q15} values.
16061 @multitable @columnfractions .50 .50
16062 @headitem C code @tab MIPS instruction
16063 @item @code{a + b} @tab @code{addu.qb}
16064 @item @code{c + d} @tab @code{addq.ph}
16065 @item @code{a - b} @tab @code{subu.qb}
16066 @item @code{c - d} @tab @code{subq.ph}
16069 The table below lists the @code{v2i16} operation for which
16070 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
16071 @code{v2i16} values.
16073 @multitable @columnfractions .50 .50
16074 @headitem C code @tab MIPS instruction
16075 @item @code{e * f} @tab @code{mul.ph}
16078 It is easier to describe the DSP built-in functions if we first define
16079 the following types:
16084 typedef unsigned int ui32;
16085 typedef long long a64;
16088 @code{q31} and @code{i32} are actually the same as @code{int}, but we
16089 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
16090 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
16091 @code{long long}, but we use @code{a64} to indicate values that are
16092 placed in one of the four DSP accumulators (@code{$ac0},
16093 @code{$ac1}, @code{$ac2} or @code{$ac3}).
16095 Also, some built-in functions prefer or require immediate numbers as
16096 parameters, because the corresponding DSP instructions accept both immediate
16097 numbers and register operands, or accept immediate numbers only. The
16098 immediate parameters are listed as follows.
16106 imm0_255: 0 to 255.
16107 imm_n32_31: -32 to 31.
16108 imm_n512_511: -512 to 511.
16111 The following built-in functions map directly to a particular MIPS DSP
16112 instruction. Please refer to the architecture specification
16113 for details on what each instruction does.
16116 v2q15 __builtin_mips_addq_ph (v2q15, v2q15);
16117 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15);
16118 q31 __builtin_mips_addq_s_w (q31, q31);
16119 v4i8 __builtin_mips_addu_qb (v4i8, v4i8);
16120 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8);
16121 v2q15 __builtin_mips_subq_ph (v2q15, v2q15);
16122 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15);
16123 q31 __builtin_mips_subq_s_w (q31, q31);
16124 v4i8 __builtin_mips_subu_qb (v4i8, v4i8);
16125 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8);
16126 i32 __builtin_mips_addsc (i32, i32);
16127 i32 __builtin_mips_addwc (i32, i32);
16128 i32 __builtin_mips_modsub (i32, i32);
16129 i32 __builtin_mips_raddu_w_qb (v4i8);
16130 v2q15 __builtin_mips_absq_s_ph (v2q15);
16131 q31 __builtin_mips_absq_s_w (q31);
16132 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15);
16133 v2q15 __builtin_mips_precrq_ph_w (q31, q31);
16134 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31);
16135 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15);
16136 q31 __builtin_mips_preceq_w_phl (v2q15);
16137 q31 __builtin_mips_preceq_w_phr (v2q15);
16138 v2q15 __builtin_mips_precequ_ph_qbl (v4i8);
16139 v2q15 __builtin_mips_precequ_ph_qbr (v4i8);
16140 v2q15 __builtin_mips_precequ_ph_qbla (v4i8);
16141 v2q15 __builtin_mips_precequ_ph_qbra (v4i8);
16142 v2q15 __builtin_mips_preceu_ph_qbl (v4i8);
16143 v2q15 __builtin_mips_preceu_ph_qbr (v4i8);
16144 v2q15 __builtin_mips_preceu_ph_qbla (v4i8);
16145 v2q15 __builtin_mips_preceu_ph_qbra (v4i8);
16146 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7);
16147 v4i8 __builtin_mips_shll_qb (v4i8, i32);
16148 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15);
16149 v2q15 __builtin_mips_shll_ph (v2q15, i32);
16150 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15);
16151 v2q15 __builtin_mips_shll_s_ph (v2q15, i32);
16152 q31 __builtin_mips_shll_s_w (q31, imm0_31);
16153 q31 __builtin_mips_shll_s_w (q31, i32);
16154 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7);
16155 v4i8 __builtin_mips_shrl_qb (v4i8, i32);
16156 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15);
16157 v2q15 __builtin_mips_shra_ph (v2q15, i32);
16158 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15);
16159 v2q15 __builtin_mips_shra_r_ph (v2q15, i32);
16160 q31 __builtin_mips_shra_r_w (q31, imm0_31);
16161 q31 __builtin_mips_shra_r_w (q31, i32);
16162 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15);
16163 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15);
16164 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15);
16165 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15);
16166 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15);
16167 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8);
16168 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8);
16169 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8);
16170 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8);
16171 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15);
16172 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31);
16173 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15);
16174 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31);
16175 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15);
16176 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15);
16177 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15);
16178 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15);
16179 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15);
16180 i32 __builtin_mips_bitrev (i32);
16181 i32 __builtin_mips_insv (i32, i32);
16182 v4i8 __builtin_mips_repl_qb (imm0_255);
16183 v4i8 __builtin_mips_repl_qb (i32);
16184 v2q15 __builtin_mips_repl_ph (imm_n512_511);
16185 v2q15 __builtin_mips_repl_ph (i32);
16186 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8);
16187 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8);
16188 void __builtin_mips_cmpu_le_qb (v4i8, v4i8);
16189 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8);
16190 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8);
16191 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8);
16192 void __builtin_mips_cmp_eq_ph (v2q15, v2q15);
16193 void __builtin_mips_cmp_lt_ph (v2q15, v2q15);
16194 void __builtin_mips_cmp_le_ph (v2q15, v2q15);
16195 v4i8 __builtin_mips_pick_qb (v4i8, v4i8);
16196 v2q15 __builtin_mips_pick_ph (v2q15, v2q15);
16197 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15);
16198 i32 __builtin_mips_extr_w (a64, imm0_31);
16199 i32 __builtin_mips_extr_w (a64, i32);
16200 i32 __builtin_mips_extr_r_w (a64, imm0_31);
16201 i32 __builtin_mips_extr_s_h (a64, i32);
16202 i32 __builtin_mips_extr_rs_w (a64, imm0_31);
16203 i32 __builtin_mips_extr_rs_w (a64, i32);
16204 i32 __builtin_mips_extr_s_h (a64, imm0_31);
16205 i32 __builtin_mips_extr_r_w (a64, i32);
16206 i32 __builtin_mips_extp (a64, imm0_31);
16207 i32 __builtin_mips_extp (a64, i32);
16208 i32 __builtin_mips_extpdp (a64, imm0_31);
16209 i32 __builtin_mips_extpdp (a64, i32);
16210 a64 __builtin_mips_shilo (a64, imm_n32_31);
16211 a64 __builtin_mips_shilo (a64, i32);
16212 a64 __builtin_mips_mthlip (a64, i32);
16213 void __builtin_mips_wrdsp (i32, imm0_63);
16214 i32 __builtin_mips_rddsp (imm0_63);
16215 i32 __builtin_mips_lbux (void *, i32);
16216 i32 __builtin_mips_lhx (void *, i32);
16217 i32 __builtin_mips_lwx (void *, i32);
16218 a64 __builtin_mips_ldx (void *, i32); /* MIPS64 only */
16219 i32 __builtin_mips_bposge32 (void);
16220 a64 __builtin_mips_madd (a64, i32, i32);
16221 a64 __builtin_mips_maddu (a64, ui32, ui32);
16222 a64 __builtin_mips_msub (a64, i32, i32);
16223 a64 __builtin_mips_msubu (a64, ui32, ui32);
16224 a64 __builtin_mips_mult (i32, i32);
16225 a64 __builtin_mips_multu (ui32, ui32);
16228 The following built-in functions map directly to a particular MIPS DSP REV 2
16229 instruction. Please refer to the architecture specification
16230 for details on what each instruction does.
16233 v4q7 __builtin_mips_absq_s_qb (v4q7);
16234 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
16235 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
16236 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
16237 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
16238 i32 __builtin_mips_append (i32, i32, imm0_31);
16239 i32 __builtin_mips_balign (i32, i32, imm0_3);
16240 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
16241 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
16242 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
16243 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
16244 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
16245 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
16246 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
16247 q31 __builtin_mips_mulq_rs_w (q31, q31);
16248 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
16249 q31 __builtin_mips_mulq_s_w (q31, q31);
16250 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
16251 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
16252 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
16253 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
16254 i32 __builtin_mips_prepend (i32, i32, imm0_31);
16255 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
16256 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
16257 v4i8 __builtin_mips_shra_qb (v4i8, i32);
16258 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
16259 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
16260 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
16261 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
16262 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
16263 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
16264 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
16265 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
16266 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
16267 q31 __builtin_mips_addqh_w (q31, q31);
16268 q31 __builtin_mips_addqh_r_w (q31, q31);
16269 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
16270 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
16271 q31 __builtin_mips_subqh_w (q31, q31);
16272 q31 __builtin_mips_subqh_r_w (q31, q31);
16273 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
16274 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
16275 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
16276 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
16277 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
16278 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
16282 @node MIPS Paired-Single Support
16283 @subsection MIPS Paired-Single Support
16285 The MIPS64 architecture includes a number of instructions that
16286 operate on pairs of single-precision floating-point values.
16287 Each pair is packed into a 64-bit floating-point register,
16288 with one element being designated the ``upper half'' and
16289 the other being designated the ``lower half''.
16291 GCC supports paired-single operations using both the generic
16292 vector extensions (@pxref{Vector Extensions}) and a collection of
16293 MIPS-specific built-in functions. Both kinds of support are
16294 enabled by the @option{-mpaired-single} command-line option.
16296 The vector type associated with paired-single values is usually
16297 called @code{v2sf}. It can be defined in C as follows:
16300 typedef float v2sf __attribute__ ((vector_size (8)));
16303 @code{v2sf} values are initialized in the same way as aggregates.
16307 v2sf a = @{1.5, 9.1@};
16310 b = (v2sf) @{e, f@};
16313 @emph{Note:} The CPU's endianness determines which value is stored in
16314 the upper half of a register and which value is stored in the lower half.
16315 On little-endian targets, the first value is the lower one and the second
16316 value is the upper one. The opposite order applies to big-endian targets.
16317 For example, the code above sets the lower half of @code{a} to
16318 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
16320 @node MIPS Loongson Built-in Functions
16321 @subsection MIPS Loongson Built-in Functions
16323 GCC provides intrinsics to access the SIMD instructions provided by the
16324 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
16325 available after inclusion of the @code{loongson.h} header file,
16326 operate on the following 64-bit vector types:
16329 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
16330 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
16331 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
16332 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
16333 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
16334 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
16337 The intrinsics provided are listed below; each is named after the
16338 machine instruction to which it corresponds, with suffixes added as
16339 appropriate to distinguish intrinsics that expand to the same machine
16340 instruction yet have different argument types. Refer to the architecture
16341 documentation for a description of the functionality of each
16345 int16x4_t packsswh (int32x2_t s, int32x2_t t);
16346 int8x8_t packsshb (int16x4_t s, int16x4_t t);
16347 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
16348 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
16349 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
16350 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
16351 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
16352 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
16353 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
16354 uint64_t paddd_u (uint64_t s, uint64_t t);
16355 int64_t paddd_s (int64_t s, int64_t t);
16356 int16x4_t paddsh (int16x4_t s, int16x4_t t);
16357 int8x8_t paddsb (int8x8_t s, int8x8_t t);
16358 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
16359 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
16360 uint64_t pandn_ud (uint64_t s, uint64_t t);
16361 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
16362 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
16363 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
16364 int64_t pandn_sd (int64_t s, int64_t t);
16365 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
16366 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
16367 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
16368 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
16369 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
16370 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
16371 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
16372 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
16373 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
16374 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
16375 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
16376 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
16377 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
16378 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
16379 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
16380 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
16381 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
16382 uint16x4_t pextrh_u (uint16x4_t s, int field);
16383 int16x4_t pextrh_s (int16x4_t s, int field);
16384 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
16385 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
16386 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
16387 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
16388 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
16389 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
16390 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
16391 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
16392 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
16393 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
16394 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
16395 int16x4_t pminsh (int16x4_t s, int16x4_t t);
16396 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
16397 uint8x8_t pmovmskb_u (uint8x8_t s);
16398 int8x8_t pmovmskb_s (int8x8_t s);
16399 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
16400 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
16401 int16x4_t pmullh (int16x4_t s, int16x4_t t);
16402 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
16403 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
16404 uint16x4_t biadd (uint8x8_t s);
16405 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
16406 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
16407 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
16408 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
16409 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
16410 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
16411 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
16412 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
16413 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
16414 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
16415 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
16416 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
16417 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
16418 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
16419 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
16420 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
16421 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
16422 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
16423 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
16424 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
16425 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
16426 uint64_t psubd_u (uint64_t s, uint64_t t);
16427 int64_t psubd_s (int64_t s, int64_t t);
16428 int16x4_t psubsh (int16x4_t s, int16x4_t t);
16429 int8x8_t psubsb (int8x8_t s, int8x8_t t);
16430 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
16431 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
16432 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
16433 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
16434 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
16435 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
16436 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
16437 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
16438 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
16439 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
16440 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
16441 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
16442 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
16443 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
16447 * Paired-Single Arithmetic::
16448 * Paired-Single Built-in Functions::
16449 * MIPS-3D Built-in Functions::
16452 @node Paired-Single Arithmetic
16453 @subsubsection Paired-Single Arithmetic
16455 The table below lists the @code{v2sf} operations for which hardware
16456 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
16457 values and @code{x} is an integral value.
16459 @multitable @columnfractions .50 .50
16460 @headitem C code @tab MIPS instruction
16461 @item @code{a + b} @tab @code{add.ps}
16462 @item @code{a - b} @tab @code{sub.ps}
16463 @item @code{-a} @tab @code{neg.ps}
16464 @item @code{a * b} @tab @code{mul.ps}
16465 @item @code{a * b + c} @tab @code{madd.ps}
16466 @item @code{a * b - c} @tab @code{msub.ps}
16467 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
16468 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
16469 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
16472 Note that the multiply-accumulate instructions can be disabled
16473 using the command-line option @code{-mno-fused-madd}.
16475 @node Paired-Single Built-in Functions
16476 @subsubsection Paired-Single Built-in Functions
16478 The following paired-single functions map directly to a particular
16479 MIPS instruction. Please refer to the architecture specification
16480 for details on what each instruction does.
16483 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
16484 Pair lower lower (@code{pll.ps}).
16486 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
16487 Pair upper lower (@code{pul.ps}).
16489 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
16490 Pair lower upper (@code{plu.ps}).
16492 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
16493 Pair upper upper (@code{puu.ps}).
16495 @item v2sf __builtin_mips_cvt_ps_s (float, float)
16496 Convert pair to paired single (@code{cvt.ps.s}).
16498 @item float __builtin_mips_cvt_s_pl (v2sf)
16499 Convert pair lower to single (@code{cvt.s.pl}).
16501 @item float __builtin_mips_cvt_s_pu (v2sf)
16502 Convert pair upper to single (@code{cvt.s.pu}).
16504 @item v2sf __builtin_mips_abs_ps (v2sf)
16505 Absolute value (@code{abs.ps}).
16507 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
16508 Align variable (@code{alnv.ps}).
16510 @emph{Note:} The value of the third parameter must be 0 or 4
16511 modulo 8, otherwise the result is unpredictable. Please read the
16512 instruction description for details.
16515 The following multi-instruction functions are also available.
16516 In each case, @var{cond} can be any of the 16 floating-point conditions:
16517 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16518 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
16519 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16522 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16523 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16524 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
16525 @code{movt.ps}/@code{movf.ps}).
16527 The @code{movt} functions return the value @var{x} computed by:
16530 c.@var{cond}.ps @var{cc},@var{a},@var{b}
16531 mov.ps @var{x},@var{c}
16532 movt.ps @var{x},@var{d},@var{cc}
16535 The @code{movf} functions are similar but use @code{movf.ps} instead
16538 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16539 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16540 Comparison of two paired-single values (@code{c.@var{cond}.ps},
16541 @code{bc1t}/@code{bc1f}).
16543 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16544 and return either the upper or lower half of the result. For example:
16548 if (__builtin_mips_upper_c_eq_ps (a, b))
16549 upper_halves_are_equal ();
16551 upper_halves_are_unequal ();
16553 if (__builtin_mips_lower_c_eq_ps (a, b))
16554 lower_halves_are_equal ();
16556 lower_halves_are_unequal ();
16560 @node MIPS-3D Built-in Functions
16561 @subsubsection MIPS-3D Built-in Functions
16563 The MIPS-3D Application-Specific Extension (ASE) includes additional
16564 paired-single instructions that are designed to improve the performance
16565 of 3D graphics operations. Support for these instructions is controlled
16566 by the @option{-mips3d} command-line option.
16568 The functions listed below map directly to a particular MIPS-3D
16569 instruction. Please refer to the architecture specification for
16570 more details on what each instruction does.
16573 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
16574 Reduction add (@code{addr.ps}).
16576 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
16577 Reduction multiply (@code{mulr.ps}).
16579 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
16580 Convert paired single to paired word (@code{cvt.pw.ps}).
16582 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
16583 Convert paired word to paired single (@code{cvt.ps.pw}).
16585 @item float __builtin_mips_recip1_s (float)
16586 @itemx double __builtin_mips_recip1_d (double)
16587 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
16588 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
16590 @item float __builtin_mips_recip2_s (float, float)
16591 @itemx double __builtin_mips_recip2_d (double, double)
16592 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
16593 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
16595 @item float __builtin_mips_rsqrt1_s (float)
16596 @itemx double __builtin_mips_rsqrt1_d (double)
16597 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
16598 Reduced-precision reciprocal square root (sequence step 1)
16599 (@code{rsqrt1.@var{fmt}}).
16601 @item float __builtin_mips_rsqrt2_s (float, float)
16602 @itemx double __builtin_mips_rsqrt2_d (double, double)
16603 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
16604 Reduced-precision reciprocal square root (sequence step 2)
16605 (@code{rsqrt2.@var{fmt}}).
16608 The following multi-instruction functions are also available.
16609 In each case, @var{cond} can be any of the 16 floating-point conditions:
16610 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16611 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
16612 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16615 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
16616 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
16617 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
16618 @code{bc1t}/@code{bc1f}).
16620 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
16621 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
16626 if (__builtin_mips_cabs_eq_s (a, b))
16632 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16633 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16634 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
16635 @code{bc1t}/@code{bc1f}).
16637 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
16638 and return either the upper or lower half of the result. For example:
16642 if (__builtin_mips_upper_cabs_eq_ps (a, b))
16643 upper_halves_are_equal ();
16645 upper_halves_are_unequal ();
16647 if (__builtin_mips_lower_cabs_eq_ps (a, b))
16648 lower_halves_are_equal ();
16650 lower_halves_are_unequal ();
16653 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16654 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16655 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
16656 @code{movt.ps}/@code{movf.ps}).
16658 The @code{movt} functions return the value @var{x} computed by:
16661 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
16662 mov.ps @var{x},@var{c}
16663 movt.ps @var{x},@var{d},@var{cc}
16666 The @code{movf} functions are similar but use @code{movf.ps} instead
16669 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16670 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16671 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16672 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16673 Comparison of two paired-single values
16674 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16675 @code{bc1any2t}/@code{bc1any2f}).
16677 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16678 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
16679 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
16684 if (__builtin_mips_any_c_eq_ps (a, b))
16689 if (__builtin_mips_all_c_eq_ps (a, b))
16695 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16696 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16697 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16698 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16699 Comparison of four paired-single values
16700 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16701 @code{bc1any4t}/@code{bc1any4f}).
16703 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
16704 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
16705 The @code{any} forms return @code{true} if any of the four results are @code{true}
16706 and the @code{all} forms return @code{true} if all four results are @code{true}.
16711 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
16716 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
16723 @node MIPS SIMD Architecture (MSA) Support
16724 @subsection MIPS SIMD Architecture (MSA) Support
16727 * MIPS SIMD Architecture Built-in Functions::
16730 GCC provides intrinsics to access the SIMD instructions provided by the
16731 MSA MIPS SIMD Architecture. The interface is made available by including
16732 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
16733 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
16736 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
16737 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
16738 data elements. The following vectors typedefs are included in @code{msa.h}:
16740 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
16741 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
16742 @item @code{v8i16}, a vector of eight signed 16-bit integers;
16743 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
16744 @item @code{v4i32}, a vector of four signed 32-bit integers;
16745 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
16746 @item @code{v2i64}, a vector of two signed 64-bit integers;
16747 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
16748 @item @code{v4f32}, a vector of four 32-bit floats;
16749 @item @code{v2f64}, a vector of two 64-bit doubles.
16752 Instructions and corresponding built-ins may have additional restrictions and/or
16753 input/output values manipulated:
16755 @item @code{imm0_1}, an integer literal in range 0 to 1;
16756 @item @code{imm0_3}, an integer literal in range 0 to 3;
16757 @item @code{imm0_7}, an integer literal in range 0 to 7;
16758 @item @code{imm0_15}, an integer literal in range 0 to 15;
16759 @item @code{imm0_31}, an integer literal in range 0 to 31;
16760 @item @code{imm0_63}, an integer literal in range 0 to 63;
16761 @item @code{imm0_255}, an integer literal in range 0 to 255;
16762 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
16763 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
16764 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
16765 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
16766 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
16767 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
16768 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
16769 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
16770 @item @code{imm1_4}, an integer literal in range 1 to 4;
16771 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
16777 #if __LONG_MAX__ == __LONG_LONG_MAX__
16780 typedef long long i64;
16783 typedef unsigned int u32;
16784 #if __LONG_MAX__ == __LONG_LONG_MAX__
16785 typedef unsigned long u64;
16787 typedef unsigned long long u64;
16790 typedef double f64;
16795 @node MIPS SIMD Architecture Built-in Functions
16796 @subsubsection MIPS SIMD Architecture Built-in Functions
16798 The intrinsics provided are listed below; each is named after the
16799 machine instruction.
16802 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
16803 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
16804 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
16805 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
16807 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
16808 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
16809 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
16810 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
16812 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
16813 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
16814 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
16815 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
16817 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
16818 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
16819 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
16820 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
16822 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
16823 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
16824 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
16825 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
16827 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
16828 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
16829 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
16830 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
16832 v16u8 __builtin_msa_and_v (v16u8, v16u8);
16834 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
16836 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
16837 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
16838 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
16839 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
16841 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
16842 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
16843 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
16844 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
16846 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
16847 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
16848 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
16849 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
16851 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
16852 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
16853 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
16854 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
16856 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
16857 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
16858 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
16859 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
16861 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
16862 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
16863 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
16864 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
16866 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
16867 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
16868 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
16869 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
16871 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
16872 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
16873 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
16874 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
16876 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
16877 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
16878 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
16879 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
16881 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
16882 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
16883 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
16884 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
16886 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
16887 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
16888 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
16889 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
16891 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
16892 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
16893 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
16894 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
16896 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
16898 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
16900 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
16902 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
16904 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
16905 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
16906 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
16907 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
16909 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
16910 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
16911 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
16912 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
16914 i32 __builtin_msa_bnz_b (v16u8);
16915 i32 __builtin_msa_bnz_h (v8u16);
16916 i32 __builtin_msa_bnz_w (v4u32);
16917 i32 __builtin_msa_bnz_d (v2u64);
16919 i32 __builtin_msa_bnz_v (v16u8);
16921 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
16923 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
16925 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
16926 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
16927 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
16928 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
16930 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
16931 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
16932 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
16933 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
16935 i32 __builtin_msa_bz_b (v16u8);
16936 i32 __builtin_msa_bz_h (v8u16);
16937 i32 __builtin_msa_bz_w (v4u32);
16938 i32 __builtin_msa_bz_d (v2u64);
16940 i32 __builtin_msa_bz_v (v16u8);
16942 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
16943 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
16944 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
16945 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
16947 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
16948 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
16949 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
16950 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
16952 i32 __builtin_msa_cfcmsa (imm0_31);
16954 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
16955 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
16956 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
16957 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
16959 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
16960 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
16961 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
16962 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
16964 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
16965 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
16966 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
16967 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
16969 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
16970 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
16971 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
16972 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
16974 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
16975 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
16976 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
16977 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
16979 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
16980 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
16981 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
16982 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
16984 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
16985 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
16986 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
16987 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
16989 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
16990 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
16991 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
16992 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
16994 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
16995 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
16996 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
16997 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
16999 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
17000 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
17001 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
17002 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
17004 void __builtin_msa_ctcmsa (imm0_31, i32);
17006 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
17007 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
17008 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
17009 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
17011 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
17012 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
17013 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
17014 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
17016 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
17017 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
17018 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
17020 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
17021 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
17022 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
17024 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
17025 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
17026 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
17028 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
17029 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
17030 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
17032 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
17033 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
17034 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
17036 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
17037 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
17038 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
17040 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
17041 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
17043 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
17044 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
17046 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
17047 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
17049 v4i32 __builtin_msa_fclass_w (v4f32);
17050 v2i64 __builtin_msa_fclass_d (v2f64);
17052 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
17053 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
17055 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
17056 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
17058 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
17059 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
17061 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
17062 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
17064 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
17065 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
17067 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
17068 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
17070 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
17071 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
17073 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
17074 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
17076 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
17077 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
17079 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
17080 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
17082 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
17083 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
17085 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
17086 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
17088 v4f32 __builtin_msa_fexupl_w (v8i16);
17089 v2f64 __builtin_msa_fexupl_d (v4f32);
17091 v4f32 __builtin_msa_fexupr_w (v8i16);
17092 v2f64 __builtin_msa_fexupr_d (v4f32);
17094 v4f32 __builtin_msa_ffint_s_w (v4i32);
17095 v2f64 __builtin_msa_ffint_s_d (v2i64);
17097 v4f32 __builtin_msa_ffint_u_w (v4u32);
17098 v2f64 __builtin_msa_ffint_u_d (v2u64);
17100 v4f32 __builtin_msa_ffql_w (v8i16);
17101 v2f64 __builtin_msa_ffql_d (v4i32);
17103 v4f32 __builtin_msa_ffqr_w (v8i16);
17104 v2f64 __builtin_msa_ffqr_d (v4i32);
17106 v16i8 __builtin_msa_fill_b (i32);
17107 v8i16 __builtin_msa_fill_h (i32);
17108 v4i32 __builtin_msa_fill_w (i32);
17109 v2i64 __builtin_msa_fill_d (i64);
17111 v4f32 __builtin_msa_flog2_w (v4f32);
17112 v2f64 __builtin_msa_flog2_d (v2f64);
17114 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
17115 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
17117 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
17118 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
17120 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
17121 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
17123 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
17124 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
17126 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
17127 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
17129 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
17130 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
17132 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
17133 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
17135 v4f32 __builtin_msa_frint_w (v4f32);
17136 v2f64 __builtin_msa_frint_d (v2f64);
17138 v4f32 __builtin_msa_frcp_w (v4f32);
17139 v2f64 __builtin_msa_frcp_d (v2f64);
17141 v4f32 __builtin_msa_frsqrt_w (v4f32);
17142 v2f64 __builtin_msa_frsqrt_d (v2f64);
17144 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
17145 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
17147 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
17148 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
17150 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
17151 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
17153 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
17154 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
17156 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
17157 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
17159 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
17160 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
17162 v4f32 __builtin_msa_fsqrt_w (v4f32);
17163 v2f64 __builtin_msa_fsqrt_d (v2f64);
17165 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
17166 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
17168 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
17169 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
17171 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
17172 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
17174 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
17175 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
17177 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
17178 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
17180 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
17181 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
17183 v4i32 __builtin_msa_ftint_s_w (v4f32);
17184 v2i64 __builtin_msa_ftint_s_d (v2f64);
17186 v4u32 __builtin_msa_ftint_u_w (v4f32);
17187 v2u64 __builtin_msa_ftint_u_d (v2f64);
17189 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
17190 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
17192 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
17193 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
17195 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
17196 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
17198 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
17199 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
17200 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
17202 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
17203 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
17204 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
17206 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
17207 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
17208 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
17210 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
17211 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
17212 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
17214 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
17215 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
17216 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
17217 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
17219 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
17220 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
17221 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
17222 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
17224 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
17225 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
17226 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
17227 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
17229 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
17230 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
17231 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
17232 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
17234 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
17235 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
17236 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
17237 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
17239 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
17240 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
17241 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
17242 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
17244 v16i8 __builtin_msa_ld_b (const void *, imm_n512_511);
17245 v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022);
17246 v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044);
17247 v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088);
17249 v16i8 __builtin_msa_ldi_b (imm_n512_511);
17250 v8i16 __builtin_msa_ldi_h (imm_n512_511);
17251 v4i32 __builtin_msa_ldi_w (imm_n512_511);
17252 v2i64 __builtin_msa_ldi_d (imm_n512_511);
17254 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
17255 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
17257 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
17258 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
17260 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
17261 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
17262 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
17263 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
17265 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
17266 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
17267 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
17268 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
17270 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
17271 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
17272 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
17273 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
17275 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
17276 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
17277 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
17278 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
17280 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
17281 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
17282 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
17283 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
17285 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
17286 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
17287 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
17288 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
17290 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
17291 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
17292 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
17293 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
17295 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
17296 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
17297 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
17298 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
17300 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
17301 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
17302 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
17303 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
17305 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
17306 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
17307 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
17308 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
17310 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
17311 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
17312 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
17313 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
17315 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
17316 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
17317 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
17318 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
17320 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
17321 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
17322 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
17323 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
17325 v16i8 __builtin_msa_move_v (v16i8);
17327 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
17328 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
17330 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
17331 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
17333 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
17334 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
17335 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
17336 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
17338 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
17339 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
17341 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
17342 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
17344 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
17345 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
17346 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
17347 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
17349 v16i8 __builtin_msa_nloc_b (v16i8);
17350 v8i16 __builtin_msa_nloc_h (v8i16);
17351 v4i32 __builtin_msa_nloc_w (v4i32);
17352 v2i64 __builtin_msa_nloc_d (v2i64);
17354 v16i8 __builtin_msa_nlzc_b (v16i8);
17355 v8i16 __builtin_msa_nlzc_h (v8i16);
17356 v4i32 __builtin_msa_nlzc_w (v4i32);
17357 v2i64 __builtin_msa_nlzc_d (v2i64);
17359 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
17361 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
17363 v16u8 __builtin_msa_or_v (v16u8, v16u8);
17365 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
17367 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
17368 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
17369 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
17370 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
17372 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
17373 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
17374 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
17375 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
17377 v16i8 __builtin_msa_pcnt_b (v16i8);
17378 v8i16 __builtin_msa_pcnt_h (v8i16);
17379 v4i32 __builtin_msa_pcnt_w (v4i32);
17380 v2i64 __builtin_msa_pcnt_d (v2i64);
17382 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
17383 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
17384 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
17385 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
17387 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
17388 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
17389 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
17390 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
17392 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
17393 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
17394 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
17396 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
17397 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
17398 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
17399 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
17401 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
17402 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
17403 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
17404 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
17406 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
17407 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
17408 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
17409 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
17411 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
17412 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
17413 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
17414 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
17416 v16i8 __builtin_msa_splat_b (v16i8, i32);
17417 v8i16 __builtin_msa_splat_h (v8i16, i32);
17418 v4i32 __builtin_msa_splat_w (v4i32, i32);
17419 v2i64 __builtin_msa_splat_d (v2i64, i32);
17421 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
17422 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
17423 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
17424 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
17426 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
17427 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
17428 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
17429 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
17431 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
17432 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
17433 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
17434 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
17436 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
17437 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
17438 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
17439 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
17441 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
17442 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
17443 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
17444 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
17446 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
17447 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
17448 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
17449 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
17451 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
17452 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
17453 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
17454 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
17456 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
17457 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
17458 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
17459 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
17461 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
17462 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
17463 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
17464 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
17466 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
17467 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
17468 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
17469 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
17471 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
17472 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
17473 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
17474 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
17476 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
17477 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
17478 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
17479 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
17481 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
17482 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
17483 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
17484 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
17486 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
17487 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
17488 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
17489 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
17491 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
17492 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
17493 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
17494 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
17496 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
17497 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
17498 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
17499 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
17501 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
17502 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
17503 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
17504 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
17506 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
17508 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
17511 @node Other MIPS Built-in Functions
17512 @subsection Other MIPS Built-in Functions
17514 GCC provides other MIPS-specific built-in functions:
17517 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
17518 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
17519 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
17520 when this function is available.
17522 @item unsigned int __builtin_mips_get_fcsr (void)
17523 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
17524 Get and set the contents of the floating-point control and status register
17525 (FPU control register 31). These functions are only available in hard-float
17526 code but can be called in both MIPS16 and non-MIPS16 contexts.
17528 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
17529 register except the condition codes, which GCC assumes are preserved.
17532 @node MSP430 Built-in Functions
17533 @subsection MSP430 Built-in Functions
17535 GCC provides a couple of special builtin functions to aid in the
17536 writing of interrupt handlers in C.
17539 @item __bic_SR_register_on_exit (int @var{mask})
17540 This clears the indicated bits in the saved copy of the status register
17541 currently residing on the stack. This only works inside interrupt
17542 handlers and the changes to the status register will only take affect
17543 once the handler returns.
17545 @item __bis_SR_register_on_exit (int @var{mask})
17546 This sets the indicated bits in the saved copy of the status register
17547 currently residing on the stack. This only works inside interrupt
17548 handlers and the changes to the status register will only take affect
17549 once the handler returns.
17551 @item __delay_cycles (long long @var{cycles})
17552 This inserts an instruction sequence that takes exactly @var{cycles}
17553 cycles (between 0 and about 17E9) to complete. The inserted sequence
17554 may use jumps, loops, or no-ops, and does not interfere with any other
17555 instructions. Note that @var{cycles} must be a compile-time constant
17556 integer - that is, you must pass a number, not a variable that may be
17557 optimized to a constant later. The number of cycles delayed by this
17561 @node NDS32 Built-in Functions
17562 @subsection NDS32 Built-in Functions
17564 These built-in functions are available for the NDS32 target:
17566 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
17567 Insert an ISYNC instruction into the instruction stream where
17568 @var{addr} is an instruction address for serialization.
17571 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
17572 Insert an ISB instruction into the instruction stream.
17575 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
17576 Return the content of a system register which is mapped by @var{sr}.
17579 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
17580 Return the content of a user space register which is mapped by @var{usr}.
17583 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
17584 Move the @var{value} to a system register which is mapped by @var{sr}.
17587 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
17588 Move the @var{value} to a user space register which is mapped by @var{usr}.
17591 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
17592 Enable global interrupt.
17595 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
17596 Disable global interrupt.
17599 @node picoChip Built-in Functions
17600 @subsection picoChip Built-in Functions
17602 GCC provides an interface to selected machine instructions from the
17603 picoChip instruction set.
17606 @item int __builtin_sbc (int @var{value})
17607 Sign bit count. Return the number of consecutive bits in @var{value}
17608 that have the same value as the sign bit. The result is the number of
17609 leading sign bits minus one, giving the number of redundant sign bits in
17612 @item int __builtin_byteswap (int @var{value})
17613 Byte swap. Return the result of swapping the upper and lower bytes of
17616 @item int __builtin_brev (int @var{value})
17617 Bit reversal. Return the result of reversing the bits in
17618 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
17621 @item int __builtin_adds (int @var{x}, int @var{y})
17622 Saturating addition. Return the result of adding @var{x} and @var{y},
17623 storing the value 32767 if the result overflows.
17625 @item int __builtin_subs (int @var{x}, int @var{y})
17626 Saturating subtraction. Return the result of subtracting @var{y} from
17627 @var{x}, storing the value @minus{}32768 if the result overflows.
17629 @item void __builtin_halt (void)
17630 Halt. The processor stops execution. This built-in is useful for
17631 implementing assertions.
17635 @node Basic PowerPC Built-in Functions
17636 @subsection Basic PowerPC Built-in Functions
17639 * Basic PowerPC Built-in Functions Available on all Configurations::
17640 * Basic PowerPC Built-in Functions Available on ISA 2.05::
17641 * Basic PowerPC Built-in Functions Available on ISA 2.06::
17642 * Basic PowerPC Built-in Functions Available on ISA 2.07::
17643 * Basic PowerPC Built-in Functions Available on ISA 3.0::
17644 * Basic PowerPC Built-in Functions Available on ISA 3.1::
17647 This section describes PowerPC built-in functions that do not require
17648 the inclusion of any special header files to declare prototypes or
17649 provide macro definitions. The sections that follow describe
17650 additional PowerPC built-in functions.
17652 @node Basic PowerPC Built-in Functions Available on all Configurations
17653 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
17655 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
17656 This function is a @code{nop} on the PowerPC platform and is included solely
17657 to maintain API compatibility with the x86 builtins.
17660 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
17661 This function returns a value of @code{1} if the run-time CPU is of type
17662 @var{cpuname} and returns @code{0} otherwise
17664 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
17665 which exports the hardware capability bits. GCC defines the macro
17666 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
17667 built-in function is fully supported.
17669 If GCC was configured to use a GLIBC before 2.23, the built-in
17670 function @code{__builtin_cpu_is} always returns a 0 and the compiler
17673 The following CPU names can be detected:
17677 IBM POWER10 Server CPU.
17679 IBM POWER9 Server CPU.
17681 IBM POWER8 Server CPU.
17683 IBM POWER7 Server CPU.
17685 IBM POWER6 Server CPU (RAW mode).
17687 IBM POWER6 Server CPU (Architected mode).
17689 IBM POWER5+ Server CPU.
17691 IBM POWER5 Server CPU.
17693 IBM 970 Server CPU (ie, Apple G5).
17695 IBM POWER4 Server CPU.
17697 IBM A2 64-bit Embedded CPU
17699 IBM PowerPC 476FP 32-bit Embedded CPU.
17701 IBM PowerPC 464 32-bit Embedded CPU.
17703 PowerPC 440 32-bit Embedded CPU.
17705 PowerPC 405 32-bit Embedded CPU.
17707 IBM PowerPC Cell Broadband Engine Architecture CPU.
17710 Here is an example:
17712 #ifdef __BUILTIN_CPU_SUPPORTS__
17713 if (__builtin_cpu_is ("power8"))
17715 do_power8 (); // POWER8 specific implementation.
17720 do_generic (); // Generic implementation.
17725 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
17726 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
17727 feature @var{feature} and returns @code{0} otherwise.
17729 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
17730 newer which exports the hardware capability bits. GCC defines the
17731 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
17732 @code{__builtin_cpu_supports} built-in function is fully supported.
17734 If GCC was configured to use a GLIBC before 2.23, the built-in
17735 function @code{__builtin_cpu_supports} always returns a 0 and the
17736 compiler issues a warning.
17738 The following features can be
17743 4xx CPU has a Multiply Accumulator.
17745 CPU has a SIMD/Vector Unit.
17747 CPU supports ISA 2.05 (eg, POWER6)
17749 CPU supports ISA 2.06 (eg, POWER7)
17751 CPU supports ISA 2.07 (eg, POWER8)
17753 CPU supports ISA 3.0 (eg, POWER9)
17755 CPU supports ISA 3.1 (eg, POWER10)
17757 CPU supports the set of compatible performance monitoring events.
17759 CPU supports the Embedded ISA category.
17761 CPU has a CELL broadband engine.
17763 CPU supports the @code{darn} (deliver a random number) instruction.
17765 CPU has a decimal floating point unit.
17767 CPU supports the data stream control register.
17769 CPU supports event base branching.
17771 CPU has a SPE double precision floating point unit.
17773 CPU has a SPE single precision floating point unit.
17775 CPU has a floating point unit.
17777 CPU has hardware transaction memory instructions.
17779 Kernel aborts hardware transactions when a syscall is made.
17780 @item htm-no-suspend
17781 CPU supports hardware transaction memory but does not support the
17782 @code{tsuspend.} instruction.
17784 CPU supports icache snooping capabilities.
17786 CPU supports 128-bit IEEE binary floating point instructions.
17788 CPU supports the integer select instruction.
17790 CPU supports the matrix-multiply assist instructions.
17792 CPU has a memory management unit.
17794 CPU does not have a timebase (eg, 601 and 403gx).
17796 CPU supports the PA Semi 6T CORE ISA.
17798 CPU supports ISA 2.00 (eg, POWER4)
17800 CPU supports ISA 2.02 (eg, POWER5)
17802 CPU supports ISA 2.03 (eg, POWER5+)
17804 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
17806 CPU supports 32-bit mode execution.
17808 CPU supports the old POWER ISA (eg, 601)
17810 CPU supports 64-bit mode execution.
17812 CPU supports a little-endian mode that uses address swizzling.
17814 Kernel supports system call vectored.
17816 CPU support simultaneous multi-threading.
17818 CPU has a signal processing extension unit.
17820 CPU supports the target address register.
17822 CPU supports true little-endian mode.
17824 CPU has unified I/D cache.
17826 CPU supports the vector cryptography instructions.
17828 CPU supports the vector-scalar extension.
17831 Here is an example:
17833 #ifdef __BUILTIN_CPU_SUPPORTS__
17834 if (__builtin_cpu_supports ("fpu"))
17836 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
17841 dst = __fadd (src1, src2); // Software FP addition function.
17846 The following built-in functions are also available on all PowerPC
17849 uint64_t __builtin_ppc_get_timebase ();
17850 unsigned long __builtin_ppc_mftb ();
17851 double __builtin_unpack_ibm128 (__ibm128, int);
17852 __ibm128 __builtin_pack_ibm128 (double, double);
17853 double __builtin_mffs (void);
17854 void __builtin_mtfsf (const int, double);
17855 void __builtin_mtfsb0 (const int);
17856 void __builtin_mtfsb1 (const int);
17857 void __builtin_set_fpscr_rn (int);
17860 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
17861 functions generate instructions to read the Time Base Register. The
17862 @code{__builtin_ppc_get_timebase} function may generate multiple
17863 instructions and always returns the 64 bits of the Time Base Register.
17864 The @code{__builtin_ppc_mftb} function always generates one instruction and
17865 returns the Time Base Register value as an unsigned long, throwing away
17866 the most significant word on 32-bit environments. The @code{__builtin_mffs}
17867 return the value of the FPSCR register. Note, ISA 3.0 supports the
17868 @code{__builtin_mffsl()} which permits software to read the control and
17869 non-sticky status bits in the FSPCR without the higher latency associated with
17870 accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant
17871 8-bit integer field mask and a double precision floating point argument
17872 and generates the @code{mtfsf} (extended mnemonic) instruction to write new
17873 values to selected fields of the FPSCR. The
17874 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
17875 as an argument. The valid bit range is between 0 and 31. The builtins map to
17876 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
17877 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
17878 changing the specified bit to a zero or one respectively. The
17879 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
17880 point rounding mode bits. The argument is a 2-bit value. The argument can
17881 either be a @code{const int} or stored in a variable. The builtin uses
17883 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
17884 the current rounding mode bits out and OR's in the new value.
17886 @node Basic PowerPC Built-in Functions Available on ISA 2.05
17887 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
17889 The basic built-in functions described in this section are
17890 available on the PowerPC family of processors starting with ISA 2.05
17891 or later. Unless specific options are explicitly disabled on the
17892 command line, specifying option @option{-mcpu=power6} has the effect of
17893 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
17894 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
17895 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
17896 @option{-mrecip-precision} options. Specify the
17897 @option{-maltivec} option explicitly in
17898 combination with the above options if desired.
17900 The following functions require option @option{-mcmpb}.
17902 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
17903 unsigned int __builtin_cmpb (unsigned int, unsigned int);
17906 The @code{__builtin_cmpb} function
17907 performs a byte-wise compare on the contents of its two arguments,
17908 returning the result of the byte-wise comparison as the returned
17909 value. For each byte comparison, the corresponding byte of the return
17910 value holds 0xff if the input bytes are equal and 0 if the input bytes
17911 are not equal. If either of the arguments to this built-in function
17912 is wider than 32 bits, the function call expands into the form that
17913 expects @code{unsigned long long int} arguments
17914 which is only available on 64-bit targets.
17916 The following built-in functions are available
17917 when hardware decimal floating point
17918 (@option{-mhard-dfp}) is available:
17920 void __builtin_set_fpscr_drn(int);
17921 _Decimal64 __builtin_ddedpd (int, _Decimal64);
17922 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
17923 _Decimal64 __builtin_denbcd (int, _Decimal64);
17924 _Decimal128 __builtin_denbcdq (int, _Decimal128);
17925 _Decimal64 __builtin_diex (long long, _Decimal64);
17926 _Decimal128 _builtin_diexq (long long, _Decimal128);
17927 _Decimal64 __builtin_dscli (_Decimal64, int);
17928 _Decimal128 __builtin_dscliq (_Decimal128, int);
17929 _Decimal64 __builtin_dscri (_Decimal64, int);
17930 _Decimal128 __builtin_dscriq (_Decimal128, int);
17931 long long __builtin_dxex (_Decimal64);
17932 long long __builtin_dxexq (_Decimal128);
17933 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
17934 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
17936 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
17937 floating point rounding mode bits. The argument is a 3-bit value. The
17938 argument can either be a @code{const int} or the value can be stored in
17940 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
17941 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
17942 mode bits out and OR's in the new value.
17946 The following functions require @option{-mhard-float},
17947 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
17950 double __builtin_recipdiv (double, double);
17951 float __builtin_recipdivf (float, float);
17952 double __builtin_rsqrt (double);
17953 float __builtin_rsqrtf (float);
17956 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
17957 @code{__builtin_rsqrtf} functions generate multiple instructions to
17958 implement the reciprocal sqrt functionality using reciprocal sqrt
17959 estimate instructions.
17961 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
17962 functions generate multiple instructions to implement division using
17963 the reciprocal estimate instructions.
17965 The following functions require @option{-mhard-float} and
17966 @option{-mmultiple} options.
17968 The @code{__builtin_unpack_longdouble} function takes a
17969 @code{long double} argument and a compile time constant of 0 or 1. If
17970 the constant is 0, the first @code{double} within the
17971 @code{long double} is returned, otherwise the second @code{double}
17972 is returned. The @code{__builtin_unpack_longdouble} function is only
17973 available if @code{long double} uses the IBM extended double
17976 The @code{__builtin_pack_longdouble} function takes two @code{double}
17977 arguments and returns a @code{long double} value that combines the two
17978 arguments. The @code{__builtin_pack_longdouble} function is only
17979 available if @code{long double} uses the IBM extended double
17982 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
17983 argument and a compile time constant of 0 or 1. If the constant is 0,
17984 the first @code{double} within the @code{__ibm128} is returned,
17985 otherwise the second @code{double} is returned.
17987 The @code{__builtin_pack_ibm128} function takes two @code{double}
17988 arguments and returns a @code{__ibm128} value that combines the two
17991 Additional built-in functions are available for the 64-bit PowerPC
17992 family of processors, for efficient use of 128-bit floating point
17993 (@code{__float128}) values.
17995 @node Basic PowerPC Built-in Functions Available on ISA 2.06
17996 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
17998 The basic built-in functions described in this section are
17999 available on the PowerPC family of processors starting with ISA 2.05
18000 or later. Unless specific options are explicitly disabled on the
18001 command line, specifying option @option{-mcpu=power7} has the effect of
18002 enabling all the same options as for @option{-mcpu=power6} in
18003 addition to the @option{-maltivec}, @option{-mpopcntd}, and
18004 @option{-mvsx} options.
18006 The following basic built-in functions require @option{-mpopcntd}:
18008 unsigned int __builtin_addg6s (unsigned int, unsigned int);
18009 long long __builtin_bpermd (long long, long long);
18010 unsigned int __builtin_cbcdtd (unsigned int);
18011 unsigned int __builtin_cdtbcd (unsigned int);
18012 long long __builtin_divde (long long, long long);
18013 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
18014 int __builtin_divwe (int, int);
18015 unsigned int __builtin_divweu (unsigned int, unsigned int);
18016 vector __int128 __builtin_pack_vector_int128 (long long, long long);
18017 void __builtin_rs6000_speculation_barrier (void);
18018 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
18021 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
18022 require a 64-bit environment.
18024 The following basic built-in functions, which are also supported on
18025 x86 targets, require @option{-mfloat128}.
18027 __float128 __builtin_fabsq (__float128);
18028 __float128 __builtin_copysignq (__float128, __float128);
18029 __float128 __builtin_infq (void);
18030 __float128 __builtin_huge_valq (void);
18031 __float128 __builtin_nanq (void);
18032 __float128 __builtin_nansq (void);
18034 __float128 __builtin_sqrtf128 (__float128);
18035 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
18038 @node Basic PowerPC Built-in Functions Available on ISA 2.07
18039 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
18041 The basic built-in functions described in this section are
18042 available on the PowerPC family of processors starting with ISA 2.07
18043 or later. Unless specific options are explicitly disabled on the
18044 command line, specifying option @option{-mcpu=power8} has the effect of
18045 enabling all the same options as for @option{-mcpu=power7} in
18046 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
18047 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
18048 @option{-mquad-memory-atomic} options.
18050 This section intentionally empty.
18052 @node Basic PowerPC Built-in Functions Available on ISA 3.0
18053 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
18055 The basic built-in functions described in this section are
18056 available on the PowerPC family of processors starting with ISA 3.0
18057 or later. Unless specific options are explicitly disabled on the
18058 command line, specifying option @option{-mcpu=power9} has the effect of
18059 enabling all the same options as for @option{-mcpu=power8} in
18060 addition to the @option{-misel} option.
18062 The following built-in functions are available on Linux 64-bit systems
18063 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
18066 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
18067 Perform a 128-bit IEEE floating point add using round to odd as the
18069 @findex __builtin_addf128_round_to_odd
18071 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
18072 Perform a 128-bit IEEE floating point subtract using round to odd as
18074 @findex __builtin_subf128_round_to_odd
18076 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
18077 Perform a 128-bit IEEE floating point multiply using round to odd as
18079 @findex __builtin_mulf128_round_to_odd
18081 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
18082 Perform a 128-bit IEEE floating point divide using round to odd as
18084 @findex __builtin_divf128_round_to_odd
18086 @item __float128 __builtin_sqrtf128_round_to_odd (__float128)
18087 Perform a 128-bit IEEE floating point square root using round to odd
18088 as the rounding mode.
18089 @findex __builtin_sqrtf128_round_to_odd
18091 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
18092 Perform a 128-bit IEEE floating point fused multiply and add operation
18093 using round to odd as the rounding mode.
18094 @findex __builtin_fmaf128_round_to_odd
18096 @item double __builtin_truncf128_round_to_odd (__float128)
18097 Convert a 128-bit IEEE floating point value to @code{double} using
18098 round to odd as the rounding mode.
18099 @findex __builtin_truncf128_round_to_odd
18102 The following additional built-in functions are also available for the
18103 PowerPC family of processors, starting with ISA 3.0 or later:
18105 long long __builtin_darn (void);
18106 long long __builtin_darn_raw (void);
18107 int __builtin_darn_32 (void);
18110 The @code{__builtin_darn} and @code{__builtin_darn_raw}
18111 functions require a
18112 64-bit environment supporting ISA 3.0 or later.
18113 The @code{__builtin_darn} function provides a 64-bit conditioned
18114 random number. The @code{__builtin_darn_raw} function provides a
18115 64-bit raw random number. The @code{__builtin_darn_32} function
18116 provides a 32-bit conditioned random number.
18118 The following additional built-in functions are also available for the
18119 PowerPC family of processors, starting with ISA 3.0 or later:
18122 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
18123 int __builtin_byte_in_range (unsigned char u, unsigned int range);
18124 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
18126 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
18127 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
18128 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
18129 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
18131 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
18132 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
18133 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
18134 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
18136 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
18137 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
18138 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
18139 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
18141 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
18142 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
18143 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
18144 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
18146 double __builtin_mffsl(void);
18149 The @code{__builtin_byte_in_set} function requires a
18150 64-bit environment supporting ISA 3.0 or later. This function returns
18151 a non-zero value if and only if its @code{u} argument exactly equals one of
18152 the eight bytes contained within its 64-bit @code{set} argument.
18154 The @code{__builtin_byte_in_range} and
18155 @code{__builtin_byte_in_either_range} require an environment
18156 supporting ISA 3.0 or later. For these two functions, the
18157 @code{range} argument is encoded as 4 bytes, organized as
18158 @code{hi_1:lo_1:hi_2:lo_2}.
18159 The @code{__builtin_byte_in_range} function returns a
18160 non-zero value if and only if its @code{u} argument is within the
18161 range bounded between @code{lo_2} and @code{hi_2} inclusive.
18162 The @code{__builtin_byte_in_either_range} function returns non-zero if
18163 and only if its @code{u} argument is within either the range bounded
18164 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
18165 between @code{lo_2} and @code{hi_2} inclusive.
18167 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
18168 if and only if the number of signficant digits of its @code{value} argument
18169 is less than its @code{comparison} argument. The
18170 @code{__builtin_dfp_dtstsfi_lt_dd} and
18171 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
18172 require that the type of the @code{value} argument be
18173 @code{__Decimal64} and @code{__Decimal128} respectively.
18175 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
18176 if and only if the number of signficant digits of its @code{value} argument
18177 is greater than its @code{comparison} argument. The
18178 @code{__builtin_dfp_dtstsfi_gt_dd} and
18179 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
18180 require that the type of the @code{value} argument be
18181 @code{__Decimal64} and @code{__Decimal128} respectively.
18183 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
18184 if and only if the number of signficant digits of its @code{value} argument
18185 equals its @code{comparison} argument. The
18186 @code{__builtin_dfp_dtstsfi_eq_dd} and
18187 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
18188 require that the type of the @code{value} argument be
18189 @code{__Decimal64} and @code{__Decimal128} respectively.
18191 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
18192 if and only if its @code{value} argument has an undefined number of
18193 significant digits, such as when @code{value} is an encoding of @code{NaN}.
18194 The @code{__builtin_dfp_dtstsfi_ov_dd} and
18195 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
18196 require that the type of the @code{value} argument be
18197 @code{__Decimal64} and @code{__Decimal128} respectively.
18199 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
18200 the FPSCR. The instruction is a lower latency version of the @code{mffs}
18201 instruction. If the @code{mffsl} instruction is not available, then the
18202 builtin uses the older @code{mffs} instruction to read the FPSCR.
18204 @node Basic PowerPC Built-in Functions Available on ISA 3.1
18205 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1
18207 The basic built-in functions described in this section are
18208 available on the PowerPC family of processors starting with ISA 3.1.
18209 Unless specific options are explicitly disabled on the
18210 command line, specifying option @option{-mcpu=power10} has the effect of
18211 enabling all the same options as for @option{-mcpu=power9}.
18213 The following built-in functions are available on Linux 64-bit systems
18214 that use a future architecture instruction set (@option{-mcpu=power10}):
18217 @exdent unsigned long long int
18218 @exdent __builtin_cfuged (unsigned long long int, unsigned long long int)
18220 Perform a 64-bit centrifuge operation, as if implemented by the
18221 @code{cfuged} instruction.
18222 @findex __builtin_cfuged
18225 @exdent unsigned long long int
18226 @exdent __builtin_cntlzdm (unsigned long long int, unsigned long long int)
18228 Perform a 64-bit count leading zeros operation under mask, as if
18229 implemented by the @code{cntlzdm} instruction.
18230 @findex __builtin_cntlzdm
18233 @exdent unsigned long long int
18234 @exdent __builtin_cnttzdm (unsigned long long int, unsigned long long int)
18236 Perform a 64-bit count trailing zeros operation under mask, as if
18237 implemented by the @code{cnttzdm} instruction.
18238 @findex __builtin_cnttzdm
18241 @exdent unsigned long long int
18242 @exdent __builtin_pdepd (unsigned long long int, unsigned long long int)
18244 Perform a 64-bit parallel bits deposit operation, as if implemented by the
18245 @code{pdepd} instruction.
18246 @findex __builtin_pdepd
18249 @exdent unsigned long long int
18250 @exdent __builtin_pextd (unsigned long long int, unsigned long long int)
18252 Perform a 64-bit parallel bits extract operation, as if implemented by the
18253 @code{pextd} instruction.
18254 @findex __builtin_pextd
18257 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed char *);
18258 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed short *);
18259 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed int *);
18260 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed long long *);
18261 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned char *);
18262 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned short *);
18263 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned int *);
18264 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned long long *);
18267 Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1
18268 @code{lxvrbx} @code{lxvrhx} @code{lxvrwx} @code{lxvrdx} instructions.
18269 @findex vsx_xl_sext
18270 @findex vsx_xl_zext
18273 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed char *);
18274 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed short *);
18275 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed int *);
18276 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed long long *);
18277 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *);
18278 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *);
18279 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *);
18280 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *);
18283 Truncate and store the rightmost element of a vector, as if implemented by the
18284 ISA 3.1 @code{stxvrbx} @code{stxvrhx} @code{stxvrwx} @code{stxvrdx} instructions.
18285 @findex vec_xst_trunc
18287 @node PowerPC AltiVec/VSX Built-in Functions
18288 @subsection PowerPC AltiVec/VSX Built-in Functions
18290 GCC provides an interface for the PowerPC family of processors to access
18291 the AltiVec operations described in Motorola's AltiVec Programming
18292 Interface Manual. The interface is made available by including
18293 @code{<altivec.h>} and using @option{-maltivec} and
18294 @option{-mabi=altivec}. The interface supports the following vector
18298 vector unsigned char
18302 vector unsigned short
18303 vector signed short
18307 vector unsigned int
18313 GCC's implementation of the high-level language interface available from
18314 C and C++ code differs from Motorola's documentation in several ways.
18319 A vector constant is a list of constant expressions within curly braces.
18322 A vector initializer requires no cast if the vector constant is of the
18323 same type as the variable it is initializing.
18326 If @code{signed} or @code{unsigned} is omitted, the signedness of the
18327 vector type is the default signedness of the base type. The default
18328 varies depending on the operating system, so a portable program should
18329 always specify the signedness.
18332 Compiling with @option{-maltivec} adds keywords @code{__vector},
18333 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
18334 @code{bool}. When compiling ISO C, the context-sensitive substitution
18335 of the keywords @code{vector}, @code{pixel} and @code{bool} is
18336 disabled. To use them, you must include @code{<altivec.h>} instead.
18339 GCC allows using a @code{typedef} name as the type specifier for a
18340 vector type, but only under the following circumstances:
18345 When using @code{__vector} instead of @code{vector}; for example,
18348 typedef signed short int16;
18349 __vector int16 data;
18353 When using @code{vector} in keyword-and-predefine mode; for example,
18356 typedef signed short int16;
18360 Note that keyword-and-predefine mode is enabled by disabling GNU
18361 extensions (e.g., by using @code{-std=c11}) and including
18362 @code{<altivec.h>}.
18366 For C, overloaded functions are implemented with macros so the following
18370 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
18374 Since @code{vec_add} is a macro, the vector constant in the example
18375 is treated as four separate arguments. Wrap the entire argument in
18376 parentheses for this to work.
18379 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
18380 Internally, GCC uses built-in functions to achieve the functionality in
18381 the aforementioned header file, but they are not supported and are
18382 subject to change without notice.
18384 GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR),
18385 which may be found at
18386 @uref{https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference}.
18387 Chapter 4 of this document fully documents the vector API interfaces
18389 provided by compliant compilers. Programmers should preferentially use
18390 the interfaces described therein. However, historically GCC has provided
18391 additional interfaces for access to vector instructions. These are
18392 briefly described below. Where the PVIPR provides a portable interface,
18393 other functions in GCC that provide the same capabilities should be
18394 considered deprecated.
18396 The PVIPR documents the following overloaded functions:
18398 @multitable @columnfractions 0.33 0.33 0.33
18400 @item @code{vec_abs}
18401 @tab @code{vec_absd}
18402 @tab @code{vec_abss}
18403 @item @code{vec_add}
18404 @tab @code{vec_addc}
18405 @tab @code{vec_adde}
18406 @item @code{vec_addec}
18407 @tab @code{vec_adds}
18408 @tab @code{vec_all_eq}
18409 @item @code{vec_all_ge}
18410 @tab @code{vec_all_gt}
18411 @tab @code{vec_all_in}
18412 @item @code{vec_all_le}
18413 @tab @code{vec_all_lt}
18414 @tab @code{vec_all_nan}
18415 @item @code{vec_all_ne}
18416 @tab @code{vec_all_nge}
18417 @tab @code{vec_all_ngt}
18418 @item @code{vec_all_nle}
18419 @tab @code{vec_all_nlt}
18420 @tab @code{vec_all_numeric}
18421 @item @code{vec_and}
18422 @tab @code{vec_andc}
18423 @tab @code{vec_any_eq}
18424 @item @code{vec_any_ge}
18425 @tab @code{vec_any_gt}
18426 @tab @code{vec_any_le}
18427 @item @code{vec_any_lt}
18428 @tab @code{vec_any_nan}
18429 @tab @code{vec_any_ne}
18430 @item @code{vec_any_nge}
18431 @tab @code{vec_any_ngt}
18432 @tab @code{vec_any_nle}
18433 @item @code{vec_any_nlt}
18434 @tab @code{vec_any_numeric}
18435 @tab @code{vec_any_out}
18436 @item @code{vec_avg}
18437 @tab @code{vec_bperm}
18438 @tab @code{vec_ceil}
18439 @item @code{vec_cipher_be}
18440 @tab @code{vec_cipherlast_be}
18441 @tab @code{vec_cmpb}
18442 @item @code{vec_cmpeq}
18443 @tab @code{vec_cmpge}
18444 @tab @code{vec_cmpgt}
18445 @item @code{vec_cmple}
18446 @tab @code{vec_cmplt}
18447 @tab @code{vec_cmpne}
18448 @item @code{vec_cmpnez}
18449 @tab @code{vec_cntlz}
18450 @tab @code{vec_cntlz_lsbb}
18451 @item @code{vec_cnttz}
18452 @tab @code{vec_cnttz_lsbb}
18453 @tab @code{vec_cpsgn}
18454 @item @code{vec_ctf}
18455 @tab @code{vec_cts}
18456 @tab @code{vec_ctu}
18457 @item @code{vec_div}
18458 @tab @code{vec_double}
18459 @tab @code{vec_doublee}
18460 @item @code{vec_doubleh}
18461 @tab @code{vec_doublel}
18462 @tab @code{vec_doubleo}
18463 @item @code{vec_eqv}
18464 @tab @code{vec_expte}
18465 @tab @code{vec_extract}
18466 @item @code{vec_extract_exp}
18467 @tab @code{vec_extract_fp32_from_shorth}
18468 @tab @code{vec_extract_fp32_from_shortl}
18469 @item @code{vec_extract_sig}
18470 @tab @code{vec_extract_4b}
18471 @tab @code{vec_first_match_index}
18472 @item @code{vec_first_match_or_eos_index}
18473 @tab @code{vec_first_mismatch_index}
18474 @tab @code{vec_first_mismatch_or_eos_index}
18475 @item @code{vec_float}
18476 @tab @code{vec_float2}
18477 @tab @code{vec_floate}
18478 @item @code{vec_floato}
18479 @tab @code{vec_floor}
18481 @item @code{vec_insert}
18482 @tab @code{vec_insert_exp}
18483 @tab @code{vec_insert4b}
18484 @item @code{vec_ld}
18485 @tab @code{vec_lde}
18486 @tab @code{vec_ldl}
18487 @item @code{vec_loge}
18488 @tab @code{vec_madd}
18489 @tab @code{vec_madds}
18490 @item @code{vec_max}
18491 @tab @code{vec_mergee}
18492 @tab @code{vec_mergeh}
18493 @item @code{vec_mergel}
18494 @tab @code{vec_mergeo}
18495 @tab @code{vec_mfvscr}
18496 @item @code{vec_min}
18497 @tab @code{vec_mradds}
18498 @tab @code{vec_msub}
18499 @item @code{vec_msum}
18500 @tab @code{vec_msums}
18501 @tab @code{vec_mtvscr}
18502 @item @code{vec_mul}
18503 @tab @code{vec_mule}
18504 @tab @code{vec_mulo}
18505 @item @code{vec_nabs}
18506 @tab @code{vec_nand}
18507 @tab @code{vec_ncipher_be}
18508 @item @code{vec_ncipherlast_be}
18509 @tab @code{vec_nearbyint}
18510 @tab @code{vec_neg}
18511 @item @code{vec_nmadd}
18512 @tab @code{vec_nmsub}
18513 @tab @code{vec_nor}
18514 @item @code{vec_or}
18515 @tab @code{vec_orc}
18516 @tab @code{vec_pack}
18517 @item @code{vec_pack_to_short_fp32}
18518 @tab @code{vec_packpx}
18519 @tab @code{vec_packs}
18520 @item @code{vec_packsu}
18521 @tab @code{vec_parity_lsbb}
18522 @tab @code{vec_perm}
18523 @item @code{vec_permxor}
18524 @tab @code{vec_pmsum_be}
18525 @tab @code{vec_popcnt}
18526 @item @code{vec_re}
18527 @tab @code{vec_recipdiv}
18528 @tab @code{vec_revb}
18529 @item @code{vec_reve}
18530 @tab @code{vec_rint}
18532 @item @code{vec_rlmi}
18533 @tab @code{vec_rlnm}
18534 @tab @code{vec_round}
18535 @item @code{vec_rsqrt}
18536 @tab @code{vec_rsqrte}
18537 @tab @code{vec_sbox_be}
18538 @item @code{vec_sel}
18539 @tab @code{vec_shasigma_be}
18540 @tab @code{vec_signed}
18541 @item @code{vec_signed2}
18542 @tab @code{vec_signede}
18543 @tab @code{vec_signedo}
18544 @item @code{vec_sl}
18545 @tab @code{vec_sld}
18546 @tab @code{vec_sldw}
18547 @item @code{vec_sll}
18548 @tab @code{vec_slo}
18549 @tab @code{vec_slv}
18550 @item @code{vec_splat}
18551 @tab @code{vec_splat_s8}
18552 @tab @code{vec_splat_s16}
18553 @item @code{vec_splat_s32}
18554 @tab @code{vec_splat_u8}
18555 @tab @code{vec_splat_u16}
18556 @item @code{vec_splat_u32}
18557 @tab @code{vec_splats}
18558 @tab @code{vec_sqrt}
18559 @item @code{vec_sr}
18560 @tab @code{vec_sra}
18561 @tab @code{vec_srl}
18562 @item @code{vec_sro}
18563 @tab @code{vec_srv}
18565 @item @code{vec_ste}
18566 @tab @code{vec_stl}
18567 @tab @code{vec_sub}
18568 @item @code{vec_subc}
18569 @tab @code{vec_sube}
18570 @tab @code{vec_subec}
18571 @item @code{vec_subs}
18572 @tab @code{vec_sum2s}
18573 @tab @code{vec_sum4s}
18574 @item @code{vec_sums}
18575 @tab @code{vec_test_data_class}
18576 @tab @code{vec_trunc}
18577 @item @code{vec_unpackh}
18578 @tab @code{vec_unpackl}
18579 @tab @code{vec_unsigned}
18580 @item @code{vec_unsigned2}
18581 @tab @code{vec_unsignede}
18582 @tab @code{vec_unsignedo}
18583 @item @code{vec_xl}
18584 @tab @code{vec_xl_be}
18585 @tab @code{vec_xl_len}
18586 @item @code{vec_xl_len_r}
18587 @tab @code{vec_xor}
18588 @tab @code{vec_xst}
18589 @item @code{vec_xst_be}
18590 @tab @code{vec_xst_len}
18591 @tab @code{vec_xst_len_r}
18596 * PowerPC AltiVec Built-in Functions on ISA 2.05::
18597 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
18598 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
18599 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
18600 * PowerPC AltiVec Built-in Functions Available on ISA 3.1::
18603 @node PowerPC AltiVec Built-in Functions on ISA 2.05
18604 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
18606 The following interfaces are supported for the generic and specific
18607 AltiVec operations and the AltiVec predicates. In cases where there
18608 is a direct mapping between generic and specific operations, only the
18609 generic names are shown here, although the specific operations can also
18612 Arguments that are documented as @code{const int} require literal
18613 integral values within the range required for that operation.
18615 Only functions excluded from the PVIPR are listed here.
18618 void vec_dss (const int);
18620 void vec_dssall (void);
18622 void vec_dst (const vector unsigned char *, int, const int);
18623 void vec_dst (const vector signed char *, int, const int);
18624 void vec_dst (const vector bool char *, int, const int);
18625 void vec_dst (const vector unsigned short *, int, const int);
18626 void vec_dst (const vector signed short *, int, const int);
18627 void vec_dst (const vector bool short *, int, const int);
18628 void vec_dst (const vector pixel *, int, const int);
18629 void vec_dst (const vector unsigned int *, int, const int);
18630 void vec_dst (const vector signed int *, int, const int);
18631 void vec_dst (const vector bool int *, int, const int);
18632 void vec_dst (const vector float *, int, const int);
18633 void vec_dst (const unsigned char *, int, const int);
18634 void vec_dst (const signed char *, int, const int);
18635 void vec_dst (const unsigned short *, int, const int);
18636 void vec_dst (const short *, int, const int);
18637 void vec_dst (const unsigned int *, int, const int);
18638 void vec_dst (const int *, int, const int);
18639 void vec_dst (const float *, int, const int);
18641 void vec_dstst (const vector unsigned char *, int, const int);
18642 void vec_dstst (const vector signed char *, int, const int);
18643 void vec_dstst (const vector bool char *, int, const int);
18644 void vec_dstst (const vector unsigned short *, int, const int);
18645 void vec_dstst (const vector signed short *, int, const int);
18646 void vec_dstst (const vector bool short *, int, const int);
18647 void vec_dstst (const vector pixel *, int, const int);
18648 void vec_dstst (const vector unsigned int *, int, const int);
18649 void vec_dstst (const vector signed int *, int, const int);
18650 void vec_dstst (const vector bool int *, int, const int);
18651 void vec_dstst (const vector float *, int, const int);
18652 void vec_dstst (const unsigned char *, int, const int);
18653 void vec_dstst (const signed char *, int, const int);
18654 void vec_dstst (const unsigned short *, int, const int);
18655 void vec_dstst (const short *, int, const int);
18656 void vec_dstst (const unsigned int *, int, const int);
18657 void vec_dstst (const int *, int, const int);
18658 void vec_dstst (const unsigned long *, int, const int);
18659 void vec_dstst (const long *, int, const int);
18660 void vec_dstst (const float *, int, const int);
18662 void vec_dststt (const vector unsigned char *, int, const int);
18663 void vec_dststt (const vector signed char *, int, const int);
18664 void vec_dststt (const vector bool char *, int, const int);
18665 void vec_dststt (const vector unsigned short *, int, const int);
18666 void vec_dststt (const vector signed short *, int, const int);
18667 void vec_dststt (const vector bool short *, int, const int);
18668 void vec_dststt (const vector pixel *, int, const int);
18669 void vec_dststt (const vector unsigned int *, int, const int);
18670 void vec_dststt (const vector signed int *, int, const int);
18671 void vec_dststt (const vector bool int *, int, const int);
18672 void vec_dststt (const vector float *, int, const int);
18673 void vec_dststt (const unsigned char *, int, const int);
18674 void vec_dststt (const signed char *, int, const int);
18675 void vec_dststt (const unsigned short *, int, const int);
18676 void vec_dststt (const short *, int, const int);
18677 void vec_dststt (const unsigned int *, int, const int);
18678 void vec_dststt (const int *, int, const int);
18679 void vec_dststt (const float *, int, const int);
18681 void vec_dstt (const vector unsigned char *, int, const int);
18682 void vec_dstt (const vector signed char *, int, const int);
18683 void vec_dstt (const vector bool char *, int, const int);
18684 void vec_dstt (const vector unsigned short *, int, const int);
18685 void vec_dstt (const vector signed short *, int, const int);
18686 void vec_dstt (const vector bool short *, int, const int);
18687 void vec_dstt (const vector pixel *, int, const int);
18688 void vec_dstt (const vector unsigned int *, int, const int);
18689 void vec_dstt (const vector signed int *, int, const int);
18690 void vec_dstt (const vector bool int *, int, const int);
18691 void vec_dstt (const vector float *, int, const int);
18692 void vec_dstt (const unsigned char *, int, const int);
18693 void vec_dstt (const signed char *, int, const int);
18694 void vec_dstt (const unsigned short *, int, const int);
18695 void vec_dstt (const short *, int, const int);
18696 void vec_dstt (const unsigned int *, int, const int);
18697 void vec_dstt (const int *, int, const int);
18698 void vec_dstt (const float *, int, const int);
18700 vector signed char vec_lvebx (int, char *);
18701 vector unsigned char vec_lvebx (int, unsigned char *);
18703 vector signed short vec_lvehx (int, short *);
18704 vector unsigned short vec_lvehx (int, unsigned short *);
18706 vector float vec_lvewx (int, float *);
18707 vector signed int vec_lvewx (int, int *);
18708 vector unsigned int vec_lvewx (int, unsigned int *);
18710 vector unsigned char vec_lvsl (int, const unsigned char *);
18711 vector unsigned char vec_lvsl (int, const signed char *);
18712 vector unsigned char vec_lvsl (int, const unsigned short *);
18713 vector unsigned char vec_lvsl (int, const short *);
18714 vector unsigned char vec_lvsl (int, const unsigned int *);
18715 vector unsigned char vec_lvsl (int, const int *);
18716 vector unsigned char vec_lvsl (int, const float *);
18718 vector unsigned char vec_lvsr (int, const unsigned char *);
18719 vector unsigned char vec_lvsr (int, const signed char *);
18720 vector unsigned char vec_lvsr (int, const unsigned short *);
18721 vector unsigned char vec_lvsr (int, const short *);
18722 vector unsigned char vec_lvsr (int, const unsigned int *);
18723 vector unsigned char vec_lvsr (int, const int *);
18724 vector unsigned char vec_lvsr (int, const float *);
18726 void vec_stvebx (vector signed char, int, signed char *);
18727 void vec_stvebx (vector unsigned char, int, unsigned char *);
18728 void vec_stvebx (vector bool char, int, signed char *);
18729 void vec_stvebx (vector bool char, int, unsigned char *);
18731 void vec_stvehx (vector signed short, int, short *);
18732 void vec_stvehx (vector unsigned short, int, unsigned short *);
18733 void vec_stvehx (vector bool short, int, short *);
18734 void vec_stvehx (vector bool short, int, unsigned short *);
18736 void vec_stvewx (vector float, int, float *);
18737 void vec_stvewx (vector signed int, int, int *);
18738 void vec_stvewx (vector unsigned int, int, unsigned int *);
18739 void vec_stvewx (vector bool int, int, int *);
18740 void vec_stvewx (vector bool int, int, unsigned int *);
18742 vector float vec_vaddfp (vector float, vector float);
18744 vector signed char vec_vaddsbs (vector bool char, vector signed char);
18745 vector signed char vec_vaddsbs (vector signed char, vector bool char);
18746 vector signed char vec_vaddsbs (vector signed char, vector signed char);
18748 vector signed short vec_vaddshs (vector bool short, vector signed short);
18749 vector signed short vec_vaddshs (vector signed short, vector bool short);
18750 vector signed short vec_vaddshs (vector signed short, vector signed short);
18752 vector signed int vec_vaddsws (vector bool int, vector signed int);
18753 vector signed int vec_vaddsws (vector signed int, vector bool int);
18754 vector signed int vec_vaddsws (vector signed int, vector signed int);
18756 vector signed char vec_vaddubm (vector bool char, vector signed char);
18757 vector signed char vec_vaddubm (vector signed char, vector bool char);
18758 vector signed char vec_vaddubm (vector signed char, vector signed char);
18759 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
18760 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
18761 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
18763 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
18764 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
18765 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
18767 vector signed short vec_vadduhm (vector bool short, vector signed short);
18768 vector signed short vec_vadduhm (vector signed short, vector bool short);
18769 vector signed short vec_vadduhm (vector signed short, vector signed short);
18770 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
18771 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
18772 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
18774 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
18775 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
18776 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
18778 vector signed int vec_vadduwm (vector bool int, vector signed int);
18779 vector signed int vec_vadduwm (vector signed int, vector bool int);
18780 vector signed int vec_vadduwm (vector signed int, vector signed int);
18781 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
18782 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
18783 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
18785 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
18786 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
18787 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
18789 vector signed char vec_vavgsb (vector signed char, vector signed char);
18791 vector signed short vec_vavgsh (vector signed short, vector signed short);
18793 vector signed int vec_vavgsw (vector signed int, vector signed int);
18795 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
18797 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
18799 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
18801 vector float vec_vcfsx (vector signed int, const int);
18803 vector float vec_vcfux (vector unsigned int, const int);
18805 vector bool int vec_vcmpeqfp (vector float, vector float);
18807 vector bool char vec_vcmpequb (vector signed char, vector signed char);
18808 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
18810 vector bool short vec_vcmpequh (vector signed short, vector signed short);
18811 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
18813 vector bool int vec_vcmpequw (vector signed int, vector signed int);
18814 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
18816 vector bool int vec_vcmpgtfp (vector float, vector float);
18818 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
18820 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
18822 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
18824 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
18826 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
18828 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
18830 vector float vec_vmaxfp (vector float, vector float);
18832 vector signed char vec_vmaxsb (vector bool char, vector signed char);
18833 vector signed char vec_vmaxsb (vector signed char, vector bool char);
18834 vector signed char vec_vmaxsb (vector signed char, vector signed char);
18836 vector signed short vec_vmaxsh (vector bool short, vector signed short);
18837 vector signed short vec_vmaxsh (vector signed short, vector bool short);
18838 vector signed short vec_vmaxsh (vector signed short, vector signed short);
18840 vector signed int vec_vmaxsw (vector bool int, vector signed int);
18841 vector signed int vec_vmaxsw (vector signed int, vector bool int);
18842 vector signed int vec_vmaxsw (vector signed int, vector signed int);
18844 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
18845 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
18846 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
18848 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
18849 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
18850 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
18852 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
18853 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
18854 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
18856 vector float vec_vminfp (vector float, vector float);
18858 vector signed char vec_vminsb (vector bool char, vector signed char);
18859 vector signed char vec_vminsb (vector signed char, vector bool char);
18860 vector signed char vec_vminsb (vector signed char, vector signed char);
18862 vector signed short vec_vminsh (vector bool short, vector signed short);
18863 vector signed short vec_vminsh (vector signed short, vector bool short);
18864 vector signed short vec_vminsh (vector signed short, vector signed short);
18866 vector signed int vec_vminsw (vector bool int, vector signed int);
18867 vector signed int vec_vminsw (vector signed int, vector bool int);
18868 vector signed int vec_vminsw (vector signed int, vector signed int);
18870 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
18871 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
18872 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
18874 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
18875 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
18876 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
18878 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
18879 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
18880 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
18882 vector bool char vec_vmrghb (vector bool char, vector bool char);
18883 vector signed char vec_vmrghb (vector signed char, vector signed char);
18884 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
18886 vector bool short vec_vmrghh (vector bool short, vector bool short);
18887 vector signed short vec_vmrghh (vector signed short, vector signed short);
18888 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
18889 vector pixel vec_vmrghh (vector pixel, vector pixel);
18891 vector float vec_vmrghw (vector float, vector float);
18892 vector bool int vec_vmrghw (vector bool int, vector bool int);
18893 vector signed int vec_vmrghw (vector signed int, vector signed int);
18894 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
18896 vector bool char vec_vmrglb (vector bool char, vector bool char);
18897 vector signed char vec_vmrglb (vector signed char, vector signed char);
18898 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
18900 vector bool short vec_vmrglh (vector bool short, vector bool short);
18901 vector signed short vec_vmrglh (vector signed short, vector signed short);
18902 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
18903 vector pixel vec_vmrglh (vector pixel, vector pixel);
18905 vector float vec_vmrglw (vector float, vector float);
18906 vector signed int vec_vmrglw (vector signed int, vector signed int);
18907 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
18908 vector bool int vec_vmrglw (vector bool int, vector bool int);
18910 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
18911 vector signed int);
18913 vector signed int vec_vmsumshm (vector signed short, vector signed short,
18914 vector signed int);
18916 vector signed int vec_vmsumshs (vector signed short, vector signed short,
18917 vector signed int);
18919 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
18920 vector unsigned int);
18922 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
18923 vector unsigned int);
18925 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
18926 vector unsigned int);
18928 vector signed short vec_vmulesb (vector signed char, vector signed char);
18930 vector signed int vec_vmulesh (vector signed short, vector signed short);
18932 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
18934 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
18936 vector signed short vec_vmulosb (vector signed char, vector signed char);
18938 vector signed int vec_vmulosh (vector signed short, vector signed short);
18940 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
18942 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
18944 vector signed char vec_vpkshss (vector signed short, vector signed short);
18946 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
18948 vector signed short vec_vpkswss (vector signed int, vector signed int);
18950 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
18952 vector bool char vec_vpkuhum (vector bool short, vector bool short);
18953 vector signed char vec_vpkuhum (vector signed short, vector signed short);
18954 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
18956 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
18958 vector bool short vec_vpkuwum (vector bool int, vector bool int);
18959 vector signed short vec_vpkuwum (vector signed int, vector signed int);
18960 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
18962 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
18964 vector signed char vec_vrlb (vector signed char, vector unsigned char);
18965 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
18967 vector signed short vec_vrlh (vector signed short, vector unsigned short);
18968 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
18970 vector signed int vec_vrlw (vector signed int, vector unsigned int);
18971 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
18973 vector signed char vec_vslb (vector signed char, vector unsigned char);
18974 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
18976 vector signed short vec_vslh (vector signed short, vector unsigned short);
18977 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
18979 vector signed int vec_vslw (vector signed int, vector unsigned int);
18980 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
18982 vector signed char vec_vspltb (vector signed char, const int);
18983 vector unsigned char vec_vspltb (vector unsigned char, const int);
18984 vector bool char vec_vspltb (vector bool char, const int);
18986 vector bool short vec_vsplth (vector bool short, const int);
18987 vector signed short vec_vsplth (vector signed short, const int);
18988 vector unsigned short vec_vsplth (vector unsigned short, const int);
18989 vector pixel vec_vsplth (vector pixel, const int);
18991 vector float vec_vspltw (vector float, const int);
18992 vector signed int vec_vspltw (vector signed int, const int);
18993 vector unsigned int vec_vspltw (vector unsigned int, const int);
18994 vector bool int vec_vspltw (vector bool int, const int);
18996 vector signed char vec_vsrab (vector signed char, vector unsigned char);
18997 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
18999 vector signed short vec_vsrah (vector signed short, vector unsigned short);
19000 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
19002 vector signed int vec_vsraw (vector signed int, vector unsigned int);
19003 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
19005 vector signed char vec_vsrb (vector signed char, vector unsigned char);
19006 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
19008 vector signed short vec_vsrh (vector signed short, vector unsigned short);
19009 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
19011 vector signed int vec_vsrw (vector signed int, vector unsigned int);
19012 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
19014 vector float vec_vsubfp (vector float, vector float);
19016 vector signed char vec_vsubsbs (vector bool char, vector signed char);
19017 vector signed char vec_vsubsbs (vector signed char, vector bool char);
19018 vector signed char vec_vsubsbs (vector signed char, vector signed char);
19020 vector signed short vec_vsubshs (vector bool short, vector signed short);
19021 vector signed short vec_vsubshs (vector signed short, vector bool short);
19022 vector signed short vec_vsubshs (vector signed short, vector signed short);
19024 vector signed int vec_vsubsws (vector bool int, vector signed int);
19025 vector signed int vec_vsubsws (vector signed int, vector bool int);
19026 vector signed int vec_vsubsws (vector signed int, vector signed int);
19028 vector signed char vec_vsububm (vector bool char, vector signed char);
19029 vector signed char vec_vsububm (vector signed char, vector bool char);
19030 vector signed char vec_vsububm (vector signed char, vector signed char);
19031 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
19032 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
19033 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
19035 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
19036 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
19037 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
19039 vector signed short vec_vsubuhm (vector bool short, vector signed short);
19040 vector signed short vec_vsubuhm (vector signed short, vector bool short);
19041 vector signed short vec_vsubuhm (vector signed short, vector signed short);
19042 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
19043 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
19044 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
19046 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
19047 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
19048 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
19050 vector signed int vec_vsubuwm (vector bool int, vector signed int);
19051 vector signed int vec_vsubuwm (vector signed int, vector bool int);
19052 vector signed int vec_vsubuwm (vector signed int, vector signed int);
19053 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
19054 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
19055 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
19057 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
19058 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
19059 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
19061 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
19063 vector signed int vec_vsum4shs (vector signed short, vector signed int);
19065 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
19067 vector unsigned int vec_vupkhpx (vector pixel);
19069 vector bool short vec_vupkhsb (vector bool char);
19070 vector signed short vec_vupkhsb (vector signed char);
19072 vector bool int vec_vupkhsh (vector bool short);
19073 vector signed int vec_vupkhsh (vector signed short);
19075 vector unsigned int vec_vupklpx (vector pixel);
19077 vector bool short vec_vupklsb (vector bool char);
19078 vector signed short vec_vupklsb (vector signed char);
19080 vector bool int vec_vupklsh (vector bool short);
19081 vector signed int vec_vupklsh (vector signed short);
19084 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
19085 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
19087 The AltiVec built-in functions described in this section are
19088 available on the PowerPC family of processors starting with ISA 2.06
19089 or later. These are normally enabled by adding @option{-mvsx} to the
19092 When @option{-mvsx} is used, the following additional vector types are
19096 vector unsigned __int128
19097 vector signed __int128
19098 vector unsigned long long int
19099 vector signed long long int
19103 The long long types are only implemented for 64-bit code generation.
19105 Only functions excluded from the PVIPR are listed here.
19108 void vec_dst (const unsigned long *, int, const int);
19109 void vec_dst (const long *, int, const int);
19111 void vec_dststt (const unsigned long *, int, const int);
19112 void vec_dststt (const long *, int, const int);
19114 void vec_dstt (const unsigned long *, int, const int);
19115 void vec_dstt (const long *, int, const int);
19117 vector unsigned char vec_lvsl (int, const unsigned long *);
19118 vector unsigned char vec_lvsl (int, const long *);
19120 vector unsigned char vec_lvsr (int, const unsigned long *);
19121 vector unsigned char vec_lvsr (int, const long *);
19123 vector unsigned char vec_lvsl (int, const double *);
19124 vector unsigned char vec_lvsr (int, const double *);
19126 vector double vec_vsx_ld (int, const vector double *);
19127 vector double vec_vsx_ld (int, const double *);
19128 vector float vec_vsx_ld (int, const vector float *);
19129 vector float vec_vsx_ld (int, const float *);
19130 vector bool int vec_vsx_ld (int, const vector bool int *);
19131 vector signed int vec_vsx_ld (int, const vector signed int *);
19132 vector signed int vec_vsx_ld (int, const int *);
19133 vector signed int vec_vsx_ld (int, const long *);
19134 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
19135 vector unsigned int vec_vsx_ld (int, const unsigned int *);
19136 vector unsigned int vec_vsx_ld (int, const unsigned long *);
19137 vector bool short vec_vsx_ld (int, const vector bool short *);
19138 vector pixel vec_vsx_ld (int, const vector pixel *);
19139 vector signed short vec_vsx_ld (int, const vector signed short *);
19140 vector signed short vec_vsx_ld (int, const short *);
19141 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
19142 vector unsigned short vec_vsx_ld (int, const unsigned short *);
19143 vector bool char vec_vsx_ld (int, const vector bool char *);
19144 vector signed char vec_vsx_ld (int, const vector signed char *);
19145 vector signed char vec_vsx_ld (int, const signed char *);
19146 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
19147 vector unsigned char vec_vsx_ld (int, const unsigned char *);
19149 void vec_vsx_st (vector double, int, vector double *);
19150 void vec_vsx_st (vector double, int, double *);
19151 void vec_vsx_st (vector float, int, vector float *);
19152 void vec_vsx_st (vector float, int, float *);
19153 void vec_vsx_st (vector signed int, int, vector signed int *);
19154 void vec_vsx_st (vector signed int, int, int *);
19155 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
19156 void vec_vsx_st (vector unsigned int, int, unsigned int *);
19157 void vec_vsx_st (vector bool int, int, vector bool int *);
19158 void vec_vsx_st (vector bool int, int, unsigned int *);
19159 void vec_vsx_st (vector bool int, int, int *);
19160 void vec_vsx_st (vector signed short, int, vector signed short *);
19161 void vec_vsx_st (vector signed short, int, short *);
19162 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
19163 void vec_vsx_st (vector unsigned short, int, unsigned short *);
19164 void vec_vsx_st (vector bool short, int, vector bool short *);
19165 void vec_vsx_st (vector bool short, int, unsigned short *);
19166 void vec_vsx_st (vector pixel, int, vector pixel *);
19167 void vec_vsx_st (vector pixel, int, unsigned short *);
19168 void vec_vsx_st (vector pixel, int, short *);
19169 void vec_vsx_st (vector bool short, int, short *);
19170 void vec_vsx_st (vector signed char, int, vector signed char *);
19171 void vec_vsx_st (vector signed char, int, signed char *);
19172 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
19173 void vec_vsx_st (vector unsigned char, int, unsigned char *);
19174 void vec_vsx_st (vector bool char, int, vector bool char *);
19175 void vec_vsx_st (vector bool char, int, unsigned char *);
19176 void vec_vsx_st (vector bool char, int, signed char *);
19178 vector double vec_xxpermdi (vector double, vector double, const int);
19179 vector float vec_xxpermdi (vector float, vector float, const int);
19180 vector long long vec_xxpermdi (vector long long, vector long long, const int);
19181 vector unsigned long long vec_xxpermdi (vector unsigned long long,
19182 vector unsigned long long, const int);
19183 vector int vec_xxpermdi (vector int, vector int, const int);
19184 vector unsigned int vec_xxpermdi (vector unsigned int,
19185 vector unsigned int, const int);
19186 vector short vec_xxpermdi (vector short, vector short, const int);
19187 vector unsigned short vec_xxpermdi (vector unsigned short,
19188 vector unsigned short, const int);
19189 vector signed char vec_xxpermdi (vector signed char, vector signed char,
19191 vector unsigned char vec_xxpermdi (vector unsigned char,
19192 vector unsigned char, const int);
19194 vector double vec_xxsldi (vector double, vector double, int);
19195 vector float vec_xxsldi (vector float, vector float, int);
19196 vector long long vec_xxsldi (vector long long, vector long long, int);
19197 vector unsigned long long vec_xxsldi (vector unsigned long long,
19198 vector unsigned long long, int);
19199 vector int vec_xxsldi (vector int, vector int, int);
19200 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
19201 vector short vec_xxsldi (vector short, vector short, int);
19202 vector unsigned short vec_xxsldi (vector unsigned short,
19203 vector unsigned short, int);
19204 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
19205 vector unsigned char vec_xxsldi (vector unsigned char,
19206 vector unsigned char, int);
19209 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
19210 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
19211 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
19212 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
19213 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
19215 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
19216 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
19218 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19219 instruction set are available, the following additional functions are
19220 available for both 32-bit and 64-bit targets. For 64-bit targets, you
19221 can use @var{vector long} instead of @var{vector long long},
19222 @var{vector bool long} instead of @var{vector bool long long}, and
19223 @var{vector unsigned long} instead of @var{vector unsigned long long}.
19225 Only functions excluded from the PVIPR are listed here.
19228 vector long long vec_vaddudm (vector long long, vector long long);
19229 vector long long vec_vaddudm (vector bool long long, vector long long);
19230 vector long long vec_vaddudm (vector long long, vector bool long long);
19231 vector unsigned long long vec_vaddudm (vector unsigned long long,
19232 vector unsigned long long);
19233 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
19234 vector unsigned long long);
19235 vector unsigned long long vec_vaddudm (vector unsigned long long,
19236 vector bool unsigned long long);
19238 vector long long vec_vclz (vector long long);
19239 vector unsigned long long vec_vclz (vector unsigned long long);
19240 vector int vec_vclz (vector int);
19241 vector unsigned int vec_vclz (vector int);
19242 vector short vec_vclz (vector short);
19243 vector unsigned short vec_vclz (vector unsigned short);
19244 vector signed char vec_vclz (vector signed char);
19245 vector unsigned char vec_vclz (vector unsigned char);
19247 vector signed char vec_vclzb (vector signed char);
19248 vector unsigned char vec_vclzb (vector unsigned char);
19250 vector long long vec_vclzd (vector long long);
19251 vector unsigned long long vec_vclzd (vector unsigned long long);
19253 vector short vec_vclzh (vector short);
19254 vector unsigned short vec_vclzh (vector unsigned short);
19256 vector int vec_vclzw (vector int);
19257 vector unsigned int vec_vclzw (vector int);
19259 vector signed char vec_vgbbd (vector signed char);
19260 vector unsigned char vec_vgbbd (vector unsigned char);
19262 vector long long vec_vmaxsd (vector long long, vector long long);
19264 vector unsigned long long vec_vmaxud (vector unsigned long long,
19265 unsigned vector long long);
19267 vector long long vec_vminsd (vector long long, vector long long);
19269 vector unsigned long long vec_vminud (vector long long, vector long long);
19271 vector int vec_vpksdss (vector long long, vector long long);
19272 vector unsigned int vec_vpksdss (vector long long, vector long long);
19274 vector unsigned int vec_vpkudus (vector unsigned long long,
19275 vector unsigned long long);
19277 vector int vec_vpkudum (vector long long, vector long long);
19278 vector unsigned int vec_vpkudum (vector unsigned long long,
19279 vector unsigned long long);
19280 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
19282 vector long long vec_vpopcnt (vector long long);
19283 vector unsigned long long vec_vpopcnt (vector unsigned long long);
19284 vector int vec_vpopcnt (vector int);
19285 vector unsigned int vec_vpopcnt (vector int);
19286 vector short vec_vpopcnt (vector short);
19287 vector unsigned short vec_vpopcnt (vector unsigned short);
19288 vector signed char vec_vpopcnt (vector signed char);
19289 vector unsigned char vec_vpopcnt (vector unsigned char);
19291 vector signed char vec_vpopcntb (vector signed char);
19292 vector unsigned char vec_vpopcntb (vector unsigned char);
19294 vector long long vec_vpopcntd (vector long long);
19295 vector unsigned long long vec_vpopcntd (vector unsigned long long);
19297 vector short vec_vpopcnth (vector short);
19298 vector unsigned short vec_vpopcnth (vector unsigned short);
19300 vector int vec_vpopcntw (vector int);
19301 vector unsigned int vec_vpopcntw (vector int);
19303 vector long long vec_vrld (vector long long, vector unsigned long long);
19304 vector unsigned long long vec_vrld (vector unsigned long long,
19305 vector unsigned long long);
19307 vector long long vec_vsld (vector long long, vector unsigned long long);
19308 vector long long vec_vsld (vector unsigned long long,
19309 vector unsigned long long);
19311 vector long long vec_vsrad (vector long long, vector unsigned long long);
19312 vector unsigned long long vec_vsrad (vector unsigned long long,
19313 vector unsigned long long);
19315 vector long long vec_vsrd (vector long long, vector unsigned long long);
19316 vector unsigned long long char vec_vsrd (vector unsigned long long,
19317 vector unsigned long long);
19319 vector long long vec_vsubudm (vector long long, vector long long);
19320 vector long long vec_vsubudm (vector bool long long, vector long long);
19321 vector long long vec_vsubudm (vector long long, vector bool long long);
19322 vector unsigned long long vec_vsubudm (vector unsigned long long,
19323 vector unsigned long long);
19324 vector unsigned long long vec_vsubudm (vector bool long long,
19325 vector unsigned long long);
19326 vector unsigned long long vec_vsubudm (vector unsigned long long,
19327 vector bool long long);
19329 vector long long vec_vupkhsw (vector int);
19330 vector unsigned long long vec_vupkhsw (vector unsigned int);
19332 vector long long vec_vupklsw (vector int);
19333 vector unsigned long long vec_vupklsw (vector int);
19336 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19337 instruction set are available, the following additional functions are
19338 available for 64-bit targets. New vector types
19339 (@var{vector __int128} and @var{vector __uint128}) are available
19340 to hold the @var{__int128} and @var{__uint128} types to use these
19343 The normal vector extract, and set operations work on
19344 @var{vector __int128} and @var{vector __uint128} types,
19345 but the index value must be 0.
19347 Only functions excluded from the PVIPR are listed here.
19350 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
19351 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
19353 vector __int128 vec_vadduqm (vector __int128, vector __int128);
19354 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
19356 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
19358 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
19361 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
19363 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
19366 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
19368 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
19371 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
19373 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
19376 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
19377 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
19379 __int128 vec_vsubuqm (__int128, __int128);
19380 __uint128 vec_vsubuqm (__uint128, __uint128);
19382 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
19383 vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char,
19385 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
19386 int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int);
19387 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
19388 int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int);
19389 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
19390 int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int);
19391 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
19392 int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int);
19394 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
19395 vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char,
19397 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
19398 int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int);
19399 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
19400 int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int);
19401 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
19402 int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int);
19403 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
19404 int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int);
19407 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
19408 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
19410 The following additional built-in functions are also available for the
19411 PowerPC family of processors, starting with ISA 3.0
19412 (@option{-mcpu=power9}) or later.
19414 Only instructions excluded from the PVIPR are listed here.
19417 unsigned int scalar_extract_exp (double source);
19418 unsigned long long int scalar_extract_exp (__ieee128 source);
19420 unsigned long long int scalar_extract_sig (double source);
19421 unsigned __int128 scalar_extract_sig (__ieee128 source);
19423 double scalar_insert_exp (unsigned long long int significand,
19424 unsigned long long int exponent);
19425 double scalar_insert_exp (double significand, unsigned long long int exponent);
19427 ieee_128 scalar_insert_exp (unsigned __int128 significand,
19428 unsigned long long int exponent);
19429 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
19431 int scalar_cmp_exp_gt (double arg1, double arg2);
19432 int scalar_cmp_exp_lt (double arg1, double arg2);
19433 int scalar_cmp_exp_eq (double arg1, double arg2);
19434 int scalar_cmp_exp_unordered (double arg1, double arg2);
19436 bool scalar_test_data_class (float source, const int condition);
19437 bool scalar_test_data_class (double source, const int condition);
19438 bool scalar_test_data_class (__ieee128 source, const int condition);
19440 bool scalar_test_neg (float source);
19441 bool scalar_test_neg (double source);
19442 bool scalar_test_neg (__ieee128 source);
19445 The @code{scalar_extract_exp} and @code{scalar_extract_sig}
19446 functions require a 64-bit environment supporting ISA 3.0 or later.
19447 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
19448 functions return the significand and the biased exponent value
19449 respectively of their @code{source} arguments.
19450 When supplied with a 64-bit @code{source} argument, the
19451 result returned by @code{scalar_extract_sig} has
19452 the @code{0x0010000000000000} bit set if the
19453 function's @code{source} argument is in normalized form.
19454 Otherwise, this bit is set to 0.
19455 When supplied with a 128-bit @code{source} argument, the
19456 @code{0x00010000000000000000000000000000} bit of the result is
19458 Note that the sign of the significand is not represented in the result
19459 returned from the @code{scalar_extract_sig} function. Use the
19460 @code{scalar_test_neg} function to test the sign of its @code{double}
19463 The @code{scalar_insert_exp}
19464 functions require a 64-bit environment supporting ISA 3.0 or later.
19465 When supplied with a 64-bit first argument, the
19466 @code{scalar_insert_exp} built-in function returns a double-precision
19467 floating point value that is constructed by assembling the values of its
19468 @code{significand} and @code{exponent} arguments. The sign of the
19469 result is copied from the most significant bit of the
19470 @code{significand} argument. The significand and exponent components
19471 of the result are composed of the least significant 11 bits of the
19472 @code{exponent} argument and the least significant 52 bits of the
19473 @code{significand} argument respectively.
19475 When supplied with a 128-bit first argument, the
19476 @code{scalar_insert_exp} built-in function returns a quad-precision
19477 ieee floating point value. The sign bit of the result is copied from
19478 the most significant bit of the @code{significand} argument.
19479 The significand and exponent components of the result are composed of
19480 the least significant 15 bits of the @code{exponent} argument and the
19481 least significant 112 bits of the @code{significand} argument respectively.
19483 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
19484 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
19485 functions return a non-zero value if @code{arg1} is greater than, less
19486 than, equal to, or not comparable to @code{arg2} respectively. The
19487 arguments are not comparable if one or the other equals NaN (not a
19490 The @code{scalar_test_data_class} built-in function returns 1
19491 if any of the condition tests enabled by the value of the
19492 @code{condition} variable are true, and 0 otherwise. The
19493 @code{condition} argument must be a compile-time constant integer with
19494 value not exceeding 127. The
19495 @code{condition} argument is encoded as a bitmask with each bit
19496 enabling the testing of a different condition, as characterized by the
19500 0x20 Test for +Infinity
19501 0x10 Test for -Infinity
19502 0x08 Test for +Zero
19503 0x04 Test for -Zero
19504 0x02 Test for +Denormal
19505 0x01 Test for -Denormal
19508 The @code{scalar_test_neg} built-in function returns 1 if its
19509 @code{source} argument holds a negative value, 0 otherwise.
19511 The following built-in functions are also available for the PowerPC family
19512 of processors, starting with ISA 3.0 or later
19513 (@option{-mcpu=power9}). These string functions are described
19514 separately in order to group the descriptions closer to the function
19517 Only functions excluded from the PVIPR are listed here.
19520 int vec_all_nez (vector signed char, vector signed char);
19521 int vec_all_nez (vector unsigned char, vector unsigned char);
19522 int vec_all_nez (vector signed short, vector signed short);
19523 int vec_all_nez (vector unsigned short, vector unsigned short);
19524 int vec_all_nez (vector signed int, vector signed int);
19525 int vec_all_nez (vector unsigned int, vector unsigned int);
19527 int vec_any_eqz (vector signed char, vector signed char);
19528 int vec_any_eqz (vector unsigned char, vector unsigned char);
19529 int vec_any_eqz (vector signed short, vector signed short);
19530 int vec_any_eqz (vector unsigned short, vector unsigned short);
19531 int vec_any_eqz (vector signed int, vector signed int);
19532 int vec_any_eqz (vector unsigned int, vector unsigned int);
19534 signed char vec_xlx (unsigned int index, vector signed char data);
19535 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
19536 signed short vec_xlx (unsigned int index, vector signed short data);
19537 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
19538 signed int vec_xlx (unsigned int index, vector signed int data);
19539 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
19540 float vec_xlx (unsigned int index, vector float data);
19542 signed char vec_xrx (unsigned int index, vector signed char data);
19543 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
19544 signed short vec_xrx (unsigned int index, vector signed short data);
19545 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
19546 signed int vec_xrx (unsigned int index, vector signed int data);
19547 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
19548 float vec_xrx (unsigned int index, vector float data);
19551 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
19552 perform pairwise comparisons between the elements at the same
19553 positions within their two vector arguments.
19554 The @code{vec_all_nez} function returns a
19555 non-zero value if and only if all pairwise comparisons are not
19556 equal and no element of either vector argument contains a zero.
19557 The @code{vec_any_eqz} function returns a
19558 non-zero value if and only if at least one pairwise comparison is equal
19559 or if at least one element of either vector argument contains a zero.
19560 The @code{vec_cmpnez} function returns a vector of the same type as
19561 its two arguments, within which each element consists of all ones to
19562 denote that either the corresponding elements of the incoming arguments are
19563 not equal or that at least one of the corresponding elements contains
19564 zero. Otherwise, the element of the returned vector contains all zeros.
19566 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
19567 element selected by the @code{index} argument from the vector
19568 represented by the @code{data} argument. The @code{index} argument
19569 always specifies a byte offset, regardless of the size of the vector
19570 element. With @code{vec_xlx}, @code{index} is the offset of the first
19571 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
19572 represents the last byte of the element to be extracted, measured
19573 from the right end of the vector. In other words, the last byte of
19574 the element to be extracted is found at position @code{(15 - index)}.
19575 There is no requirement that @code{index} be a multiple of the vector
19576 element size. However, if the size of the vector element added to
19577 @code{index} is greater than 15, the content of the returned value is
19580 The following functions are also available if the ISA 3.0 instruction
19581 set additions (@option{-mcpu=power9}) are available.
19583 Only functions excluded from the PVIPR are listed here.
19586 vector long long vec_vctz (vector long long);
19587 vector unsigned long long vec_vctz (vector unsigned long long);
19588 vector int vec_vctz (vector int);
19589 vector unsigned int vec_vctz (vector int);
19590 vector short vec_vctz (vector short);
19591 vector unsigned short vec_vctz (vector unsigned short);
19592 vector signed char vec_vctz (vector signed char);
19593 vector unsigned char vec_vctz (vector unsigned char);
19595 vector signed char vec_vctzb (vector signed char);
19596 vector unsigned char vec_vctzb (vector unsigned char);
19598 vector long long vec_vctzd (vector long long);
19599 vector unsigned long long vec_vctzd (vector unsigned long long);
19601 vector short vec_vctzh (vector short);
19602 vector unsigned short vec_vctzh (vector unsigned short);
19604 vector int vec_vctzw (vector int);
19605 vector unsigned int vec_vctzw (vector int);
19607 vector int vec_vprtyb (vector int);
19608 vector unsigned int vec_vprtyb (vector unsigned int);
19609 vector long long vec_vprtyb (vector long long);
19610 vector unsigned long long vec_vprtyb (vector unsigned long long);
19612 vector int vec_vprtybw (vector int);
19613 vector unsigned int vec_vprtybw (vector unsigned int);
19615 vector long long vec_vprtybd (vector long long);
19616 vector unsigned long long vec_vprtybd (vector unsigned long long);
19619 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
19623 vector long vec_vprtyb (vector long);
19624 vector unsigned long vec_vprtyb (vector unsigned long);
19625 vector __int128 vec_vprtyb (vector __int128);
19626 vector __uint128 vec_vprtyb (vector __uint128);
19628 vector long vec_vprtybd (vector long);
19629 vector unsigned long vec_vprtybd (vector unsigned long);
19631 vector __int128 vec_vprtybq (vector __int128);
19632 vector __uint128 vec_vprtybd (vector __uint128);
19635 The following built-in functions are available for the PowerPC family
19636 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}).
19638 Only functions excluded from the PVIPR are listed here.
19641 __vector unsigned char
19642 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
19643 __vector unsigned short
19644 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
19645 __vector unsigned int
19646 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
19649 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
19650 @code{vec_absdw} built-in functions each computes the absolute
19651 differences of the pairs of vector elements supplied in its two vector
19652 arguments, placing the absolute differences into the corresponding
19653 elements of the vector result.
19655 The following built-in functions are available for the PowerPC family
19656 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
19658 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
19659 vector unsigned long long vec_vrlnm (vector unsigned long long,
19660 vector unsigned long long);
19663 The result of @code{vec_vrlnm} is obtained by rotating each element
19664 of the first argument vector left and ANDing it with a mask. The
19665 second argument vector contains the mask beginning in bits 11:15,
19666 the mask end in bits 19:23, and the shift count in bits 27:31,
19669 If the cryptographic instructions are enabled (@option{-mcrypto} or
19670 @option{-mcpu=power8}), the following builtins are enabled.
19672 Only functions excluded from the PVIPR are listed here.
19675 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
19677 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
19678 vector unsigned long long);
19680 vector unsigned long long __builtin_crypto_vcipherlast
19681 (vector unsigned long long,
19682 vector unsigned long long);
19684 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
19685 vector unsigned long long);
19687 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
19688 vector unsigned long long);
19690 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
19691 vector unsigned char,
19692 vector unsigned char);
19694 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
19695 vector unsigned short,
19696 vector unsigned short);
19698 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
19699 vector unsigned int,
19700 vector unsigned int);
19702 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
19703 vector unsigned long long,
19704 vector unsigned long long);
19706 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
19707 vector unsigned char);
19709 vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short,
19710 vector unsigned short);
19712 vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int,
19713 vector unsigned int);
19715 vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long,
19716 vector unsigned long long);
19718 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
19721 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
19724 The second argument to @var{__builtin_crypto_vshasigmad} and
19725 @var{__builtin_crypto_vshasigmaw} must be a constant
19726 integer that is 0 or 1. The third argument to these built-in functions
19727 must be a constant integer in the range of 0 to 15.
19729 The following sign extension builtins are provided:
19732 vector signed int vec_signexti (vector signed char a);
19733 vector signed long long vec_signextll (vector signed char a);
19734 vector signed int vec_signexti (vector signed short a);
19735 vector signed long long vec_signextll (vector signed short a);
19736 vector signed long long vec_signextll (vector signed int a);
19737 vector signed long long vec_signextq (vector signed long long a);
19740 Each element of the result is produced by sign-extending the element of the
19741 input vector that would fall in the least significant portion of the result
19742 element. For example, a sign-extension of a vector signed char to a vector
19743 signed long long will sign extend the rightmost byte of each doubleword.
19745 @node PowerPC AltiVec Built-in Functions Available on ISA 3.1
19746 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1
19748 The following additional built-in functions are also available for the
19749 PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}):
19753 @exdent vector unsigned long long int
19754 @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int);
19756 Perform a vector centrifuge operation, as if implemented by the
19757 @code{vcfuged} instruction.
19761 @exdent vector unsigned long long int
19762 @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int);
19764 Perform a vector count leading zeros under bit mask operation, as if
19765 implemented by the @code{vclzdm} instruction.
19769 @exdent vector unsigned long long int
19770 @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int);
19772 Perform a vector count trailing zeros under bit mask operation, as if
19773 implemented by the @code{vctzdm} instruction.
19777 @exdent vector signed char
19778 @exdent vec_clrl (vector signed char a, unsigned int n);
19779 @exdent vector unsigned char
19780 @exdent vec_clrl (vector unsigned char a, unsigned int n);
19782 Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if
19783 implemented by the @code{vclrlb} instruction on a big-endian target
19784 and by the @code{vclrrb} instruction on a little-endian target. A
19785 value of @code{n} that is greater than 16 is treated as if it equaled 16.
19789 @exdent vector signed char
19790 @exdent vec_clrr (vector signed char a, unsigned int n);
19791 @exdent vector unsigned char
19792 @exdent vec_clrr (vector unsigned char a, unsigned int n);
19794 Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if
19795 implemented by the @code{vclrrb} instruction on a big-endian target
19796 and by the @code{vclrlb} instruction on a little-endian target. A
19797 value of @code{n} that is greater than 16 is treated as if it equaled 16.
19801 @exdent vector unsigned long long int
19802 @exdent vec_gnb (vector unsigned __int128, const unsigned char);
19804 Perform a 128-bit vector gather operation, as if implemented by the
19805 @code{vgnb} instruction. The second argument must be a literal
19806 integer value between 2 and 7 inclusive.
19813 @exdent vector unsigned long long int
19814 @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int);
19815 @exdent vector unsigned long long int
19816 @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int);
19817 @exdent vector unsigned long long int
19818 @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int);
19819 @exdent vector unsigned long long int
19820 @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int);
19822 Extract an element from two concatenated vectors starting at the given byte index
19823 in natural-endian order, and place it zero-extended in doubleword 1 of the result
19824 according to natural element order. If the byte index is out of range for the
19825 data type, the intrinsic will be rejected.
19826 For little-endian, this output will match the placement by the hardware
19827 instruction, i.e., dword[0] in RTL notation. For big-endian, an additional
19828 instruction is needed to move it from the "left" doubleword to the "right" one.
19829 For little-endian, semantics matching the @code{vextdubvrx},
19830 @code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for
19831 big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx},
19832 @code{vextduwvlx} instructions
19833 will be generated. Note that some fairly anomalous results can be generated if
19834 the byte index is not aligned on an element boundary for the element being
19835 extracted. This is a limitation of the bi-endian vector programming model is
19836 consistent with the limitation on @code{vec_perm}.
19837 @findex vec_extractl
19840 @exdent vector unsigned long long int
19841 @exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int);
19842 @exdent vector unsigned long long int
19843 @exdent vec_extracth (vector unsigned short, vector unsigned short,
19845 @exdent vector unsigned long long int
19846 @exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int);
19847 @exdent vector unsigned long long int
19848 @exdent vec_extracth (vector unsigned long long, vector unsigned long long,
19851 Extract an element from two concatenated vectors starting at the given byte
19852 index. The index is based on big endian order for a little endian system.
19853 Similarly, the index is based on little endian order for a big endian system.
19854 The extraced elements are zero-extended and put in doubleword 1
19855 according to natural element order. If the byte index is out of range for the
19856 data type, the intrinsic will be rejected. For little-endian, this output
19857 will match the placement by the hardware instruction (vextdubvrx, vextduhvrx,
19858 vextduwvrx, vextddvrx) i.e., dword[0] in RTL
19859 notation. For big-endian, an additional instruction is needed to move it
19860 from the "left" doubleword to the "right" one. For little-endian, semantics
19861 matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx}
19862 instructions will be generated, while for big-endian, semantics matching the
19863 @code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will
19864 be generated. Note that some fairly anomalous
19865 results can be generated if the byte index is not aligned on the
19866 element boundary for the element being extracted. This is a
19867 limitation of the bi-endian vector programming model consistent with the
19868 limitation on @code{vec_perm}.
19869 @findex vec_extracth
19871 @exdent vector unsigned long long int
19872 @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int);
19874 Perform a vector parallel bits deposit operation, as if implemented by
19875 the @code{vpdepd} instruction.
19881 @exdent vector unsigned char
19882 @exdent vec_insertl (unsigned char, vector unsigned char, unsigned int);
19883 @exdent vector unsigned short
19884 @exdent vec_insertl (unsigned short, vector unsigned short, unsigned int);
19885 @exdent vector unsigned int
19886 @exdent vec_insertl (unsigned int, vector unsigned int, unsigned int);
19887 @exdent vector unsigned long long
19888 @exdent vec_insertl (unsigned long long, vector unsigned long long,
19890 @exdent vector unsigned char
19891 @exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int;
19892 @exdent vector unsigned short
19893 @exdent vec_insertl (vector unsigned short, vector unsigned short,
19895 @exdent vector unsigned int
19896 @exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int);
19899 Let src be the first argument, when the first argument is a scalar, or the
19900 rightmost element of the left doubleword of the first argument, when the first
19901 argument is a vector. Insert the source into the destination at the position
19902 given by the third argument, using natural element order in the second
19903 argument. The rest of the second argument is unchanged. If the byte
19904 index is greater than 14 for halfwords, greater than 12 for words, or
19905 greater than 8 for doublewords the result is undefined. For little-endian,
19906 the generated code will be semantically equivalent to @code{vins[bhwd]rx}
19907 instructions. Similarly for big-endian it will be semantically equivalent
19908 to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be
19909 generated if the byte index is not aligned on an element boundary for the
19910 type of element being inserted.
19911 @findex vec_insertl
19914 @exdent vector unsigned char
19915 @exdent vec_inserth (unsigned char, vector unsigned char, unsigned int);
19916 @exdent vector unsigned short
19917 @exdent vec_inserth (unsigned short, vector unsigned short, unsigned int);
19918 @exdent vector unsigned int
19919 @exdent vec_inserth (unsigned int, vector unsigned int, unsigned int);
19920 @exdent vector unsigned long long
19921 @exdent vec_inserth (unsigned long long, vector unsigned long long,
19923 @exdent vector unsigned char
19924 @exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int);
19925 @exdent vector unsigned short
19926 @exdent vec_inserth (vector unsigned short, vector unsigned short,
19928 @exdent vector unsigned int
19929 @exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int);
19932 Let src be the first argument, when the first argument is a scalar, or the
19933 rightmost element of the first argument, when the first argument is a vector.
19934 Insert src into the second argument at the position identified by the third
19935 argument, using opposite element order in the second argument, and leaving the
19936 rest of the second argument unchanged. If the byte index is greater than 14
19937 for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be
19938 rejected. Note that the underlying hardware instruction uses the same register
19939 for the second argument and the result.
19940 For little-endian, the code generation will be semantically equivalent to
19941 @code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to
19942 @code{vins[bhwd]rx}.
19943 Note that some fairly anomalous results can be generated if the byte index is
19944 not aligned on an element boundary for the sort of element being inserted.
19945 @findex vec_inserth
19947 Vector Replace Element
19949 @exdent vector signed int vec_replace_elt (vector signed int, signed int,
19951 @exdent vector unsigned int vec_replace_elt (vector unsigned int,
19952 unsigned int, const int);
19953 @exdent vector float vec_replace_elt (vector float, float, const int);
19954 @exdent vector signed long long vec_replace_elt (vector signed long long,
19955 signed long long, const int);
19956 @exdent vector unsigned long long vec_replace_elt (vector unsigned long long,
19957 unsigned long long, const int);
19958 @exdent vector double rec_replace_elt (vector double, double, const int);
19960 The third argument (constrained to [0,3]) identifies the natural-endian
19961 element number of the first argument that will be replaced by the second
19962 argument to produce the result. The other elements of the first argument will
19963 remain unchanged in the result.
19965 If it's desirable to insert a word at an unaligned position, use
19966 vec_replace_unaligned instead.
19968 @findex vec_replace_element
19970 Vector Replace Unaligned
19972 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19973 signed int, const int);
19974 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19975 unsigned int, const int);
19976 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19978 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19979 signed long long, const int);
19980 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19981 unsigned long long, const int);
19982 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
19983 double, const int);
19986 The second argument replaces a portion of the first argument to produce the
19987 result, with the rest of the first argument unchanged in the result. The
19988 third argument identifies the byte index (using left-to-right, or big-endian
19989 order) where the high-order byte of the second argument will be placed, with
19990 the remaining bytes of the second argument placed naturally "to the right"
19991 of the high-order byte.
19993 The programmer is responsible for understanding the endianness issues involved
19994 with the first argument and the result.
19995 @findex vec_replace_unaligned
19997 Vector Shift Left Double Bit Immediate
19999 @exdent vector signed char vec_sldb (vector signed char, vector signed char,
20000 const unsigned int);
20001 @exdent vector unsigned char vec_sldb (vector unsigned char,
20002 vector unsigned char, const unsigned int);
20003 @exdent vector signed short vec_sldb (vector signed short, vector signed short,
20004 const unsigned int);
20005 @exdent vector unsigned short vec_sldb (vector unsigned short,
20006 vector unsigned short, const unsigned int);
20007 @exdent vector signed int vec_sldb (vector signed int, vector signed int,
20008 const unsigned int);
20009 @exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int,
20010 const unsigned int);
20011 @exdent vector signed long long vec_sldb (vector signed long long,
20012 vector signed long long, const unsigned int);
20013 @exdent vector unsigned long long vec_sldb (vector unsigned long long,
20014 vector unsigned long long, const unsigned int);
20017 Shift the combined input vectors left by the amount specified by the low-order
20018 three bits of the third argument, and return the leftmost remaining 128 bits.
20019 Code using this instruction must be endian-aware.
20023 Vector Shift Right Double Bit Immediate
20026 @exdent vector signed char vec_srdb (vector signed char, vector signed char,
20027 const unsigned int);
20028 @exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char,
20029 const unsigned int);
20030 @exdent vector signed short vec_srdb (vector signed short, vector signed short,
20031 const unsigned int);
20032 @exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short,
20033 const unsigned int);
20034 @exdent vector signed int vec_srdb (vector signed int, vector signed int,
20035 const unsigned int);
20036 @exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int,
20037 const unsigned int);
20038 @exdent vector signed long long vec_srdb (vector signed long long,
20039 vector signed long long, const unsigned int);
20040 @exdent vector unsigned long long vec_srdb (vector unsigned long long,
20041 vector unsigned long long, const unsigned int);
20044 Shift the combined input vectors right by the amount specified by the low-order
20045 three bits of the third argument, and return the remaining 128 bits. Code
20046 using this built-in must be endian-aware.
20053 @exdent vector signed int vec_splati (const signed int);
20054 @exdent vector float vec_splati (const float);
20057 Splat a 32-bit immediate into a vector of words.
20062 @exdent vector double vec_splatid (const float);
20065 Convert a single precision floating-point value to double-precision and splat
20066 the result to a vector of double-precision floats.
20068 @findex vec_splatid
20071 @exdent vector signed int vec_splati_ins (vector signed int,
20072 const unsigned int, const signed int);
20073 @exdent vector unsigned int vec_splati_ins (vector unsigned int,
20074 const unsigned int, const unsigned int);
20075 @exdent vector float vec_splati_ins (vector float, const unsigned int,
20079 Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word
20080 identified by argument 2 of each doubleword of argument 1 and return the
20081 result. The other words of argument 1 are unchanged.
20083 @findex vec_splati_ins
20085 Vector Blend Variable
20088 @exdent vector signed char vec_blendv (vector signed char, vector signed char,
20089 vector unsigned char);
20090 @exdent vector unsigned char vec_blendv (vector unsigned char,
20091 vector unsigned char, vector unsigned char);
20092 @exdent vector signed short vec_blendv (vector signed short,
20093 vector signed short, vector unsigned short);
20094 @exdent vector unsigned short vec_blendv (vector unsigned short,
20095 vector unsigned short, vector unsigned short);
20096 @exdent vector signed int vec_blendv (vector signed int, vector signed int,
20097 vector unsigned int);
20098 @exdent vector unsigned int vec_blendv (vector unsigned int,
20099 vector unsigned int, vector unsigned int);
20100 @exdent vector signed long long vec_blendv (vector signed long long,
20101 vector signed long long, vector unsigned long long);
20102 @exdent vector unsigned long long vec_blendv (vector unsigned long long,
20103 vector unsigned long long, vector unsigned long long);
20104 @exdent vector float vec_blendv (vector float, vector float,
20105 vector unsigned int);
20106 @exdent vector double vec_blendv (vector double, vector double,
20107 vector unsigned long long);
20110 Blend the first and second argument vectors according to the sign bits of the
20111 corresponding elements of the third argument vector. This is similar to the
20112 @code{vsel} and @code{xxsel} instructions but for bigger elements.
20116 Vector Permute Extended
20119 @exdent vector signed char vec_permx (vector signed char, vector signed char,
20120 vector unsigned char, const int);
20121 @exdent vector unsigned char vec_permx (vector unsigned char,
20122 vector unsigned char, vector unsigned char, const int);
20123 @exdent vector signed short vec_permx (vector signed short,
20124 vector signed short, vector unsigned char, const int);
20125 @exdent vector unsigned short vec_permx (vector unsigned short,
20126 vector unsigned short, vector unsigned char, const int);
20127 @exdent vector signed int vec_permx (vector signed int, vector signed int,
20128 vector unsigned char, const int);
20129 @exdent vector unsigned int vec_permx (vector unsigned int,
20130 vector unsigned int, vector unsigned char, const int);
20131 @exdent vector signed long long vec_permx (vector signed long long,
20132 vector signed long long, vector unsigned char, const int);
20133 @exdent vector unsigned long long vec_permx (vector unsigned long long,
20134 vector unsigned long long, vector unsigned char, const int);
20135 @exdent vector float (vector float, vector float, vector unsigned char,
20137 @exdent vector double (vector double, vector double, vector unsigned char,
20141 Perform a partial permute of the first two arguments, which form a 32-byte
20142 section of an emulated vector up to 256 bytes wide, using the partial permute
20143 control vector in the third argument. The fourth argument (constrained to
20144 values of 0-7) identifies which 32-byte section of the emulated vector is
20145 contained in the first two arguments.
20149 @exdent vector unsigned long long int
20150 @exdent vec_pext (vector unsigned long long int, vector unsigned long long int);
20152 Perform a vector parallel bit extract operation, as if implemented by
20153 the @code{vpextd} instruction.
20157 @exdent vector unsigned char vec_stril (vector unsigned char);
20158 @exdent vector signed char vec_stril (vector signed char);
20159 @exdent vector unsigned short vec_stril (vector unsigned short);
20160 @exdent vector signed short vec_stril (vector signed short);
20162 Isolate the left-most non-zero elements of the incoming vector argument,
20163 replacing all elements to the right of the left-most zero element
20164 found within the argument with zero. The typical implementation uses
20165 the @code{vstribl} or @code{vstrihl} instruction on big-endian targets
20166 and uses the @code{vstribr} or @code{vstrihr} instruction on
20167 little-endian targets.
20171 @exdent int vec_stril_p (vector unsigned char);
20172 @exdent int vec_stril_p (vector signed char);
20173 @exdent int short vec_stril_p (vector unsigned short);
20174 @exdent int vec_stril_p (vector signed short);
20176 Return a non-zero value if and only if the argument contains a zero
20177 element. The typical implementation uses
20178 the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets
20179 and uses the @code{vstribr.} or @code{vstrihr.} instruction on
20180 little-endian targets. Choose this built-in to check for presence of
20181 zero element if the same argument is also passed to @code{vec_stril}.
20182 @findex vec_stril_p
20185 @exdent vector unsigned char vec_strir (vector unsigned char);
20186 @exdent vector signed char vec_strir (vector signed char);
20187 @exdent vector unsigned short vec_strir (vector unsigned short);
20188 @exdent vector signed short vec_strir (vector signed short);
20190 Isolate the right-most non-zero elements of the incoming vector argument,
20191 replacing all elements to the left of the right-most zero element
20192 found within the argument with zero. The typical implementation uses
20193 the @code{vstribr} or @code{vstrihr} instruction on big-endian targets
20194 and uses the @code{vstribl} or @code{vstrihl} instruction on
20195 little-endian targets.
20199 @exdent int vec_strir_p (vector unsigned char);
20200 @exdent int vec_strir_p (vector signed char);
20201 @exdent int short vec_strir_p (vector unsigned short);
20202 @exdent int vec_strir_p (vector signed short);
20204 Return a non-zero value if and only if the argument contains a zero
20205 element. The typical implementation uses
20206 the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets
20207 and uses the @code{vstribl.} or @code{vstrihl.} instruction on
20208 little-endian targets. Choose this built-in to check for presence of
20209 zero element if the same argument is also passed to @code{vec_strir}.
20210 @findex vec_strir_p
20213 @exdent vector unsigned char
20214 @exdent vec_ternarylogic (vector unsigned char, vector unsigned char,
20215 vector unsigned char, const unsigned int);
20216 @exdent vector unsigned short
20217 @exdent vec_ternarylogic (vector unsigned short, vector unsigned short,
20218 vector unsigned short, const unsigned int);
20219 @exdent vector unsigned int
20220 @exdent vec_ternarylogic (vector unsigned int, vector unsigned int,
20221 vector unsigned int, const unsigned int);
20222 @exdent vector unsigned long long int
20223 @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int,
20224 vector unsigned long long int, const unsigned int);
20225 @exdent vector unsigned __int128
20226 @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128,
20227 vector unsigned __int128, const unsigned int);
20229 Perform a 128-bit vector evaluate operation, as if implemented by the
20230 @code{xxeval} instruction. The fourth argument must be a literal
20231 integer value between 0 and 255 inclusive.
20232 @findex vec_ternarylogic
20235 @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int);
20236 @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int);
20237 @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int);
20238 @exdent vector unsigned int vec_genpcvm (vector unsigned long long int,
20242 Vector Integer Multiply/Divide/Modulo
20245 @exdent vector signed int
20246 @exdent vec_mulh (vector signed int a, vector signed int b);
20247 @exdent vector unsigned int
20248 @exdent vec_mulh (vector unsigned int a, vector unsigned int b);
20251 For each integer value @code{i} from 0 to 3, do the following. The integer
20252 value in word element @code{i} of a is multiplied by the integer value in word
20253 element @code{i} of b. The high-order 32 bits of the 64-bit product are placed
20254 into word element @code{i} of the vector returned.
20257 @exdent vector signed long long
20258 @exdent vec_mulh (vector signed long long a, vector signed long long b);
20259 @exdent vector unsigned long long
20260 @exdent vec_mulh (vector unsigned long long a, vector unsigned long long b);
20263 For each integer value @code{i} from 0 to 1, do the following. The integer
20264 value in doubleword element @code{i} of a is multiplied by the integer value in
20265 doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product
20266 are placed into doubleword element @code{i} of the vector returned.
20269 @exdent vector unsigned long long
20270 @exdent vec_mul (vector unsigned long long a, vector unsigned long long b);
20271 @exdent vector signed long long
20272 @exdent vec_mul (vector signed long long a, vector signed long long b);
20275 For each integer value @code{i} from 0 to 1, do the following. The integer
20276 value in doubleword element @code{i} of a is multiplied by the integer value in
20277 doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product
20278 are placed into doubleword element @code{i} of the vector returned.
20281 @exdent vector signed int
20282 @exdent vec_div (vector signed int a, vector signed int b);
20283 @exdent vector unsigned int
20284 @exdent vec_div (vector unsigned int a, vector unsigned int b);
20287 For each integer value @code{i} from 0 to 3, do the following. The integer in
20288 word element @code{i} of a is divided by the integer in word element @code{i}
20289 of b. The unique integer quotient is placed into the word element @code{i} of
20290 the vector returned. If an attempt is made to perform any of the divisions
20291 <anything> ÷ 0 then the quotient is undefined.
20294 @exdent vector signed long long
20295 @exdent vec_div (vector signed long long a, vector signed long long b);
20296 @exdent vector unsigned long long
20297 @exdent vec_div (vector unsigned long long a, vector unsigned long long b);
20300 For each integer value @code{i} from 0 to 1, do the following. The integer in
20301 doubleword element @code{i} of a is divided by the integer in doubleword
20302 element @code{i} of b. The unique integer quotient is placed into the
20303 doubleword element @code{i} of the vector returned. If an attempt is made to
20304 perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then
20305 the quotient is undefined.
20308 @exdent vector signed int
20309 @exdent vec_dive (vector signed int a, vector signed int b);
20310 @exdent vector unsigned int
20311 @exdent vec_dive (vector unsigned int a, vector unsigned int b);
20314 For each integer value @code{i} from 0 to 3, do the following. The integer in
20315 word element @code{i} of a is shifted left by 32 bits, then divided by the
20316 integer in word element @code{i} of b. The unique integer quotient is placed
20317 into the word element @code{i} of the vector returned. If the quotient cannot
20318 be represented in 32 bits, or if an attempt is made to perform any of the
20319 divisions <anything> ÷ 0 then the quotient is undefined.
20322 @exdent vector signed long long
20323 @exdent vec_dive (vector signed long long a, vector signed long long b);
20324 @exdent vector unsigned long long
20325 @exdent vec_dive (vector unsigned long long a, vector unsigned long long b);
20328 For each integer value @code{i} from 0 to 1, do the following. The integer in
20329 doubleword element @code{i} of a is shifted left by 64 bits, then divided by
20330 the integer in doubleword element @code{i} of b. The unique integer quotient is
20331 placed into the doubleword element @code{i} of the vector returned. If the
20332 quotient cannot be represented in 64 bits, or if an attempt is made to perform
20333 <anything> ÷ 0 then the quotient is undefined.
20336 @exdent vector signed int
20337 @exdent vec_mod (vector signed int a, vector signed int b);
20338 @exdent vector unsigned int
20339 @exdent vec_mod (vector unsigned int a, vector unsigned int b);
20342 For each integer value @code{i} from 0 to 3, do the following. The integer in
20343 word element @code{i} of a is divided by the integer in word element @code{i}
20344 of b. The unique integer remainder is placed into the word element @code{i} of
20345 the vector returned. If an attempt is made to perform any of the divisions
20346 0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined.
20349 @exdent vector signed long long
20350 @exdent vec_mod (vector signed long long a, vector signed long long b);
20351 @exdent vector unsigned long long
20352 @exdent vec_mod (vector unsigned long long a, vector unsigned long long b);
20355 For each integer value @code{i} from 0 to 1, do the following. The integer in
20356 doubleword element @code{i} of a is divided by the integer in doubleword
20357 element @code{i} of b. The unique integer remainder is placed into the
20358 doubleword element @code{i} of the vector returned. If an attempt is made to
20359 perform <anything> ÷ 0 then the remainder is undefined.
20361 Generate PCV from specified Mask size, as if implemented by the
20362 @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where
20363 immediate value is either 0, 1, 2 or 3.
20364 @findex vec_genpcvm
20367 @exdent vector unsigned __int128 vec_rl (vector unsigned __int128 A,
20368 vector unsigned __int128 B);
20369 @exdent vector signed __int128 vec_rl (vector signed __int128 A,
20370 vector unsigned __int128 B);
20373 Result value: Each element of R is obtained by rotating the corresponding element
20374 of A left by the number of bits specified by the corresponding element of B.
20378 @exdent vector unsigned __int128 vec_rlmi (vector unsigned __int128,
20379 vector unsigned __int128,
20380 vector unsigned __int128);
20381 @exdent vector signed __int128 vec_rlmi (vector signed __int128,
20382 vector signed __int128,
20383 vector unsigned __int128);
20386 Returns the result of rotating the first input and inserting it under mask
20387 into the second input. The first bit in the mask, the last bit in the mask are
20388 obtained from the two 7-bit fields bits [108:115] and bits [117:123]
20389 respectively of the second input. The shift is obtained from the third input
20390 in the 7-bit field [125:131] where all bits counted from zero at the left.
20393 @exdent vector unsigned __int128 vec_rlnm (vector unsigned __int128,
20394 vector unsigned __int128,
20395 vector unsigned __int128);
20396 @exdent vector signed __int128 vec_rlnm (vector signed __int128,
20397 vector unsigned __int128,
20398 vector unsigned __int128);
20401 Returns the result of rotating the first input and ANDing it with a mask. The
20402 first bit in the mask and the last bit in the mask are obtained from the two
20403 7-bit fields bits [117:123] and bits [125:131] respectively of the second
20404 input. The shift is obtained from the third input in the 7-bit field bits
20405 [125:131] where all bits counted from zero at the left.
20408 @exdent vector unsigned __int128 vec_sl(vector unsigned __int128 A, vector unsigned __int128 B);
20409 @exdent vector signed __int128 vec_sl(vector signed __int128 A, vector unsigned __int128 B);
20412 Result value: Each element of R is obtained by shifting the corresponding element of
20413 A left by the number of bits specified by the corresponding element of B.
20416 @exdent vector unsigned __int128 vec_sr(vector unsigned __int128 A, vector unsigned __int128 B);
20417 @exdent vector signed __int128 vec_sr(vector signed __int128 A, vector unsigned __int128 B);
20420 Result value: Each element of R is obtained by shifting the corresponding element of
20421 A right by the number of bits specified by the corresponding element of B.
20424 @exdent vector unsigned __int128 vec_sra(vector unsigned __int128 A, vector unsigned __int128 B);
20425 @exdent vector signed __int128 vec_sra(vector signed __int128 A, vector unsigned __int128 B);
20428 Result value: Each element of R is obtained by arithmetic shifting the corresponding
20429 element of A right by the number of bits specified by the corresponding element of B.
20432 @exdent vector unsigned __int128 vec_mule (vector unsigned long long,
20433 vector unsigned long long);
20434 @exdent vector signed __int128 vec_mule (vector signed long long,
20435 vector signed long long);
20438 Returns a vector containing a 128-bit integer result of multiplying the even
20439 doubleword elements of the two inputs.
20442 @exdent vector unsigned __int128 vec_mulo (vector unsigned long long,
20443 vector unsigned long long);
20444 @exdent vector signed __int128 vec_mulo (vector signed long long,
20445 vector signed long long);
20448 Returns a vector containing a 128-bit integer result of multiplying the odd
20449 doubleword elements of the two inputs.
20452 @exdent vector unsigned __int128 vec_div (vector unsigned __int128,
20453 vector unsigned __int128);
20454 @exdent vector signed __int128 vec_div (vector signed __int128,
20455 vector signed __int128);
20458 Returns the result of dividing the first operand by the second operand. An
20459 attempt to divide any value by zero or to divide the most negative signed
20460 128-bit integer by negative one results in an undefined value.
20463 @exdent vector unsigned __int128 vec_dive (vector unsigned __int128,
20464 vector unsigned __int128);
20465 @exdent vector signed __int128 vec_dive (vector signed __int128,
20466 vector signed __int128);
20469 The result is produced by shifting the first input left by 128 bits and
20470 dividing by the second. If an attempt is made to divide by zero or the result
20471 is larger than 128 bits, the result is undefined.
20474 @exdent vector unsigned __int128 vec_mod (vector unsigned __int128,
20475 vector unsigned __int128);
20476 @exdent vector signed __int128 vec_mod (vector signed __int128,
20477 vector signed __int128);
20480 The result is the modulo result of dividing the first input by the second
20483 The following builtins perform 128-bit vector comparisons. The
20484 @code{vec_all_xx}, @code{vec_any_xx}, and @code{vec_cmpxx}, where @code{xx} is
20485 one of the operations @code{eq, ne, gt, lt, ge, le} perform pairwise
20486 comparisons between the elements at the same positions within their two vector
20487 arguments. The @code{vec_all_xx}function returns a non-zero value if and only
20488 if all pairwise comparisons are true. The @code{vec_any_xx} function returns
20489 a non-zero value if and only if at least one pairwise comparison is true. The
20490 @code{vec_cmpxx}function returns a vector of the same type as its two
20491 arguments, within which each element consists of all ones to denote that
20492 specified logical comparison of the corresponding elements was true.
20493 Otherwise, the element of the returned vector contains all zeros.
20496 vector bool __int128 vec_cmpeq (vector signed __int128, vector signed __int128);
20497 vector bool __int128 vec_cmpeq (vector unsigned __int128, vector unsigned __int128);
20498 vector bool __int128 vec_cmpne (vector signed __int128, vector signed __int128);
20499 vector bool __int128 vec_cmpne (vector unsigned __int128, vector unsigned __int128);
20500 vector bool __int128 vec_cmpgt (vector signed __int128, vector signed __int128);
20501 vector bool __int128 vec_cmpgt (vector unsigned __int128, vector unsigned __int128);
20502 vector bool __int128 vec_cmplt (vector signed __int128, vector signed __int128);
20503 vector bool __int128 vec_cmplt (vector unsigned __int128, vector unsigned __int128);
20504 vector bool __int128 vec_cmpge (vector signed __int128, vector signed __int128);
20505 vector bool __int128 vec_cmpge (vector unsigned __int128, vector unsigned __int128);
20506 vector bool __int128 vec_cmple (vector signed __int128, vector signed __int128);
20507 vector bool __int128 vec_cmple (vector unsigned __int128, vector unsigned __int128);
20509 int vec_all_eq (vector signed __int128, vector signed __int128);
20510 int vec_all_eq (vector unsigned __int128, vector unsigned __int128);
20511 int vec_all_ne (vector signed __int128, vector signed __int128);
20512 int vec_all_ne (vector unsigned __int128, vector unsigned __int128);
20513 int vec_all_gt (vector signed __int128, vector signed __int128);
20514 int vec_all_gt (vector unsigned __int128, vector unsigned __int128);
20515 int vec_all_lt (vector signed __int128, vector signed __int128);
20516 int vec_all_lt (vector unsigned __int128, vector unsigned __int128);
20517 int vec_all_ge (vector signed __int128, vector signed __int128);
20518 int vec_all_ge (vector unsigned __int128, vector unsigned __int128);
20519 int vec_all_le (vector signed __int128, vector signed __int128);
20520 int vec_all_le (vector unsigned __int128, vector unsigned __int128);
20522 int vec_any_eq (vector signed __int128, vector signed __int128);
20523 int vec_any_eq (vector unsigned __int128, vector unsigned __int128);
20524 int vec_any_ne (vector signed __int128, vector signed __int128);
20525 int vec_any_ne (vector unsigned __int128, vector unsigned __int128);
20526 int vec_any_gt (vector signed __int128, vector signed __int128);
20527 int vec_any_gt (vector unsigned __int128, vector unsigned __int128);
20528 int vec_any_lt (vector signed __int128, vector signed __int128);
20529 int vec_any_lt (vector unsigned __int128, vector unsigned __int128);
20530 int vec_any_ge (vector signed __int128, vector signed __int128);
20531 int vec_any_ge (vector unsigned __int128, vector unsigned __int128);
20532 int vec_any_le (vector signed __int128, vector signed __int128);
20533 int vec_any_le (vector unsigned __int128, vector unsigned __int128);
20537 @node PowerPC Hardware Transactional Memory Built-in Functions
20538 @subsection PowerPC Hardware Transactional Memory Built-in Functions
20539 GCC provides two interfaces for accessing the Hardware Transactional
20540 Memory (HTM) instructions available on some of the PowerPC family
20541 of processors (eg, POWER8). The two interfaces come in a low level
20542 interface, consisting of built-in functions specific to PowerPC and a
20543 higher level interface consisting of inline functions that are common
20544 between PowerPC and S/390.
20546 @subsubsection PowerPC HTM Low Level Built-in Functions
20548 The following low level built-in functions are available with
20549 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
20550 They all generate the machine instruction that is part of the name.
20552 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
20553 the full 4-bit condition register value set by their associated hardware
20554 instruction. The header file @code{htmintrin.h} defines some macros that can
20555 be used to decipher the return value. The @code{__builtin_tbegin} builtin
20556 returns a simple @code{true} or @code{false} value depending on whether a transaction was
20557 successfully started or not. The arguments of the builtins match exactly the
20558 type and order of the associated hardware instruction's operands, except for
20559 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
20560 Refer to the ISA manual for a description of each instruction's operands.
20563 unsigned int __builtin_tbegin (unsigned int);
20564 unsigned int __builtin_tend (unsigned int);
20566 unsigned int __builtin_tabort (unsigned int);
20567 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int);
20568 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int);
20569 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int);
20570 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int);
20572 unsigned int __builtin_tcheck (void);
20573 unsigned int __builtin_treclaim (unsigned int);
20574 unsigned int __builtin_trechkpt (void);
20575 unsigned int __builtin_tsr (unsigned int);
20578 In addition to the above HTM built-ins, we have added built-ins for
20579 some common extended mnemonics of the HTM instructions:
20582 unsigned int __builtin_tendall (void);
20583 unsigned int __builtin_tresume (void);
20584 unsigned int __builtin_tsuspend (void);
20587 Note that the semantics of the above HTM builtins are required to mimic
20588 the locking semantics used for critical sections. Builtins that are used
20589 to create a new transaction or restart a suspended transaction must have
20590 lock acquisition like semantics while those builtins that end or suspend a
20591 transaction must have lock release like semantics. Specifically, this must
20592 mimic lock semantics as specified by C++11, for example: Lock acquisition is
20593 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
20594 that returns 0, and lock release is as-if an execution of
20595 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
20596 implicit implementation-defined lock used for all transactions. The HTM
20597 instructions associated with with the builtins inherently provide the
20598 correct acquisition and release hardware barriers required. However,
20599 the compiler must also be prohibited from moving loads and stores across
20600 the builtins in a way that would violate their semantics. This has been
20601 accomplished by adding memory barriers to the associated HTM instructions
20602 (which is a conservative approach to provide acquire and release semantics).
20603 Earlier versions of the compiler did not treat the HTM instructions as
20604 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
20605 be used to determine whether the current compiler treats HTM instructions
20606 as memory barriers or not. This allows the user to explicitly add memory
20607 barriers to their code when using an older version of the compiler.
20609 The following set of built-in functions are available to gain access
20610 to the HTM specific special purpose registers.
20613 unsigned long __builtin_get_texasr (void);
20614 unsigned long __builtin_get_texasru (void);
20615 unsigned long __builtin_get_tfhar (void);
20616 unsigned long __builtin_get_tfiar (void);
20618 void __builtin_set_texasr (unsigned long);
20619 void __builtin_set_texasru (unsigned long);
20620 void __builtin_set_tfhar (unsigned long);
20621 void __builtin_set_tfiar (unsigned long);
20624 Example usage of these low level built-in functions may look like:
20627 #include <htmintrin.h>
20629 int num_retries = 10;
20633 if (__builtin_tbegin (0))
20635 /* Transaction State Initiated. */
20636 if (is_locked (lock))
20637 __builtin_tabort (0);
20638 ... transaction code...
20639 __builtin_tend (0);
20644 /* Transaction State Failed. Use locks if the transaction
20645 failure is "persistent" or we've tried too many times. */
20646 if (num_retries-- <= 0
20647 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
20649 acquire_lock (lock);
20650 ... non transactional fallback path...
20651 release_lock (lock);
20658 One final built-in function has been added that returns the value of
20659 the 2-bit Transaction State field of the Machine Status Register (MSR)
20660 as stored in @code{CR0}.
20663 unsigned long __builtin_ttest (void)
20666 This built-in can be used to determine the current transaction state
20667 using the following code example:
20670 #include <htmintrin.h>
20672 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
20674 if (tx_state == _HTM_TRANSACTIONAL)
20676 /* Code to use in transactional state. */
20678 else if (tx_state == _HTM_NONTRANSACTIONAL)
20680 /* Code to use in non-transactional state. */
20682 else if (tx_state == _HTM_SUSPENDED)
20684 /* Code to use in transaction suspended state. */
20688 @subsubsection PowerPC HTM High Level Inline Functions
20690 The following high level HTM interface is made available by including
20691 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
20692 where CPU is `power8' or later. This interface is common between PowerPC
20693 and S/390, allowing users to write one HTM source implementation that
20694 can be compiled and executed on either system.
20697 long __TM_simple_begin (void);
20698 long __TM_begin (void* const TM_buff);
20699 long __TM_end (void);
20700 void __TM_abort (void);
20701 void __TM_named_abort (unsigned char const code);
20702 void __TM_resume (void);
20703 void __TM_suspend (void);
20705 long __TM_is_user_abort (void* const TM_buff);
20706 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code);
20707 long __TM_is_illegal (void* const TM_buff);
20708 long __TM_is_footprint_exceeded (void* const TM_buff);
20709 long __TM_nesting_depth (void* const TM_buff);
20710 long __TM_is_nested_too_deep(void* const TM_buff);
20711 long __TM_is_conflict(void* const TM_buff);
20712 long __TM_is_failure_persistent(void* const TM_buff);
20713 long __TM_failure_address(void* const TM_buff);
20714 long long __TM_failure_code(void* const TM_buff);
20717 Using these common set of HTM inline functions, we can create
20718 a more portable version of the HTM example in the previous
20719 section that will work on either PowerPC or S/390:
20722 #include <htmxlintrin.h>
20724 int num_retries = 10;
20725 TM_buff_type TM_buff;
20729 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
20731 /* Transaction State Initiated. */
20732 if (is_locked (lock))
20734 ... transaction code...
20740 /* Transaction State Failed. Use locks if the transaction
20741 failure is "persistent" or we've tried too many times. */
20742 if (num_retries-- <= 0
20743 || __TM_is_failure_persistent (TM_buff))
20745 acquire_lock (lock);
20746 ... non transactional fallback path...
20747 release_lock (lock);
20754 @node PowerPC Atomic Memory Operation Functions
20755 @subsection PowerPC Atomic Memory Operation Functions
20756 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
20757 instructions. GCC provides support for these instructions in 64-bit
20758 environments. All of the functions are declared in the include file
20761 The functions supported are:
20766 uint32_t amo_lwat_add (uint32_t *, uint32_t);
20767 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
20768 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
20769 uint32_t amo_lwat_and (uint32_t *, uint32_t);
20770 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
20771 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
20772 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
20774 int32_t amo_lwat_sadd (int32_t *, int32_t);
20775 int32_t amo_lwat_smax (int32_t *, int32_t);
20776 int32_t amo_lwat_smin (int32_t *, int32_t);
20777 int32_t amo_lwat_sswap (int32_t *, int32_t);
20779 uint64_t amo_ldat_add (uint64_t *, uint64_t);
20780 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
20781 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
20782 uint64_t amo_ldat_and (uint64_t *, uint64_t);
20783 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
20784 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
20785 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
20787 int64_t amo_ldat_sadd (int64_t *, int64_t);
20788 int64_t amo_ldat_smax (int64_t *, int64_t);
20789 int64_t amo_ldat_smin (int64_t *, int64_t);
20790 int64_t amo_ldat_sswap (int64_t *, int64_t);
20792 void amo_stwat_add (uint32_t *, uint32_t);
20793 void amo_stwat_xor (uint32_t *, uint32_t);
20794 void amo_stwat_ior (uint32_t *, uint32_t);
20795 void amo_stwat_and (uint32_t *, uint32_t);
20796 void amo_stwat_umax (uint32_t *, uint32_t);
20797 void amo_stwat_umin (uint32_t *, uint32_t);
20799 void amo_stwat_sadd (int32_t *, int32_t);
20800 void amo_stwat_smax (int32_t *, int32_t);
20801 void amo_stwat_smin (int32_t *, int32_t);
20803 void amo_stdat_add (uint64_t *, uint64_t);
20804 void amo_stdat_xor (uint64_t *, uint64_t);
20805 void amo_stdat_ior (uint64_t *, uint64_t);
20806 void amo_stdat_and (uint64_t *, uint64_t);
20807 void amo_stdat_umax (uint64_t *, uint64_t);
20808 void amo_stdat_umin (uint64_t *, uint64_t);
20810 void amo_stdat_sadd (int64_t *, int64_t);
20811 void amo_stdat_smax (int64_t *, int64_t);
20812 void amo_stdat_smin (int64_t *, int64_t);
20815 @node PowerPC Matrix-Multiply Assist Built-in Functions
20816 @subsection PowerPC Matrix-Multiply Assist Built-in Functions
20817 ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions.
20818 GCC provides support for these instructions through the following built-in
20819 functions which are enabled with the @code{-mmma} option. The vec_t type
20820 below is defined to be a normal vector unsigned char type. The uint2, uint4
20821 and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants
20822 respectively. The compiler will verify that they are constants and that
20823 their values are within range.
20825 The built-in functions supported are:
20828 void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t);
20829 void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t);
20830 void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t);
20831 void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t);
20832 void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t);
20833 void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t);
20834 void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t);
20836 void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t);
20837 void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t);
20838 void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t);
20839 void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t);
20840 void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t);
20841 void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t);
20842 void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t);
20843 void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t);
20844 void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t);
20845 void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t);
20846 void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t);
20847 void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t);
20848 void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t);
20849 void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t);
20850 void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t);
20851 void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t);
20852 void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t);
20854 void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
20855 void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
20857 void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20858 void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20859 void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
20861 void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20862 void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20863 void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20864 void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20866 void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20867 void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20868 void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20869 void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20870 void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20871 void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20872 void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20873 void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20874 void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20875 void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
20877 void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4);
20878 void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4);
20879 void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4);
20880 void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4);
20881 void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4);
20883 void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t);
20884 void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t);
20885 void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t);
20886 void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t);
20887 void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t);
20889 void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20890 void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20891 void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20892 void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20893 void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
20895 void __builtin_mma_xxmtacc (__vector_quad *);
20896 void __builtin_mma_xxmfacc (__vector_quad *);
20897 void __builtin_mma_xxsetaccz (__vector_quad *);
20899 void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t);
20900 void __builtin_mma_disassemble_acc (void *, __vector_quad *);
20902 void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t);
20903 void __builtin_vsx_disassemble_pair (void *, __vector_pair *);
20905 vec_t __builtin_vsx_xvcvspbf16 (vec_t);
20906 vec_t __builtin_vsx_xvcvbf16spn (vec_t);
20908 __vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *);
20909 void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *);
20912 @node PRU Built-in Functions
20913 @subsection PRU Built-in Functions
20915 GCC provides a couple of special builtin functions to aid in utilizing
20916 special PRU instructions.
20918 The built-in functions supported are:
20921 @item __delay_cycles (long long @var{cycles})
20922 This inserts an instruction sequence that takes exactly @var{cycles}
20923 cycles (between 0 and 0xffffffff) to complete. The inserted sequence
20924 may use jumps, loops, or no-ops, and does not interfere with any other
20925 instructions. Note that @var{cycles} must be a compile-time constant
20926 integer - that is, you must pass a number, not a variable that may be
20927 optimized to a constant later. The number of cycles delayed by this
20930 @item __halt (void)
20931 This inserts a HALT instruction to stop processor execution.
20933 @item unsigned int __lmbd (unsigned int @var{wordval}, unsigned int @var{bitval})
20934 This inserts LMBD instruction to calculate the left-most bit with value
20935 @var{bitval} in value @var{wordval}. Only the least significant bit
20936 of @var{bitval} is taken into account.
20939 @node RISC-V Built-in Functions
20940 @subsection RISC-V Built-in Functions
20942 These built-in functions are available for the RISC-V family of
20945 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
20946 Returns the value that is currently set in the @samp{tp} register.
20949 @node RX Built-in Functions
20950 @subsection RX Built-in Functions
20951 GCC supports some of the RX instructions which cannot be expressed in
20952 the C programming language via the use of built-in functions. The
20953 following functions are supported:
20955 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
20956 Generates the @code{brk} machine instruction.
20959 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
20960 Generates the @code{clrpsw} machine instruction to clear the specified
20961 bit in the processor status word.
20964 @deftypefn {Built-in Function} void __builtin_rx_int (int)
20965 Generates the @code{int} machine instruction to generate an interrupt
20966 with the specified value.
20969 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
20970 Generates the @code{machi} machine instruction to add the result of
20971 multiplying the top 16 bits of the two arguments into the
20975 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
20976 Generates the @code{maclo} machine instruction to add the result of
20977 multiplying the bottom 16 bits of the two arguments into the
20981 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
20982 Generates the @code{mulhi} machine instruction to place the result of
20983 multiplying the top 16 bits of the two arguments into the
20987 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
20988 Generates the @code{mullo} machine instruction to place the result of
20989 multiplying the bottom 16 bits of the two arguments into the
20993 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
20994 Generates the @code{mvfachi} machine instruction to read the top
20995 32 bits of the accumulator.
20998 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
20999 Generates the @code{mvfacmi} machine instruction to read the middle
21000 32 bits of the accumulator.
21003 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
21004 Generates the @code{mvfc} machine instruction which reads the control
21005 register specified in its argument and returns its value.
21008 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
21009 Generates the @code{mvtachi} machine instruction to set the top
21010 32 bits of the accumulator.
21013 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
21014 Generates the @code{mvtaclo} machine instruction to set the bottom
21015 32 bits of the accumulator.
21018 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
21019 Generates the @code{mvtc} machine instruction which sets control
21020 register number @code{reg} to @code{val}.
21023 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
21024 Generates the @code{mvtipl} machine instruction set the interrupt
21028 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
21029 Generates the @code{racw} machine instruction to round the accumulator
21030 according to the specified mode.
21033 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
21034 Generates the @code{revw} machine instruction which swaps the bytes in
21035 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
21036 and also bits 16--23 occupy bits 24--31 and vice versa.
21039 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
21040 Generates the @code{rmpa} machine instruction which initiates a
21041 repeated multiply and accumulate sequence.
21044 @deftypefn {Built-in Function} void __builtin_rx_round (float)
21045 Generates the @code{round} machine instruction which returns the
21046 floating-point argument rounded according to the current rounding mode
21047 set in the floating-point status word register.
21050 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
21051 Generates the @code{sat} machine instruction which returns the
21052 saturated value of the argument.
21055 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
21056 Generates the @code{setpsw} machine instruction to set the specified
21057 bit in the processor status word.
21060 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
21061 Generates the @code{wait} machine instruction.
21064 @node S/390 System z Built-in Functions
21065 @subsection S/390 System z Built-in Functions
21066 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
21067 Generates the @code{tbegin} machine instruction starting a
21068 non-constrained hardware transaction. If the parameter is non-NULL the
21069 memory area is used to store the transaction diagnostic buffer and
21070 will be passed as first operand to @code{tbegin}. This buffer can be
21071 defined using the @code{struct __htm_tdb} C struct defined in
21072 @code{htmintrin.h} and must reside on a double-word boundary. The
21073 second tbegin operand is set to @code{0xff0c}. This enables
21074 save/restore of all GPRs and disables aborts for FPR and AR
21075 manipulations inside the transaction body. The condition code set by
21076 the tbegin instruction is returned as integer value. The tbegin
21077 instruction by definition overwrites the content of all FPRs. The
21078 compiler will generate code which saves and restores the FPRs. For
21079 soft-float code it is recommended to used the @code{*_nofloat}
21080 variant. In order to prevent a TDB from being written it is required
21081 to pass a constant zero value as parameter. Passing a zero value
21082 through a variable is not sufficient. Although modifications of
21083 access registers inside the transaction will not trigger an
21084 transaction abort it is not supported to actually modify them. Access
21085 registers do not get saved when entering a transaction. They will have
21086 undefined state when reaching the abort code.
21089 Macros for the possible return codes of tbegin are defined in the
21090 @code{htmintrin.h} header file:
21093 @item _HTM_TBEGIN_STARTED
21094 @code{tbegin} has been executed as part of normal processing. The
21095 transaction body is supposed to be executed.
21096 @item _HTM_TBEGIN_INDETERMINATE
21097 The transaction was aborted due to an indeterminate condition which
21098 might be persistent.
21099 @item _HTM_TBEGIN_TRANSIENT
21100 The transaction aborted due to a transient failure. The transaction
21101 should be re-executed in that case.
21102 @item _HTM_TBEGIN_PERSISTENT
21103 The transaction aborted due to a persistent failure. Re-execution
21104 under same circumstances will not be productive.
21107 @defmac _HTM_FIRST_USER_ABORT_CODE
21108 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
21109 specifies the first abort code which can be used for
21110 @code{__builtin_tabort}. Values below this threshold are reserved for
21114 @deftp {Data type} {struct __htm_tdb}
21115 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
21116 the structure of the transaction diagnostic block as specified in the
21117 Principles of Operation manual chapter 5-91.
21120 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
21121 Same as @code{__builtin_tbegin} but without FPR saves and restores.
21122 Using this variant in code making use of FPRs will leave the FPRs in
21123 undefined state when entering the transaction abort handler code.
21126 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
21127 In addition to @code{__builtin_tbegin} a loop for transient failures
21128 is generated. If tbegin returns a condition code of 2 the transaction
21129 will be retried as often as specified in the second argument. The
21130 perform processor assist instruction is used to tell the CPU about the
21131 number of fails so far.
21134 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
21135 Same as @code{__builtin_tbegin_retry} but without FPR saves and
21136 restores. Using this variant in code making use of FPRs will leave
21137 the FPRs in undefined state when entering the transaction abort
21141 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
21142 Generates the @code{tbeginc} machine instruction starting a constrained
21143 hardware transaction. The second operand is set to @code{0xff08}.
21146 @deftypefn {Built-in Function} int __builtin_tend (void)
21147 Generates the @code{tend} machine instruction finishing a transaction
21148 and making the changes visible to other threads. The condition code
21149 generated by tend is returned as integer value.
21152 @deftypefn {Built-in Function} void __builtin_tabort (int)
21153 Generates the @code{tabort} machine instruction with the specified
21154 abort code. Abort codes from 0 through 255 are reserved and will
21155 result in an error message.
21158 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
21159 Generates the @code{ppa rX,rY,1} machine instruction. Where the
21160 integer parameter is loaded into rX and a value of zero is loaded into
21161 rY. The integer parameter specifies the number of times the
21162 transaction repeatedly aborted.
21165 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
21166 Generates the @code{etnd} machine instruction. The current nesting
21167 depth is returned as integer value. For a nesting depth of 0 the code
21168 is not executed as part of an transaction.
21171 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
21173 Generates the @code{ntstg} machine instruction. The second argument
21174 is written to the first arguments location. The store operation will
21175 not be rolled-back in case of an transaction abort.
21178 @node SH Built-in Functions
21179 @subsection SH Built-in Functions
21180 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
21181 families of processors:
21183 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
21184 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
21185 used by system code that manages threads and execution contexts. The compiler
21186 normally does not generate code that modifies the contents of @samp{GBR} and
21187 thus the value is preserved across function calls. Changing the @samp{GBR}
21188 value in user code must be done with caution, since the compiler might use
21189 @samp{GBR} in order to access thread local variables.
21193 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
21194 Returns the value that is currently set in the @samp{GBR} register.
21195 Memory loads and stores that use the thread pointer as a base address are
21196 turned into @samp{GBR} based displacement loads and stores, if possible.
21204 int get_tcb_value (void)
21206 // Generate @samp{mov.l @@(8,gbr),r0} instruction
21207 return ((my_tcb*)__builtin_thread_pointer ())->c;
21213 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
21214 Returns the value that is currently set in the @samp{FPSCR} register.
21217 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
21218 Sets the @samp{FPSCR} register to the specified value @var{val}, while
21219 preserving the current values of the FR, SZ and PR bits.
21222 @node SPARC VIS Built-in Functions
21223 @subsection SPARC VIS Built-in Functions
21225 GCC supports SIMD operations on the SPARC using both the generic vector
21226 extensions (@pxref{Vector Extensions}) as well as built-in functions for
21227 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
21228 switch, the VIS extension is exposed as the following built-in functions:
21231 typedef int v1si __attribute__ ((vector_size (4)));
21232 typedef int v2si __attribute__ ((vector_size (8)));
21233 typedef short v4hi __attribute__ ((vector_size (8)));
21234 typedef short v2hi __attribute__ ((vector_size (4)));
21235 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
21236 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
21238 void __builtin_vis_write_gsr (int64_t);
21239 int64_t __builtin_vis_read_gsr (void);
21241 void * __builtin_vis_alignaddr (void *, long);
21242 void * __builtin_vis_alignaddrl (void *, long);
21243 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
21244 v2si __builtin_vis_faligndatav2si (v2si, v2si);
21245 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
21246 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
21248 v4hi __builtin_vis_fexpand (v4qi);
21250 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
21251 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
21252 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
21253 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
21254 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
21255 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
21256 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
21258 v4qi __builtin_vis_fpack16 (v4hi);
21259 v8qi __builtin_vis_fpack32 (v2si, v8qi);
21260 v2hi __builtin_vis_fpackfix (v2si);
21261 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
21263 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
21265 long __builtin_vis_edge8 (void *, void *);
21266 long __builtin_vis_edge8l (void *, void *);
21267 long __builtin_vis_edge16 (void *, void *);
21268 long __builtin_vis_edge16l (void *, void *);
21269 long __builtin_vis_edge32 (void *, void *);
21270 long __builtin_vis_edge32l (void *, void *);
21272 long __builtin_vis_fcmple16 (v4hi, v4hi);
21273 long __builtin_vis_fcmple32 (v2si, v2si);
21274 long __builtin_vis_fcmpne16 (v4hi, v4hi);
21275 long __builtin_vis_fcmpne32 (v2si, v2si);
21276 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
21277 long __builtin_vis_fcmpgt32 (v2si, v2si);
21278 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
21279 long __builtin_vis_fcmpeq32 (v2si, v2si);
21281 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
21282 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
21283 v2si __builtin_vis_fpadd32 (v2si, v2si);
21284 v1si __builtin_vis_fpadd32s (v1si, v1si);
21285 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
21286 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
21287 v2si __builtin_vis_fpsub32 (v2si, v2si);
21288 v1si __builtin_vis_fpsub32s (v1si, v1si);
21290 long __builtin_vis_array8 (long, long);
21291 long __builtin_vis_array16 (long, long);
21292 long __builtin_vis_array32 (long, long);
21295 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
21296 functions also become available:
21299 long __builtin_vis_bmask (long, long);
21300 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
21301 v2si __builtin_vis_bshufflev2si (v2si, v2si);
21302 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
21303 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
21305 long __builtin_vis_edge8n (void *, void *);
21306 long __builtin_vis_edge8ln (void *, void *);
21307 long __builtin_vis_edge16n (void *, void *);
21308 long __builtin_vis_edge16ln (void *, void *);
21309 long __builtin_vis_edge32n (void *, void *);
21310 long __builtin_vis_edge32ln (void *, void *);
21313 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
21314 functions also become available:
21317 void __builtin_vis_cmask8 (long);
21318 void __builtin_vis_cmask16 (long);
21319 void __builtin_vis_cmask32 (long);
21321 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
21323 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
21324 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
21325 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
21326 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
21327 v2si __builtin_vis_fsll16 (v2si, v2si);
21328 v2si __builtin_vis_fslas16 (v2si, v2si);
21329 v2si __builtin_vis_fsrl16 (v2si, v2si);
21330 v2si __builtin_vis_fsra16 (v2si, v2si);
21332 long __builtin_vis_pdistn (v8qi, v8qi);
21334 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
21336 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
21337 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
21339 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
21340 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
21341 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
21342 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
21343 v2si __builtin_vis_fpadds32 (v2si, v2si);
21344 v1si __builtin_vis_fpadds32s (v1si, v1si);
21345 v2si __builtin_vis_fpsubs32 (v2si, v2si);
21346 v1si __builtin_vis_fpsubs32s (v1si, v1si);
21348 long __builtin_vis_fucmple8 (v8qi, v8qi);
21349 long __builtin_vis_fucmpne8 (v8qi, v8qi);
21350 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
21351 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
21353 float __builtin_vis_fhadds (float, float);
21354 double __builtin_vis_fhaddd (double, double);
21355 float __builtin_vis_fhsubs (float, float);
21356 double __builtin_vis_fhsubd (double, double);
21357 float __builtin_vis_fnhadds (float, float);
21358 double __builtin_vis_fnhaddd (double, double);
21360 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
21361 int64_t __builtin_vis_xmulx (int64_t, int64_t);
21362 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
21365 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
21366 functions also become available:
21369 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
21370 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
21371 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
21372 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
21374 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
21375 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
21376 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
21377 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
21379 long __builtin_vis_fpcmple8 (v8qi, v8qi);
21380 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
21381 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
21382 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
21383 long __builtin_vis_fpcmpule32 (v2si, v2si);
21384 long __builtin_vis_fpcmpugt32 (v2si, v2si);
21386 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
21387 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
21388 v2si __builtin_vis_fpmax32 (v2si, v2si);
21390 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
21391 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
21392 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
21394 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
21395 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
21396 v2si __builtin_vis_fpmin32 (v2si, v2si);
21398 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
21399 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
21400 v2si __builtin_vis_fpminu32 (v2si, v2si);
21403 When you use the @option{-mvis4b} switch, the VIS version 4.0B
21404 built-in functions also become available:
21407 v8qi __builtin_vis_dictunpack8 (double, int);
21408 v4hi __builtin_vis_dictunpack16 (double, int);
21409 v2si __builtin_vis_dictunpack32 (double, int);
21411 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
21412 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
21413 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
21414 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
21416 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
21417 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
21418 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
21419 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
21421 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
21422 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
21423 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
21424 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
21426 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
21427 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
21428 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
21429 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
21430 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
21431 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
21433 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
21434 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
21435 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
21437 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
21438 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
21439 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
21442 @node TI C6X Built-in Functions
21443 @subsection TI C6X Built-in Functions
21445 GCC provides intrinsics to access certain instructions of the TI C6X
21446 processors. These intrinsics, listed below, are available after
21447 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
21448 to C6X instructions.
21451 int _sadd (int, int);
21452 int _ssub (int, int);
21453 int _sadd2 (int, int);
21454 int _ssub2 (int, int);
21455 long long _mpy2 (int, int);
21456 long long _smpy2 (int, int);
21457 int _add4 (int, int);
21458 int _sub4 (int, int);
21459 int _saddu4 (int, int);
21461 int _smpy (int, int);
21462 int _smpyh (int, int);
21463 int _smpyhl (int, int);
21464 int _smpylh (int, int);
21466 int _sshl (int, int);
21467 int _subc (int, int);
21469 int _avg2 (int, int);
21470 int _avgu4 (int, int);
21472 int _clrr (int, int);
21473 int _extr (int, int);
21474 int _extru (int, int);
21479 @node TILE-Gx Built-in Functions
21480 @subsection TILE-Gx Built-in Functions
21482 GCC provides intrinsics to access every instruction of the TILE-Gx
21483 processor. The intrinsics are of the form:
21487 unsigned long long __insn_@var{op} (...)
21491 Where @var{op} is the name of the instruction. Refer to the ISA manual
21492 for the complete list of instructions.
21494 GCC also provides intrinsics to directly access the network registers.
21495 The intrinsics are:
21498 unsigned long long __tile_idn0_receive (void);
21499 unsigned long long __tile_idn1_receive (void);
21500 unsigned long long __tile_udn0_receive (void);
21501 unsigned long long __tile_udn1_receive (void);
21502 unsigned long long __tile_udn2_receive (void);
21503 unsigned long long __tile_udn3_receive (void);
21504 void __tile_idn_send (unsigned long long);
21505 void __tile_udn_send (unsigned long long);
21508 The intrinsic @code{void __tile_network_barrier (void)} is used to
21509 guarantee that no network operations before it are reordered with
21512 @node TILEPro Built-in Functions
21513 @subsection TILEPro Built-in Functions
21515 GCC provides intrinsics to access every instruction of the TILEPro
21516 processor. The intrinsics are of the form:
21520 unsigned __insn_@var{op} (...)
21525 where @var{op} is the name of the instruction. Refer to the ISA manual
21526 for the complete list of instructions.
21528 GCC also provides intrinsics to directly access the network registers.
21529 The intrinsics are:
21532 unsigned __tile_idn0_receive (void);
21533 unsigned __tile_idn1_receive (void);
21534 unsigned __tile_sn_receive (void);
21535 unsigned __tile_udn0_receive (void);
21536 unsigned __tile_udn1_receive (void);
21537 unsigned __tile_udn2_receive (void);
21538 unsigned __tile_udn3_receive (void);
21539 void __tile_idn_send (unsigned);
21540 void __tile_sn_send (unsigned);
21541 void __tile_udn_send (unsigned);
21544 The intrinsic @code{void __tile_network_barrier (void)} is used to
21545 guarantee that no network operations before it are reordered with
21548 @node x86 Built-in Functions
21549 @subsection x86 Built-in Functions
21551 These built-in functions are available for the x86-32 and x86-64 family
21552 of computers, depending on the command-line switches used.
21554 If you specify command-line switches such as @option{-msse},
21555 the compiler could use the extended instruction sets even if the built-ins
21556 are not used explicitly in the program. For this reason, applications
21557 that perform run-time CPU detection must compile separate files for each
21558 supported architecture, using the appropriate flags. In particular,
21559 the file containing the CPU detection code should be compiled without
21562 The following machine modes are available for use with MMX built-in functions
21563 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
21564 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
21565 vector of eight 8-bit integers. Some of the built-in functions operate on
21566 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
21568 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
21569 of two 32-bit floating-point values.
21571 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
21572 floating-point values. Some instructions use a vector of four 32-bit
21573 integers, these use @code{V4SI}. Finally, some instructions operate on an
21574 entire vector register, interpreting it as a 128-bit integer, these use mode
21577 The x86-32 and x86-64 family of processors use additional built-in
21578 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
21579 floating point and @code{TC} 128-bit complex floating-point values.
21581 The following floating-point built-in functions are always available. All
21582 of them implement the function that is part of the name.
21585 __float128 __builtin_fabsq (__float128)
21586 __float128 __builtin_copysignq (__float128, __float128)
21589 The following built-in functions are always available.
21592 @item __float128 __builtin_infq (void)
21593 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
21594 @findex __builtin_infq
21596 @item __float128 __builtin_huge_valq (void)
21597 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
21598 @findex __builtin_huge_valq
21600 @item __float128 __builtin_nanq (void)
21601 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
21602 @findex __builtin_nanq
21604 @item __float128 __builtin_nansq (void)
21605 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
21606 @findex __builtin_nansq
21609 The following built-in function is always available.
21612 @item void __builtin_ia32_pause (void)
21613 Generates the @code{pause} machine instruction with a compiler memory
21617 The following built-in functions are always available and can be used to
21618 check the target platform type.
21620 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
21621 This function runs the CPU detection code to check the type of CPU and the
21622 features supported. This built-in function needs to be invoked along with the built-in functions
21623 to check CPU type and features, @code{__builtin_cpu_is} and
21624 @code{__builtin_cpu_supports}, only when used in a function that is
21625 executed before any constructors are called. The CPU detection code is
21626 automatically executed in a very high priority constructor.
21628 For example, this function has to be used in @code{ifunc} resolvers that
21629 check for CPU type using the built-in functions @code{__builtin_cpu_is}
21630 and @code{__builtin_cpu_supports}, or in constructors on targets that
21631 don't support constructor priority.
21634 static void (*resolve_memcpy (void)) (void)
21636 // ifunc resolvers fire before constructors, explicitly call the init
21638 __builtin_cpu_init ();
21639 if (__builtin_cpu_supports ("ssse3"))
21640 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
21642 return default_memcpy;
21645 void *memcpy (void *, const void *, size_t)
21646 __attribute__ ((ifunc ("resolve_memcpy")));
21651 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
21652 This function returns a positive integer if the run-time CPU
21653 is of type @var{cpuname}
21654 and returns @code{0} otherwise. The following CPU names can be detected:
21667 Intel Silvermont CPU.
21676 Intel Core i7 Nehalem CPU.
21679 Intel Core i7 Westmere CPU.
21682 Intel Core i7 Sandy Bridge CPU.
21685 Intel Core i7 Ivy Bridge CPU.
21688 Intel Core i7 Haswell CPU.
21691 Intel Core i7 Broadwell CPU.
21694 Intel Core i7 Skylake CPU.
21696 @item skylake-avx512
21697 Intel Core i7 Skylake AVX512 CPU.
21700 Intel Core i7 Cannon Lake CPU.
21702 @item icelake-client
21703 Intel Core i7 Ice Lake Client CPU.
21705 @item icelake-server
21706 Intel Core i7 Ice Lake Server CPU.
21709 Intel Core i7 Cascadelake CPU.
21712 Intel Core i7 Tigerlake CPU.
21715 Intel Core i7 Cooperlake CPU.
21717 @item sapphirerapids
21718 Intel Core i7 sapphirerapids CPU.
21721 Intel Core i7 Alderlake CPU.
21724 Intel Core i7 Rocketlake CPU.
21727 Intel Atom Bonnell CPU.
21730 Intel Atom Silvermont CPU.
21733 Intel Atom Goldmont CPU.
21735 @item goldmont-plus
21736 Intel Atom Goldmont Plus CPU.
21739 Intel Atom Tremont CPU.
21742 Intel Knights Landing CPU.
21745 Intel Knights Mill CPU.
21748 AMD Family 10h CPU.
21751 AMD Family 10h Barcelona CPU.
21754 AMD Family 10h Shanghai CPU.
21757 AMD Family 10h Istanbul CPU.
21760 AMD Family 14h CPU.
21763 AMD Family 15h CPU.
21766 AMD Family 15h Bulldozer version 1.
21769 AMD Family 15h Bulldozer version 2.
21772 AMD Family 15h Bulldozer version 3.
21775 AMD Family 15h Bulldozer version 4.
21778 AMD Family 16h CPU.
21781 AMD Family 17h CPU.
21784 AMD Family 17h Zen version 1.
21787 AMD Family 17h Zen version 2.
21790 AMD Family 19h CPU.
21793 AMD Family 19h Zen version 3.
21796 Baseline x86-64 microarchitecture level (as defined in x86-64 psABI).
21799 x86-64-v2 microarchitecture level.
21802 x86-64-v3 microarchitecture level.
21805 x86-64-v4 microarchitecture level.
21808 Here is an example:
21810 if (__builtin_cpu_is ("corei7"))
21812 do_corei7 (); // Core i7 specific implementation.
21816 do_generic (); // Generic implementation.
21821 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
21822 This function returns a positive integer if the run-time CPU
21823 supports @var{feature}
21824 and returns @code{0} otherwise. The following features can be detected:
21832 POPCNT instruction.
21840 SSSE3 instructions.
21842 SSE4.1 instructions.
21844 SSE4.2 instructions.
21850 SSE4A instructions.
21858 AVX512F instructions.
21866 PCLMUL instructions.
21868 AVX512VL instructions.
21870 AVX512BW instructions.
21872 AVX512DQ instructions.
21874 AVX512CD instructions.
21876 AVX512ER instructions.
21878 AVX512PF instructions.
21880 AVX512VBMI instructions.
21882 AVX512IFMA instructions.
21884 AVX5124VNNIW instructions.
21886 AVX5124FMAPS instructions.
21887 @item avx512vpopcntdq
21888 AVX512VPOPCNTDQ instructions.
21890 AVX512VBMI2 instructions.
21894 VPCLMULQDQ instructions.
21896 AVX512VNNI instructions.
21898 AVX512BITALG instructions.
21901 Here is an example:
21903 if (__builtin_cpu_supports ("popcnt"))
21905 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
21909 count = generic_countbits (n); //generic implementation.
21914 The following built-in functions are made available by @option{-mmmx}.
21915 All of them generate the machine instruction that is part of the name.
21918 v8qi __builtin_ia32_paddb (v8qi, v8qi);
21919 v4hi __builtin_ia32_paddw (v4hi, v4hi);
21920 v2si __builtin_ia32_paddd (v2si, v2si);
21921 v8qi __builtin_ia32_psubb (v8qi, v8qi);
21922 v4hi __builtin_ia32_psubw (v4hi, v4hi);
21923 v2si __builtin_ia32_psubd (v2si, v2si);
21924 v8qi __builtin_ia32_paddsb (v8qi, v8qi);
21925 v4hi __builtin_ia32_paddsw (v4hi, v4hi);
21926 v8qi __builtin_ia32_psubsb (v8qi, v8qi);
21927 v4hi __builtin_ia32_psubsw (v4hi, v4hi);
21928 v8qi __builtin_ia32_paddusb (v8qi, v8qi);
21929 v4hi __builtin_ia32_paddusw (v4hi, v4hi);
21930 v8qi __builtin_ia32_psubusb (v8qi, v8qi);
21931 v4hi __builtin_ia32_psubusw (v4hi, v4hi);
21932 v4hi __builtin_ia32_pmullw (v4hi, v4hi);
21933 v4hi __builtin_ia32_pmulhw (v4hi, v4hi);
21934 di __builtin_ia32_pand (di, di);
21935 di __builtin_ia32_pandn (di,di);
21936 di __builtin_ia32_por (di, di);
21937 di __builtin_ia32_pxor (di, di);
21938 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi);
21939 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi);
21940 v2si __builtin_ia32_pcmpeqd (v2si, v2si);
21941 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi);
21942 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi);
21943 v2si __builtin_ia32_pcmpgtd (v2si, v2si);
21944 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi);
21945 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi);
21946 v2si __builtin_ia32_punpckhdq (v2si, v2si);
21947 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi);
21948 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi);
21949 v2si __builtin_ia32_punpckldq (v2si, v2si);
21950 v8qi __builtin_ia32_packsswb (v4hi, v4hi);
21951 v4hi __builtin_ia32_packssdw (v2si, v2si);
21952 v8qi __builtin_ia32_packuswb (v4hi, v4hi);
21954 v4hi __builtin_ia32_psllw (v4hi, v4hi);
21955 v2si __builtin_ia32_pslld (v2si, v2si);
21956 v1di __builtin_ia32_psllq (v1di, v1di);
21957 v4hi __builtin_ia32_psrlw (v4hi, v4hi);
21958 v2si __builtin_ia32_psrld (v2si, v2si);
21959 v1di __builtin_ia32_psrlq (v1di, v1di);
21960 v4hi __builtin_ia32_psraw (v4hi, v4hi);
21961 v2si __builtin_ia32_psrad (v2si, v2si);
21962 v4hi __builtin_ia32_psllwi (v4hi, int);
21963 v2si __builtin_ia32_pslldi (v2si, int);
21964 v1di __builtin_ia32_psllqi (v1di, int);
21965 v4hi __builtin_ia32_psrlwi (v4hi, int);
21966 v2si __builtin_ia32_psrldi (v2si, int);
21967 v1di __builtin_ia32_psrlqi (v1di, int);
21968 v4hi __builtin_ia32_psrawi (v4hi, int);
21969 v2si __builtin_ia32_psradi (v2si, int);
21972 The following built-in functions are made available either with
21973 @option{-msse}, or with @option{-m3dnowa}. All of them generate
21974 the machine instruction that is part of the name.
21977 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi);
21978 v8qi __builtin_ia32_pavgb (v8qi, v8qi);
21979 v4hi __builtin_ia32_pavgw (v4hi, v4hi);
21980 v1di __builtin_ia32_psadbw (v8qi, v8qi);
21981 v8qi __builtin_ia32_pmaxub (v8qi, v8qi);
21982 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi);
21983 v8qi __builtin_ia32_pminub (v8qi, v8qi);
21984 v4hi __builtin_ia32_pminsw (v4hi, v4hi);
21985 int __builtin_ia32_pmovmskb (v8qi);
21986 void __builtin_ia32_maskmovq (v8qi, v8qi, char *);
21987 void __builtin_ia32_movntq (di *, di);
21988 void __builtin_ia32_sfence (void);
21991 The following built-in functions are available when @option{-msse} is used.
21992 All of them generate the machine instruction that is part of the name.
21995 int __builtin_ia32_comieq (v4sf, v4sf);
21996 int __builtin_ia32_comineq (v4sf, v4sf);
21997 int __builtin_ia32_comilt (v4sf, v4sf);
21998 int __builtin_ia32_comile (v4sf, v4sf);
21999 int __builtin_ia32_comigt (v4sf, v4sf);
22000 int __builtin_ia32_comige (v4sf, v4sf);
22001 int __builtin_ia32_ucomieq (v4sf, v4sf);
22002 int __builtin_ia32_ucomineq (v4sf, v4sf);
22003 int __builtin_ia32_ucomilt (v4sf, v4sf);
22004 int __builtin_ia32_ucomile (v4sf, v4sf);
22005 int __builtin_ia32_ucomigt (v4sf, v4sf);
22006 int __builtin_ia32_ucomige (v4sf, v4sf);
22007 v4sf __builtin_ia32_addps (v4sf, v4sf);
22008 v4sf __builtin_ia32_subps (v4sf, v4sf);
22009 v4sf __builtin_ia32_mulps (v4sf, v4sf);
22010 v4sf __builtin_ia32_divps (v4sf, v4sf);
22011 v4sf __builtin_ia32_addss (v4sf, v4sf);
22012 v4sf __builtin_ia32_subss (v4sf, v4sf);
22013 v4sf __builtin_ia32_mulss (v4sf, v4sf);
22014 v4sf __builtin_ia32_divss (v4sf, v4sf);
22015 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf);
22016 v4sf __builtin_ia32_cmpltps (v4sf, v4sf);
22017 v4sf __builtin_ia32_cmpleps (v4sf, v4sf);
22018 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf);
22019 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf);
22020 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf);
22021 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf);
22022 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf);
22023 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf);
22024 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf);
22025 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf);
22026 v4sf __builtin_ia32_cmpordps (v4sf, v4sf);
22027 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf);
22028 v4sf __builtin_ia32_cmpltss (v4sf, v4sf);
22029 v4sf __builtin_ia32_cmpless (v4sf, v4sf);
22030 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf);
22031 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf);
22032 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf);
22033 v4sf __builtin_ia32_cmpnless (v4sf, v4sf);
22034 v4sf __builtin_ia32_cmpordss (v4sf, v4sf);
22035 v4sf __builtin_ia32_maxps (v4sf, v4sf);
22036 v4sf __builtin_ia32_maxss (v4sf, v4sf);
22037 v4sf __builtin_ia32_minps (v4sf, v4sf);
22038 v4sf __builtin_ia32_minss (v4sf, v4sf);
22039 v4sf __builtin_ia32_andps (v4sf, v4sf);
22040 v4sf __builtin_ia32_andnps (v4sf, v4sf);
22041 v4sf __builtin_ia32_orps (v4sf, v4sf);
22042 v4sf __builtin_ia32_xorps (v4sf, v4sf);
22043 v4sf __builtin_ia32_movss (v4sf, v4sf);
22044 v4sf __builtin_ia32_movhlps (v4sf, v4sf);
22045 v4sf __builtin_ia32_movlhps (v4sf, v4sf);
22046 v4sf __builtin_ia32_unpckhps (v4sf, v4sf);
22047 v4sf __builtin_ia32_unpcklps (v4sf, v4sf);
22048 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si);
22049 v4sf __builtin_ia32_cvtsi2ss (v4sf, int);
22050 v2si __builtin_ia32_cvtps2pi (v4sf);
22051 int __builtin_ia32_cvtss2si (v4sf);
22052 v2si __builtin_ia32_cvttps2pi (v4sf);
22053 int __builtin_ia32_cvttss2si (v4sf);
22054 v4sf __builtin_ia32_rcpps (v4sf);
22055 v4sf __builtin_ia32_rsqrtps (v4sf);
22056 v4sf __builtin_ia32_sqrtps (v4sf);
22057 v4sf __builtin_ia32_rcpss (v4sf);
22058 v4sf __builtin_ia32_rsqrtss (v4sf);
22059 v4sf __builtin_ia32_sqrtss (v4sf);
22060 v4sf __builtin_ia32_shufps (v4sf, v4sf, int);
22061 void __builtin_ia32_movntps (float *, v4sf);
22062 int __builtin_ia32_movmskps (v4sf);
22065 The following built-in functions are available when @option{-msse} is used.
22068 @item v4sf __builtin_ia32_loadups (float *)
22069 Generates the @code{movups} machine instruction as a load from memory.
22070 @item void __builtin_ia32_storeups (float *, v4sf)
22071 Generates the @code{movups} machine instruction as a store to memory.
22072 @item v4sf __builtin_ia32_loadss (float *)
22073 Generates the @code{movss} machine instruction as a load from memory.
22074 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
22075 Generates the @code{movhps} machine instruction as a load from memory.
22076 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
22077 Generates the @code{movlps} machine instruction as a load from memory
22078 @item void __builtin_ia32_storehps (v2sf *, v4sf)
22079 Generates the @code{movhps} machine instruction as a store to memory.
22080 @item void __builtin_ia32_storelps (v2sf *, v4sf)
22081 Generates the @code{movlps} machine instruction as a store to memory.
22084 The following built-in functions are available when @option{-msse2} is used.
22085 All of them generate the machine instruction that is part of the name.
22088 int __builtin_ia32_comisdeq (v2df, v2df);
22089 int __builtin_ia32_comisdlt (v2df, v2df);
22090 int __builtin_ia32_comisdle (v2df, v2df);
22091 int __builtin_ia32_comisdgt (v2df, v2df);
22092 int __builtin_ia32_comisdge (v2df, v2df);
22093 int __builtin_ia32_comisdneq (v2df, v2df);
22094 int __builtin_ia32_ucomisdeq (v2df, v2df);
22095 int __builtin_ia32_ucomisdlt (v2df, v2df);
22096 int __builtin_ia32_ucomisdle (v2df, v2df);
22097 int __builtin_ia32_ucomisdgt (v2df, v2df);
22098 int __builtin_ia32_ucomisdge (v2df, v2df);
22099 int __builtin_ia32_ucomisdneq (v2df, v2df);
22100 v2df __builtin_ia32_cmpeqpd (v2df, v2df);
22101 v2df __builtin_ia32_cmpltpd (v2df, v2df);
22102 v2df __builtin_ia32_cmplepd (v2df, v2df);
22103 v2df __builtin_ia32_cmpgtpd (v2df, v2df);
22104 v2df __builtin_ia32_cmpgepd (v2df, v2df);
22105 v2df __builtin_ia32_cmpunordpd (v2df, v2df);
22106 v2df __builtin_ia32_cmpneqpd (v2df, v2df);
22107 v2df __builtin_ia32_cmpnltpd (v2df, v2df);
22108 v2df __builtin_ia32_cmpnlepd (v2df, v2df);
22109 v2df __builtin_ia32_cmpngtpd (v2df, v2df);
22110 v2df __builtin_ia32_cmpngepd (v2df, v2df);
22111 v2df __builtin_ia32_cmpordpd (v2df, v2df);
22112 v2df __builtin_ia32_cmpeqsd (v2df, v2df);
22113 v2df __builtin_ia32_cmpltsd (v2df, v2df);
22114 v2df __builtin_ia32_cmplesd (v2df, v2df);
22115 v2df __builtin_ia32_cmpunordsd (v2df, v2df);
22116 v2df __builtin_ia32_cmpneqsd (v2df, v2df);
22117 v2df __builtin_ia32_cmpnltsd (v2df, v2df);
22118 v2df __builtin_ia32_cmpnlesd (v2df, v2df);
22119 v2df __builtin_ia32_cmpordsd (v2df, v2df);
22120 v2di __builtin_ia32_paddq (v2di, v2di);
22121 v2di __builtin_ia32_psubq (v2di, v2di);
22122 v2df __builtin_ia32_addpd (v2df, v2df);
22123 v2df __builtin_ia32_subpd (v2df, v2df);
22124 v2df __builtin_ia32_mulpd (v2df, v2df);
22125 v2df __builtin_ia32_divpd (v2df, v2df);
22126 v2df __builtin_ia32_addsd (v2df, v2df);
22127 v2df __builtin_ia32_subsd (v2df, v2df);
22128 v2df __builtin_ia32_mulsd (v2df, v2df);
22129 v2df __builtin_ia32_divsd (v2df, v2df);
22130 v2df __builtin_ia32_minpd (v2df, v2df);
22131 v2df __builtin_ia32_maxpd (v2df, v2df);
22132 v2df __builtin_ia32_minsd (v2df, v2df);
22133 v2df __builtin_ia32_maxsd (v2df, v2df);
22134 v2df __builtin_ia32_andpd (v2df, v2df);
22135 v2df __builtin_ia32_andnpd (v2df, v2df);
22136 v2df __builtin_ia32_orpd (v2df, v2df);
22137 v2df __builtin_ia32_xorpd (v2df, v2df);
22138 v2df __builtin_ia32_movsd (v2df, v2df);
22139 v2df __builtin_ia32_unpckhpd (v2df, v2df);
22140 v2df __builtin_ia32_unpcklpd (v2df, v2df);
22141 v16qi __builtin_ia32_paddb128 (v16qi, v16qi);
22142 v8hi __builtin_ia32_paddw128 (v8hi, v8hi);
22143 v4si __builtin_ia32_paddd128 (v4si, v4si);
22144 v2di __builtin_ia32_paddq128 (v2di, v2di);
22145 v16qi __builtin_ia32_psubb128 (v16qi, v16qi);
22146 v8hi __builtin_ia32_psubw128 (v8hi, v8hi);
22147 v4si __builtin_ia32_psubd128 (v4si, v4si);
22148 v2di __builtin_ia32_psubq128 (v2di, v2di);
22149 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi);
22150 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi);
22151 v2di __builtin_ia32_pand128 (v2di, v2di);
22152 v2di __builtin_ia32_pandn128 (v2di, v2di);
22153 v2di __builtin_ia32_por128 (v2di, v2di);
22154 v2di __builtin_ia32_pxor128 (v2di, v2di);
22155 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi);
22156 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi);
22157 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi);
22158 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi);
22159 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si);
22160 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi);
22161 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi);
22162 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si);
22163 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi);
22164 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi);
22165 v16qi __builtin_ia32_pminub128 (v16qi, v16qi);
22166 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi);
22167 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi);
22168 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi);
22169 v4si __builtin_ia32_punpckhdq128 (v4si, v4si);
22170 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di);
22171 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi);
22172 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi);
22173 v4si __builtin_ia32_punpckldq128 (v4si, v4si);
22174 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di);
22175 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi);
22176 v8hi __builtin_ia32_packssdw128 (v4si, v4si);
22177 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi);
22178 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi);
22179 void __builtin_ia32_maskmovdqu (v16qi, v16qi);
22180 v2df __builtin_ia32_loadupd (double *);
22181 void __builtin_ia32_storeupd (double *, v2df);
22182 v2df __builtin_ia32_loadhpd (v2df, double const *);
22183 v2df __builtin_ia32_loadlpd (v2df, double const *);
22184 int __builtin_ia32_movmskpd (v2df);
22185 int __builtin_ia32_pmovmskb128 (v16qi);
22186 void __builtin_ia32_movnti (int *, int);
22187 void __builtin_ia32_movnti64 (long long int *, long long int);
22188 void __builtin_ia32_movntpd (double *, v2df);
22189 void __builtin_ia32_movntdq (v2df *, v2df);
22190 v4si __builtin_ia32_pshufd (v4si, int);
22191 v8hi __builtin_ia32_pshuflw (v8hi, int);
22192 v8hi __builtin_ia32_pshufhw (v8hi, int);
22193 v2di __builtin_ia32_psadbw128 (v16qi, v16qi);
22194 v2df __builtin_ia32_sqrtpd (v2df);
22195 v2df __builtin_ia32_sqrtsd (v2df);
22196 v2df __builtin_ia32_shufpd (v2df, v2df, int);
22197 v2df __builtin_ia32_cvtdq2pd (v4si);
22198 v4sf __builtin_ia32_cvtdq2ps (v4si);
22199 v4si __builtin_ia32_cvtpd2dq (v2df);
22200 v2si __builtin_ia32_cvtpd2pi (v2df);
22201 v4sf __builtin_ia32_cvtpd2ps (v2df);
22202 v4si __builtin_ia32_cvttpd2dq (v2df);
22203 v2si __builtin_ia32_cvttpd2pi (v2df);
22204 v2df __builtin_ia32_cvtpi2pd (v2si);
22205 int __builtin_ia32_cvtsd2si (v2df);
22206 int __builtin_ia32_cvttsd2si (v2df);
22207 long long __builtin_ia32_cvtsd2si64 (v2df);
22208 long long __builtin_ia32_cvttsd2si64 (v2df);
22209 v4si __builtin_ia32_cvtps2dq (v4sf);
22210 v2df __builtin_ia32_cvtps2pd (v4sf);
22211 v4si __builtin_ia32_cvttps2dq (v4sf);
22212 v2df __builtin_ia32_cvtsi2sd (v2df, int);
22213 v2df __builtin_ia32_cvtsi642sd (v2df, long long);
22214 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df);
22215 v2df __builtin_ia32_cvtss2sd (v2df, v4sf);
22216 void __builtin_ia32_clflush (const void *);
22217 void __builtin_ia32_lfence (void);
22218 void __builtin_ia32_mfence (void);
22219 v16qi __builtin_ia32_loaddqu (const char *);
22220 void __builtin_ia32_storedqu (char *, v16qi);
22221 v1di __builtin_ia32_pmuludq (v2si, v2si);
22222 v2di __builtin_ia32_pmuludq128 (v4si, v4si);
22223 v8hi __builtin_ia32_psllw128 (v8hi, v8hi);
22224 v4si __builtin_ia32_pslld128 (v4si, v4si);
22225 v2di __builtin_ia32_psllq128 (v2di, v2di);
22226 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi);
22227 v4si __builtin_ia32_psrld128 (v4si, v4si);
22228 v2di __builtin_ia32_psrlq128 (v2di, v2di);
22229 v8hi __builtin_ia32_psraw128 (v8hi, v8hi);
22230 v4si __builtin_ia32_psrad128 (v4si, v4si);
22231 v2di __builtin_ia32_pslldqi128 (v2di, int);
22232 v8hi __builtin_ia32_psllwi128 (v8hi, int);
22233 v4si __builtin_ia32_pslldi128 (v4si, int);
22234 v2di __builtin_ia32_psllqi128 (v2di, int);
22235 v2di __builtin_ia32_psrldqi128 (v2di, int);
22236 v8hi __builtin_ia32_psrlwi128 (v8hi, int);
22237 v4si __builtin_ia32_psrldi128 (v4si, int);
22238 v2di __builtin_ia32_psrlqi128 (v2di, int);
22239 v8hi __builtin_ia32_psrawi128 (v8hi, int);
22240 v4si __builtin_ia32_psradi128 (v4si, int);
22241 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi);
22242 v2di __builtin_ia32_movq128 (v2di);
22245 The following built-in functions are available when @option{-msse3} is used.
22246 All of them generate the machine instruction that is part of the name.
22249 v2df __builtin_ia32_addsubpd (v2df, v2df);
22250 v4sf __builtin_ia32_addsubps (v4sf, v4sf);
22251 v2df __builtin_ia32_haddpd (v2df, v2df);
22252 v4sf __builtin_ia32_haddps (v4sf, v4sf);
22253 v2df __builtin_ia32_hsubpd (v2df, v2df);
22254 v4sf __builtin_ia32_hsubps (v4sf, v4sf);
22255 v16qi __builtin_ia32_lddqu (char const *);
22256 void __builtin_ia32_monitor (void *, unsigned int, unsigned int);
22257 v4sf __builtin_ia32_movshdup (v4sf);
22258 v4sf __builtin_ia32_movsldup (v4sf);
22259 void __builtin_ia32_mwait (unsigned int, unsigned int);
22262 The following built-in functions are available when @option{-mssse3} is used.
22263 All of them generate the machine instruction that is part of the name.
22266 v2si __builtin_ia32_phaddd (v2si, v2si);
22267 v4hi __builtin_ia32_phaddw (v4hi, v4hi);
22268 v4hi __builtin_ia32_phaddsw (v4hi, v4hi);
22269 v2si __builtin_ia32_phsubd (v2si, v2si);
22270 v4hi __builtin_ia32_phsubw (v4hi, v4hi);
22271 v4hi __builtin_ia32_phsubsw (v4hi, v4hi);
22272 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi);
22273 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi);
22274 v8qi __builtin_ia32_pshufb (v8qi, v8qi);
22275 v8qi __builtin_ia32_psignb (v8qi, v8qi);
22276 v2si __builtin_ia32_psignd (v2si, v2si);
22277 v4hi __builtin_ia32_psignw (v4hi, v4hi);
22278 v1di __builtin_ia32_palignr (v1di, v1di, int);
22279 v8qi __builtin_ia32_pabsb (v8qi);
22280 v2si __builtin_ia32_pabsd (v2si);
22281 v4hi __builtin_ia32_pabsw (v4hi);
22284 The following built-in functions are available when @option{-mssse3} is used.
22285 All of them generate the machine instruction that is part of the name.
22288 v4si __builtin_ia32_phaddd128 (v4si, v4si);
22289 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi);
22290 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi);
22291 v4si __builtin_ia32_phsubd128 (v4si, v4si);
22292 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi);
22293 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi);
22294 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi);
22295 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi);
22296 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi);
22297 v16qi __builtin_ia32_psignb128 (v16qi, v16qi);
22298 v4si __builtin_ia32_psignd128 (v4si, v4si);
22299 v8hi __builtin_ia32_psignw128 (v8hi, v8hi);
22300 v2di __builtin_ia32_palignr128 (v2di, v2di, int);
22301 v16qi __builtin_ia32_pabsb128 (v16qi);
22302 v4si __builtin_ia32_pabsd128 (v4si);
22303 v8hi __builtin_ia32_pabsw128 (v8hi);
22306 The following built-in functions are available when @option{-msse4.1} is
22307 used. All of them generate the machine instruction that is part of the
22311 v2df __builtin_ia32_blendpd (v2df, v2df, const int);
22312 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int);
22313 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df);
22314 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf);
22315 v2df __builtin_ia32_dppd (v2df, v2df, const int);
22316 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int);
22317 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int);
22318 v2di __builtin_ia32_movntdqa (v2di *);
22319 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int);
22320 v8hi __builtin_ia32_packusdw128 (v4si, v4si);
22321 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi);
22322 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int);
22323 v2di __builtin_ia32_pcmpeqq (v2di, v2di);
22324 v8hi __builtin_ia32_phminposuw128 (v8hi);
22325 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi);
22326 v4si __builtin_ia32_pmaxsd128 (v4si, v4si);
22327 v4si __builtin_ia32_pmaxud128 (v4si, v4si);
22328 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi);
22329 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi);
22330 v4si __builtin_ia32_pminsd128 (v4si, v4si);
22331 v4si __builtin_ia32_pminud128 (v4si, v4si);
22332 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi);
22333 v4si __builtin_ia32_pmovsxbd128 (v16qi);
22334 v2di __builtin_ia32_pmovsxbq128 (v16qi);
22335 v8hi __builtin_ia32_pmovsxbw128 (v16qi);
22336 v2di __builtin_ia32_pmovsxdq128 (v4si);
22337 v4si __builtin_ia32_pmovsxwd128 (v8hi);
22338 v2di __builtin_ia32_pmovsxwq128 (v8hi);
22339 v4si __builtin_ia32_pmovzxbd128 (v16qi);
22340 v2di __builtin_ia32_pmovzxbq128 (v16qi);
22341 v8hi __builtin_ia32_pmovzxbw128 (v16qi);
22342 v2di __builtin_ia32_pmovzxdq128 (v4si);
22343 v4si __builtin_ia32_pmovzxwd128 (v8hi);
22344 v2di __builtin_ia32_pmovzxwq128 (v8hi);
22345 v2di __builtin_ia32_pmuldq128 (v4si, v4si);
22346 v4si __builtin_ia32_pmulld128 (v4si, v4si);
22347 int __builtin_ia32_ptestc128 (v2di, v2di);
22348 int __builtin_ia32_ptestnzc128 (v2di, v2di);
22349 int __builtin_ia32_ptestz128 (v2di, v2di);
22350 v2df __builtin_ia32_roundpd (v2df, const int);
22351 v4sf __builtin_ia32_roundps (v4sf, const int);
22352 v2df __builtin_ia32_roundsd (v2df, v2df, const int);
22353 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int);
22356 The following built-in functions are available when @option{-msse4.1} is
22360 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
22361 Generates the @code{insertps} machine instruction.
22362 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
22363 Generates the @code{pextrb} machine instruction.
22364 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
22365 Generates the @code{pinsrb} machine instruction.
22366 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
22367 Generates the @code{pinsrd} machine instruction.
22368 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
22369 Generates the @code{pinsrq} machine instruction in 64bit mode.
22372 The following built-in functions are changed to generate new SSE4.1
22373 instructions when @option{-msse4.1} is used.
22376 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
22377 Generates the @code{extractps} machine instruction.
22378 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
22379 Generates the @code{pextrd} machine instruction.
22380 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
22381 Generates the @code{pextrq} machine instruction in 64bit mode.
22384 The following built-in functions are available when @option{-msse4.2} is
22385 used. All of them generate the machine instruction that is part of the
22389 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int);
22390 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int);
22391 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int);
22392 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int);
22393 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int);
22394 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int);
22395 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int);
22396 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int);
22397 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int);
22398 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int);
22399 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int);
22400 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int);
22401 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int);
22402 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int);
22403 v2di __builtin_ia32_pcmpgtq (v2di, v2di);
22406 The following built-in functions are available when @option{-msse4.2} is
22410 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
22411 Generates the @code{crc32b} machine instruction.
22412 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
22413 Generates the @code{crc32w} machine instruction.
22414 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
22415 Generates the @code{crc32l} machine instruction.
22416 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
22417 Generates the @code{crc32q} machine instruction.
22420 The following built-in functions are changed to generate new SSE4.2
22421 instructions when @option{-msse4.2} is used.
22424 @item int __builtin_popcount (unsigned int)
22425 Generates the @code{popcntl} machine instruction.
22426 @item int __builtin_popcountl (unsigned long)
22427 Generates the @code{popcntl} or @code{popcntq} machine instruction,
22428 depending on the size of @code{unsigned long}.
22429 @item int __builtin_popcountll (unsigned long long)
22430 Generates the @code{popcntq} machine instruction.
22433 The following built-in functions are available when @option{-mavx} is
22434 used. All of them generate the machine instruction that is part of the
22438 v4df __builtin_ia32_addpd256 (v4df,v4df);
22439 v8sf __builtin_ia32_addps256 (v8sf,v8sf);
22440 v4df __builtin_ia32_addsubpd256 (v4df,v4df);
22441 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf);
22442 v4df __builtin_ia32_andnpd256 (v4df,v4df);
22443 v8sf __builtin_ia32_andnps256 (v8sf,v8sf);
22444 v4df __builtin_ia32_andpd256 (v4df,v4df);
22445 v8sf __builtin_ia32_andps256 (v8sf,v8sf);
22446 v4df __builtin_ia32_blendpd256 (v4df,v4df,int);
22447 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int);
22448 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df);
22449 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf);
22450 v2df __builtin_ia32_cmppd (v2df,v2df,int);
22451 v4df __builtin_ia32_cmppd256 (v4df,v4df,int);
22452 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int);
22453 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int);
22454 v2df __builtin_ia32_cmpsd (v2df,v2df,int);
22455 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int);
22456 v4df __builtin_ia32_cvtdq2pd256 (v4si);
22457 v8sf __builtin_ia32_cvtdq2ps256 (v8si);
22458 v4si __builtin_ia32_cvtpd2dq256 (v4df);
22459 v4sf __builtin_ia32_cvtpd2ps256 (v4df);
22460 v8si __builtin_ia32_cvtps2dq256 (v8sf);
22461 v4df __builtin_ia32_cvtps2pd256 (v4sf);
22462 v4si __builtin_ia32_cvttpd2dq256 (v4df);
22463 v8si __builtin_ia32_cvttps2dq256 (v8sf);
22464 v4df __builtin_ia32_divpd256 (v4df,v4df);
22465 v8sf __builtin_ia32_divps256 (v8sf,v8sf);
22466 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int);
22467 v4df __builtin_ia32_haddpd256 (v4df,v4df);
22468 v8sf __builtin_ia32_haddps256 (v8sf,v8sf);
22469 v4df __builtin_ia32_hsubpd256 (v4df,v4df);
22470 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf);
22471 v32qi __builtin_ia32_lddqu256 (pcchar);
22472 v32qi __builtin_ia32_loaddqu256 (pcchar);
22473 v4df __builtin_ia32_loadupd256 (pcdouble);
22474 v8sf __builtin_ia32_loadups256 (pcfloat);
22475 v2df __builtin_ia32_maskloadpd (pcv2df,v2df);
22476 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df);
22477 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf);
22478 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf);
22479 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df);
22480 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df);
22481 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf);
22482 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf);
22483 v4df __builtin_ia32_maxpd256 (v4df,v4df);
22484 v8sf __builtin_ia32_maxps256 (v8sf,v8sf);
22485 v4df __builtin_ia32_minpd256 (v4df,v4df);
22486 v8sf __builtin_ia32_minps256 (v8sf,v8sf);
22487 v4df __builtin_ia32_movddup256 (v4df);
22488 int __builtin_ia32_movmskpd256 (v4df);
22489 int __builtin_ia32_movmskps256 (v8sf);
22490 v8sf __builtin_ia32_movshdup256 (v8sf);
22491 v8sf __builtin_ia32_movsldup256 (v8sf);
22492 v4df __builtin_ia32_mulpd256 (v4df,v4df);
22493 v8sf __builtin_ia32_mulps256 (v8sf,v8sf);
22494 v4df __builtin_ia32_orpd256 (v4df,v4df);
22495 v8sf __builtin_ia32_orps256 (v8sf,v8sf);
22496 v2df __builtin_ia32_pd_pd256 (v4df);
22497 v4df __builtin_ia32_pd256_pd (v2df);
22498 v4sf __builtin_ia32_ps_ps256 (v8sf);
22499 v8sf __builtin_ia32_ps256_ps (v4sf);
22500 int __builtin_ia32_ptestc256 (v4di,v4di,ptest);
22501 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest);
22502 int __builtin_ia32_ptestz256 (v4di,v4di,ptest);
22503 v8sf __builtin_ia32_rcpps256 (v8sf);
22504 v4df __builtin_ia32_roundpd256 (v4df,int);
22505 v8sf __builtin_ia32_roundps256 (v8sf,int);
22506 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf);
22507 v8sf __builtin_ia32_rsqrtps256 (v8sf);
22508 v4df __builtin_ia32_shufpd256 (v4df,v4df,int);
22509 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int);
22510 v4si __builtin_ia32_si_si256 (v8si);
22511 v8si __builtin_ia32_si256_si (v4si);
22512 v4df __builtin_ia32_sqrtpd256 (v4df);
22513 v8sf __builtin_ia32_sqrtps_nr256 (v8sf);
22514 v8sf __builtin_ia32_sqrtps256 (v8sf);
22515 void __builtin_ia32_storedqu256 (pchar,v32qi);
22516 void __builtin_ia32_storeupd256 (pdouble,v4df);
22517 void __builtin_ia32_storeups256 (pfloat,v8sf);
22518 v4df __builtin_ia32_subpd256 (v4df,v4df);
22519 v8sf __builtin_ia32_subps256 (v8sf,v8sf);
22520 v4df __builtin_ia32_unpckhpd256 (v4df,v4df);
22521 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf);
22522 v4df __builtin_ia32_unpcklpd256 (v4df,v4df);
22523 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf);
22524 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df);
22525 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf);
22526 v4df __builtin_ia32_vbroadcastsd256 (pcdouble);
22527 v4sf __builtin_ia32_vbroadcastss (pcfloat);
22528 v8sf __builtin_ia32_vbroadcastss256 (pcfloat);
22529 v2df __builtin_ia32_vextractf128_pd256 (v4df,int);
22530 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int);
22531 v4si __builtin_ia32_vextractf128_si256 (v8si,int);
22532 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int);
22533 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int);
22534 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int);
22535 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int);
22536 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int);
22537 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int);
22538 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int);
22539 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int);
22540 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int);
22541 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int);
22542 v2df __builtin_ia32_vpermilpd (v2df,int);
22543 v4df __builtin_ia32_vpermilpd256 (v4df,int);
22544 v4sf __builtin_ia32_vpermilps (v4sf,int);
22545 v8sf __builtin_ia32_vpermilps256 (v8sf,int);
22546 v2df __builtin_ia32_vpermilvarpd (v2df,v2di);
22547 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di);
22548 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si);
22549 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si);
22550 int __builtin_ia32_vtestcpd (v2df,v2df,ptest);
22551 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest);
22552 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest);
22553 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest);
22554 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest);
22555 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest);
22556 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest);
22557 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest);
22558 int __builtin_ia32_vtestzpd (v2df,v2df,ptest);
22559 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest);
22560 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest);
22561 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest);
22562 void __builtin_ia32_vzeroall (void);
22563 void __builtin_ia32_vzeroupper (void);
22564 v4df __builtin_ia32_xorpd256 (v4df,v4df);
22565 v8sf __builtin_ia32_xorps256 (v8sf,v8sf);
22568 The following built-in functions are available when @option{-mavx2} is
22569 used. All of them generate the machine instruction that is part of the
22573 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int);
22574 v32qi __builtin_ia32_pabsb256 (v32qi);
22575 v16hi __builtin_ia32_pabsw256 (v16hi);
22576 v8si __builtin_ia32_pabsd256 (v8si);
22577 v16hi __builtin_ia32_packssdw256 (v8si,v8si);
22578 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi);
22579 v16hi __builtin_ia32_packusdw256 (v8si,v8si);
22580 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi);
22581 v32qi __builtin_ia32_paddb256 (v32qi,v32qi);
22582 v16hi __builtin_ia32_paddw256 (v16hi,v16hi);
22583 v8si __builtin_ia32_paddd256 (v8si,v8si);
22584 v4di __builtin_ia32_paddq256 (v4di,v4di);
22585 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi);
22586 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi);
22587 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi);
22588 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi);
22589 v4di __builtin_ia32_palignr256 (v4di,v4di,int);
22590 v4di __builtin_ia32_andsi256 (v4di,v4di);
22591 v4di __builtin_ia32_andnotsi256 (v4di,v4di);
22592 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi);
22593 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi);
22594 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi);
22595 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int);
22596 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi);
22597 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi);
22598 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si);
22599 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di);
22600 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi);
22601 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi);
22602 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si);
22603 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di);
22604 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi);
22605 v8si __builtin_ia32_phaddd256 (v8si,v8si);
22606 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi);
22607 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi);
22608 v8si __builtin_ia32_phsubd256 (v8si,v8si);
22609 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi);
22610 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi);
22611 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi);
22612 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi);
22613 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi);
22614 v8si __builtin_ia32_pmaxsd256 (v8si,v8si);
22615 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi);
22616 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi);
22617 v8si __builtin_ia32_pmaxud256 (v8si,v8si);
22618 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi);
22619 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi);
22620 v8si __builtin_ia32_pminsd256 (v8si,v8si);
22621 v32qi __builtin_ia32_pminub256 (v32qi,v32qi);
22622 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi);
22623 v8si __builtin_ia32_pminud256 (v8si,v8si);
22624 int __builtin_ia32_pmovmskb256 (v32qi);
22625 v16hi __builtin_ia32_pmovsxbw256 (v16qi);
22626 v8si __builtin_ia32_pmovsxbd256 (v16qi);
22627 v4di __builtin_ia32_pmovsxbq256 (v16qi);
22628 v8si __builtin_ia32_pmovsxwd256 (v8hi);
22629 v4di __builtin_ia32_pmovsxwq256 (v8hi);
22630 v4di __builtin_ia32_pmovsxdq256 (v4si);
22631 v16hi __builtin_ia32_pmovzxbw256 (v16qi);
22632 v8si __builtin_ia32_pmovzxbd256 (v16qi);
22633 v4di __builtin_ia32_pmovzxbq256 (v16qi);
22634 v8si __builtin_ia32_pmovzxwd256 (v8hi);
22635 v4di __builtin_ia32_pmovzxwq256 (v8hi);
22636 v4di __builtin_ia32_pmovzxdq256 (v4si);
22637 v4di __builtin_ia32_pmuldq256 (v8si,v8si);
22638 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi);
22639 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi);
22640 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi);
22641 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi);
22642 v8si __builtin_ia32_pmulld256 (v8si,v8si);
22643 v4di __builtin_ia32_pmuludq256 (v8si,v8si);
22644 v4di __builtin_ia32_por256 (v4di,v4di);
22645 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi);
22646 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi);
22647 v8si __builtin_ia32_pshufd256 (v8si,int);
22648 v16hi __builtin_ia32_pshufhw256 (v16hi,int);
22649 v16hi __builtin_ia32_pshuflw256 (v16hi,int);
22650 v32qi __builtin_ia32_psignb256 (v32qi,v32qi);
22651 v16hi __builtin_ia32_psignw256 (v16hi,v16hi);
22652 v8si __builtin_ia32_psignd256 (v8si,v8si);
22653 v4di __builtin_ia32_pslldqi256 (v4di,int);
22654 v16hi __builtin_ia32_psllwi256 (16hi,int);
22655 v16hi __builtin_ia32_psllw256(v16hi,v8hi);
22656 v8si __builtin_ia32_pslldi256 (v8si,int);
22657 v8si __builtin_ia32_pslld256(v8si,v4si);
22658 v4di __builtin_ia32_psllqi256 (v4di,int);
22659 v4di __builtin_ia32_psllq256(v4di,v2di);
22660 v16hi __builtin_ia32_psrawi256 (v16hi,int);
22661 v16hi __builtin_ia32_psraw256 (v16hi,v8hi);
22662 v8si __builtin_ia32_psradi256 (v8si,int);
22663 v8si __builtin_ia32_psrad256 (v8si,v4si);
22664 v4di __builtin_ia32_psrldqi256 (v4di, int);
22665 v16hi __builtin_ia32_psrlwi256 (v16hi,int);
22666 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi);
22667 v8si __builtin_ia32_psrldi256 (v8si,int);
22668 v8si __builtin_ia32_psrld256 (v8si,v4si);
22669 v4di __builtin_ia32_psrlqi256 (v4di,int);
22670 v4di __builtin_ia32_psrlq256(v4di,v2di);
22671 v32qi __builtin_ia32_psubb256 (v32qi,v32qi);
22672 v32hi __builtin_ia32_psubw256 (v16hi,v16hi);
22673 v8si __builtin_ia32_psubd256 (v8si,v8si);
22674 v4di __builtin_ia32_psubq256 (v4di,v4di);
22675 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi);
22676 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi);
22677 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi);
22678 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi);
22679 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi);
22680 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi);
22681 v8si __builtin_ia32_punpckhdq256 (v8si,v8si);
22682 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di);
22683 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi);
22684 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi);
22685 v8si __builtin_ia32_punpckldq256 (v8si,v8si);
22686 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di);
22687 v4di __builtin_ia32_pxor256 (v4di,v4di);
22688 v4di __builtin_ia32_movntdqa256 (pv4di);
22689 v4sf __builtin_ia32_vbroadcastss_ps (v4sf);
22690 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf);
22691 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df);
22692 v4di __builtin_ia32_vbroadcastsi256 (v2di);
22693 v4si __builtin_ia32_pblendd128 (v4si,v4si);
22694 v8si __builtin_ia32_pblendd256 (v8si,v8si);
22695 v32qi __builtin_ia32_pbroadcastb256 (v16qi);
22696 v16hi __builtin_ia32_pbroadcastw256 (v8hi);
22697 v8si __builtin_ia32_pbroadcastd256 (v4si);
22698 v4di __builtin_ia32_pbroadcastq256 (v2di);
22699 v16qi __builtin_ia32_pbroadcastb128 (v16qi);
22700 v8hi __builtin_ia32_pbroadcastw128 (v8hi);
22701 v4si __builtin_ia32_pbroadcastd128 (v4si);
22702 v2di __builtin_ia32_pbroadcastq128 (v2di);
22703 v8si __builtin_ia32_permvarsi256 (v8si,v8si);
22704 v4df __builtin_ia32_permdf256 (v4df,int);
22705 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf);
22706 v4di __builtin_ia32_permdi256 (v4di,int);
22707 v4di __builtin_ia32_permti256 (v4di,v4di,int);
22708 v4di __builtin_ia32_extract128i256 (v4di,int);
22709 v4di __builtin_ia32_insert128i256 (v4di,v2di,int);
22710 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si);
22711 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di);
22712 v4si __builtin_ia32_maskloadd (pcv4si,v4si);
22713 v2di __builtin_ia32_maskloadq (pcv2di,v2di);
22714 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si);
22715 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di);
22716 void __builtin_ia32_maskstored (pv4si,v4si,v4si);
22717 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di);
22718 v8si __builtin_ia32_psllv8si (v8si,v8si);
22719 v4si __builtin_ia32_psllv4si (v4si,v4si);
22720 v4di __builtin_ia32_psllv4di (v4di,v4di);
22721 v2di __builtin_ia32_psllv2di (v2di,v2di);
22722 v8si __builtin_ia32_psrav8si (v8si,v8si);
22723 v4si __builtin_ia32_psrav4si (v4si,v4si);
22724 v8si __builtin_ia32_psrlv8si (v8si,v8si);
22725 v4si __builtin_ia32_psrlv4si (v4si,v4si);
22726 v4di __builtin_ia32_psrlv4di (v4di,v4di);
22727 v2di __builtin_ia32_psrlv2di (v2di,v2di);
22728 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int);
22729 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int);
22730 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int);
22731 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int);
22732 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int);
22733 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int);
22734 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int);
22735 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int);
22736 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int);
22737 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int);
22738 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int);
22739 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int);
22740 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int);
22741 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int);
22742 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int);
22743 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int);
22746 The following built-in functions are available when @option{-maes} is
22747 used. All of them generate the machine instruction that is part of the
22751 v2di __builtin_ia32_aesenc128 (v2di, v2di);
22752 v2di __builtin_ia32_aesenclast128 (v2di, v2di);
22753 v2di __builtin_ia32_aesdec128 (v2di, v2di);
22754 v2di __builtin_ia32_aesdeclast128 (v2di, v2di);
22755 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int);
22756 v2di __builtin_ia32_aesimc128 (v2di);
22759 The following built-in function is available when @option{-mpclmul} is
22763 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
22764 Generates the @code{pclmulqdq} machine instruction.
22767 The following built-in function is available when @option{-mfsgsbase} is
22768 used. All of them generate the machine instruction that is part of the
22772 unsigned int __builtin_ia32_rdfsbase32 (void);
22773 unsigned long long __builtin_ia32_rdfsbase64 (void);
22774 unsigned int __builtin_ia32_rdgsbase32 (void);
22775 unsigned long long __builtin_ia32_rdgsbase64 (void);
22776 void _writefsbase_u32 (unsigned int);
22777 void _writefsbase_u64 (unsigned long long);
22778 void _writegsbase_u32 (unsigned int);
22779 void _writegsbase_u64 (unsigned long long);
22782 The following built-in function is available when @option{-mrdrnd} is
22783 used. All of them generate the machine instruction that is part of the
22787 unsigned int __builtin_ia32_rdrand16_step (unsigned short *);
22788 unsigned int __builtin_ia32_rdrand32_step (unsigned int *);
22789 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *);
22792 The following built-in function is available when @option{-mptwrite} is
22793 used. All of them generate the machine instruction that is part of the
22797 void __builtin_ia32_ptwrite32 (unsigned);
22798 void __builtin_ia32_ptwrite64 (unsigned long long);
22801 The following built-in functions are available when @option{-msse4a} is used.
22802 All of them generate the machine instruction that is part of the name.
22805 void __builtin_ia32_movntsd (double *, v2df);
22806 void __builtin_ia32_movntss (float *, v4sf);
22807 v2di __builtin_ia32_extrq (v2di, v16qi);
22808 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int);
22809 v2di __builtin_ia32_insertq (v2di, v2di);
22810 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int);
22813 The following built-in functions are available when @option{-mxop} is used.
22815 v2df __builtin_ia32_vfrczpd (v2df);
22816 v4sf __builtin_ia32_vfrczps (v4sf);
22817 v2df __builtin_ia32_vfrczsd (v2df);
22818 v4sf __builtin_ia32_vfrczss (v4sf);
22819 v4df __builtin_ia32_vfrczpd256 (v4df);
22820 v8sf __builtin_ia32_vfrczps256 (v8sf);
22821 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di);
22822 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di);
22823 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si);
22824 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi);
22825 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi);
22826 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df);
22827 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf);
22828 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di);
22829 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si);
22830 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi);
22831 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi);
22832 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df);
22833 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf);
22834 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi);
22835 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi);
22836 v4si __builtin_ia32_vpcomeqd (v4si, v4si);
22837 v2di __builtin_ia32_vpcomeqq (v2di, v2di);
22838 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi);
22839 v4si __builtin_ia32_vpcomequd (v4si, v4si);
22840 v2di __builtin_ia32_vpcomequq (v2di, v2di);
22841 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi);
22842 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi);
22843 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi);
22844 v4si __builtin_ia32_vpcomfalsed (v4si, v4si);
22845 v2di __builtin_ia32_vpcomfalseq (v2di, v2di);
22846 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi);
22847 v4si __builtin_ia32_vpcomfalseud (v4si, v4si);
22848 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di);
22849 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi);
22850 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi);
22851 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi);
22852 v4si __builtin_ia32_vpcomged (v4si, v4si);
22853 v2di __builtin_ia32_vpcomgeq (v2di, v2di);
22854 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi);
22855 v4si __builtin_ia32_vpcomgeud (v4si, v4si);
22856 v2di __builtin_ia32_vpcomgeuq (v2di, v2di);
22857 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi);
22858 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi);
22859 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi);
22860 v4si __builtin_ia32_vpcomgtd (v4si, v4si);
22861 v2di __builtin_ia32_vpcomgtq (v2di, v2di);
22862 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi);
22863 v4si __builtin_ia32_vpcomgtud (v4si, v4si);
22864 v2di __builtin_ia32_vpcomgtuq (v2di, v2di);
22865 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi);
22866 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi);
22867 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi);
22868 v4si __builtin_ia32_vpcomled (v4si, v4si);
22869 v2di __builtin_ia32_vpcomleq (v2di, v2di);
22870 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi);
22871 v4si __builtin_ia32_vpcomleud (v4si, v4si);
22872 v2di __builtin_ia32_vpcomleuq (v2di, v2di);
22873 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi);
22874 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi);
22875 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi);
22876 v4si __builtin_ia32_vpcomltd (v4si, v4si);
22877 v2di __builtin_ia32_vpcomltq (v2di, v2di);
22878 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi);
22879 v4si __builtin_ia32_vpcomltud (v4si, v4si);
22880 v2di __builtin_ia32_vpcomltuq (v2di, v2di);
22881 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi);
22882 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi);
22883 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi);
22884 v4si __builtin_ia32_vpcomned (v4si, v4si);
22885 v2di __builtin_ia32_vpcomneq (v2di, v2di);
22886 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi);
22887 v4si __builtin_ia32_vpcomneud (v4si, v4si);
22888 v2di __builtin_ia32_vpcomneuq (v2di, v2di);
22889 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi);
22890 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi);
22891 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi);
22892 v4si __builtin_ia32_vpcomtrued (v4si, v4si);
22893 v2di __builtin_ia32_vpcomtrueq (v2di, v2di);
22894 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi);
22895 v4si __builtin_ia32_vpcomtrueud (v4si, v4si);
22896 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di);
22897 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi);
22898 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi);
22899 v4si __builtin_ia32_vphaddbd (v16qi);
22900 v2di __builtin_ia32_vphaddbq (v16qi);
22901 v8hi __builtin_ia32_vphaddbw (v16qi);
22902 v2di __builtin_ia32_vphadddq (v4si);
22903 v4si __builtin_ia32_vphaddubd (v16qi);
22904 v2di __builtin_ia32_vphaddubq (v16qi);
22905 v8hi __builtin_ia32_vphaddubw (v16qi);
22906 v2di __builtin_ia32_vphaddudq (v4si);
22907 v4si __builtin_ia32_vphadduwd (v8hi);
22908 v2di __builtin_ia32_vphadduwq (v8hi);
22909 v4si __builtin_ia32_vphaddwd (v8hi);
22910 v2di __builtin_ia32_vphaddwq (v8hi);
22911 v8hi __builtin_ia32_vphsubbw (v16qi);
22912 v2di __builtin_ia32_vphsubdq (v4si);
22913 v4si __builtin_ia32_vphsubwd (v8hi);
22914 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si);
22915 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di);
22916 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di);
22917 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si);
22918 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di);
22919 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di);
22920 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si);
22921 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi);
22922 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si);
22923 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi);
22924 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si);
22925 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si);
22926 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi);
22927 v16qi __builtin_ia32_vprotb (v16qi, v16qi);
22928 v4si __builtin_ia32_vprotd (v4si, v4si);
22929 v2di __builtin_ia32_vprotq (v2di, v2di);
22930 v8hi __builtin_ia32_vprotw (v8hi, v8hi);
22931 v16qi __builtin_ia32_vpshab (v16qi, v16qi);
22932 v4si __builtin_ia32_vpshad (v4si, v4si);
22933 v2di __builtin_ia32_vpshaq (v2di, v2di);
22934 v8hi __builtin_ia32_vpshaw (v8hi, v8hi);
22935 v16qi __builtin_ia32_vpshlb (v16qi, v16qi);
22936 v4si __builtin_ia32_vpshld (v4si, v4si);
22937 v2di __builtin_ia32_vpshlq (v2di, v2di);
22938 v8hi __builtin_ia32_vpshlw (v8hi, v8hi);
22941 The following built-in functions are available when @option{-mfma4} is used.
22942 All of them generate the machine instruction that is part of the name.
22945 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df);
22946 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf);
22947 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df);
22948 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf);
22949 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df);
22950 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf);
22951 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df);
22952 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf);
22953 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df);
22954 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf);
22955 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df);
22956 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf);
22957 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df);
22958 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf);
22959 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df);
22960 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf);
22961 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df);
22962 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf);
22963 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df);
22964 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf);
22965 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df);
22966 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf);
22967 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df);
22968 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf);
22969 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df);
22970 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf);
22971 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df);
22972 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf);
22973 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df);
22974 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf);
22975 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df);
22976 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf);
22980 The following built-in functions are available when @option{-mlwp} is used.
22983 void __builtin_ia32_llwpcb16 (void *);
22984 void __builtin_ia32_llwpcb32 (void *);
22985 void __builtin_ia32_llwpcb64 (void *);
22986 void * __builtin_ia32_llwpcb16 (void);
22987 void * __builtin_ia32_llwpcb32 (void);
22988 void * __builtin_ia32_llwpcb64 (void);
22989 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short);
22990 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int);
22991 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int);
22992 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short);
22993 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int);
22994 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int);
22997 The following built-in functions are available when @option{-mbmi} is used.
22998 All of them generate the machine instruction that is part of the name.
23000 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
23001 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
23004 The following built-in functions are available when @option{-mbmi2} is used.
23005 All of them generate the machine instruction that is part of the name.
23007 unsigned int _bzhi_u32 (unsigned int, unsigned int);
23008 unsigned int _pdep_u32 (unsigned int, unsigned int);
23009 unsigned int _pext_u32 (unsigned int, unsigned int);
23010 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long);
23011 unsigned long long _pdep_u64 (unsigned long long, unsigned long long);
23012 unsigned long long _pext_u64 (unsigned long long, unsigned long long);
23015 The following built-in functions are available when @option{-mlzcnt} is used.
23016 All of them generate the machine instruction that is part of the name.
23018 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
23019 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
23020 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
23023 The following built-in functions are available when @option{-mfxsr} is used.
23024 All of them generate the machine instruction that is part of the name.
23026 void __builtin_ia32_fxsave (void *);
23027 void __builtin_ia32_fxrstor (void *);
23028 void __builtin_ia32_fxsave64 (void *);
23029 void __builtin_ia32_fxrstor64 (void *);
23032 The following built-in functions are available when @option{-mxsave} is used.
23033 All of them generate the machine instruction that is part of the name.
23035 void __builtin_ia32_xsave (void *, long long);
23036 void __builtin_ia32_xrstor (void *, long long);
23037 void __builtin_ia32_xsave64 (void *, long long);
23038 void __builtin_ia32_xrstor64 (void *, long long);
23041 The following built-in functions are available when @option{-mxsaveopt} is used.
23042 All of them generate the machine instruction that is part of the name.
23044 void __builtin_ia32_xsaveopt (void *, long long);
23045 void __builtin_ia32_xsaveopt64 (void *, long long);
23048 The following built-in functions are available when @option{-mtbm} is used.
23049 Both of them generate the immediate form of the bextr machine instruction.
23051 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
23052 const unsigned int);
23053 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
23054 const unsigned long long);
23058 The following built-in functions are available when @option{-m3dnow} is used.
23059 All of them generate the machine instruction that is part of the name.
23062 void __builtin_ia32_femms (void);
23063 v8qi __builtin_ia32_pavgusb (v8qi, v8qi);
23064 v2si __builtin_ia32_pf2id (v2sf);
23065 v2sf __builtin_ia32_pfacc (v2sf, v2sf);
23066 v2sf __builtin_ia32_pfadd (v2sf, v2sf);
23067 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf);
23068 v2si __builtin_ia32_pfcmpge (v2sf, v2sf);
23069 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf);
23070 v2sf __builtin_ia32_pfmax (v2sf, v2sf);
23071 v2sf __builtin_ia32_pfmin (v2sf, v2sf);
23072 v2sf __builtin_ia32_pfmul (v2sf, v2sf);
23073 v2sf __builtin_ia32_pfrcp (v2sf);
23074 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf);
23075 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf);
23076 v2sf __builtin_ia32_pfrsqrt (v2sf);
23077 v2sf __builtin_ia32_pfsub (v2sf, v2sf);
23078 v2sf __builtin_ia32_pfsubr (v2sf, v2sf);
23079 v2sf __builtin_ia32_pi2fd (v2si);
23080 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi);
23083 The following built-in functions are available when @option{-m3dnowa} is used.
23084 All of them generate the machine instruction that is part of the name.
23087 v2si __builtin_ia32_pf2iw (v2sf);
23088 v2sf __builtin_ia32_pfnacc (v2sf, v2sf);
23089 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf);
23090 v2sf __builtin_ia32_pi2fw (v2si);
23091 v2sf __builtin_ia32_pswapdsf (v2sf);
23092 v2si __builtin_ia32_pswapdsi (v2si);
23095 The following built-in functions are available when @option{-mrtm} is used
23096 They are used for restricted transactional memory. These are the internal
23097 low level functions. Normally the functions in
23098 @ref{x86 transactional memory intrinsics} should be used instead.
23101 int __builtin_ia32_xbegin ();
23102 void __builtin_ia32_xend ();
23103 void __builtin_ia32_xabort (status);
23104 int __builtin_ia32_xtest ();
23107 The following built-in functions are available when @option{-mmwaitx} is used.
23108 All of them generate the machine instruction that is part of the name.
23110 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int);
23111 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int);
23114 The following built-in functions are available when @option{-mclzero} is used.
23115 All of them generate the machine instruction that is part of the name.
23117 void __builtin_i32_clzero (void *);
23120 The following built-in functions are available when @option{-mpku} is used.
23121 They generate reads and writes to PKRU.
23123 void __builtin_ia32_wrpkru (unsigned int);
23124 unsigned int __builtin_ia32_rdpkru ();
23127 The following built-in functions are available when
23128 @option{-mshstk} option is used. They support shadow stack
23129 machine instructions from Intel Control-flow Enforcement Technology (CET).
23130 Each built-in function generates the machine instruction that is part
23131 of the function's name. These are the internal low-level functions.
23132 Normally the functions in @ref{x86 control-flow protection intrinsics}
23133 should be used instead.
23136 unsigned int __builtin_ia32_rdsspd (void);
23137 unsigned long long __builtin_ia32_rdsspq (void);
23138 void __builtin_ia32_incsspd (unsigned int);
23139 void __builtin_ia32_incsspq (unsigned long long);
23140 void __builtin_ia32_saveprevssp(void);
23141 void __builtin_ia32_rstorssp(void *);
23142 void __builtin_ia32_wrssd(unsigned int, void *);
23143 void __builtin_ia32_wrssq(unsigned long long, void *);
23144 void __builtin_ia32_wrussd(unsigned int, void *);
23145 void __builtin_ia32_wrussq(unsigned long long, void *);
23146 void __builtin_ia32_setssbsy(void);
23147 void __builtin_ia32_clrssbsy(void *);
23150 @node x86 transactional memory intrinsics
23151 @subsection x86 Transactional Memory Intrinsics
23153 These hardware transactional memory intrinsics for x86 allow you to use
23154 memory transactions with RTM (Restricted Transactional Memory).
23155 This support is enabled with the @option{-mrtm} option.
23156 For using HLE (Hardware Lock Elision) see
23157 @ref{x86 specific memory model extensions for transactional memory} instead.
23159 A memory transaction commits all changes to memory in an atomic way,
23160 as visible to other threads. If the transaction fails it is rolled back
23161 and all side effects discarded.
23163 Generally there is no guarantee that a memory transaction ever succeeds
23164 and suitable fallback code always needs to be supplied.
23166 @deftypefn {RTM Function} {unsigned} _xbegin ()
23167 Start a RTM (Restricted Transactional Memory) transaction.
23168 Returns @code{_XBEGIN_STARTED} when the transaction
23169 started successfully (note this is not 0, so the constant has to be
23170 explicitly tested).
23172 If the transaction aborts, all side effects
23173 are undone and an abort code encoded as a bit mask is returned.
23174 The following macros are defined:
23177 @item _XABORT_EXPLICIT
23178 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
23179 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
23180 @item _XABORT_RETRY
23181 Transaction retry is possible.
23182 @item _XABORT_CONFLICT
23183 Transaction abort due to a memory conflict with another thread.
23184 @item _XABORT_CAPACITY
23185 Transaction abort due to the transaction using too much memory.
23186 @item _XABORT_DEBUG
23187 Transaction abort due to a debug trap.
23188 @item _XABORT_NESTED
23189 Transaction abort in an inner nested transaction.
23192 There is no guarantee
23193 any transaction ever succeeds, so there always needs to be a valid
23197 @deftypefn {RTM Function} {void} _xend ()
23198 Commit the current transaction. When no transaction is active this faults.
23199 All memory side effects of the transaction become visible
23200 to other threads in an atomic manner.
23203 @deftypefn {RTM Function} {int} _xtest ()
23204 Return a nonzero value if a transaction is currently active, otherwise 0.
23207 @deftypefn {RTM Function} {void} _xabort (status)
23208 Abort the current transaction. When no transaction is active this is a no-op.
23209 The @var{status} is an 8-bit constant; its value is encoded in the return
23210 value from @code{_xbegin}.
23213 Here is an example showing handling for @code{_XABORT_RETRY}
23214 and a fallback path for other failures:
23217 #include <immintrin.h>
23219 int n_tries, max_tries;
23220 unsigned status = _XABORT_EXPLICIT;
23223 for (n_tries = 0; n_tries < max_tries; n_tries++)
23225 status = _xbegin ();
23226 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
23229 if (status == _XBEGIN_STARTED)
23231 ... transaction code...
23236 ... non-transactional fallback path...
23241 Note that, in most cases, the transactional and non-transactional code
23242 must synchronize together to ensure consistency.
23244 @node x86 control-flow protection intrinsics
23245 @subsection x86 Control-Flow Protection Intrinsics
23247 @deftypefn {CET Function} {ret_type} _get_ssp (void)
23248 Get the current value of shadow stack pointer if shadow stack support
23249 from Intel CET is enabled in the hardware or @code{0} otherwise.
23250 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
23251 and @code{unsigned int} for 32-bit targets.
23254 @deftypefn {CET Function} void _inc_ssp (unsigned int)
23255 Increment the current shadow stack pointer by the size specified by the
23256 function argument. The argument is masked to a byte value for security
23257 reasons, so to increment by more than 255 bytes you must call the function
23261 The shadow stack unwind code looks like:
23264 #include <immintrin.h>
23266 /* Unwind the shadow stack for EH. */
23267 #define _Unwind_Frames_Extra(x) \
23270 _Unwind_Word ssp = _get_ssp (); \
23273 _Unwind_Word tmp = (x); \
23274 while (tmp > 255) \
23286 This code runs unconditionally on all 64-bit processors. For 32-bit
23287 processors the code runs on those that support multi-byte NOP instructions.
23289 @node Target Format Checks
23290 @section Format Checks Specific to Particular Target Machines
23292 For some target machines, GCC supports additional options to the
23294 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
23297 * Solaris Format Checks::
23298 * Darwin Format Checks::
23301 @node Solaris Format Checks
23302 @subsection Solaris Format Checks
23304 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
23305 check. @code{cmn_err} accepts a subset of the standard @code{printf}
23306 conversions, and the two-argument @code{%b} conversion for displaying
23307 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
23309 @node Darwin Format Checks
23310 @subsection Darwin Format Checks
23312 In addition to the full set of format archetypes (attribute format style
23313 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
23314 @code{strfmon}), Darwin targets also support the @code{CFString} (or
23315 @code{__CFString__}) archetype in the @code{format} attribute.
23316 Declarations with this archetype are parsed for correct syntax
23317 and argument types. However, parsing of the format string itself and
23318 validating arguments against it in calls to such functions is currently
23321 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
23322 also be used as format arguments. Note that the relevant headers are only likely to be
23323 available on Darwin (OSX) installations. On such installations, the XCode and system
23324 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
23325 associated functions.
23328 @section Pragmas Accepted by GCC
23330 @cindex @code{#pragma}
23332 GCC supports several types of pragmas, primarily in order to compile
23333 code originally written for other compilers. Note that in general
23334 we do not recommend the use of pragmas; @xref{Function Attributes},
23335 for further explanation.
23337 The GNU C preprocessor recognizes several pragmas in addition to the
23338 compiler pragmas documented here. Refer to the CPP manual for more
23342 * AArch64 Pragmas::
23347 * RS/6000 and PowerPC Pragmas::
23350 * Solaris Pragmas::
23351 * Symbol-Renaming Pragmas::
23352 * Structure-Layout Pragmas::
23354 * Diagnostic Pragmas::
23355 * Visibility Pragmas::
23356 * Push/Pop Macro Pragmas::
23357 * Function Specific Option Pragmas::
23358 * Loop-Specific Pragmas::
23361 @node AArch64 Pragmas
23362 @subsection AArch64 Pragmas
23364 The pragmas defined by the AArch64 target correspond to the AArch64
23365 target function attributes. They can be specified as below:
23367 #pragma GCC target("string")
23370 where @code{@var{string}} can be any string accepted as an AArch64 target
23371 attribute. @xref{AArch64 Function Attributes}, for more details
23372 on the permissible values of @code{string}.
23375 @subsection ARM Pragmas
23377 The ARM target defines pragmas for controlling the default addition of
23378 @code{long_call} and @code{short_call} attributes to functions.
23379 @xref{Function Attributes}, for information about the effects of these
23384 @cindex pragma, long_calls
23385 Set all subsequent functions to have the @code{long_call} attribute.
23387 @item no_long_calls
23388 @cindex pragma, no_long_calls
23389 Set all subsequent functions to have the @code{short_call} attribute.
23391 @item long_calls_off
23392 @cindex pragma, long_calls_off
23393 Do not affect the @code{long_call} or @code{short_call} attributes of
23394 subsequent functions.
23398 @subsection M32C Pragmas
23401 @item GCC memregs @var{number}
23402 @cindex pragma, memregs
23403 Overrides the command-line option @code{-memregs=} for the current
23404 file. Use with care! This pragma must be before any function in the
23405 file, and mixing different memregs values in different objects may
23406 make them incompatible. This pragma is useful when a
23407 performance-critical function uses a memreg for temporary values,
23408 as it may allow you to reduce the number of memregs used.
23410 @item ADDRESS @var{name} @var{address}
23411 @cindex pragma, address
23412 For any declared symbols matching @var{name}, this does three things
23413 to that symbol: it forces the symbol to be located at the given
23414 address (a number), it forces the symbol to be volatile, and it
23415 changes the symbol's scope to be static. This pragma exists for
23416 compatibility with other compilers, but note that the common
23417 @code{1234H} numeric syntax is not supported (use @code{0x1234}
23421 #pragma ADDRESS port3 0x103
23428 @subsection MeP Pragmas
23432 @item custom io_volatile (on|off)
23433 @cindex pragma, custom io_volatile
23434 Overrides the command-line option @code{-mio-volatile} for the current
23435 file. Note that for compatibility with future GCC releases, this
23436 option should only be used once before any @code{io} variables in each
23439 @item GCC coprocessor available @var{registers}
23440 @cindex pragma, coprocessor available
23441 Specifies which coprocessor registers are available to the register
23442 allocator. @var{registers} may be a single register, register range
23443 separated by ellipses, or comma-separated list of those. Example:
23446 #pragma GCC coprocessor available $c0...$c10, $c28
23449 @item GCC coprocessor call_saved @var{registers}
23450 @cindex pragma, coprocessor call_saved
23451 Specifies which coprocessor registers are to be saved and restored by
23452 any function using them. @var{registers} may be a single register,
23453 register range separated by ellipses, or comma-separated list of
23457 #pragma GCC coprocessor call_saved $c4...$c6, $c31
23460 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
23461 @cindex pragma, coprocessor subclass
23462 Creates and defines a register class. These register classes can be
23463 used by inline @code{asm} constructs. @var{registers} may be a single
23464 register, register range separated by ellipses, or comma-separated
23465 list of those. Example:
23468 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
23470 asm ("cpfoo %0" : "=B" (x));
23473 @item GCC disinterrupt @var{name} , @var{name} @dots{}
23474 @cindex pragma, disinterrupt
23475 For the named functions, the compiler adds code to disable interrupts
23476 for the duration of those functions. If any functions so named
23477 are not encountered in the source, a warning is emitted that the pragma is
23478 not used. Examples:
23481 #pragma disinterrupt foo
23482 #pragma disinterrupt bar, grill
23483 int foo () @{ @dots{} @}
23486 @item GCC call @var{name} , @var{name} @dots{}
23487 @cindex pragma, call
23488 For the named functions, the compiler always uses a register-indirect
23489 call model when calling the named functions. Examples:
23499 @subsection PRU Pragmas
23503 @item ctable_entry @var{index} @var{constant_address}
23504 @cindex pragma, ctable_entry
23505 Specifies that the PRU CTABLE entry given by @var{index} has the value
23506 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
23507 when the load/store address is known and can be addressed with some CTABLE
23508 entry. For example:
23511 /* will compile to "sbco Rx, 2, 0x10, 4" */
23512 #pragma ctable_entry 2 0x4802a000
23513 *(unsigned int *)0x4802a010 = val;
23518 @node RS/6000 and PowerPC Pragmas
23519 @subsection RS/6000 and PowerPC Pragmas
23521 The RS/6000 and PowerPC targets define one pragma for controlling
23522 whether or not the @code{longcall} attribute is added to function
23523 declarations by default. This pragma overrides the @option{-mlongcall}
23524 option, but not the @code{longcall} and @code{shortcall} attributes.
23525 @xref{RS/6000 and PowerPC Options}, for more information about when long
23526 calls are and are not necessary.
23530 @cindex pragma, longcall
23531 Apply the @code{longcall} attribute to all subsequent function
23535 Do not apply the @code{longcall} attribute to subsequent function
23539 @c Describe h8300 pragmas here.
23540 @c Describe sh pragmas here.
23541 @c Describe v850 pragmas here.
23543 @node S/390 Pragmas
23544 @subsection S/390 Pragmas
23546 The pragmas defined by the S/390 target correspond to the S/390
23547 target function attributes and some the additional options:
23554 Note that options of the pragma, unlike options of the target
23555 attribute, do change the value of preprocessor macros like
23556 @code{__VEC__}. They can be specified as below:
23559 #pragma GCC target("string[,string]...")
23560 #pragma GCC target("string"[,"string"]...)
23563 @node Darwin Pragmas
23564 @subsection Darwin Pragmas
23566 The following pragmas are available for all architectures running the
23567 Darwin operating system. These are useful for compatibility with other
23571 @item mark @var{tokens}@dots{}
23572 @cindex pragma, mark
23573 This pragma is accepted, but has no effect.
23575 @item options align=@var{alignment}
23576 @cindex pragma, options align
23577 This pragma sets the alignment of fields in structures. The values of
23578 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
23579 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
23580 properly; to restore the previous setting, use @code{reset} for the
23583 @item segment @var{tokens}@dots{}
23584 @cindex pragma, segment
23585 This pragma is accepted, but has no effect.
23587 @item unused (@var{var} [, @var{var}]@dots{})
23588 @cindex pragma, unused
23589 This pragma declares variables to be possibly unused. GCC does not
23590 produce warnings for the listed variables. The effect is similar to
23591 that of the @code{unused} attribute, except that this pragma may appear
23592 anywhere within the variables' scopes.
23595 @node Solaris Pragmas
23596 @subsection Solaris Pragmas
23598 The Solaris target supports @code{#pragma redefine_extname}
23599 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
23600 @code{#pragma} directives for compatibility with the system compiler.
23603 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
23604 @cindex pragma, align
23606 Increase the minimum alignment of each @var{variable} to @var{alignment}.
23607 This is the same as GCC's @code{aligned} attribute @pxref{Variable
23608 Attributes}). Macro expansion occurs on the arguments to this pragma
23609 when compiling C and Objective-C@. It does not currently occur when
23610 compiling C++, but this is a bug which may be fixed in a future
23613 @item fini (@var{function} [, @var{function}]...)
23614 @cindex pragma, fini
23616 This pragma causes each listed @var{function} to be called after
23617 main, or during shared module unloading, by adding a call to the
23618 @code{.fini} section.
23620 @item init (@var{function} [, @var{function}]...)
23621 @cindex pragma, init
23623 This pragma causes each listed @var{function} to be called during
23624 initialization (before @code{main}) or during shared module loading, by
23625 adding a call to the @code{.init} section.
23629 @node Symbol-Renaming Pragmas
23630 @subsection Symbol-Renaming Pragmas
23632 GCC supports a @code{#pragma} directive that changes the name used in
23633 assembly for a given declaration. While this pragma is supported on all
23634 platforms, it is intended primarily to provide compatibility with the
23635 Solaris system headers. This effect can also be achieved using the asm
23636 labels extension (@pxref{Asm Labels}).
23639 @item redefine_extname @var{oldname} @var{newname}
23640 @cindex pragma, redefine_extname
23642 This pragma gives the C function @var{oldname} the assembly symbol
23643 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
23644 is defined if this pragma is available (currently on all platforms).
23647 This pragma and the @code{asm} labels extension interact in a complicated
23648 manner. Here are some corner cases you may want to be aware of:
23651 @item This pragma silently applies only to declarations with external
23652 linkage. The @code{asm} label feature does not have this restriction.
23654 @item In C++, this pragma silently applies only to declarations with
23655 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
23657 @item If either of the ways of changing the assembly name of a
23658 declaration are applied to a declaration whose assembly name has
23659 already been determined (either by a previous use of one of these
23660 features, or because the compiler needed the assembly name in order to
23661 generate code), and the new name is different, a warning issues and
23662 the name does not change.
23664 @item The @var{oldname} used by @code{#pragma redefine_extname} is
23665 always the C-language name.
23668 @node Structure-Layout Pragmas
23669 @subsection Structure-Layout Pragmas
23671 For compatibility with Microsoft Windows compilers, GCC supports a
23672 set of @code{#pragma} directives that change the maximum alignment of
23673 members of structures (other than zero-width bit-fields), unions, and
23674 classes subsequently defined. The @var{n} value below always is required
23675 to be a small power of two and specifies the new alignment in bytes.
23678 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
23679 @item @code{#pragma pack()} sets the alignment to the one that was in
23680 effect when compilation started (see also command-line option
23681 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
23682 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
23683 setting on an internal stack and then optionally sets the new alignment.
23684 @item @code{#pragma pack(pop)} restores the alignment setting to the one
23685 saved at the top of the internal stack (and removes that stack entry).
23686 Note that @code{#pragma pack([@var{n}])} does not influence this internal
23687 stack; thus it is possible to have @code{#pragma pack(push)} followed by
23688 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
23689 @code{#pragma pack(pop)}.
23692 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
23693 directive which lays out structures and unions subsequently defined as the
23694 documented @code{__attribute__ ((ms_struct))}.
23697 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
23698 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
23699 @item @code{#pragma ms_struct reset} goes back to the default layout.
23702 Most targets also support the @code{#pragma scalar_storage_order} directive
23703 which lays out structures and unions subsequently defined as the documented
23704 @code{__attribute__ ((scalar_storage_order))}.
23707 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
23708 of the scalar fields to big-endian.
23709 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
23710 of the scalar fields to little-endian.
23711 @item @code{#pragma scalar_storage_order default} goes back to the endianness
23712 that was in effect when compilation started (see also command-line option
23713 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
23717 @subsection Weak Pragmas
23719 For compatibility with SVR4, GCC supports a set of @code{#pragma}
23720 directives for declaring symbols to be weak, and defining weak
23724 @item #pragma weak @var{symbol}
23725 @cindex pragma, weak
23726 This pragma declares @var{symbol} to be weak, as if the declaration
23727 had the attribute of the same name. The pragma may appear before
23728 or after the declaration of @var{symbol}. It is not an error for
23729 @var{symbol} to never be defined at all.
23731 @item #pragma weak @var{symbol1} = @var{symbol2}
23732 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
23733 It is an error if @var{symbol2} is not defined in the current
23737 @node Diagnostic Pragmas
23738 @subsection Diagnostic Pragmas
23740 GCC allows the user to selectively enable or disable certain types of
23741 diagnostics, and change the kind of the diagnostic. For example, a
23742 project's policy might require that all sources compile with
23743 @option{-Werror} but certain files might have exceptions allowing
23744 specific types of warnings. Or, a project might selectively enable
23745 diagnostics and treat them as errors depending on which preprocessor
23746 macros are defined.
23749 @item #pragma GCC diagnostic @var{kind} @var{option}
23750 @cindex pragma, diagnostic
23752 Modifies the disposition of a diagnostic. Note that not all
23753 diagnostics are modifiable; at the moment only warnings (normally
23754 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
23755 Use @option{-fdiagnostics-show-option} to determine which diagnostics
23756 are controllable and which option controls them.
23758 @var{kind} is @samp{error} to treat this diagnostic as an error,
23759 @samp{warning} to treat it like a warning (even if @option{-Werror} is
23760 in effect), or @samp{ignored} if the diagnostic is to be ignored.
23761 @var{option} is a double quoted string that matches the command-line
23765 #pragma GCC diagnostic warning "-Wformat"
23766 #pragma GCC diagnostic error "-Wformat"
23767 #pragma GCC diagnostic ignored "-Wformat"
23770 Note that these pragmas override any command-line options. GCC keeps
23771 track of the location of each pragma, and issues diagnostics according
23772 to the state as of that point in the source file. Thus, pragmas occurring
23773 after a line do not affect diagnostics caused by that line.
23775 @item #pragma GCC diagnostic push
23776 @itemx #pragma GCC diagnostic pop
23778 Causes GCC to remember the state of the diagnostics as of each
23779 @code{push}, and restore to that point at each @code{pop}. If a
23780 @code{pop} has no matching @code{push}, the command-line options are
23784 #pragma GCC diagnostic error "-Wuninitialized"
23785 foo(a); /* error is given for this one */
23786 #pragma GCC diagnostic push
23787 #pragma GCC diagnostic ignored "-Wuninitialized"
23788 foo(b); /* no diagnostic for this one */
23789 #pragma GCC diagnostic pop
23790 foo(c); /* error is given for this one */
23791 #pragma GCC diagnostic pop
23792 foo(d); /* depends on command-line options */
23795 @item #pragma GCC diagnostic ignored_attributes
23797 Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress
23798 warnings about unknown scoped attributes (in C++11 and C2X). For example,
23799 @code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables
23800 warning about the following declaration:
23803 [[vendor::attr]] void f();
23806 whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents
23807 warning about both of these declarations:
23810 [[vendor::safe]] void f();
23811 [[vendor::unsafe]] void f2();
23816 GCC also offers a simple mechanism for printing messages during
23820 @item #pragma message @var{string}
23821 @cindex pragma, diagnostic
23823 Prints @var{string} as a compiler message on compilation. The message
23824 is informational only, and is neither a compilation warning nor an
23825 error. Newlines can be included in the string by using the @samp{\n}
23829 #pragma message "Compiling " __FILE__ "..."
23832 @var{string} may be parenthesized, and is printed with location
23833 information. For example,
23836 #define DO_PRAGMA(x) _Pragma (#x)
23837 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
23839 TODO(Remember to fix this)
23843 prints @samp{/tmp/file.c:4: note: #pragma message:
23844 TODO - Remember to fix this}.
23846 @item #pragma GCC error @var{message}
23847 @cindex pragma, diagnostic
23848 Generates an error message. This pragma @emph{is} considered to
23849 indicate an error in the compilation, and it will be treated as such.
23851 Newlines can be included in the string by using the @samp{\n}
23852 escape sequence. They will be displayed as newlines even if the
23853 @option{-fmessage-length} option is set to zero.
23855 The error is only generated if the pragma is present in the code after
23856 pre-processing has been completed. It does not matter however if the
23857 code containing the pragma is unreachable:
23861 #pragma GCC error "this error is not seen"
23866 #pragma GCC error "this error is seen"
23870 @item #pragma GCC warning @var{message}
23871 @cindex pragma, diagnostic
23872 This is just like @samp{pragma GCC error} except that a warning
23873 message is issued instead of an error message. Unless
23874 @option{-Werror} is in effect, in which case this pragma will generate
23879 @node Visibility Pragmas
23880 @subsection Visibility Pragmas
23883 @item #pragma GCC visibility push(@var{visibility})
23884 @itemx #pragma GCC visibility pop
23885 @cindex pragma, visibility
23887 This pragma allows the user to set the visibility for multiple
23888 declarations without having to give each a visibility attribute
23889 (@pxref{Function Attributes}).
23891 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
23892 declarations. Class members and template specializations are not
23893 affected; if you want to override the visibility for a particular
23894 member or instantiation, you must use an attribute.
23899 @node Push/Pop Macro Pragmas
23900 @subsection Push/Pop Macro Pragmas
23902 For compatibility with Microsoft Windows compilers, GCC supports
23903 @samp{#pragma push_macro(@var{"macro_name"})}
23904 and @samp{#pragma pop_macro(@var{"macro_name"})}.
23907 @item #pragma push_macro(@var{"macro_name"})
23908 @cindex pragma, push_macro
23909 This pragma saves the value of the macro named as @var{macro_name} to
23910 the top of the stack for this macro.
23912 @item #pragma pop_macro(@var{"macro_name"})
23913 @cindex pragma, pop_macro
23914 This pragma sets the value of the macro named as @var{macro_name} to
23915 the value on top of the stack for this macro. If the stack for
23916 @var{macro_name} is empty, the value of the macro remains unchanged.
23923 #pragma push_macro("X")
23926 #pragma pop_macro("X")
23931 In this example, the definition of X as 1 is saved by @code{#pragma
23932 push_macro} and restored by @code{#pragma pop_macro}.
23934 @node Function Specific Option Pragmas
23935 @subsection Function Specific Option Pragmas
23938 @item #pragma GCC target (@var{string}, @dots{})
23939 @cindex pragma GCC target
23941 This pragma allows you to set target-specific options for functions
23942 defined later in the source file. One or more strings can be
23943 specified. Each function that is defined after this point is treated
23944 as if it had been declared with one @code{target(}@var{string}@code{)}
23945 attribute for each @var{string} argument. The parentheses around
23946 the strings in the pragma are optional. @xref{Function Attributes},
23947 for more information about the @code{target} attribute and the attribute
23950 The @code{#pragma GCC target} pragma is presently implemented for
23951 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
23953 @item #pragma GCC optimize (@var{string}, @dots{})
23954 @cindex pragma GCC optimize
23956 This pragma allows you to set global optimization options for functions
23957 defined later in the source file. One or more strings can be
23958 specified. Each function that is defined after this point is treated
23959 as if it had been declared with one @code{optimize(}@var{string}@code{)}
23960 attribute for each @var{string} argument. The parentheses around
23961 the strings in the pragma are optional. @xref{Function Attributes},
23962 for more information about the @code{optimize} attribute and the attribute
23965 @item #pragma GCC push_options
23966 @itemx #pragma GCC pop_options
23967 @cindex pragma GCC push_options
23968 @cindex pragma GCC pop_options
23970 These pragmas maintain a stack of the current target and optimization
23971 options. It is intended for include files where you temporarily want
23972 to switch to using a different @samp{#pragma GCC target} or
23973 @samp{#pragma GCC optimize} and then to pop back to the previous
23976 @item #pragma GCC reset_options
23977 @cindex pragma GCC reset_options
23979 This pragma clears the current @code{#pragma GCC target} and
23980 @code{#pragma GCC optimize} to use the default switches as specified
23981 on the command line.
23985 @node Loop-Specific Pragmas
23986 @subsection Loop-Specific Pragmas
23989 @item #pragma GCC ivdep
23990 @cindex pragma GCC ivdep
23992 With this pragma, the programmer asserts that there are no loop-carried
23993 dependencies which would prevent consecutive iterations of
23994 the following loop from executing concurrently with SIMD
23995 (single instruction multiple data) instructions.
23997 For example, the compiler can only unconditionally vectorize the following
23998 loop with the pragma:
24001 void foo (int n, int *a, int *b, int *c)
24005 for (i = 0; i < n; ++i)
24006 a[i] = b[i] + c[i];
24011 In this example, using the @code{restrict} qualifier had the same
24012 effect. In the following example, that would not be possible. Assume
24013 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
24014 that it can unconditionally vectorize the following loop:
24017 void ignore_vec_dep (int *a, int k, int c, int m)
24020 for (int i = 0; i < m; i++)
24021 a[i] = a[i + k] * c;
24025 @item #pragma GCC unroll @var{n}
24026 @cindex pragma GCC unroll @var{n}
24028 You can use this pragma to control how many times a loop should be unrolled.
24029 It must be placed immediately before a @code{for}, @code{while} or @code{do}
24030 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
24031 @var{n} is an integer constant expression specifying the unrolling factor.
24032 The values of @math{0} and @math{1} block any unrolling of the loop.
24036 @node Unnamed Fields
24037 @section Unnamed Structure and Union Fields
24038 @cindex @code{struct}
24039 @cindex @code{union}
24041 As permitted by ISO C11 and for compatibility with other compilers,
24042 GCC allows you to define
24043 a structure or union that contains, as fields, structures and unions
24044 without names. For example:
24058 In this example, you are able to access members of the unnamed
24059 union with code like @samp{foo.b}. Note that only unnamed structs and
24060 unions are allowed, you may not have, for example, an unnamed
24063 You must never create such structures that cause ambiguous field definitions.
24064 For example, in this structure:
24076 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
24077 The compiler gives errors for such constructs.
24079 @opindex fms-extensions
24080 Unless @option{-fms-extensions} is used, the unnamed field must be a
24081 structure or union definition without a tag (for example, @samp{struct
24082 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
24083 also be a definition with a tag such as @samp{struct foo @{ int a;
24084 @};}, a reference to a previously defined structure or union such as
24085 @samp{struct foo;}, or a reference to a @code{typedef} name for a
24086 previously defined structure or union type.
24088 @opindex fplan9-extensions
24089 The option @option{-fplan9-extensions} enables
24090 @option{-fms-extensions} as well as two other extensions. First, a
24091 pointer to a structure is automatically converted to a pointer to an
24092 anonymous field for assignments and function calls. For example:
24095 struct s1 @{ int a; @};
24096 struct s2 @{ struct s1; @};
24097 extern void f1 (struct s1 *);
24098 void f2 (struct s2 *p) @{ f1 (p); @}
24102 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
24103 converted into a pointer to the anonymous field.
24105 Second, when the type of an anonymous field is a @code{typedef} for a
24106 @code{struct} or @code{union}, code may refer to the field using the
24107 name of the @code{typedef}.
24110 typedef struct @{ int a; @} s1;
24111 struct s2 @{ s1; @};
24112 s1 f1 (struct s2 *p) @{ return p->s1; @}
24115 These usages are only permitted when they are not ambiguous.
24118 @section Thread-Local Storage
24119 @cindex Thread-Local Storage
24120 @cindex @acronym{TLS}
24121 @cindex @code{__thread}
24123 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
24124 are allocated such that there is one instance of the variable per extant
24125 thread. The runtime model GCC uses to implement this originates
24126 in the IA-64 processor-specific ABI, but has since been migrated
24127 to other processors as well. It requires significant support from
24128 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
24129 system libraries (@file{libc.so} and @file{libpthread.so}), so it
24130 is not available everywhere.
24132 At the user level, the extension is visible with a new storage
24133 class keyword: @code{__thread}. For example:
24137 extern __thread struct state s;
24138 static __thread char *p;
24141 The @code{__thread} specifier may be used alone, with the @code{extern}
24142 or @code{static} specifiers, but with no other storage class specifier.
24143 When used with @code{extern} or @code{static}, @code{__thread} must appear
24144 immediately after the other storage class specifier.
24146 The @code{__thread} specifier may be applied to any global, file-scoped
24147 static, function-scoped static, or static data member of a class. It may
24148 not be applied to block-scoped automatic or non-static data member.
24150 When the address-of operator is applied to a thread-local variable, it is
24151 evaluated at run time and returns the address of the current thread's
24152 instance of that variable. An address so obtained may be used by any
24153 thread. When a thread terminates, any pointers to thread-local variables
24154 in that thread become invalid.
24156 No static initialization may refer to the address of a thread-local variable.
24158 In C++, if an initializer is present for a thread-local variable, it must
24159 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
24162 See @uref{https://www.akkadia.org/drepper/tls.pdf,
24163 ELF Handling For Thread-Local Storage} for a detailed explanation of
24164 the four thread-local storage addressing models, and how the runtime
24165 is expected to function.
24168 * C99 Thread-Local Edits::
24169 * C++98 Thread-Local Edits::
24172 @node C99 Thread-Local Edits
24173 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
24175 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
24176 that document the exact semantics of the language extension.
24180 @cite{5.1.2 Execution environments}
24182 Add new text after paragraph 1
24185 Within either execution environment, a @dfn{thread} is a flow of
24186 control within a program. It is implementation defined whether
24187 or not there may be more than one thread associated with a program.
24188 It is implementation defined how threads beyond the first are
24189 created, the name and type of the function called at thread
24190 startup, and how threads may be terminated. However, objects
24191 with thread storage duration shall be initialized before thread
24196 @cite{6.2.4 Storage durations of objects}
24198 Add new text before paragraph 3
24201 An object whose identifier is declared with the storage-class
24202 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
24203 Its lifetime is the entire execution of the thread, and its
24204 stored value is initialized only once, prior to thread startup.
24208 @cite{6.4.1 Keywords}
24210 Add @code{__thread}.
24213 @cite{6.7.1 Storage-class specifiers}
24215 Add @code{__thread} to the list of storage class specifiers in
24218 Change paragraph 2 to
24221 With the exception of @code{__thread}, at most one storage-class
24222 specifier may be given [@dots{}]. The @code{__thread} specifier may
24223 be used alone, or immediately following @code{extern} or
24227 Add new text after paragraph 6
24230 The declaration of an identifier for a variable that has
24231 block scope that specifies @code{__thread} shall also
24232 specify either @code{extern} or @code{static}.
24234 The @code{__thread} specifier shall be used only with
24239 @node C++98 Thread-Local Edits
24240 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
24242 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
24243 that document the exact semantics of the language extension.
24247 @b{[intro.execution]}
24249 New text after paragraph 4
24252 A @dfn{thread} is a flow of control within the abstract machine.
24253 It is implementation defined whether or not there may be more than
24257 New text after paragraph 7
24260 It is unspecified whether additional action must be taken to
24261 ensure when and whether side effects are visible to other threads.
24267 Add @code{__thread}.
24270 @b{[basic.start.main]}
24272 Add after paragraph 5
24275 The thread that begins execution at the @code{main} function is called
24276 the @dfn{main thread}. It is implementation defined how functions
24277 beginning threads other than the main thread are designated or typed.
24278 A function so designated, as well as the @code{main} function, is called
24279 a @dfn{thread startup function}. It is implementation defined what
24280 happens if a thread startup function returns. It is implementation
24281 defined what happens to other threads when any thread calls @code{exit}.
24285 @b{[basic.start.init]}
24287 Add after paragraph 4
24290 The storage for an object of thread storage duration shall be
24291 statically initialized before the first statement of the thread startup
24292 function. An object of thread storage duration shall not require
24293 dynamic initialization.
24297 @b{[basic.start.term]}
24299 Add after paragraph 3
24302 The type of an object with thread storage duration shall not have a
24303 non-trivial destructor, nor shall it be an array type whose elements
24304 (directly or indirectly) have non-trivial destructors.
24310 Add ``thread storage duration'' to the list in paragraph 1.
24315 Thread, static, and automatic storage durations are associated with
24316 objects introduced by declarations [@dots{}].
24319 Add @code{__thread} to the list of specifiers in paragraph 3.
24322 @b{[basic.stc.thread]}
24324 New section before @b{[basic.stc.static]}
24327 The keyword @code{__thread} applied to a non-local object gives the
24328 object thread storage duration.
24330 A local variable or class data member declared both @code{static}
24331 and @code{__thread} gives the variable or member thread storage
24336 @b{[basic.stc.static]}
24341 All objects that have neither thread storage duration, dynamic
24342 storage duration nor are local [@dots{}].
24348 Add @code{__thread} to the list in paragraph 1.
24353 With the exception of @code{__thread}, at most one
24354 @var{storage-class-specifier} shall appear in a given
24355 @var{decl-specifier-seq}. The @code{__thread} specifier may
24356 be used alone, or immediately following the @code{extern} or
24357 @code{static} specifiers. [@dots{}]
24360 Add after paragraph 5
24363 The @code{__thread} specifier can be applied only to the names of objects
24364 and to anonymous unions.
24370 Add after paragraph 6
24373 Non-@code{static} members shall not be @code{__thread}.
24377 @node Binary constants
24378 @section Binary Constants using the @samp{0b} Prefix
24379 @cindex Binary constants using the @samp{0b} prefix
24381 Integer constants can be written as binary constants, consisting of a
24382 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
24383 @samp{0B}. This is particularly useful in environments that operate a
24384 lot on the bit level (like microcontrollers).
24386 The following statements are identical:
24395 The type of these constants follows the same rules as for octal or
24396 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
24399 @node C++ Extensions
24400 @chapter Extensions to the C++ Language
24401 @cindex extensions, C++ language
24402 @cindex C++ language extensions
24404 The GNU compiler provides these extensions to the C++ language (and you
24405 can also use most of the C language extensions in your C++ programs). If you
24406 want to write code that checks whether these features are available, you can
24407 test for the GNU compiler the same way as for C programs: check for a
24408 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
24409 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
24410 Predefined Macros,cpp,The GNU C Preprocessor}).
24413 * C++ Volatiles:: What constitutes an access to a volatile object.
24414 * Restricted Pointers:: C99 restricted pointers and references.
24415 * Vague Linkage:: Where G++ puts inlines, vtables and such.
24416 * C++ Interface:: You can use a single C++ header file for both
24417 declarations and definitions.
24418 * Template Instantiation:: Methods for ensuring that exactly one copy of
24419 each needed template instantiation is emitted.
24420 * Bound member functions:: You can extract a function pointer to the
24421 method denoted by a @samp{->*} or @samp{.*} expression.
24422 * C++ Attributes:: Variable, function, and type attributes for C++ only.
24423 * Function Multiversioning:: Declaring multiple function versions.
24424 * Type Traits:: Compiler support for type traits.
24425 * C++ Concepts:: Improved support for generic programming.
24426 * Deprecated Features:: Things will disappear from G++.
24427 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
24430 @node C++ Volatiles
24431 @section When is a Volatile C++ Object Accessed?
24432 @cindex accessing volatiles
24433 @cindex volatile read
24434 @cindex volatile write
24435 @cindex volatile access
24437 The C++ standard differs from the C standard in its treatment of
24438 volatile objects. It fails to specify what constitutes a volatile
24439 access, except to say that C++ should behave in a similar manner to C
24440 with respect to volatiles, where possible. However, the different
24441 lvalueness of expressions between C and C++ complicate the behavior.
24442 G++ behaves the same as GCC for volatile access, @xref{C
24443 Extensions,,Volatiles}, for a description of GCC's behavior.
24445 The C and C++ language specifications differ when an object is
24446 accessed in a void context:
24449 volatile int *src = @var{somevalue};
24453 The C++ standard specifies that such expressions do not undergo lvalue
24454 to rvalue conversion, and that the type of the dereferenced object may
24455 be incomplete. The C++ standard does not specify explicitly that it
24456 is lvalue to rvalue conversion that is responsible for causing an
24457 access. There is reason to believe that it is, because otherwise
24458 certain simple expressions become undefined. However, because it
24459 would surprise most programmers, G++ treats dereferencing a pointer to
24460 volatile object of complete type as GCC would do for an equivalent
24461 type in C@. When the object has incomplete type, G++ issues a
24462 warning; if you wish to force an error, you must force a conversion to
24463 rvalue with, for instance, a static cast.
24465 When using a reference to volatile, G++ does not treat equivalent
24466 expressions as accesses to volatiles, but instead issues a warning that
24467 no volatile is accessed. The rationale for this is that otherwise it
24468 becomes difficult to determine where volatile access occur, and not
24469 possible to ignore the return value from functions returning volatile
24470 references. Again, if you wish to force a read, cast the reference to
24473 G++ implements the same behavior as GCC does when assigning to a
24474 volatile object---there is no reread of the assigned-to object, the
24475 assigned rvalue is reused. Note that in C++ assignment expressions
24476 are lvalues, and if used as an lvalue, the volatile object is
24477 referred to. For instance, @var{vref} refers to @var{vobj}, as
24478 expected, in the following example:
24482 volatile int &vref = vobj = @var{something};
24485 @node Restricted Pointers
24486 @section Restricting Pointer Aliasing
24487 @cindex restricted pointers
24488 @cindex restricted references
24489 @cindex restricted this pointer
24491 As with the C front end, G++ understands the C99 feature of restricted pointers,
24492 specified with the @code{__restrict__}, or @code{__restrict} type
24493 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
24494 language flag, @code{restrict} is not a keyword in C++.
24496 In addition to allowing restricted pointers, you can specify restricted
24497 references, which indicate that the reference is not aliased in the local
24501 void fn (int *__restrict__ rptr, int &__restrict__ rref)
24508 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
24509 @var{rref} refers to a (different) unaliased integer.
24511 You may also specify whether a member function's @var{this} pointer is
24512 unaliased by using @code{__restrict__} as a member function qualifier.
24515 void T::fn () __restrict__
24522 Within the body of @code{T::fn}, @var{this} has the effective
24523 definition @code{T *__restrict__ const this}. Notice that the
24524 interpretation of a @code{__restrict__} member function qualifier is
24525 different to that of @code{const} or @code{volatile} qualifier, in that it
24526 is applied to the pointer rather than the object. This is consistent with
24527 other compilers that implement restricted pointers.
24529 As with all outermost parameter qualifiers, @code{__restrict__} is
24530 ignored in function definition matching. This means you only need to
24531 specify @code{__restrict__} in a function definition, rather than
24532 in a function prototype as well.
24534 @node Vague Linkage
24535 @section Vague Linkage
24536 @cindex vague linkage
24538 There are several constructs in C++ that require space in the object
24539 file but are not clearly tied to a single translation unit. We say that
24540 these constructs have ``vague linkage''. Typically such constructs are
24541 emitted wherever they are needed, though sometimes we can be more
24545 @item Inline Functions
24546 Inline functions are typically defined in a header file which can be
24547 included in many different compilations. Hopefully they can usually be
24548 inlined, but sometimes an out-of-line copy is necessary, if the address
24549 of the function is taken or if inlining fails. In general, we emit an
24550 out-of-line copy in all translation units where one is needed. As an
24551 exception, we only emit inline virtual functions with the vtable, since
24552 it always requires a copy.
24554 Local static variables and string constants used in an inline function
24555 are also considered to have vague linkage, since they must be shared
24556 between all inlined and out-of-line instances of the function.
24560 C++ virtual functions are implemented in most compilers using a lookup
24561 table, known as a vtable. The vtable contains pointers to the virtual
24562 functions provided by a class, and each object of the class contains a
24563 pointer to its vtable (or vtables, in some multiple-inheritance
24564 situations). If the class declares any non-inline, non-pure virtual
24565 functions, the first one is chosen as the ``key method'' for the class,
24566 and the vtable is only emitted in the translation unit where the key
24569 @emph{Note:} If the chosen key method is later defined as inline, the
24570 vtable is still emitted in every translation unit that defines it.
24571 Make sure that any inline virtuals are declared inline in the class
24572 body, even if they are not defined there.
24574 @item @code{type_info} objects
24575 @cindex @code{type_info}
24577 C++ requires information about types to be written out in order to
24578 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
24579 For polymorphic classes (classes with virtual functions), the @samp{type_info}
24580 object is written out along with the vtable so that @samp{dynamic_cast}
24581 can determine the dynamic type of a class object at run time. For all
24582 other types, we write out the @samp{type_info} object when it is used: when
24583 applying @samp{typeid} to an expression, throwing an object, or
24584 referring to a type in a catch clause or exception specification.
24586 @item Template Instantiations
24587 Most everything in this section also applies to template instantiations,
24588 but there are other options as well.
24589 @xref{Template Instantiation,,Where's the Template?}.
24593 When used with GNU ld version 2.8 or later on an ELF system such as
24594 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
24595 these constructs will be discarded at link time. This is known as
24598 On targets that don't support COMDAT, but do support weak symbols, GCC
24599 uses them. This way one copy overrides all the others, but
24600 the unused copies still take up space in the executable.
24602 For targets that do not support either COMDAT or weak symbols,
24603 most entities with vague linkage are emitted as local symbols to
24604 avoid duplicate definition errors from the linker. This does not happen
24605 for local statics in inlines, however, as having multiple copies
24606 almost certainly breaks things.
24608 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
24609 another way to control placement of these constructs.
24611 @node C++ Interface
24612 @section C++ Interface and Implementation Pragmas
24614 @cindex interface and implementation headers, C++
24615 @cindex C++ interface and implementation headers
24616 @cindex pragmas, interface and implementation
24618 @code{#pragma interface} and @code{#pragma implementation} provide the
24619 user with a way of explicitly directing the compiler to emit entities
24620 with vague linkage (and debugging information) in a particular
24623 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
24624 by COMDAT support and the ``key method'' heuristic
24625 mentioned in @ref{Vague Linkage}. Using them can actually cause your
24626 program to grow due to unnecessary out-of-line copies of inline
24630 @item #pragma interface
24631 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
24632 @kindex #pragma interface
24633 Use this directive in @emph{header files} that define object classes, to save
24634 space in most of the object files that use those classes. Normally,
24635 local copies of certain information (backup copies of inline member
24636 functions, debugging information, and the internal tables that implement
24637 virtual functions) must be kept in each object file that includes class
24638 definitions. You can use this pragma to avoid such duplication. When a
24639 header file containing @samp{#pragma interface} is included in a
24640 compilation, this auxiliary information is not generated (unless
24641 the main input source file itself uses @samp{#pragma implementation}).
24642 Instead, the object files contain references to be resolved at link
24645 The second form of this directive is useful for the case where you have
24646 multiple headers with the same name in different directories. If you
24647 use this form, you must specify the same string to @samp{#pragma
24650 @item #pragma implementation
24651 @itemx #pragma implementation "@var{objects}.h"
24652 @kindex #pragma implementation
24653 Use this pragma in a @emph{main input file}, when you want full output from
24654 included header files to be generated (and made globally visible). The
24655 included header file, in turn, should use @samp{#pragma interface}.
24656 Backup copies of inline member functions, debugging information, and the
24657 internal tables used to implement virtual functions are all generated in
24658 implementation files.
24660 @cindex implied @code{#pragma implementation}
24661 @cindex @code{#pragma implementation}, implied
24662 @cindex naming convention, implementation headers
24663 If you use @samp{#pragma implementation} with no argument, it applies to
24664 an include file with the same basename@footnote{A file's @dfn{basename}
24665 is the name stripped of all leading path information and of trailing
24666 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
24667 file. For example, in @file{allclass.cc}, giving just
24668 @samp{#pragma implementation}
24669 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
24671 Use the string argument if you want a single implementation file to
24672 include code from multiple header files. (You must also use
24673 @samp{#include} to include the header file; @samp{#pragma
24674 implementation} only specifies how to use the file---it doesn't actually
24677 There is no way to split up the contents of a single header file into
24678 multiple implementation files.
24681 @cindex inlining and C++ pragmas
24682 @cindex C++ pragmas, effect on inlining
24683 @cindex pragmas in C++, effect on inlining
24684 @samp{#pragma implementation} and @samp{#pragma interface} also have an
24685 effect on function inlining.
24687 If you define a class in a header file marked with @samp{#pragma
24688 interface}, the effect on an inline function defined in that class is
24689 similar to an explicit @code{extern} declaration---the compiler emits
24690 no code at all to define an independent version of the function. Its
24691 definition is used only for inlining with its callers.
24693 @opindex fno-implement-inlines
24694 Conversely, when you include the same header file in a main source file
24695 that declares it as @samp{#pragma implementation}, the compiler emits
24696 code for the function itself; this defines a version of the function
24697 that can be found via pointers (or by callers compiled without
24698 inlining). If all calls to the function can be inlined, you can avoid
24699 emitting the function by compiling with @option{-fno-implement-inlines}.
24700 If any calls are not inlined, you will get linker errors.
24702 @node Template Instantiation
24703 @section Where's the Template?
24704 @cindex template instantiation
24706 C++ templates were the first language feature to require more
24707 intelligence from the environment than was traditionally found on a UNIX
24708 system. Somehow the compiler and linker have to make sure that each
24709 template instance occurs exactly once in the executable if it is needed,
24710 and not at all otherwise. There are two basic approaches to this
24711 problem, which are referred to as the Borland model and the Cfront model.
24714 @item Borland model
24715 Borland C++ solved the template instantiation problem by adding the code
24716 equivalent of common blocks to their linker; the compiler emits template
24717 instances in each translation unit that uses them, and the linker
24718 collapses them together. The advantage of this model is that the linker
24719 only has to consider the object files themselves; there is no external
24720 complexity to worry about. The disadvantage is that compilation time
24721 is increased because the template code is being compiled repeatedly.
24722 Code written for this model tends to include definitions of all
24723 templates in the header file, since they must be seen to be
24727 The AT&T C++ translator, Cfront, solved the template instantiation
24728 problem by creating the notion of a template repository, an
24729 automatically maintained place where template instances are stored. A
24730 more modern version of the repository works as follows: As individual
24731 object files are built, the compiler places any template definitions and
24732 instantiations encountered in the repository. At link time, the link
24733 wrapper adds in the objects in the repository and compiles any needed
24734 instances that were not previously emitted. The advantages of this
24735 model are more optimal compilation speed and the ability to use the
24736 system linker; to implement the Borland model a compiler vendor also
24737 needs to replace the linker. The disadvantages are vastly increased
24738 complexity, and thus potential for error; for some code this can be
24739 just as transparent, but in practice it can been very difficult to build
24740 multiple programs in one directory and one program in multiple
24741 directories. Code written for this model tends to separate definitions
24742 of non-inline member templates into a separate file, which should be
24743 compiled separately.
24746 G++ implements the Borland model on targets where the linker supports it,
24747 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
24748 Otherwise G++ implements neither automatic model.
24750 You have the following options for dealing with template instantiations:
24754 Do nothing. Code written for the Borland model works fine, but
24755 each translation unit contains instances of each of the templates it
24756 uses. The duplicate instances will be discarded by the linker, but in
24757 a large program, this can lead to an unacceptable amount of code
24758 duplication in object files or shared libraries.
24760 Duplicate instances of a template can be avoided by defining an explicit
24761 instantiation in one object file, and preventing the compiler from doing
24762 implicit instantiations in any other object files by using an explicit
24763 instantiation declaration, using the @code{extern template} syntax:
24766 extern template int max (int, int);
24769 This syntax is defined in the C++ 2011 standard, but has been supported by
24770 G++ and other compilers since well before 2011.
24772 Explicit instantiations can be used for the largest or most frequently
24773 duplicated instances, without having to know exactly which other instances
24774 are used in the rest of the program. You can scatter the explicit
24775 instantiations throughout your program, perhaps putting them in the
24776 translation units where the instances are used or the translation units
24777 that define the templates themselves; you can put all of the explicit
24778 instantiations you need into one big file; or you can create small files
24785 template class Foo<int>;
24786 template ostream& operator <<
24787 (ostream&, const Foo<int>&);
24791 for each of the instances you need, and create a template instantiation
24792 library from those.
24794 This is the simplest option, but also offers flexibility and
24795 fine-grained control when necessary. It is also the most portable
24796 alternative and programs using this approach will work with most modern
24800 @opindex fno-implicit-templates
24801 Compile your code with @option{-fno-implicit-templates} to disable the
24802 implicit generation of template instances, and explicitly instantiate
24803 all the ones you use. This approach requires more knowledge of exactly
24804 which instances you need than do the others, but it's less
24805 mysterious and allows greater control if you want to ensure that only
24806 the intended instances are used.
24808 If you are using Cfront-model code, you can probably get away with not
24809 using @option{-fno-implicit-templates} when compiling files that don't
24810 @samp{#include} the member template definitions.
24812 If you use one big file to do the instantiations, you may want to
24813 compile it without @option{-fno-implicit-templates} so you get all of the
24814 instances required by your explicit instantiations (but not by any
24815 other files) without having to specify them as well.
24817 In addition to forward declaration of explicit instantiations
24818 (with @code{extern}), G++ has extended the template instantiation
24819 syntax to support instantiation of the compiler support data for a
24820 template class (i.e.@: the vtable) without instantiating any of its
24821 members (with @code{inline}), and instantiation of only the static data
24822 members of a template class, without the support data or member
24823 functions (with @code{static}):
24826 inline template class Foo<int>;
24827 static template class Foo<int>;
24831 @node Bound member functions
24832 @section Extracting the Function Pointer from a Bound Pointer to Member Function
24834 @cindex pointer to member function
24835 @cindex bound pointer to member function
24837 In C++, pointer to member functions (PMFs) are implemented using a wide
24838 pointer of sorts to handle all the possible call mechanisms; the PMF
24839 needs to store information about how to adjust the @samp{this} pointer,
24840 and if the function pointed to is virtual, where to find the vtable, and
24841 where in the vtable to look for the member function. If you are using
24842 PMFs in an inner loop, you should really reconsider that decision. If
24843 that is not an option, you can extract the pointer to the function that
24844 would be called for a given object/PMF pair and call it directly inside
24845 the inner loop, to save a bit of time.
24847 Note that you still pay the penalty for the call through a
24848 function pointer; on most modern architectures, such a call defeats the
24849 branch prediction features of the CPU@. This is also true of normal
24850 virtual function calls.
24852 The syntax for this extension is
24856 extern int (A::*fp)();
24857 typedef int (*fptr)(A *);
24859 fptr p = (fptr)(a.*fp);
24862 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
24863 no object is needed to obtain the address of the function. They can be
24864 converted to function pointers directly:
24867 fptr p1 = (fptr)(&A::foo);
24870 @opindex Wno-pmf-conversions
24871 You must specify @option{-Wno-pmf-conversions} to use this extension.
24873 @node C++ Attributes
24874 @section C++-Specific Variable, Function, and Type Attributes
24876 Some attributes only make sense for C++ programs.
24879 @item abi_tag ("@var{tag}", ...)
24880 @cindex @code{abi_tag} function attribute
24881 @cindex @code{abi_tag} variable attribute
24882 @cindex @code{abi_tag} type attribute
24883 The @code{abi_tag} attribute can be applied to a function, variable, or class
24884 declaration. It modifies the mangled name of the entity to
24885 incorporate the tag name, in order to distinguish the function or
24886 class from an earlier version with a different ABI; perhaps the class
24887 has changed size, or the function has a different return type that is
24888 not encoded in the mangled name.
24890 The attribute can also be applied to an inline namespace, but does not
24891 affect the mangled name of the namespace; in this case it is only used
24892 for @option{-Wabi-tag} warnings and automatic tagging of functions and
24893 variables. Tagging inline namespaces is generally preferable to
24894 tagging individual declarations, but the latter is sometimes
24895 necessary, such as when only certain members of a class need to be
24898 The argument can be a list of strings of arbitrary length. The
24899 strings are sorted on output, so the order of the list is
24902 A redeclaration of an entity must not add new ABI tags,
24903 since doing so would change the mangled name.
24905 The ABI tags apply to a name, so all instantiations and
24906 specializations of a template have the same tags. The attribute will
24907 be ignored if applied to an explicit specialization or instantiation.
24909 The @option{-Wabi-tag} flag enables a warning about a class which does
24910 not have all the ABI tags used by its subobjects and virtual functions; for users with code
24911 that needs to coexist with an earlier ABI, using this option can help
24912 to find all affected types that need to be tagged.
24914 When a type involving an ABI tag is used as the type of a variable or
24915 return type of a function where that tag is not already present in the
24916 signature of the function, the tag is automatically applied to the
24917 variable or function. @option{-Wabi-tag} also warns about this
24918 situation; this warning can be avoided by explicitly tagging the
24919 variable or function or moving it into a tagged inline namespace.
24921 @item init_priority (@var{priority})
24922 @cindex @code{init_priority} variable attribute
24924 In Standard C++, objects defined at namespace scope are guaranteed to be
24925 initialized in an order in strict accordance with that of their definitions
24926 @emph{in a given translation unit}. No guarantee is made for initializations
24927 across translation units. However, GNU C++ allows users to control the
24928 order of initialization of objects defined at namespace scope with the
24929 @code{init_priority} attribute by specifying a relative @var{priority},
24930 a constant integral expression currently bounded between 101 and 65535
24931 inclusive. Lower numbers indicate a higher priority.
24933 In the following example, @code{A} would normally be created before
24934 @code{B}, but the @code{init_priority} attribute reverses that order:
24937 Some_Class A __attribute__ ((init_priority (2000)));
24938 Some_Class B __attribute__ ((init_priority (543)));
24942 Note that the particular values of @var{priority} do not matter; only their
24946 @cindex @code{warn_unused} type attribute
24948 For C++ types with non-trivial constructors and/or destructors it is
24949 impossible for the compiler to determine whether a variable of this
24950 type is truly unused if it is not referenced. This type attribute
24951 informs the compiler that variables of this type should be warned
24952 about if they appear to be unused, just like variables of fundamental
24955 This attribute is appropriate for types which just represent a value,
24956 such as @code{std::string}; it is not appropriate for types which
24957 control a resource, such as @code{std::lock_guard}.
24959 This attribute is also accepted in C, but it is unnecessary because C
24960 does not have constructors or destructors.
24964 @node Function Multiversioning
24965 @section Function Multiversioning
24966 @cindex function versions
24968 With the GNU C++ front end, for x86 targets, you may specify multiple
24969 versions of a function, where each function is specialized for a
24970 specific target feature. At runtime, the appropriate version of the
24971 function is automatically executed depending on the characteristics of
24972 the execution platform. Here is an example.
24975 __attribute__ ((target ("default")))
24978 // The default version of foo.
24982 __attribute__ ((target ("sse4.2")))
24985 // foo version for SSE4.2
24989 __attribute__ ((target ("arch=atom")))
24992 // foo version for the Intel ATOM processor
24996 __attribute__ ((target ("arch=amdfam10")))
24999 // foo version for the AMD Family 0x10 processors.
25006 assert ((*p) () == foo ());
25011 In the above example, four versions of function foo are created. The
25012 first version of foo with the target attribute "default" is the default
25013 version. This version gets executed when no other target specific
25014 version qualifies for execution on a particular platform. A new version
25015 of foo is created by using the same function signature but with a
25016 different target string. Function foo is called or a pointer to it is
25017 taken just like a regular function. GCC takes care of doing the
25018 dispatching to call the right version at runtime. Refer to the
25019 @uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
25020 Function Multiversioning} for more details.
25023 @section Type Traits
25025 The C++ front end implements syntactic extensions that allow
25026 compile-time determination of
25027 various characteristics of a type (or of a
25031 @item __has_nothrow_assign (type)
25032 If @code{type} is @code{const}-qualified or is a reference type then
25033 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
25034 is @code{true} then the trait is @code{true}, else if @code{type} is
25035 a cv-qualified class or union type with copy assignment operators that are
25036 known not to throw an exception then the trait is @code{true}, else it is
25038 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25039 @code{void}, or an array of unknown bound.
25041 @item __has_nothrow_copy (type)
25042 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
25043 @code{true}, else if @code{type} is a cv-qualified class or union type
25044 with copy constructors that are known not to throw an exception then
25045 the trait is @code{true}, else it is @code{false}.
25046 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25047 @code{void}, or an array of unknown bound.
25049 @item __has_nothrow_constructor (type)
25050 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
25051 is @code{true}, else if @code{type} is a cv class or union type (or array
25052 thereof) with a default constructor that is known not to throw an
25053 exception then the trait is @code{true}, else it is @code{false}.
25054 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25055 @code{void}, or an array of unknown bound.
25057 @item __has_trivial_assign (type)
25058 If @code{type} is @code{const}- qualified or is a reference type then
25059 the trait is @code{false}. Otherwise if @code{__is_pod (type)} is
25060 @code{true} then the trait is @code{true}, else if @code{type} is
25061 a cv-qualified class or union type with a trivial copy assignment
25062 ([class.copy]) then the trait is @code{true}, else it is @code{false}.
25063 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25064 @code{void}, or an array of unknown bound.
25066 @item __has_trivial_copy (type)
25067 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference
25068 type then the trait is @code{true}, else if @code{type} is a cv class
25069 or union type with a trivial copy constructor ([class.copy]) then the trait
25070 is @code{true}, else it is @code{false}. Requires: @code{type} shall be
25071 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
25074 @item __has_trivial_constructor (type)
25075 If @code{__is_pod (type)} is @code{true} then the trait is @code{true},
25076 else if @code{type} is a cv-qualified class or union type (or array thereof)
25077 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
25078 else it is @code{false}.
25079 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25080 @code{void}, or an array of unknown bound.
25082 @item __has_trivial_destructor (type)
25083 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type
25084 then the trait is @code{true}, else if @code{type} is a cv class or union
25085 type (or array thereof) with a trivial destructor ([class.dtor]) then
25086 the trait is @code{true}, else it is @code{false}.
25087 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25088 @code{void}, or an array of unknown bound.
25090 @item __has_virtual_destructor (type)
25091 If @code{type} is a class type with a virtual destructor
25092 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
25093 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25094 @code{void}, or an array of unknown bound.
25096 @item __is_abstract (type)
25097 If @code{type} is an abstract class ([class.abstract]) then the trait
25098 is @code{true}, else it is @code{false}.
25099 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25100 @code{void}, or an array of unknown bound.
25102 @item __is_base_of (base_type, derived_type)
25103 If @code{base_type} is a base class of @code{derived_type}
25104 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
25105 Top-level cv-qualifications of @code{base_type} and
25106 @code{derived_type} are ignored. For the purposes of this trait, a
25107 class type is considered is own base.
25108 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
25109 are @code{true} and @code{base_type} and @code{derived_type} are not the same
25110 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
25111 type. A diagnostic is produced if this requirement is not met.
25113 @item __is_class (type)
25114 If @code{type} is a cv-qualified class type, and not a union type
25115 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
25117 @item __is_empty (type)
25118 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
25119 Otherwise @code{type} is considered empty if and only if: @code{type}
25120 has no non-static data members, or all non-static data members, if
25121 any, are bit-fields of length 0, and @code{type} has no virtual
25122 members, and @code{type} has no virtual base classes, and @code{type}
25123 has no base classes @code{base_type} for which
25124 @code{__is_empty (base_type)} is @code{false}.
25125 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25126 @code{void}, or an array of unknown bound.
25128 @item __is_enum (type)
25129 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
25130 @code{true}, else it is @code{false}.
25132 @item __is_literal_type (type)
25133 If @code{type} is a literal type ([basic.types]) the trait is
25134 @code{true}, else it is @code{false}.
25135 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25136 @code{void}, or an array of unknown bound.
25138 @item __is_pod (type)
25139 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
25140 else it is @code{false}.
25141 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25142 @code{void}, or an array of unknown bound.
25144 @item __is_polymorphic (type)
25145 If @code{type} is a polymorphic class ([class.virtual]) then the trait
25146 is @code{true}, else it is @code{false}.
25147 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25148 @code{void}, or an array of unknown bound.
25150 @item __is_standard_layout (type)
25151 If @code{type} is a standard-layout type ([basic.types]) the trait is
25152 @code{true}, else it 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_trivial (type)
25157 If @code{type} is a trivial type ([basic.types]) the trait is
25158 @code{true}, else it is @code{false}.
25159 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25160 @code{void}, or an array of unknown bound.
25162 @item __is_union (type)
25163 If @code{type} is a cv union type ([basic.compound]) the trait is
25164 @code{true}, else it is @code{false}.
25166 @item __underlying_type (type)
25167 The underlying type of @code{type}.
25168 Requires: @code{type} shall be an enumeration type ([dcl.enum]).
25170 @item __integer_pack (length)
25171 When used as the pattern of a pack expansion within a template
25172 definition, expands to a template argument pack containing integers
25173 from @code{0} to @code{length-1}. This is provided for efficient
25174 implementation of @code{std::make_integer_sequence}.
25180 @section C++ Concepts
25182 C++ concepts provide much-improved support for generic programming. In
25183 particular, they allow the specification of constraints on template arguments.
25184 The constraints are used to extend the usual overloading and partial
25185 specialization capabilities of the language, allowing generic data structures
25186 and algorithms to be ``refined'' based on their properties rather than their
25189 The following keywords are reserved for concepts.
25193 States an expression as an assumption, and if possible, verifies that the
25194 assumption is valid. For example, @code{assume(n > 0)}.
25197 Introduces an axiom definition. Axioms introduce requirements on values.
25200 Introduces a universally quantified object in an axiom. For example,
25201 @code{forall (int n) n + 0 == n}).
25204 Introduces a concept definition. Concepts are sets of syntactic and semantic
25205 requirements on types and their values.
25208 Introduces constraints on template arguments or requirements for a member
25209 function of a class template.
25213 The front end also exposes a number of internal mechanism that can be used
25214 to simplify the writing of type traits. Note that some of these traits are
25215 likely to be removed in the future.
25218 @item __is_same (type1, type2)
25219 A binary type trait: @code{true} whenever the type arguments are the same.
25224 @node Deprecated Features
25225 @section Deprecated Features
25227 In the past, the GNU C++ compiler was extended to experiment with new
25228 features, at a time when the C++ language was still evolving. Now that
25229 the C++ standard is complete, some of those features are superseded by
25230 superior alternatives. Using the old features might cause a warning in
25231 some cases that the feature will be dropped in the future. In other
25232 cases, the feature might be gone already.
25234 G++ allows a virtual function returning @samp{void *} to be overridden
25235 by one returning a different pointer type. This extension to the
25236 covariant return type rules is now deprecated and will be removed from a
25239 The use of default arguments in function pointers, function typedefs
25240 and other places where they are not permitted by the standard is
25241 deprecated and will be removed from a future version of G++.
25243 G++ allows floating-point literals to appear in integral constant expressions,
25244 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
25245 This extension is deprecated and will be removed from a future version.
25247 G++ allows static data members of const floating-point type to be declared
25248 with an initializer in a class definition. The standard only allows
25249 initializers for static members of const integral types and const
25250 enumeration types so this extension has been deprecated and will be removed
25251 from a future version.
25253 G++ allows attributes to follow a parenthesized direct initializer,
25254 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
25255 has been ignored since G++ 3.3 and is deprecated.
25257 G++ allows anonymous structs and unions to have members that are not
25258 public non-static data members (i.e.@: fields). These extensions are
25261 @node Backwards Compatibility
25262 @section Backwards Compatibility
25263 @cindex Backwards Compatibility
25264 @cindex ARM [Annotated C++ Reference Manual]
25266 Now that there is a definitive ISO standard C++, G++ has a specification
25267 to adhere to. The C++ language evolved over time, and features that
25268 used to be acceptable in previous drafts of the standard, such as the ARM
25269 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
25270 compilation of C++ written to such drafts, G++ contains some backwards
25271 compatibilities. @emph{All such backwards compatibility features are
25272 liable to disappear in future versions of G++.} They should be considered
25273 deprecated. @xref{Deprecated Features}.
25277 @item Implicit C language
25278 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
25279 scope to set the language. On such systems, all system header files are
25280 implicitly scoped inside a C language scope. Such headers must
25281 correctly prototype function argument types, there is no leeway for
25282 @code{()} to indicate an unspecified set of arguments.
25286 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
25287 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr